harness-plan

name: harness-plan description: "Plans and tracks tasks in .claude/harness/plans.json. Use when creating plans, adding tasks, updating markers, checking progress, or brainstorming an idea into tasks." when_to_use: "create a plan, add a task, mark task done, where am I, check progress, sync plans, archive phases, brainstorm idea, rough idea, design spec" allowed-tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob", "WebSearch", "Task"] argument-hint: "[create|add|update|sync|archive|brainstorm|sync --no-retro|sync --snapshot|--ci]" effort: xhigh model: opus

Harness Plan

Bootstrap Check (runs before any subcommand)

Before executing any subcommand, ensure the JSON plans storage is initialised:

If .claude/harness/plans.json exists → proceed normally.
If Plans.md exists but .claude/harness/plans.json does not → auto-migrate:
```
harness plan-cli migrate
```
If neither exists → no action needed; the JSON file is created automatically on the first write (harness plan-cli add-phase ...).

This check is performed silently. Inform the user only if migration was triggered.

Quick Reference

User Input	Subcommand	Behavior
"create a plan"	`create`	Default behavior, interactive interview → `harness plan-cli add-phase`/`add-task`
"add a task"	`add`	Add new task via `harness plan-cli add-task`
"mark complete"	`update`	Change task status to cc:done via `harness plan-cli update`
"where am I?" / "check progress" / `harness-plan sync` / "sync status"	`sync`	Compare implementation with plan state (`harness plan-cli list`/`get`) and sync via `harness plan-cli update`
`harness-plan sync --snapshot`	`sync --snapshot`	Save point-in-time progress snapshot
"rough idea" / "brainstorm" / `harness-plan brainstorm`	`brainstorm`	Shape idea → design spec → tasks via `harness plan-cli add-phase`/`add-task`
"archive old phases" / `harness-plan archive`	`archive`	Archive phases via `harness plan-cli archive <phase-id>` (sets `status: archived` in plans.json)

Subcommand Details

Each subcommand has its own reference file. Open the matching file when invoking that subcommand.

Subcommand	Reference
`create`	references/create.md — interview flow, TDD decision rules, plan generation via `harness plan-cli`
`add`	references/add.md — insertion rules, DoD/Depends auto-inference
`update`	references/update.md — marker mapping, single-task status changes
`sync`	references/sync.md — discrepancy detection, retrospective, --snapshot
`brainstorm`	references/brainstorm.md — two-stage idea → spec → plan flow
`archive`	references/archive.md — phase archival, retention, naming
(CLI reference)	cli-reference.md — all subcommands, flags, exit codes, agent examples
(quality gate)	references/planning-quality.md — 8-step planning quality contract for `create` and high-impact `add`

CI mode (--ci) — applies to create only: no interview; uses the existing plan state (harness plan-cli list) and only performs task decomposition. See references/create.md "CI Mode" section.

Retrospective skip (--no-retro) — applies to sync only: skips the automatic retrospective pass. See references/sync.md "Step 6: Retrospective".

Plans Format Conventions

Task data is stored in .claude/harness/plans.json (repo root — never the plugin cache path). The canonical schema is defined in plan_types.go. Key invariants:

Newest phase first — add-phase prepends; phases are listed newest-on-top.
Phases are never reordered — gaps in IDs are allowed (archived phases are soft-deleted via status: archived).
DoD must be verifiable — yes/no answerable; banned: "looks good", "works properly".
All writes go through the CLI — never edit plans.json directly; use harness plan-cli subcommands.
Location rule — see harness/rules/plans-json-location.md; plugin cache copies are frozen snapshots and must not be read or written.

Marker List

Compact summary. For full semantics (including the cc:done [hash] artifact format and blocked reason annotation), see references/task-fields.md "Status Markers".

Marker	Meaning
`pm:requested`	Requested by PM
`cc:TODO`	Not started
`cc:WIP`	In progress
`cc:done`	Worker completed
`pm:confirmed`	PM review completed
`blocked`	Blocked (reason must always be noted)
`[ralph]`	Iterative loop task — executed by `harness-ralph-loop`; requires `Verify:` line. See references/ralph-tasks.md

Optional Briefs / Manifest

harness-plan create attaches briefs only when needed.

Tasks involving UI get a design brief
Tasks involving API get a contract brief
Briefs are supplementary materials that briefly define what to build; they do not replace the plan
A machine-readable JSON list of skill frontmatter can be generated with scripts/generate-skill-manifest.sh

Reference:

docs/plans/briefs-manifest.md

Delegation to `harness-planner` Agent

For mechanical plans mutations (mark task status, add a row, archive completed phases), skills and agents may delegate to the harness-planner agent (Haiku, low effort) instead of running the edit inline.

The planner agent now calls the harness plan-cli binary — it does not edit Plans.md or plans.json directly. All writes go through the CLI so atomic I/O guarantees are preserved.

Subcommand handled by agent	CLI call used internally
`update`	`harness plan-cli update <task_id> --status <status>`
`add`	`harness plan-cli add-phase` or `harness plan-cli add-task <phaseID>`
`archive`	`harness plan-cli archive <phaseID>`

The same CLI calls apply when this skill performs the edit inline (without delegating): the SSOT is .claude/harness/plans.json, and every read goes through harness plan-cli list/get, every write through a harness plan-cli subcommand.

Subcommands not delegated (require Opus reasoning, stay in this skill): create, brainstorm, sync.

Invocation pattern — callers use the Agent tool with subagent_type: "harness-planner" and pass a planner-request.v1 JSON payload. The agent returns a planner-response.v1 JSON. See harness/agents/harness-planner.md for the full schema and per-operation flows.

The harness-plan skill itself remains the user-facing entry point — delegation is opt-in for callers that want cheap, deterministic edits without burning Opus tokens.

Team Mode / Issue Bridge

.claude/harness/plans.json is maintained as the source of truth, and GitHub Issue integration is only used in opt-in team mode.

Do not use the bridge for solo development
Team mode creates one tracking issue and generates dry-run sub-issue payloads for each task underneath it
scripts/plans-issue-bridge.sh does not actually update GitHub; it always returns dry-run payloads
This bridge does not modify the plan