plan-phase

name	plan-phase
description	Harness Code phase planner for a versioned roadmap phase. Produces an interface-freeze + swim-lane document for parallel execution. Use in plan mode. Supports --consensus for multi-agent architectural consensus across named Plan teammates.

-plan-phase

Runtime State

For reflections, handoffs, and latest handoff pointers, follow <harness>-config/shared/runtime-state.md. This repo/branch/run-isolated contract supersedes any older flat closeout examples retained for historical context in this skill.

shared/phase-loop/protocol.md is the canonical shared contract for execution-ready plan metadata, including phase_loop_plan_version: 1, roadmap_sha256, optional Dispatch Hints, and downstream roadmap-amendment rules.

When this skill runs through the live phase-loop adapter, the child launch is a non-interactive <harness> -p session and the final response must still include a shared automation: closeout with verification_status. The repo-injected workflow bundle remains authoritative whether the adapter delivers it inline or through the run-local context-file fallback. That repo-owned bundle includes the full Harness workflow pack (<harness>-phase-roadmap-builder, <harness>-plan-phase, <harness>-execute-phase, and <harness>-phase-loop) and does not depend on installed bridge skills under resolve_skill_bundle_root("claude")/.

Phase-Loop Adapter Mode

When the prompt or run-local context file starts with a concrete <harness>-plan-phase <roadmap> <phase> command from .codex/phase-loop/runs/, this adapter mode overrides the delegation-first interactive workflow below.

• Do not read installed handoffs under resolve_skill_bundle_root("claude")/**; the run-local phase-loop context is the only predecessor context.
• Do not call ToolSearch, TaskCreate, TeamCreate, TeamDelete, Agent, SendMessage, ExitPlanMode, advisor(), or AskUserQuestion.
• Resolve the roadmap and phase from the first command line, read only the repo-local roadmap and relevant files, and write the repo-local plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md artifact directly.
• The plan artifact frontmatter is part of the trust contract. roadmap: MUST be the exact repo-relative path from repo root to the roadmap file, not a shortened basename or suffix, and roadmap_sha256: MUST be the SHA-256 of that exact roadmap file.
• Do not read or write ~/.claude/** reflection or handoff files, and do not edit .codex/phase-loop/ runner artifacts. Adapter-mode closeout happens only through stdout plus repo-local artifacts.
• If ambiguity, access, dirty-state, or missing-input handling would normally ask a user, stop and emit a shared automation: closeout with status: blocked, human_required set accurately, the frozen blocker_class, concrete blocker_summary, and verification_status: blocked.
• End stdout with one shared automation: closeout. Do not wait for interactive approval after the artifact is written.

Dispatch Hints

When non-default executor policy is needed, add an optional ## Dispatch Hints section using the frozen vocabulary from shared/phase-loop/protocol.md instead of inventing Harness-only plan metadata.

When model, effort, work-unit defaults, lane-specific policy, fallback, policy source, or override reason must also be frozen, add optional ## Execution Policy using the protocol syntax. Precedence is CLI/operator override, phase-plan policy, roadmap policy, Dispatch Hints, then registry defaults; silent downgrade is forbidden unless explicit fallback or default inheritance is recorded.

Model & Effort Tiering (right-size per lane, don't default to the ceiling)

The runtime resolves one planning model per executor (codex → gpt-5.6-sol, claude → claude-fable-5), so reasoning effort is the primary cost dial. The normalized effort ladder, cheapest first, is:

minimal < low < medium < high < xhigh < max

Registry action defaults today are blunt — plan/roadmap/review = high, execute/repair = medium — applied uniformly regardless of how hard the lane actually is. As the planner you have the complexity signal the runtime lacks; use it:

• Default each lane to the cheapest effort you believe will succeed, not the action default. A mechanical edit, a config bump, a docs-sweep lane, or a rename rarely needs more than low/minimal.
• Escalate only with a stated reason. Subtle concurrency, cross-module refactors, security-sensitive logic, or ambiguous specs justify high/xhigh; record why in the rule's reason=.
• Express the choice in an ## Execution Policy section the runtime parses (selector = default, an action, or a lane alias):

## Execution Policy
- default: effort=low, reason=most lanes are mechanical this phase
- execute: effort=medium
- SL-3: effort=high, reason=constant-time comparison is subtly wrong-prone
- SL-7: effort=minimal, reason=docs sweep only

Two hard syntax rules the parser enforces (a malformed line fails the whole section, not just that line):

• Lane selectors are the numeric lane id (SL-3, P2A → use lane <name>: for non-numeric names). SL-DOCS-style names are rejected; write SL-7 or lane SL-DOCS: ….
• No commas inside a reason= value — the comma separates assignments, so reason=docs sweep, no logic breaks parsing. Keep reasons comma-free.

Operator --model/--effort and CLI overrides still win, so this never blocks a human from forcing a tier. The goal is to stop paying high for a one-line change by default.

Model class (vendor-agnostic role). Alongside effort, a rule may set a model_class — planner / implementer / worker — which resolves to a concrete model per executor. The shipped model_policy already routes planning to the planner class at max and implementation to the implementer class, so you rarely set this by hand; reach for it when a specific lane wants a cheaper worker-class model for a bounded, schema-checked subtask. The worker class must never author a final patch, and an executor that can't run at max (e.g. gemini) is never the max-effort planner of record.

Run mode is separate. model_policy (what model) is independent of run_mode (autonomous default vs opt-in governed review). Planning a phase does not enable the governed panel; that is an operator opt-in.

Planner Literal Validation

Before writing a plan document to the project path, validate the complete draft with phase_loop_runtime.planner_validation.validate_plan_dispatch_hints. In Plan Mode, run this after the scratch draft is fully emitted and before ExitPlanMode; in adapter/default flows, run it before writing plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md. If findings are returned, do not write the plan artifact. Stop with a validation_failed closeout: terminal_status=blocked, verification_status=blocked, blocker_class=contract_bug, human_required=false, and a non-secret blocker_summary listing each finding's field_path, literal, allowed_values, and suggested_fix.

The validator imports its defaults from phase_loop_runtime.models: DISPATCH_CAPABILITIES, EXECUTORS, and PRODUCT_LOOP_ACTIONS. Keep these allowed values inline in the planner prompt so invented literals are visibly out of contract:

• dispatch_hints.required_capabilities: live_launch, dry_run, skill_bundle_injection, inline_instructions, context_file_instructions, manual_handoff, subagents, explicit_approval_controls, structured_output, browser_automation
• dispatch_hints.executors[]: codex, claude, gemini, opencode, pi, command, manual
• ## Execution Policy selectors: work-unit defaults, roadmap, plan, execute, repair, review, maintain-skills, and lane selectors such as SL-2
• terminal_status: unplanned, planned, executing, executed, awaiting_phase_closeout, complete, blocked, unknown
• verification_status: not_run, passed, failed, blocked
• blocker_class: missing_secret, account_or_billing_setup, admin_approval, destructive_operation, ambiguous_roadmap_selection, product_decision_missing, dirty_worktree_conflict, branch_sync_conflict, stalled_child_observation, repeated_verification_failure, sandbox_command_restriction, upstream_phase_unmet, contract_bug, gold_record_amendment, unretryable_external_outage, stuck_loop

Architecture-first planner for a single phase of a multi-phase specification. Produces a plan document containing interface freezes, swim lanes with disjoint file ownership, a lane DAG, per-lane task lists (test → impl → verify), and testable acceptance criteria. Designed to be run in plan mode and handed off to <harness>-execute-phase for parallel execution.

When to use

• The input is a multi-phase spec (e.g., specs/phase-plans-v1.md) and the user wants to plan a specific phase.
• The work touches more than one area of the codebase and would benefit from parallel lane execution.
• You need interface contracts frozen before lanes diverge.

When NOT to use

• Single-file, single-concern change → use /<harness>-plan-detailed instead.
• Pure research / "how does X work" → use Agent(subagent_type: "Explore") directly, no plan doc needed.
• No phase structure in the spec → use /<harness>-plan-detailed or ad-hoc planning.

Inputs

Arg	Required	Meaning
<spec-path>	no	Path to the spec file (relative to repo root). Default: auto-detected specs/phase-plans-v*.md at the highest version.
<phase-name-or-id>	yes	A phase heading, short alias (P1–P7), or any fuzzy match. Ambiguous → stop and ask via AskUserQuestion.
--output <path>	no	Override the default output path. Default: plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md. <PHASE_ALIAS> MUST be uppercase exactly as declared in the roadmap (e.g., FOUND, DESIGNFOUND); lowercase or alternate filename variants force an extra plan-iteration roundtrip because the runner uses the uppercase alias to locate the plan artifact.
--consensus	no	Enable multi-agent architectural consensus (2–3 Plan teammates with different framings).
--review-external	no	After writing the plan doc, run Gemini + Codex CLIs in parallel to review it. Requires gemini and codex installed and authenticated. Produces a _reviews.md sibling file.

Repos may supply a phase alias table (JSON file) via $PLAN_PHASE_ALIASES or fall back to the built-in P1–P7 table. If the alias isn't recognized and no custom table is set, stop and ask via AskUserQuestion with the actual spec headings.

Environment variables

Variable	Default	Meaning
PLAN_SPEC	Auto-detected highest specs/phase-plans-v*.md	Path to the spec file.
PLAN_VERSION	Extracted v\d+ from spec filename	Version string embedded in output filename.
PLAN_PHASE_ALIASES	Built-in alias table	Path to a JSON file mapping alias → phase heading.

Example .env:

PLAN_SPEC=specs/phase-plans-v1.md

Invocation examples:

/<harness>-plan-phase P1
/<harness>-plan-phase P3 --consensus
/<harness>-plan-phase P3 --review-external
/<harness>-plan-phase specs/roadmap.md "Phase 3: Billing" --consensus --review-external

Expected helpers

The skill references these _shared/ helpers. Each degrades gracefully if absent:

• _shared/next_reflection_path.py — legacy helper only; current closeout writes reflections to resolve_skill_bundle_root("codex")/<harness>-plan-phase/reflections/<repo_hash>/<branch_slug>/<run_id>.md.
• _shared/review_with_cli.py — required only for --review-external. No fallback; if absent, surface an AskUserQuestion with [skip review this run, abort].
• _shared/scaffold_docs_catalog.py — used by SL-docs.1. If absent, the docs lane records "docs-catalog rescan helper unavailable; manual catalog audit" in its commit message and proceeds.

Deferred tool preloading

Load tools used later in a single query so mid-workflow calls don't pay a round-trip:

ToolSearch(query: "select:TaskCreate,AskUserQuestion,ExitPlanMode")

Workflow (delegation-first)

The main thread is an orchestrator only: brief specialists, synthesize output, enforce consensus, write the final doc, emit tasks. See ## Teamwork & delegation posture for the posture rules.

Step 0 — Read predecessor handoff (if present)

Handoffs are keyed on the current repo so each workspace has its own slot. Resolve both candidate paths first:

REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
if [ -z "$REPO_ROOT" ]; then
  REPO_KEY="_no-git-$(pwd | sha1sum | cut -c1-12)"
else
  REPO_KEY="$(basename "$REPO_ROOT")-$(printf '%s' "$REPO_ROOT" | sha1sum | cut -c1-12)"
fi
ROADMAP_HANDOFF="$(python3 - <<'PYH'
from pathlib import Path
repo = Path.cwd().resolve()
skill = "<harness>-phase-roadmap-builder"
try:
    # Primary: the installed phase_loop_runtime.skill_paths resolver.
    from phase_loop_runtime.skill_paths import resolve_handoff_root
    print(resolve_handoff_root(repo) / skill / "latest.md")
except Exception:
    # Fallback: the repo-local handoff_path.py mirror, only when the runtime is not importable.
    from importlib import util
    spec = util.spec_from_file_location("handoff_path", repo / "shared" / "phase-loop" / "handoff_path.py")
    mod = util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    print(mod.resolve_handoff_path(repo, skill))
PYH
)"
EXECUTE_HANDOFF="$(python3 - <<'PYH'
from pathlib import Path
repo = Path.cwd().resolve()
skill = "<harness>-execute-phase"
try:
    # Primary: the installed phase_loop_runtime.skill_paths resolver.
    from phase_loop_runtime.skill_paths import resolve_handoff_root
    print(resolve_handoff_root(repo) / skill / "latest.md")
except Exception:
    # Fallback: the repo-local handoff_path.py mirror, only when the runtime is not importable.
    from importlib import util
    spec = util.spec_from_file_location("handoff_path", repo / "shared" / "phase-loop" / "handoff_path.py")
    mod = util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    print(mod.resolve_handoff_path(repo, skill))
PYH
)"

The predecessor skill may be either:

• <harness>-phase-roadmap-builder (first time planning a phase against a new roadmap) → $ROADMAP_HANDOFF
• <harness>-execute-phase (planning the next phase after a prior one finished executing) → $EXECUTE_HANDOFF

Check both paths. If both exist, pick the one with the newer timestamp: in its metadata header. If only one exists, use it. If neither, proceed standalone.

Defense-in-depth checks (the repo-key scheme prevents the common cross-project case, but these still catch symlink-shared workspaces, manual file copies, and stale handoffs):

• from: must match the expected predecessor.
• Timestamp must be recent (<7 days).
• Every artifact: path must resolve under $(git rev-parse --show-toplevel).

On any failure, flag via AskUserQuestion with [use anyway, ignore, abort].

Fold the handoff's "Open items" and "Repo-specific gotchas" into the brief given to Step 2's Explore teammates so they know what to watch for.

Step 1 — Resolve spec path, phase, and PHASE_ID

Spec path resolution (in order):

1. $PLAN_SPEC env var → use verbatim.
2. <spec-path> arg → use verbatim.
3. Glob specs/phase-plans-v*.md; pick the highest version.
4. Else any specs/*.md if exactly one exists → use it and note the assumption.
5. Else stop and ask via AskUserQuestion.

Version string (for output filename): $PLAN_VERSION → pattern v\d+ in filename → v1 default.

Phase alias table: $PLAN_PHASE_ALIASES (JSON file) → built-in table.

Phase name: short alias → fuzzy match → 0 matches: stop + ask → multiple matches: stop + disambiguate.

PHASE_ALIAS: the resolved short alias in lowercase (e.g., p1). If none exists, use phase-<N>.

Output path: --output override, else plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md.

Step 2 — Parallel reconnaissance via Explore teammates

Skip this reconnaissance when the context is already in session. If the files this phase touches have already been read, the architecture was just discussed, or the caller supplied the file map, do not spawn Explore teammates to re-gather what you already have — plan directly from it. Keep reconnaissance proportional: launch one focused Explore per genuinely-unknown area, not a full three-way fan-out for a one- or two-file change.

Preflight: call TeamDelete defensively to flush any inherited team context from a predecessor skill run, then TeamCreate a fresh team named for this run before dispatching any Agent calls. Recognize these error signatures as benign on the TeamDelete: Team X does not exist or already leading team X.

Launch up to 3 Agent(subagent_type: "Explore") calls in a single message. One per major area the phase touches. Each Agent call MUST set name: so it can be re-addressed later via SendMessage.

Teammate-naming template: explore-<area> (e.g., explore-schema, explore-workers).

Each brief must include:

• The phase's Objective + Exit criteria copied verbatim from the spec.
• A scoped question: "Map existing code in <paths> relevant to this phase. Surface: (a) existing utilities/patterns to reuse, (b) current type/schema/interface shapes that constrain the design, (c) places that will need to change, (d) hidden coupling that would break worktree isolation."
• A 1–2 sentence architecture context: how these paths fit the larger system.
• Related files the teammate should know about but not rewrite (type defs, tests, shared config).
• A preload instruction: "Load SendMessage via ToolSearch(query: \"select:SendMessage\") as your first action so you can reply without a round-trip."
• An explicit deliverable statement: "Your deliverable is a SendMessage to team-lead with your findings; do not rely on text output or idle without reporting."
• A length guideline: "Be as short as possible while citing every load-bearing file:line. No fixed word cap."

Apply the /<harness>-task-contextualizer checklist to every brief.

Block until all return. Their findings populate ## Context.

Step 2.5 — Explore teammate recovery

If a teammate idles without a substantive reply, send one targeted SendMessage nudge naming the missing deliverable. On a second non-response, proceed with main-thread read-only reconnaissance rather than respawning the teammate.

Step 3 — Architectural decisions

With --consensus: Launch 2–3 Agent(subagent_type: "Plan") calls in a single message, each with a distinct framing:

Name	Framing
arch-minimal	Minimal change. Preserve current module boundaries. Add, don't refactor.
arch-clean	Clean architecture. Willing to refactor to make the design right.
arch-parallel	Maximize parallelism. Prefer more, smaller lanes over fewer, fatter lanes, even if it adds interface surface.

Each teammate's brief includes: the spec phase section, all Explore teammate findings, and its framing. Apply the /<harness>-task-contextualizer checklist — architecture context and related-files list carry over from the Explore briefs. Each must return: (1) proposed interface freezes, (2) proposed lane decomposition with file ownership, (3) rationale, (4) known risks.

Synthesize per the Consensus mechanism below. If round 1 doesn't converge, re-address the same named teammates via SendMessage (not new Agent calls) with the specific disagreement surfaced. Max 2 rounds.

Without --consensus: Launch 1 Agent(subagent_type: "Plan", name: "arch-baseline") for baseline architecture decisions.

Preamble lane archetype

The "preamble lane" concentrates single-writer files AND freezes interface shapes on Day 1, letting all downstream lanes run in parallel without contending for the same index/config/init file.

When to use: ≥2 parallel lanes would otherwise need to touch the same index/config/init file, OR ≥2 lanes consume the same frozen type.

Template sketch:

### SL-0 — Preamble (interface + single-writer setup)
- **Scope**: Freeze shared types and stub the single-writer files every downstream lane will import from.
- **Owned files**: `src/index.ts`, `src/config.ts`, `src/__init__.py` (list every shared index/config/init file)
- **Interfaces provided**: `FooContract`, `BarRegistry`, `WorkerRouter` (frozen type names)
- **Interfaces consumed**: (none)
- **Parallel-safe**: no (terminal in preamble position — no downstream lane modifies SL-0's files)
- **Tasks**: one test task pinning the frozen type shapes; one impl task adding the stubs; one verify task

Downstream lanes depend on SL-0 and consume its frozen interfaces; they must not list any SL-0 owned file in their own Owned files.

Step 4 — Lane decomposition (main thread)

Synthesize Explore + Plan output into swim lanes. For each lane, determine:

• Scope — one sentence.
• Owned files — glob list. Must be disjoint from every other lane's globs. Before emitting the plan, scan every lane's owned files for overlap with every other lane in the same wave. If overlap is found, either (a) move the shared file into a preamble lane that all dependents consume, or (b) collapse the overlapping lanes into a single lane. Overlap surviving into the final plan triggers overlapping_write_ownership lane-IR diagnostic at runtime and refuses execution (Pattern B from 2026-05-25 runner failure analysis). Owned files MUST enumerate the COMPLETE set the executor will touch — not just headline source files. For every primary file added or modified, include matching test file(s), snapshot file(s), generated artifact(s), .env.example / .env.local.example if env shape changes, package.json + pnpm-lock.yaml (or equivalent) if dependencies change, and migration files matching the timestamp pattern. Under-enumeration causes the closeout's phase_owned_dirty check to fail closed (Pattern A from 2026-05-25 — hit ~70% of phases in that drive).
• Interfaces provided — symbols, types, endpoints, migrations this lane publishes.
• Interfaces consumed — symbols this lane depends on from other lanes.
• Parallel-safe — yes / no / mixed (with explanation if not yes).

Run the Lane validation checklist (below) before proceeding. If it fails, return to Step 3 with the failure noted.

Step 5 — Task authoring (main thread)

For each lane, author an ordered task list:

• One test task (write failing tests for the lane's contracts).
• One or more impl tasks (each depends on the preceding test task).
• One verify task (runs the full test suite for the lane, plus any integration checks).

Tasks are identified <SL-ID>.<N>.

Every phase must include a terminal SL-docs lane after the impl/verify lanes. See ## Docs-sweep lane template below. No opt-out — force a conscious doc decision every phase, even if the lane ends up recording "no cross-cutting changes needed."

Step 6 — Emit per-lane tasks via TaskCreate

Plan-mode note: TaskCreate writes outside the scratch file and is blocked in plan mode. Author the task bodies in-thread during Step 5 so they are ready, but defer the actual TaskCreate invocations until AFTER ExitPlanMode approval (Step 8).

For each lane, emit one TaskCreate:

• Title: <SL-ID> — <lane name>
• Body: Depends on: <upstream SL-IDs>, Blocks: <downstream SL-IDs>, Parallel-safe: <flag>, and the ordered child task list (test / impl / verify).

This makes the lane DAG visible in the user's task pane and becomes the hand-off surface for <harness>-execute-phase.

Step 7 — Write plan doc

Draft the plan in the plan-mode scratch file only. The scratch-file path is given in the plan-mode system reminder — do not guess it. Do NOT write to plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md yet; plan mode forbids writes outside the scratch file. The project-path copy + staging happens in the Close-out "Stage artifact" section after ExitPlanMode approval.

Then validate the scratch draft with validate_plan_dispatch_hints. If it returns findings, stop without writing the project-path artifact and emit the validation_failed closeout described in ## Planner Literal Validation. If scripts/validate_plan_doc.py exists (shell test [ -f scripts/validate_plan_doc.py ]), run it against the scratch file and fix any errors before ExitPlanMode:

python scripts/validate_plan_doc.py <scratch-file-path>

Otherwise walk the Lane validation checklist by hand and note manual verification in the post-approval closeout or Execution Notes. The validator checks required headings, disjoint file ownership, DAG acyclicity, grep-assertion-paired-with-tests, and eager-reexport risks.

Step 7.75 — Advisor review

After the plan doc is drafted in the scratch file and before ExitPlanMode, call advisor(). Expect 1–4 contract-tightening suggestions per run, typically covering: under-specified freezes, asserted-but-unverified file paths, test-outline mechanism gaps, and spec-vs-contract conflicts. Apply the findings to the scratch draft before calling ExitPlanMode.

Step 7.5 — External CLI review (only if --review-external)

Run the shared review script:

python3 "$(git rev-parse --show-toplevel)/.claude/skills/_shared/review_with_cli.py" \
  --artifact plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md \
  --prompt-file "$(git rev-parse --show-toplevel)/.claude/skills/<harness>-plan-phase/assets/review_prompt.md" \
  --out plans/phase-plan-<VERSION>-<PHASE_ALIAS>_reviews.md

If the script reports the frontier-model cache is empty, it prints a discovery prompt to stderr. Surface to the user via AskUserQuestion with options [run discovery now, skip review this run, abort].

Tell the user: "Review written to plans/phase-plan-<VERSION>-<PHASE_ALIAS>_reviews.md. When Gemini and Codex flag the same concern, treat it as real; divergent comments are context, not verdicts."

Step 8 — ExitPlanMode

Call ExitPlanMode. The plan doc is the approval surface. After approval, execute the deferred actions in this order: Close-out "Stage artifact" (writes the project-path plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md and stages it unless forbidden), then Step 6 TaskCreate invocations, then Close-out "Reflection + Handoff".

Plan document template

Use this frontmatter and these headings verbatim — the phase-loop runner trusts the frontmatter before it trusts the plan body:

---
phase_loop_plan_version: 1
phase: <PHASE_ALIAS>
roadmap: <repo-relative roadmap path, e.g. specs/phase-plans-v1.md>
roadmap_sha256: <sha256 of that roadmap file>
---

# <PHASE_ID>: <Phase Name>

## Context
<Synthesized from Explore teammates. What exists, what constrains the design, what will change.>

## Interface Freeze Gates
- [ ] IF-0-<PHASE>-<N> — <one-line description of the frozen interface>
- [ ] IF-0-<PHASE>-<N+1> — …

## Cross-Repo Gates
<Omit entirely if the phase only touches this repo.>
- [ ] IF-XR-<N> — <interface that must be frozen across repo boundaries>

## Lane Index & Dependencies

SL-1 — <lane name>
  Depends on: (none)
  Blocks: SL-3, SL-4
  Parallel-safe: yes

SL-2 — <lane name>
  Depends on: (none)
  Blocks: SL-4
  Parallel-safe: yes

## Lanes

### SL-1 — <lane name>
- **Scope**: <one sentence>
- **Owned files**: `path/one/**`, `path/two/*.ts` (MUST be a single-line inline bullet, comma-separated backticked globs; do NOT use nested sub-bullets — the downstream file-touch auditor expects inline form)
- **Interfaces provided**: `FooContract`, `POST /api/bar`
- **Interfaces consumed**: (none)
- **Tasks**:

| Task ID | Type | Depends on | Files in scope | Tests owned | Test command |
|---|---|---|---|---|---|
| SL-1.1 | test | — | `path/one/__tests__/foo.test.ts` | `FooContract` shape | `pnpm test path/one/__tests__/foo.test.ts` |
| SL-1.2 | impl | SL-1.1 | `path/one/foo.ts` | — | — |
| SL-1.3 | verify | SL-1.2 | `path/one/**` | all SL-1 tests | `pnpm test path/one` |

### SL-2 — <lane name>
…

### SL-docs — Documentation & spec reconciliation

(See `## Docs-sweep lane template` earlier in this skill for the full lane spec. Copy it verbatim and set `Depends on:` to list every other SL-N in this phase.)

## Execution Notes
- <Parallelism caveats, sequencing gotchas, lanes that can't be worktree-isolated (shared migrations, shared generated files), etc.>
- **Single-writer files**: <files multiple lanes might want to touch but only one is allowed to modify — e.g., barrel index files, generated types, nav config, worker router. List the owner lane for each. If a single-writer file is also touched by a later phase, name this phase's owner lane and have them author-at-plan-time any additions the later phase's consumer lanes will need. Re-opening the file from the later phase's lane adds a cross-phase serialization edge that shouldn't exist.>
- **Known destructive changes**: <any deletions a lane legitimately performs, named by file path. If empty, write "none — every lane is purely additive." This is the whitelist <harness>-execute-phase's pre-merge check uses to distinguish legitimate deletions from stale-base accidents.>
- **Expected add/add conflicts**: <if SL-0 preamble stubs a file that a later lane replaces the body of, list the file path here. The orchestrator pre-authorizes `git checkout --theirs <path>` resolution at merge time.>
- **SL-0 re-exports**: <if the preamble adds symbols to an `__init__.py`, specify the `__getattr__` lazy pattern (not top-level imports). Eager re-exports break package load when a later lane drops or renames the symbol.>
- **Worktree naming**: <harness>-execute-phase allocates unique worktree names via `scripts/allocate_worktree_name.sh`. Plan doc does not need to spell out lane worktree paths.
- **Stale-base guidance** (copy verbatim): Lane teammates working in isolated worktrees do not see sibling-lane merges automatically. If a lane finds its worktree base is pre-<first upstream dependency's merge>, it MUST stop and report rather than committing — the orchestrator will re-spawn or rebase. Silent `git reset --hard` or `git checkout HEAD~N -- …` in a stale worktree produces commits that destroy peer-lane work on `--no-ff` merge.
- (If `--consensus` was used) **Architectural choices**: <consensus summary, or unresolved disagreement with dissent recorded>

## Acceptance Criteria
- [ ] EC-<ALIAS>-<N> — proven by `<command / test>`
- [ ] EC-<ALIAS>-<M> — proven by `<command / test>`

## Verification
<Concrete end-to-end commands to run after all lanes merge. pnpm, supabase, curl, playwright, etc.>

ID conventions

ID	Format	Example
PHASE_ID	Spec identifier, else PHASE-<kebab>	PHASE-1-shared-semantics
Lane ID	SL-<N>	SL-3
Task ID	<LANE_ID>.<N>	SL-3.2
Interface freeze	IF-0-<PHASE>-<N>	IF-0-P1-1
Cross-repo freeze	IF-XR-<N>	IF-XR-2

Defaults only — if the spec already uses its own identifiers (e.g., P1-SL-AUTH-01), adopt those verbatim.

Any non-numeric lane alias (e.g., SL-docs) must still appear in the machine-readable ## Lane Index & Dependencies block as SL-<N> for compatibility with downstream audit/validator tooling that expects SL-\d+. Its Depends on: line must be on its own line (not inlined with prose that could regex-match as a dependency). The alias (e.g., SL-docs) remains valid as the author-facing lane heading in ## Lanes.

Task types & dependency rules

Type	Purpose	Rules
test	Write failing tests that pin down the lane's contracts.	Must precede any impl task in the same lane.
impl	Write the code that makes the preceding tests pass.	Must depend on exactly one test task in the same lane.
verify	Run the full lane test suite + any integration checks.	Last task in the lane. Depends on the last impl task.
docs	Update cross-cutting documentation and the docs catalog.	Lives in the terminal SL-docs lane. Depends on every other lane's final verify task.

Docs-sweep lane template

Every phase plan must include this as the final lane. Copy verbatim into the ## Lanes section, adjust Depends on: to list every other SL-N in the phase, and edit the Scope notes if the phase has atypical docs impact.

### SL-docs — Documentation & spec reconciliation

- **Scope**: Refresh the docs catalog, update cross-cutting documentation touched or invalidated by this phase's impl lanes, and append any post-execution amendments to phase specs whose interface freezes turned out wrong.
- **Owned files** (read `.claude/docs-catalog.json` for the authoritative list; a minimum set is below, but the catalog is canonical):
  - Root: `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `MIGRATION.md`, `ARCHITECTURE.md`, `DESIGN.md`, `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`
  - Agent indexes: `llm.txt`, `llms.txt`, `llms-full.txt`
  - Service manifests: `services.json`, `openapi.yaml`/`.yml`/`.json`
  - `docs/**`, `rfcs/**`, `adrs/**`
  - `.claude/docs-catalog.json` (this lane maintains it)
  - The current phase's section of `specs/phase-plans-v<N>.md` (append-only amendments)
  - Any prior `plans/phase-plan-v<N>-<alias>.md` or prior spec phase sections whose contracts this phase invalidated (prior-phase amendments allowed)
- **Interfaces provided**: (none)
- **Interfaces consumed**: (none)
- **Parallel-safe**: no (terminal)
- **Depends on**: every other `SL-N` in this phase

**Tasks**:

| Task ID | Type | Depends on | Files in scope | Action |
|---|---|---|---|---|
| SL-docs.1 | docs | — | `.claude/docs-catalog.json` | Rescan: `python3 "$(git rev-parse --show-toplevel)/.claude/skills/_shared/scaffold_docs_catalog.py" --rescan`. Picks up any new doc files created by impl lanes; preserves `touched_by_phases` history. |
| SL-docs.2 | docs | SL-docs.1 | per catalog | For each file in the catalog, decide: does this phase's work change it? If yes, update the file and append the current phase alias to its `touched_by_phases`. If no, leave it. Record in commit message any files intentionally skipped. |
| SL-docs.3 | docs | SL-docs.2 | `specs/phase-plans-v<N>.md`, prior plans | Append `### Post-execution amendments` subsections to any phase section (current or prior) whose interface freeze was empirically wrong this run. Named freeze IDs + dated correction. |
| SL-docs.4 | verify | SL-docs.3 | — | Run any repo doc linters (`markdownlint`, `vale`, `prettier --check`, Mermaid/PlantUML render check). If none configured, no-op. |

No opt-out. A phase with nothing to change still runs SL-docs and records that explicitly in its commit message — the audit trail.

Consensus mechanism (synthesis rule)

Applied by the main thread after --consensus Step 3a:

1. Unanimous across all teammates → accept directly.
2. Majority (2 of 3) → accept the majority view; record the dissenting view under ## Execution Notes > Architectural choices > Dissent.
3. No majority → re-address the same named teammates via SendMessage with the specific conflict surfaced. Max 1 additional round.
4. Still no convergence → main thread picks (biased toward arch-parallel for this skill's purpose) and records the full disagreement under ## Execution Notes > Unresolved architectural disagreements.

Lane validation checklist

Before writing the plan doc, verify:

• Disjoint file ownership — no two lanes' Owned files globs intersect. For generated files, call out shared-generated status in Execution Notes.
• Owned files is inline, one line — no nested bullets; comma-separated backticked concrete paths/globs only. Do not use prose entries such as "callsite wiring", "new migration file", "or equivalent", or "additions to"; resolve those to actual files before writing the plan.
• DAG has no cycles — a topological sort of Depends on: succeeds.
• Every impl task has a preceding test task in the same lane.
• Every acceptance criterion is a testable assertion, not prose. "Users can log in" is not testable; "POST /api/auth returns 200 with a valid session cookie for a registered user" is. validate_plan_doc.py WARNs (check K) on a criterion that names no command/path/assertion.
• Reference the roadmap goal ID, don't restate it. When the anchored roadmap phase declares EC-<ALIAS>-<N> exit-criterion IDs, author each acceptance item as - [ ] EC-<ALIAS>-<N> — proven by <command> — reference the goal by ID (the roadmap exit-criterion is the single source of truth) rather than restating the goal text, so validation always checks the plan against the original goal and a plan can never silently weaken it. Every declared EC-ID should be referenced by ≥1 acceptance item (runtime goal-coverage + validate_plan_doc.py check P). Write the ID as plain text at the item's start — - [ ] EC-<ALIAS>-<N> — … — never backticked or bolded (`EC-…`/**EC-…** are not recognized as leading refs), and copy the alias verbatim from the roadmap (a case- or digit-drifted EC-p1-1 reads as a dangling ref). One item may reference several IDs when a single command proves them: - [ ] EC-<ALIAS>-1, EC-<ALIAS>-2 — proven by \``. Plan-internal done-conditions (no EC-ref) stay allowed. If the phase declares no EC-IDs (legacy), author testable assertions as before.
• Each acceptance criterion names the command that proves it. The definition of done (canonical term: acceptance_criteria) and the ## Verification commands are one contract, not two parallel lists — cite the proving command (or test file) in or beside each - [ ] item so done is mechanically checkable.
• Grep assertions are paired with tests. Any acceptance criterion using rg or grep as its sole check must also cite a test file — grep alone is defeated by renaming a symbol to pass the regex.
• UI changes get a visual check. When any lane owns UI/visual files (*.tsx/*.jsx/*.vue/*.svelte, *.css/*.scss, components/**), ## Verification must include a browser/screenshot step (Playwright-via-PMCP or claude-in-chrome) and at least one acceptance criterion phrased as a visually observable outcome. validate_plan_doc.py WARNs (check L) when UI files change but Verification names no browser step.
• Interface freeze gates are concrete — name the symbol/endpoint/migration, not a vibe.
• Stale-base resilience — for each lane that isn't a DAG root, list every upstream symbol, migration number, or file path it reads under Interfaces consumed. This gives <harness>-execute-phase evidence to verify the base wasn't stale and narrows the blast radius of a mis-based commit. Execution Notes must call out "if lane teammate finds its worktree base is pre-, stop and report — do not rebase silently."
• Synthesis lanes are explicit reducers — any lane that writes a docs summary, truth table, readiness matrix, release summary, or other synthesized artifact lists every producer lane under Depends on and every consumed finding under Interfaces consumed. Mark these lanes Parallel-safe: no.
• No completion-order assumptions — the plan never relies on lane numbering, prose ordering, or "last lane" wording to sequence final artifact writes; the DAG is the only sequencing mechanism.
• Cross-lane file deletions called out — if any lane legitimately deletes a file that another lane produces (rare but real: a lane replacing a stub), record it under Execution Notes' "Known destructive changes" block.
• Expected add/add conflicts declared — if SL-0 preamble stubs a file that a lane replaces, add it under Execution Notes' "Expected add/add conflicts" block.
• SL-0 re-exports use __getattr__ lazy form — declared under Execution Notes' "SL-0 re-exports" block.
• Plan doc passes validate_plan_doc.py — run the validator and confirm zero errors before calling ExitPlanMode. The validator catches structural issues (missing headings, duplicate lane IDs, malformed task tables) that manual review misses.
• Terminal SL-docs lane present — every phase plan must include the docs-sweep lane from ## Docs-sweep lane template. Depends on: lists every other lane in the phase. No opt-out; a phase with no doc changes still runs the lane and records that.

Teamwork & delegation posture

• Main thread = orchestrator only. Brief, synthesize, write, emit. Do not Grep/Read the codebase directly during Steps 2–5. If you find yourself doing so, the teammate's brief was incomplete — re-brief via SendMessage.
• Parallel-by-default. Step 2 (Explore) and Step 3a (consensus Plan) MUST be issued as a single message with multiple Agent tool calls.
• Name every teammate. Set name: on every Agent call so you can re-address via SendMessage without losing context or paying to restart.
• Task list as source of truth for the lane DAG. Step 6's per-lane TaskCreate is how the plan becomes actionable; each lane task is addressable by ID for <harness>-execute-phase.
• Hand-off to <harness>-execute-phase. After ExitPlanMode approval, invoke /<harness>-execute-phase <plan-doc-path>. See that skill for the full execution contract (team creation, worktree isolation, merge policy). Do NOT pass isolation: "worktree" alongside team_name — the harness drops isolation in that combination.
• Manual hand-off (when <harness>-execute-phase is unavailable). Run python scripts/validate_plan_doc.py <plan-doc-path> first. Then execute each lane in one of two ways:
  • (a) Standalone — Agent(isolation: "worktree", name: "<SL-ID>", subagent_type: "general-purpose") without team_name. The isolation kwarg is honored in this form; loses team coordination.
  • (b) Teamed — TeamCreate + Agent(team_name=…, name="<SL-ID>", subagent_type="general-purpose"), and the teammate's first tool call is EnterWorktree (load via ToolSearch(query="select:EnterWorktree")). Worktree via tool, team coordination preserved.

Output contract

After ExitPlanMode approval, three artifacts exist:

1. plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md — committable, valid markdown, all headings present.
2. The plan-mode scratch file — identical contents.
3. One TaskCreate'd top-level task per lane, each with test / impl / verify children, containing Depends on: / Blocks: / Parallel-safe: metadata in the body.

Those three are the full hand-off surface — everything downstream (manual lane execution or <harness>-execute-phase) reads from them.

Close-out — Stage artifact (preservation guarantee)

After ExitPlanMode is approved, before exiting:

1. Verify frontmatter before staging:
   • phase_loop_plan_version: 1
   • phase: <PHASE_ALIAS>
   • roadmap: <repo-relative roadmap path from repo root>
   • roadmap_sha256: <sha256 of that roadmap file>
2. Run validate_plan_dispatch_hints before copying or staging the project-path artifact; stop with the validation_failed closeout if it returns findings.
3. Run python scripts/validate_plan_doc.py plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md when the script is present; fix any frontmatter/path/hash failures before continuing.
4. Run git status --short -- plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md and include the _reviews.md sibling if --review-external produced one.
5. If the plan or review artifact is untracked or modified and the user did not explicitly forbid staging, run git add plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md plus the review sibling if present.
6. Rerun git status --short -- plans/phase-plan-<VERSION>-<PHASE_ALIAS>.md and report Artifact state: staged|tracked|modified|unstaged|blocked.
7. Do not commit unless the user explicitly asked for a commit.

When the generated plan is ready to execute, set Next phase: <PHASE_ALIAS> - execution ready and Next command: /<harness>-execute-phase <PHASE_ALIAS>. If execution should not start yet, set Next phase: <PHASE_ALIAS> - blocked: <reason> and Next command: none - <reason>.

Close-out — Reflection + Handoff

After artifacts are staged or confirmed tracked, resolve paths. Treat _shared/next_reflection_path.py as optional-if-present: check existence, use it when available, otherwise fall back to an inline date-based filename.

REFLECTION_PATH=resolve_skill_bundle_root("codex")/<harness>-plan-phase/reflections/<repo_hash>/<branch_slug>/<run_id>.md
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
REPO_LOCAL_HANDOFF=$(python3 - <<'PYH'
from pathlib import Path
repo = Path.cwd().resolve()
skill = "<harness>-plan-phase"
try:
    # Primary: the installed phase_loop_runtime.skill_paths resolver.
    from phase_loop_runtime.skill_paths import resolve_handoff_root
    print(resolve_handoff_root(repo) / skill / "latest.md")
except Exception:
    # Fallback: the repo-local handoff_path.py mirror, only when the runtime is not importable.
    from importlib import util
    spec = util.spec_from_file_location("handoff_path", repo / "shared" / "phase-loop" / "handoff_path.py")
    mod = util.module_from_spec(spec)
    spec.loader.exec_module(mod)
    print(mod.resolve_handoff_path(repo, skill))
PYH
)
mkdir -p "$(dirname "$REPO_LOCAL_HANDOFF")"
SKILL_MD=resolve_skill_bundle_root("codex")/<harness>-plan-phase/SKILL.md

Primary path: the orchestrator writes BOTH files directly with the Write tool. Before writing either file, ensure the plan doc has been staged in the preceding Close-out "Stage artifact" section unless the user explicitly forbade staging.

FILE 1 — REPO-AGNOSTIC reflection → <REFLECTION_PATH>:

# <harness>-plan-phase reflection — <ISO timestamp>

## Run context
- Skill: <harness>-plan-phase
- Timestamp: <ISO timestamp>
- Repo: <repo>
- Branch: <branch>
- Commit: <commit>
- Artifact: <artifact path if any, or none>

## What worked
- <bullet, about the SKILL's instructions>

## What didn't
- <bullet, about friction or gaps in the SKILL's instructions>

## Improvements to SKILL.md
- <specific, actionable change to the instructions>

Do NOT reference this project, codebase, filenames, or domain in FILE 1. Feedback is about how the skill's instructions performed, for a future meta-skill that digests reflections across runs.

FILE 2 — REPO-SPECIFIC handoff → <REPO_LOCAL_HANDOFF> (per-repo slot; overwrites any prior handoff from this skill in the same repo):

<!--
  Consumer validation — before acting on this handoff:
  1. Verify `from:` matches the expected predecessor skill.
  2. Verify `timestamp:` is within the last 7 days.
  3. Verify every `artifact:` path resolves under your current
     `$(git rev-parse --show-toplevel)`. If any path points to a
     different repo, stop and surface it to the user — the handoff
     was written against a different workspace.
-->
---
from: <harness>-plan-phase
timestamp: <ISO>
artifact: <absolute path to plan doc + reviews if any>
artifact_state: <staged|tracked|modified|unstaged|blocked>
next_skill: <<harness>-execute-phase|none>
next_command: </<harness>-execute-phase PHASE_ALIAS|none - reason>
next_phase: <PHASE_ALIAS - execution ready|PHASE_ALIAS - blocked: reason>
---

# Handoff for <harness>-execute-phase

## Summary
<2-3 sentences: phase planned, lanes count, plan doc path.>

## Key decisions made this run
- <numbered, one line each — lane boundaries, IF-freeze signatures, consensus outcomes if --consensus was used>

## Open items for <harness>-execute-phase
- <concrete — e.g., "SL-2 depends on SL-1's StoreRegistry.get signature; ensure lane ordering in dispatch">

## Repo-specific gotchas surfaced
- <quirks of THIS codebase discovered during planning>

## Planning artifacts staged this run
- <path> @ <artifact_state>

## Execute-phase's likely scope
- <file globs from Owned files across lanes>

Optional alternative: when fresh-context independent review is desired, the orchestrator MAY instead spawn ONE close-out agent using the frontier tier with the prompt below. Use this only when the orchestrator wants a clean-context review of the transcript before writing.

Agent(
  subagent_type: "general-purpose",
  model: "<frontier-model-id>",
  name: "<harness>-plan-phase-closeout",
  prompt: """
    Review the skill at <SKILL_MD> and the current execution transcript.
    Produce the two files above (same schemas) via the Write tool to
    <REFLECTION_PATH> and <REPO_LOCAL_HANDOFF>.
  """
)

After the files are written, print to the user:

Plan written to <plan-doc-path>. Reflection saved to <REFLECTION_PATH>. Handoff written to <REPO_LOCAL_HANDOFF>.

Recommended next step: run /clear to reset your context window, then invoke /<harness>-execute-phase <alias>. The next skill reads the handoff automatically.

Use phase_loop_runtime.skill_paths resolver helpers for harness skill roots, handoff roots, helper roots, and reflection roots.

Spec Closeout Plan

Generated phase plans must include a machine-readable section:

## Spec Closeout Plan
- schema: `spec_delta_closeout.v1`
- decision: `<one of no_spec_delta, roadmap_amendment, canonical_spec_update, governed_pipeline_refresh, mirror_cutover_required, dotfiles_skill_source_update, human_source_judgment_required>`
- target surfaces: `<repo-relative paths or globs>`
- evidence paths: `<repo-relative metadata-only artifacts>`
- redaction posture: `metadata_only`
- downstream handling: `<none, roadmap amendment, Governed Pipeline refresh, mirror cutover, or human source judgment>`

Validate that the decision literal is in vocabulary, target surfaces and evidence paths are present, and redaction posture is metadata_only. Missing, malformed, or out-of-vocabulary spec-closeout sections are repairable contract_bug blockers unless the plan explicitly requires human_source_judgment_required. This section must preserve the allowed ## Execution Policy selector vocabulary and must not invent new Dispatch Hints selectors. Reducer and verification lanes keep the existing work-unit=phase_reducer and work-unit=phase_verify policy literals.

Verification Contract

Generated plans must contain machine-checkable verification commands and an effective automation.suite_command; phase plans must validate those commands through IF-0-VC-2 before they are handoff-ready. If an acceptance item depends on operational evidence that cannot be machine-checked directly, the plan must name the operational evidence artifact and the runner-stamped amendment mechanism that records it. proxy evidence requires a roadmap amendment before downstream plans rely on it.

Closeout

Manifest write

After the plan artifact and repo-local handoff path are known, perform a best-effort plan-manifest append through phase_loop_runtime.plan_manifest.append_entry. Append a type=phase entry with status=committed, slug, file, created_at, owner_skill=<harness>-plan-phase, handoff_ref, roadmap_ref, phase_alias, if_gates_produced, and lanes. Resolve paths with phase_loop_runtime.skill_paths helpers and keep the manifest write best-effort during the dual-mode window: failures are non-fatal, emit a ledger warning, and are mentioned in the mandatory reflection without changing the existing plan closeout result. A legacy plans/manifest.json using the schema/entries layout raises unsupported manifest schema_version: 0; treat that exact error as the expected non-fatal case (warn, do not block or migrate in place). phase_loop_runtime may resolve from the installed dotfiles runtime on PYTHONPATH even when the target repo neither vendors nor installs it — use the importable package; a missing repo-local checkout is not a blocker.

Closeout payload shape is defined by EmitPhaseCloseout in phase_loop_runtime/baml_src/emit_phase_closeout.baml (if that path is absent in the checkout, use the operator/prompt-supplied field contract or the installed phase_loop_runtime package — the missing vendored BAML source is not a blocker); keep skill text focused on value selection and handoff routing, not duplicated field ceremony.

Before final response, write a reflection for every non-trivial run. Write it to resolve_skill_bundle_root("codex")/<harness>-plan-phase/reflections/<repo_hash>/<branch_slug>/<run_id>.md. The reflection must include ## Run context with skill name, ISO timestamp, repo, branch, commit, and artifact path if any, followed by ## What worked, ## What didn't, and ## Improvements to SKILL.md. skip only when no artifact was produced AND no decision was made AND the run was pure inspection.