---
name: harness-workflow
description: 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.

```json
{
  "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`

```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:

```markdown
# 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:

```bash
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.