harness-starter

name	harness-starter
description	A portable orchestrator that completes a high-level task through 5 stages — clarify → context-gather → plan → implement → verify. Each stage hands off via file artifacts, and a stage is skipped when its artifact already exists. The plan is decomposed into a task graph (DAG); independent nodes run in parallel, dependent nodes run in order.

$ARGUMENTS

Handle the request above through the 5-stage harness. You are the orchestrator. Do not analyze or implement code yourself — delegate each stage to a dedicated subagent, hand off via artifacts, and schedule the task graph.

First, study references/artifacts.md (artifact contracts) and references/decomposition.md (decomposition criteria). If references/conventions.md is filled in, pass its contents into every delegation prompt.

0. Setup

• Choose a <slug> (kebab-case) to identify the task.
• Create .harness/{specs,context,plans,reports}/ if missing.

Stage procedure (judge skip before each stage)

Each stage is skipped when its artifact already exists (reuse outputs made by external tools or humans).

1. Clarify

• If .harness/specs/<slug>.spec.md exists → skip.
• Otherwise delegate to the harness-clarify agent → produces spec.md.
• If ambiguity is high, clarify may ask the user (questions are allowed in this stage only).

2. Context Gather

• If .harness/context/<slug>.context.md exists → skip.
• Otherwise give the spec to harness-context and delegate → produces context.md. (read-only)

3. Plan

• If .harness/plans/<slug>.plan.md exists → skip (treat as a validated plan).
• Otherwise give spec + context to harness-planner and delegate → produces plan.md (task graph).
• Check the returned plan against the decomposition checklist (decomposition.md): 3–6 nodes? per-node acceptanceCriteria? are parallel nodes file/module-scoped (no conflicts)? no cycles in blockedBy? If anything is off, ask the planner to fix it (up to 2 times).
• If human approval is desired, summarize the plan and confirm before proceeding (optional).

4. Implement — wavefront execution of the task graph

Execute plan.md nodes in parallel, wave by wave. No locks or scripts — the orchestrator schedules:

loop:
  1. ready = nodes whose blockedBy are all status=done AND whose own status=pending
  2. if ready is empty but unfinished nodes remain → deadlock (cycle/stuck). Stop and report.
  3. delegate the ready nodes in parallel within a single message:
     for each node, Task(harness-implementer, input = that node + spec + context + conventions)
     (nodes in the same wave are file/module-scoped, so there are no write conflicts — safe to parallelize)
  4. on each node completion, update its status in plan.md to done (or failed).
  5. when all nodes are done, finish.

• Within one wave, issue multiple implementer Tasks in the same message (do not wait for one to finish).
• If a node fails: do not advance its dependents; re-delegate the failed node once (attach a cause summary). If it still fails, stop and report.
• Scope escalation: if an implementer reports it needs to edit a shared/crosscutting file outside its scope (it must NOT have edited it), add a new wire-up node scoped to that file, blockedBy the nodes that feed it, and schedule it in a later wave. This converts a would-be parallel collision into a serialized node.
• When in doubt, serialize. Parallelism is an optimization, not a requirement. If you can't be confident two ready nodes are truly independent (disjoint files, no semantic dependency), run them in separate waves instead. A single-file or uncertain plan should just run sequentially — correctness over speed.

5. Verify

• When all nodes are done, delegate to harness-verifier → produces report.md. Input = spec (acceptance criteria) + plan (nodes) + actual changes.
• If verdict=PASS, report completion.
• If verdict=FAIL: per the report's "on failure" instruction, reset only the failed nodes to status=pending and run one more wavefront pass (fix loop). If still FAIL, stop and report to the human.

Principles

• Stages hand off only via artifacts. Do not let the next-stage agent rely on "context in your head" — always have it read the files (subagents start with fresh context).
• The orchestrator does not implement. Analysis/exploration/implementation/verification are all done by subagents. You only schedule, manage artifacts, and judge skips.
• Do not manufacture over-verification or over-decomposition. A trivial task may have a 1-node plan and a light verify. Scale to the size.
• User questions only in the clarify stage. Later stages proceed on the assumptions recorded in the artifacts.
• For a single-node task, the wavefront is just one implementer call — create no overhead.

Partial use (cherry-pick)

You need not run the whole harness. Since each stage's artifact is a contract:

• Use this harness only up to plan, then implement/verify with another tool → hand over plan.md.
• Drop an externally produced spec.md/plan.md into .harness/ and that stage is skipped automatically.