Harness Plan

harness-plan — Epic Planning for the Harness Control Loop

Fills the gap between harness-init (environment setup) and harness-loop (autonomous sprints). Runs once per epic. Re-runs continue the same epic draft from wherever it was interrupted.

The skill orchestrates the Planner sub-agent through three artifacts:

1. product-spec.md — What / Why / Out of Scope / Constraints (interactive)
2. roadmap.md — sprint decomposition with bundling: split|bundled
3. One tracker Issue per sprint (when _config.yml.tracker != none)

After this skill finishes, the project is ready for /harness-loop.

Required Reading — Open BEFORE doing the step

Claude Code tends to skim SKILL.md. For each Planner dispatch below you MUST open and read the listed prompt template + reference file(s) before invoking the sub-agent. Planner is dispatched as fresh invocations per phase — never a single long session.

| Step | Planner phase | Required file(s) to open | |---|---|---| | Step 3.5 | Foundation readiness (no sub-agent) | [references/foundation-sprint-guide.md](references/foundation-sprint-guide.md), [../harness-init/references/scripts.md](../harness-init/references/scripts.md) §foundation-readiness.sh | | Step 4 | interview | [references/prompt-templates/planner-interview.md](references/prompt-templates/planner-interview.md), [references/product-spec-guide.md](references/product-spec-guide.md) | | Step 5 | roadmap | [references/prompt-templates/planner-roadmap.md](references/prompt-templates/planner-roadmap.md), [references/roadmap-guide.md](references/roadmap-guide.md) (foundation-sprint-guide.md when sprint-0 is inserted) | | Step 7 | contract-draft × N sprint (parallel-safe) | [references/prompt-templates/planner-contract.md](references/prompt-templates/planner-contract.md), [../harness-init/references/rubric-presets.md](../harness-init/references/rubric-presets.md) (foundation-sprint-checklist.md for type: foundation sprint-0) | | Step 8 | Tracker Issue creation | [references/issue-create.md](references/issue-create.md) |

.ja.md variants exist for Japanese projects; pick language-matched pair.

Language Rules

Resolve narrative language: explicit override (in English, 日本語で) > project mandate in CLAUDE.md / AGENTS.md > current user prompt > fallback skill source language (English).

Never infer from machine text (git log, progress.md, JSON keys, state enums, file paths, commands). Keep such tokens unchanged. AskUserQuestion body uses resolved language; option labels/descriptions stay bilingual (English / 日本語).

Reference files exist as .md (English) and .ja.md (Japanese). Pick the pair matching the resolved language for narrative guidance; YAML schemas and templates are language-agnostic.

Prerequisites

Before any generation step, check:

1. Harness initialised — .harness/_config.yml and

.harness/templates/product-spec.md must exist. If not, instruct the user to run /harness-init first and stop.

1. Git repo — git rev-parse --is-inside-work-tree must succeed.
2. jq available — command -v jq. Required for _state.json

reads/writes (all state IO uses jq for JSON parsing).

1. Tracker pre-flight — if _config.yml.tracker == github, verify

gh auth status now to fail fast. See [issue-create.md](references/issue-create.md) §Pre-flight.

1. Fresh agent registry after /harness-init — if

Task(subagent_type="generator"|"evaluator"|"planner") is missing or falls back to a general-purpose agent, /clear is insufficient. Fully exit Claude Code, relaunch the repo with claude --resume, then retry /harness-plan.

If any check fails, stop with a clear error. Do not partially generate.

Boot Sequence

Always execute before any write:

1. git log --oneline -20
2. tail -30 .harness/progress.md (if it exists)
3. cat .harness/_state.json (if it exists)

If _state.json.phase ∈ {product-spec-draft, roadmap-draft, roadmap-approved, issues-pending}, the skill offers resume vs restart via AskUserQuestion. harness-plan runs prior to harness-loop so mode is not yet decided — the Boot Sequence here always behaves interactively. If the user invoked with --auto-approve-roadmap, resume is chosen automatically; otherwise the user confirms.

Execution Flow (10 steps)

Step 1: Detect Existing Epic

if .harness//product-spec.md exists:
  AskUserQuestion:
    question: "Existing epic(s) detected. What to do?" /
              "既存の epic を検出しました。"
    options:
      - "Continue the most recent epic / 最新 epic を継続"
      - "Start a new epic / 新規 epic を開始"
      - "Cancel / キャンセル"

"Continue" picks the epic named in _state.json.current_epic, or the most recently modified .harness// directory if state is silent. "Start new" prompts for epic name (Step 2). "Cancel" exits cleanly.

With --auto-approve-roadmap, the skill always continues when state is populated, else starts new with a derived epic name (kebab-case from the first 3 non-stopword tokens of the user prompt).

Step 2: Epic Name

AskUserQuestion:
  question: "Epic name (kebab-case)?" / "Epic 名（kebab-case）?"
  options:
    - " (Recommended)"
    - "Let me type it / 手入力"

Validation:

• Kebab-case regex ^[a-z][a-z0-9-]{2,40}$
• Not already present under .harness/
• If invalid, re-ask once with the regex in the message

Create .harness// and switch _state.json.current_epic to this name.

Step 3: Copy product-spec Template

Copy .harness/templates/product-spec.md → .harness//product-spec.md if the target does not exist. If it exists from a previous run, keep it — Step 4 resumes in place.

Step 3.5: Foundation Readiness Check

Run .harness/scripts/foundation-readiness.sh --epic before any Planner dispatch. It writes .harness//foundation-readiness.md, emits a JSON summary on stdout, and may set _state.json.foundation_readiness / foundation_sprint_needed.

Use [references/foundation-sprint-guide.md](references/foundation-sprint-guide.md) §Foundation readiness check for the exact JSON schema, severity matrix, RED-path AskUserQuestion options, --auto-approve-roadmap behavior, and state-write timing. Re-runs and --replan use the same flow.

Step 4: Interactive product-spec Drafting (Planner phase=interview)

This is the only conversational Planner phase — a single long session dedicated to the interview. All subsequent phases (roadmap generation, contract drafting, ruling) are dispatched as separate fresh Planner invocations to avoid context bloat.

Invoke the Planner sub-agent with the [planner-interview](references/prompt-templates/planner-interview.md) prompt template (substitute {{EPIC_NAME}}, {{USER_REQUEST}}, {{PROJECT_TYPE}}). Also reference [product-spec-guide.md](references/product-spec-guide.md) for section structure.

The Planner walks the five sections in order — Why, What, Out of Scope, Constraints, Success Signals — asking section-specific AskUserQuestion rounds and writing answers into the matching section of .harness//product-spec.md.

Compact resilience (per Planner role contract): the Planner appends each user response to .harness/progress.md as it collects them, so even if context compaction fires mid-interview, a resume can reconstruct the conversation from progress.md tail + existing product-spec.md draft.

Key enforcement (from the guide):

• Reject "How" leakage (framework / library / schema picks) and redirect

to Constraints only if externally mandated

• Bullet count target for What: 3–7
• Success Signals may be empty; mark success_signals: unspecified in

frontmatter if so

Set _state.json.phase = "product-spec-draft" at step start. Keep it at "product-spec-draft" until the Planner declares the spec complete via the cross-check checklist; the transition out happens when Step 5 begins (phase is advanced to "roadmap-draft" there).

Before moving to Step 5, the Planner runs the cross-check checklist from the guide. Any "no" answer re-opens the relevant section via AskUserQuestion. If the skill was invoked with --auto-approve-roadmap (interview was pre-filled or resumed without user intervention), emit a TODO(product-spec): line to progress.md instead of re-opening — the user must resolve before harness-loop starts.

Commit: git add .harness//product-spec.md && git commit -m "harness-plan: product-spec for ".

Step 5: Planner Generates roadmap.md (fresh Planner, phase=roadmap)

Invoke a new fresh Planner sub-agent (not a continuation of the interview session from Step 4 — that session has already exited). Use the [planner-roadmap](references/prompt-templates/planner-roadmap.md) prompt template (substitute {{EPIC_NAME}}).

Inputs (the fresh Planner reads from disk):

• .harness//product-spec.md (finalized in Step 4)
• [roadmap-guide.md](references/roadmap-guide.md) — decomposition /

bundling doctrine

Output: .harness//roadmap.md with YAML frontmatter listing sprints and bundling flags. See the guide §roadmap.md Output Format for the canonical schema.

The Planner must:

• Emit split by default; bundle only with a written bundling_reason

citing one of the four coupling axes (schema, auth, UI, contract)

• Enforce reciprocal bundled_with references
• Cap sprints at 6 per epic; if more, pause and advise the user to split

the epic. With --auto-approve-roadmap, truncate with a TODO(epic-split) note in progress.md for post-hoc resolution

• Cap bundle size at 3 sprints
• For each sprint, decide generator_backend per the rubric and

AskUserQuestion flow in [roadmap-guide.md §Backend Recommendation](references/roadmap-guide.md) and [planner-roadmap.md prompt template](references/prompt-templates/planner-roadmap.md). The Planner asks the user via AskUserQuestion (interactive mode only) per sprint — options are (Recommended) + (epic default) + remaining enum (deduplicated). In continuous / autonomous-ralph / scheduled mode, the rubric primary is auto-confirmed without prompting (Pre-flight Gates forbid AskUserQuestion). With --auto-approve-roadmap, backend is auto-confirmed regardless of mode (still respects the rubric). Bundle peers share the primary peer's choice — one question per bundle, not per peer. When _config.yml.sprint_level_generator_override == false (legacy compat), skip rubric + AskUserQuestion entirely and write generator_backend: null for every sprint

Set _state.json.phase = "roadmap-draft" at step start.

Step 6: Roadmap Approval

The roadmap approval gate is always interactive. The mode value (interactive / continuous / autonomous-ralph / scheduled) is selected at harness-loop startup, not at harness-init, so harness-plan has no basis for implicit acceptance. The only exception is explicit user override via the --auto-approve-roadmap flag (see §Usage).

Default path (no flag):

AskUserQuestion:
  question: "Roadmap:  sprints,  bundle groups. Approve?" /
            "Roadmap:  sprints,  bundle。承認？"
  (Show Sprint Summary table from roadmap.md as description)
  options:
    - "Approve / 承認"
    - "Request changes / 変更を要求"
    - "Cancel / キャンセル"

• Approve → proceed to Step 7
• Request changes → collect free-form change request via a follow-up

AskUserQuestion; Planner regenerates roadmap.md with the feedback. Loop at most 3 times — after that, abort to Cancel with a note in progress.md

• Cancel → write progress.md line, leave roadmap.md as draft, exit

With --auto-approve-roadmap flag: skip the prompt and proceed to Step 7 directly. Append one progress line recording auto-approval ([] auto-approved via --auto-approve-roadmap). The user takes responsibility for pre-reviewing roadmap.md before invoking this mode.

Set _state.json.phase = "roadmap-approved" on approval (either path).

Commit: git add .harness//roadmap.md && git commit -m "harness-plan: roadmap for ".

Step 7: Draft Sprint Contracts (fresh Planner × N, phase=contract-draft)

For each sprint in roadmap.md.sprints, dispatch one fresh Planner sub-agent using the [planner-contract](references/prompt-templates/planner-contract.md) prompt template. Substitute {{EPIC_NAME}}, {{SPRINT_NUMBER}}, {{SPRINT_FEATURE}}, {{SPRINT_BUNDLING}}, {{SPRINT_BUNDLED_WITH}}, {{SPRINT_GOAL}}, {{RUBRIC_PRESET}}.

Each invocation is independent — no shared context between sprints, each Planner reads only product-spec + roadmap + its own sprint metadata. This is the file-mediated peer-processes discipline the harness series follows throughout.

Parallel execution: Sprints are independent, so dispatch them in parallel if the Task tool supports it. For N sprints the total wall time approaches the slowest single contract-draft time rather than N×. If parallel dispatch fails, fall back to sequential — correctness is identical either way.

Preparation (before dispatching):

1. Create directory .harness//sprints/sprint--/ for

each sprint

1. Copy .harness/templates/shared_state.md into each sprint directory
2. Create empty feedback/ and evidence/ subdirectories in each

sprint directory

Each fresh Planner then writes contract.md into its own sprint directory, following its role contract. Draft fields:

• sprint, feature, bundling, bundled_with (from roadmap)
• goal, acceptance_scenarios (elaborated per sprint)
• rubric with axes selected from rubric-presets.md based on

_config.yml.rubric_preset — but threshold left as ? placeholder

• max_iterations left as ? placeholder
• status: pending-negotiation

The ? placeholders are filled by the Negotiation phase inside harness-loop (Generator ⇄ Evaluator, with Planner ruling as tiebreaker). harness-plan must NOT set threshold / max_iterations values itself.

Step 8: Create Tracker Issues

Set _state.json.phase = "issues-pending" at step start so resume after a mid-loop failure can locate the correct entry point. Dispatch on _config.yml.tracker. Full detail in [issue-create.md](references/issue-create.md):

• github → gh issue create per sprint, with duplicate detection and

epic-link formatting. On every successful create, append to _state.json.sprint_issues[] atomically so resume can skip already-created sprints

• gitlab → record pending payloads to

.harness//pending-issues.md (an epic-level ledger file owned by harness-plan). shared_state.md is sprint-scoped and does not exist yet at this phase — never write there. No CLI call in v1

• none → skip; emit one progress line noting tracker-free mode

gh CLI absence: if tracker == github and gh is missing, abort the skill. Do not silently fall back to gitlab / none — the user's tracker choice is load-bearing for the audit trail.

On failure mid-loop, _state.json.phase stays at "issues-pending" and partial sprint_issues is preserved. Resume re-enters Step 8 and the duplicate-detection path in issue-create.md skips the already-created sprints.

Step 9: Finalize Handoff Cursor in _state.json

Step 8 already transitioned phase to "ready-for-loop" and built up sprint_issues incrementally. Step 9 finalizes the remaining cursor fields that harness-loop reads on its Boot Sequence:

{
  "current_epic": "",
  "current_sprint": 1,
  "phase": "ready-for-loop",
  "iteration": 0,
  "last_agent": "planner",
  "next_action": "harness-loop:negotiate-sprint-1",
  "completed": false,
  "pending_human": false,
  "aborted_reason": null
}

Preserve all other fields written by harness-init (max_iterations, max_wall_time_sec, max_cost_usd, allowed_mcp_servers, etc.). The mode field is not set here — it is written by harness-loop on startup. Use a merge, not a replace, via jq '.foo = "bar"' on the existing file.

Step 10: Summary Report

Emit to the user:

• Epic dir

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: anyoneanderson
• Source: anyoneanderson/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.