minhtran3124/agent-harness/writing-plans

Writing Plans

Create specs/<slug>/PLAN.md for work that needs a plan. Announce this skill, then Read `rules/plan-format.md` and Read `rules/terminology.md` before authoring: both are path-scoped and a new plan does not load them automatically. From terminology.md, §3 is the load-bearing one — every Verify:, Done:, and Success Criterion must be decidable by running something, never by judging that output "is correct" or "looks right".

Required inputs

Read specs/<slug>/design.md and specs/<slug>/research-brief.md. Stop and tell the user when a required brief is missing. If the scope contains independent subsystems, propose separate plans.

Authoring flow

1. Map created/changed files and their responsibilities. Follow existing patterns and give each

unit a clear boundary; do not introduce unrelated refactors.

1. Write ## 3. Success Criteria first. Each observable behavior needs a re-runnable, pipe-free,

sub-60-second check and expected exit code, using the canonical schema from plan-format.md.

1. For every new plan, add exact ## Global Constraints. Decompose tasks in canonical ### Task

syntax. Give every task Files, imperative Action, automated Verify, measurable Done, mapped Criteria (SC-n), and an Interfaces line naming what it consumes/produces. Make actions test-first where applicable.

1. Ensure same-wave tasks have no file overlap and no unresolved dependency. Use waves only for

genuinely independent work.

1. When design.md has a ## What must be true section, first write ### Assumption coverage in

## 5. Risks, after the risk bullets with a blank line (start Risks with - none when there are no risks): the plan renderer cards only the first bullet list. Give each design A<n> one line: - A<n> → SC-n, - A<n> → Task x.y, - A<n> → accepted risk: <reason>, or - A<n> → retired by DC<n> when the design retired it; write - none (design has no assumptions) when that section is - none — <reason>. Check that every named SC-n and task exists in the plan. Then run python3 scripts/check_plan_contract.py specs/<slug>/PLAN.md, read references/review-loop.md, review the plan, and save it. Then run python3 skills/visual-planner/render_plan.py specs/<slug>/PLAN.md --summarize, which refreshes the At-a-glance block and writes the plain PLAN.html; use visual-planner only when the user asks for its graph-derived overlay.

Handoff

State the saved plan path. Before any code change, use using-git-worktrees unless already isolated, then invoke subagent-driven-development. Ask which execution mode only when the user has not stated one; both modes use the same gates.