harness-plan

Harness Plan

Harness integrated planning skill. Integrates the following three legacy skills:

planning (plan-with-agent) — Turning ideas into Plans.md
plans-management — Task state management / marker updates
sync-status — Verifying synchronization between Plans.md and implementation

Quick Reference

User input	Subcommand	Behavior
"Create a plan" / `/harness-plan create`	`create`	Spec delta / skip reason → Plans.md task generation
"Add a task" / `/harness-plan add`	`add`	Add a new task to Plans.md
"Mark as complete" / `/harness-plan update`	`update`	Change the task marker to cc:complete
"Where are we now?" / `/harness-plan sync`	`sync`	Cross-check and synchronize implementation with Plans.md
`/harness-sync`	`sync`	Progress check (equivalent to the independent sync surface)
`/harness-plan create`	`create`	Planning with the dual sources of truth spec.md / Plans.md
`/harness-plan list`	`list`	`plans/manifest.json` List the named Plans in
`/harness-plan switch <name>`	`switch`	active plan を `.claude/state/active-plan.json` save to

Default scope: all work that can proceed now (operator ruling 2026-07-24)

Plan request (create / invocation with no arguments / "plan it") is by default interpreted as "all work that can currently be started"。

Unless the user explicitly specifies a scope, identify all open items that fall within the request context (remaining phases, unhandled follow-ups, known improvements, and all issues mentioned in the request text) and include them in the plan. Do not arbitrarily narrow it down to a minimal subset
Even when there are many items, do not narrow them down; instead, present the full set classified into Required / Recommended / Optional / Reject. For exclusions, state the reason explicitly as Reject (do not silently drop them)
If you judge that "do only part first" is appropriate, express it not as a narrowed-down plan but as the execution order (Phase split / Depends) within the full plan

Literal companion commands（CC 2.1.108+）

/recap: When returning after a long time, re-obtain the summary before entering sync , then enter
/undo: /rewind An alias for . Use it as-is when you want to immediately revert the most recent plan update

Subcommand details

Standard planning quality contract

See references/planning-quality.md

harness-plan is a planning surface that produces the co-required planning output of the spec.md product contract and the Plans.md task contract. Precedence remains spec.md > sub-spec > Plans.md as-is. Plans.md is the task ledger, and root spec.md is the product contract, and the hierarchical relationship is not to be broken. Do not drop the given information as-is into Plans.md. For plan creation or large task additions, check the latest information, existing specifications, memory, and multi-perspective discussion via TeamAgent / subagents, and convert only the elements that should be adopted into this product into a task contract. /harness-plan create は Spec delta or Spec skip reason と Plans.md task generation together as a set. The output must always include Spec delta or Spec skip reason . Spec delta / Spec skip reason is generated by Harness, and the consumer only approves or revises it.

Non-trivial planning gate:

Planning that is not a one-off, minor task is handled on the premise of a TeamAgent or subagent. Here, non-trivial refers to requests that affect multiple tasks / multiple files / multiple sessions / product behavior / API / data model / permissions / billing / external integrations / distribution surfaces / security. If the Task tool is available, run the independent perspectives of Product / Architecture / Security / QA / Skeptic. If it is not available, サブエージェント未使用 and state this explicitly, then evaluate the same perspectives separately on your own.

The output of non-trivial planning must always include the following verification.

team_validation_mode: not_required_lightweight / native / subagent / manual-pass / unavailable
spec.md / sub-spec / Plans.md consistency
Confirmation of prevention of reinventing the wheel via harness-mem / harness-recall / repo memory
Whether it deviates from the product purpose
Whether there are any problems with security, permissions, confidential information, or the supply chain
Whether there is a lint / formatter baseline. If it is not set for a plan that includes source code changes, place a setup task before the implementation task
Whether it is a plan that actually works. In other words, whether test / smoke / CI / review / release gate have been incorporated into the task DoD

For lightweight tasks, use any of team_validation_mode: not_required_lightweight is sufficient. non-trivial planning is native / subagent / manual-pass . unavailable must not be left as Required. Product / Architecture / Security / QA / Skeptic are verification perspectives, not agent_type names. Request them as perspectives from the available TeamAgent / Task subagents, and do not require spawning arbitrary agents. The Security gate does not require actually reading confidential information. .env or secrets must be read, stop as a Risk Gate and confirm with permitted existing guards / evidence.

Situations where it applies:

create Create a new plan with
add Add a task that affects product behavior / API / permissions / billing / external integrations / distribution surfaces with
The user has provided an external product, competitor, draft specification, improvement proposal, or comparison material
There is a risk of conflict with existing specifications or past decisions

Situations where it may be treated lightly:

For marker updates only, update
For status verification only, sync
typo, format, README/CHANGELOG only
Narrow changes whose correct answer is fixed by existing spec and tests

Quality flow:

Break down the input information and make explicit the evaluation targets, scoring axes, and uncertain facts
Obtain the latest information. For external facts, prioritize WebSearch / official documentation / primary sources, and cross-check important points with multiple sources
Existing specifications, root spec.md, Plans.md, README, docs, CLAUDE.md, and related skills
harness-mem / harness-recall / .claude/agent-memory/ / .claude/state/ etc., check the available memory surfaces project-scoped
For non-trivial planning, use TeamAgent / Task subagents and conduct independent reviews from different perspectives such as Product / Architecture / Security / QA / Skeptic
For plans that include source code changes, check the lint / formatter baseline, and if it is not set, have the setup task come first
Produce a neutral scoring review and classify into Required / Recommended / Optional / Reject
$easy In the format, report the proposal, rationale, and what will happen
Reflect only the adopted proposal into root spec.md / Plans.md / test task

Lane Taxonomy + Stage Gate

Fast / Gate / Release は Treat as Plans metadata, not a new skill . Do not change the 5 column template of Plans.md (Task / Content / DoD / Depends / Status), and embed lane ([lane:fast] / [lane:gate] / [lane:release]), stage (the 5 stages: verification → planning → TDD implementation → review → PR closeout), and unknown data contract (not_observed != absent, explicitly state unverifiable facts as unknown ) at the beginning of Content or DoD. For the tag list, worked example, and DoD examples per stage, refer to references/create.md .

create — plan creation

See references/create.md

Hear out ideas and requirements, and generate an actionable Plans.md.

Flow:

Check conversation context (extract from the immediately preceding discussion or conduct new interviews)
Ask what to build (max 3 questions)
Plan quality check(latest information, existing specifications, memory, TeamAgent / sub-agent multi-perspective review, scoring)
Technical research (WebSearch)
Feature list extraction
spec.md / Plans.md dual source of truth check(Spec delta or Spec skip reason + Plans.md task)
Priority matrix (Required / Recommended / Optional / Reject)
TDD adoption decision (test design)
Generate Plans.md (withcc:TODO marker)
Generate pre-approval section（plan-time pre-approval）
Guide to the next action

create — pre-approval section (plan-time pre-approval)

create When finalizing the plan with pre-approval section, after producing the Plans.md task and before approval, always generate the following. The purpose is not to allow everything with a permanent allowlist, but to confirm, once at plan approval time, the "stops / asks" that are likely to occur for each work scope, by moving them forward.

Extraction targets:

Target files, related paths, and expected change scope for each task
Verification commands, PR closeout commands, and external API / CLI calls written in the DoD
secret-read path（.env*, secrets/**, *.pem, *.key, .ssh/**, .aws/**, credentials , etc.)
External transmission (git push, gh pr create, gh api, curl / API call, release / publish / deploy）
Destructive operations (rm -rf, migration destructive step, force push, production apply）

Fixed format:

## 事前確認
- 事項: <secret-read / external-send / destructive の具体操作>
  理由: <DoD または task 実行上必要な理由を 1 行>
  scope: Phase <phase> / Task <task>

Output rules:

A single line of 理由 must not contain secret values. Limit it to paths / command names / target services.
At plan approval, present all items in the pre-approval section at once, and obtain approval / rejection from the user.
Record the approval result as .claude/state/plan-preapprovals.json に plan-preapproval.v2 . The schema is templates/schemas/plan-preapproval.v2.json. v1 is limited to read compatibility with existing records.
For records, maintain 事項 + 理由 1 行 + scope (phase/task) . Listoperations requires secret-read / external-send / destructive . Forpaths / commands / targets , list the targets. Insertdecision、approved_at、RFC3339 の expires_at .
max_uses sets an upper limit including the necessary number of retries. The default is 10.uses is set to 0 at the time of new approval.
Confirmation is only once, at plan approval.harness-work / breezing While running, do not issue AskUserQuestion based solely on declared matters.
Unplanned secret-read / external transmission / destructive operations not in the record are stopped by the runtime floor / ask as before. Do not narrow the safety net.
Approval of secret-read is not permission to display the secret value. Declare the minimal necessary path, and at work start treat it as input for per-run reflection into the project config's runtimefloor.secretAllow .

spec.md / Plans.md dual-source-of-truth check (default)

Plans.md is the task contract for "what should be done", root spec.md is treated as the product contract for "what is correct". co-required planning output means both outputs are required, and precedence is maintained as spec.md > sub-spec > Plans.md . When the implementation may drift, update the root spec.md before generating Plans.md. create と product-impacting add reads the root spec.md every time.

Preferred storage locations:

root spec.md
consumer repo に root spec.md only when there is no existing project spec / architecture / product compass
consumer repo に root spec.md only when there is nodocs/spec/00-project-spec.md
In a repo with existing conventions, a spec path that follows those conventions

Conditions requiring creation/update:

Tasks that decide user-visible behavior, APIs, data models, permissions, billing, or external integrations
Tasks where there are multiple implementation approaches and the choice changes product behavior
Tasks where there are signs in past or current conversation that "the spec was ambiguous and the implementation drifted"
Tasks where Plans.md contains the work content but the correct conditions as a project are not in a stable document

Unnecessary conditions:

typo, format, dependency bump, README/CHANGELOG only
Narrow refactors with no behavior change
Fixes where the correct answer is sufficiently fixed by existing specs and tests

Output contract:

Spec delta: when updating the product contract, write the target spec path and the changes
Spec skip reason: when not updating the product contract, write the reason
Spec delta / Spec skip reason is generated by the Harness, and the consumer only approves/corrects it
even for docs-only / mechanical tasks, Spec skip reason in the task context / sprint contract
Do not conclude that a missing search result, unavailable memory, or unread file is absent.not_observed != absent
Do not make the user write the spec from scratch. The agent creates the minimal delta from existing specs and input, and only presents decision branches when ambiguous

References:

docs/plans/spec-ssot.md

Session startup guidance upon create completion (required)

create When is finished, do not stop at just explaining; provide as a set:the startup command for a new session と the first instruction prompt to enter as-is after startup .

The priority order is as follows:

Only 1 incomplete task, or it is natural to start only the first one
- Startup command: claude
- First input: /harness-work <task番号>
There are multiple weakly dependent tasks, and it is natural to proceed with them together
- Startup command: claude
- First input: /breezing all
- Alternative: /harness-work all
Assumes long-running execution or re-entry
- Startup command: ENABLE_PROMPT_CACHING_1H=1 claude
- First input: /harness-loop all
- Alternative: /breezing all

Include at least the following 3 lines:

新しいセッションの起動コマンド:
起動後の最初の入力:
向いている場面:

Example:

新しいセッションの起動コマンド: claude
起動後の最初の入力: /breezing all
向いている場面: Phase 1 の task が複数あり、まとめて進めるほうが自然なため

If recommending a long-running setup, also include the Claude Code session startup command:

新しいセッションの起動コマンド: ENABLE_PROMPT_CACHING_1H=1 claude
起動後の最初の入力: /harness-loop all
向いている場面: 5 分を超える待機や resume をまたぐ長時間タスクのため

Notes:

scripts/claude-longrun.sh is a development helper script for this repository and is not distributed to consumer environments after plugin install
Therefore, in consumer-facing guidance, always prioritize the ENABLE_PROMPT_CACHING_1H=1 claude one-line command
If you want to use an equivalent wrapper only during repository development,bash scripts/claude-longrun.sh may be used on a local checkout

CI mode (--ci): No hearing. Use the existing Plans.md as-is and only perform task breakdown.

add — Add task

Add a new task to Plans.md. For product-impacting additions, following the "spec.md / Plans.md dual source of truth check" above, also output Spec delta or Spec skip reason .

/harness-plan add タスク名: 詳細説明 [--phase フェーズ番号]

The task is cc:TODO It is added with the marker.

update — Update marker

Change the task status marker.

/harness-plan update [タスク名|タスク番号] [WIP|完了|blocked]

Marker correspondence table:

command	marker
`WIP`	`cc:WIP`
`完了` / `done`	`cc:完了`
`blocked`	`blocked`
`TODO`	`cc:TODO`

sync — Sync progress

Compare the implementation status with Plans.md, detect and update differences (fetch current Plans.md → detect format → fetch git status → analyze agent trace → detect differences → propose marker fixes → present next actions). cc:完了 If there is at least 1 task, run a retrospective by default ON that analyzes estimation accuracy, blocking causes, and scope changes (sync --no-retro to skip). For the complete version of Step 0-6 and the procedure for recording to harness-mem, see references/sync.md .

team mode / issue bridge

Keep Plans.md as the source of truth, and use GitHub Issue integration only in opt-in team mode.

Do not use bridge in solo development
In team mode, create one tracking issue, and under it generate per-task sub-issue payloads in dry-run
scripts/plans-issue-bridge.sh does not actually update GitHub and always returns dry-run payloads
Changes to Plans.md are not made by this bridge

Reference:

docs/plans/team-mode.md

named Plans

When using multiple Plans.md files, use plans/manifest.json as the source of truth and select by name (in 1 run, use only 1 named plan. For long-running / CI / issue bridge, do not rely on the active pointer; pass --plan <name> . The manifest path is project root relative only).

scripts/plan-registry.sh list
scripts/plan-registry.sh switch roadmap
scripts/plans-issue-bridge.sh --plan roadmap --format markdown
node scripts/generate-sprint-contract.js --plan roadmap 9.1.1

Reference: docs/plans/named-plans.md

Plans.md format conventions

Format

A 5-column (Task / Content / DoD / Depends / Status) Markdown table. DoD must be a verifiable one-liner that can be judged Yes/No ("feels good" and "works properly" are prohibited). Depends is one of -(no dependency) / task number / comma-separated multiple / phase dependency. For the full generated template (including the Purpose line), see references/create.md .

Grading design for DoD / acceptance_criteria

DoD や acceptance_criteria When writing, judge by whether "a part-time worker can mark ○× on the checklist." The discipline of translating into 3 layers: the mechanical ○× floor (tests, character count, exit code) / LLM perspective grading (structure, appeal checklist) / essential doc reference (the relevant clauses of spec.md and decisions.md), and the translation procedure when ambiguous adjectives (good/proper/easy to understand, etc.) are detected are references/criteria-design.md refer to.

TDD tags

In Plans.md tasks, a tag explicitly indicating the TDD judgment can be written in the content or the DoD.

tag	Meaning	`tdd_required` Inference
`[tdd:required]`	This task needs a failing test written first	`true`
`[tdd:skip:<reason>]`	This task omits TDD with a reason	`false`, `skip_tdd_reason=<reason>`

<reason> is not left empty. Example: [tdd:skip:docs-only]、[tdd:skip:no-test-framework-detected]。

When there is no tag, tdd_required is inferred in the following order.

Plans.md tag: [tdd:required] / [tdd:skip:<reason>]
files: src/, app/, cmd/, lib/, pkg/, internal/, go/ etc., required if it includes source implementation
TDD inference: if docs-only or no test framework, not required with a skip reason

optional briefs / manifest

harness-plan create attaches a brief only when necessary.

The project spec SSOT is a document that fixes the correct conditions for the entire project, and is created only when necessary
For tasks that include UI, design brief
For tasks that include API, contract brief
The brief is supplementary material that briefly fixes "what to build," and does not replace Plans.md or the spec SSOT
The list of skill frontmatter is scripts/generate-skill-manifest.sh can be made into machine-readable JSON with