FESADev/.agents/skills/harness-workflow/SKILL.md

name, description

name	description
harness-workflow	Plan and run the Harness Engineering workflow for this repository. Use when Codex needs to read `AGENTS.md` and `docs/*.md`, discuss implementation scope, draft phase plans, or create/update `phases/index.json`, `phases/{phase}/index.json`, and `phases/{phase}/stepN.md` files for staged execution.

Harness Workflow

Use this skill when the user is working in the Harness template and wants structured planning or phase-file generation.

Workflow

1. Explore first

Read these files before proposing steps:

• /AGENTS.md
• /docs/PRD.md
• /docs/ARCHITECTURE.md
• /docs/ADR.md
• /docs/UI_GUIDE.md

If the user explicitly asks for parallel exploration, use built-in Codex subagents such as explorer, or the repo-scoped custom agent phase_planner.

2. Discuss before locking the plan

If scope, sequencing, or architecture choices are still ambiguous, surface the decision points before creating phases/ files.

3. Design steps with strict boundaries

When drafting a phase plan:

1. Keep scope minimal. One step should usually touch one layer or one module.
2. Make each step self-contained. Every stepN.md must work in an isolated Codex session.
3. List prerequisite files explicitly. Never rely on "as discussed above".
4. Specify interfaces or invariants, not line-by-line implementations.
5. Use executable acceptance commands, not vague success criteria.
6. Write concrete warnings in "do not do X because Y" form.
7. Use kebab-case step names.

Files to generate

phases/index.json

Top-level phase registry. Append to phases[] when the file already exists.

{
  "phases": [
    {
      "dir": "0-mvp",
      "status": "pending"
    }
  ]
}

• dir: phase directory name.
• status: pending, completed, error, or blocked.
• Timestamp fields are written by scripts/execute.py; do not seed them during planning.

phases/{phase}/index.json

{
  "project": "<project-name>",
  "phase": "<phase-name>",
  "steps": [
    { "step": 0, "name": "project-setup", "status": "pending" },
    { "step": 1, "name": "core-types", "status": "pending" },
    { "step": 2, "name": "api-layer", "status": "pending" }
  ]
}

• project: from AGENTS.md.
• phase: directory name.
• steps[].step: zero-based integer.
• steps[].name: kebab-case slug.
• steps[].status: initialize to pending.

phases/{phase}/stepN.md

Each step file should contain:

1. A title.
2. A "read these files first" section.
3. A concrete task section.
4. Executable acceptance criteria.
5. Verification instructions.
6. Explicit prohibitions.

Recommended structure:

# Step {N}: {name}

## Read First
- /AGENTS.md
- /docs/ARCHITECTURE.md
- /docs/ADR.md
- {files from previous steps}

## Task
{specific instructions}

## Acceptance Criteria
```bash
python scripts/validate_workspace.py

Verification

1. Run the acceptance commands.
2. Check AGENTS and docs for rule drift.
3. Update the matching step in phases/{phase}/index.json:
   • completed + summary
   • error + error_message
   • blocked + blocked_reason

Do Not

• {concrete prohibition}

Execution

Run the generated phase with:

python scripts/execute.py <phase-name>
python scripts/execute.py <phase-name> --push

scripts/execute.py handles:

• feat-{phase} branch checkout/creation
• guardrail injection from AGENTS.md and docs/*.md
• accumulation of completed-step summaries into later prompts
• up to 3 retries with prior error feedback
• two-phase commit of code changes and metadata updates
• timestamps such as created_at, started_at, completed_at, failed_at, and blocked_at

Recovery rules

• If a step is error, reset its status to pending, remove error_message, then rerun.
• If a step is blocked, resolve the blocker, reset to pending, remove blocked_reason, then rerun.