plan-proposal

plan-proposal

Orchestrates the planning phase of an OpenSpec change on develop. Composes existing skills — it does not reimplement them. Twin of ship-it, which owns the implementation phase inside the worktree. The two split at the git-worktree boundary, which is also the interactive/headless line.

flowchart LR
  subgraph Planning ["PLANNING — develop, human present"]
    A["new/ff/continue"] --> B["doubt-review"]
    B --> C["scenario-design + category-fold + manifest"]
    C --> D["plan-proposal (this skill)"]
  end
  D -->|"boundary: commit + spawn worktree"| E["ship-it"]
  subgraph Implementation ["IMPLEMENTATION — worktree"]
    E
  end

Hard constraint — main session only (never a subagent)

plan-proposal MUST run in the main interactive session. It invokes doubt-driven-review (which spawns a fresh-context reviewer, and a second cross-model reviewer — automatically when a @propose-review-N role resolves, offered interactively only when none does; nested subagent spawn is blocked) and scenario-design (whose proposal/design-stage HARD gate calls ask_user). Both need a live main session.

Guard: if you detect you are running inside a subagent context (nested reviewer spawn would be blocked, or ask_user is unavailable), STOP and surface: "plan-proposal must run in the main session — doubt-review and the scenario-design gate cannot run nested. Re-invoke from the main session on develop." Do not degrade the doubt-review to a self-questioning fallback.

Preconditions

• On the develop branch (planning happens on develop; the worktree is spawned from the planning commit).
• openspec CLI available; resolve the change name from --change <name>, the conversation, or openspec list --json (ask if ambiguous).
• Announce: "Planning change: <change> (override with /plan-proposal <other>)."

Procedure

1. Ensure planning artifacts exist

Bring the change to a drafted state using the existing generated skills — do not hand-roll the directory:

• No change dir yet → openspec-new-change (or -ff for the fast path).
• Partial artifacts → openspec-continue-change.

State in the drafting request: "plan-proposal is driving this change". The openspec/config.yaml rules.tasks rule sees it and skips its "Run plan-proposal now?" confirm (no re-entry). rules.proposal may still offer pending mockups while proposal.md is written — that is expected; Step 1b only re-offers rows not declined.

Artifacts live at openspec/changes/<change>/: proposal.md, design.md (when the change warrants one), specs/**/spec.md, tasks.md.

Cite code claims in design.md. Instruct the author to cite the path (and :line when the statement is line-specific) for every statement in design.md about existing code behaviour — e.g. packages/server/src/pi-core-checker.ts:42. Not gated: a citation makes a wrong-file or "does not exist" claim cheap to spot before review.

1b. Adopt pending mockups (idempotent backstop)

Backstop for direct entry, -continue on an existing proposal, re-runs, and SHIP_IT_BLOCKED hand-backs. Runs after the artifacts exist, before doubt-review, so reviewers and scenario-design see the mockup at its final path.

1. Collect every root mockups/AGENTS.md row whose Purpose cell ends with Pending change: <intent>, minus rows that also carry See change: (owned by a change — never offered), minus rows already declined in this session (including a decline in the rules.proposal multiselect during Step 1).
2. None left → ask nothing, change nothing, go to Step 2.
3. Otherwise ONE ask_user multiselect offering every remaining row; the user matches, you do not judge similarity. Unchosen rows count as declined. Live-component mocks (entry dir with mock.tsx) follow their decision.json: run node packages/mockup-loop/src/mock-site/cli.mjs adoptable and offer its options in order with their labels (entry, intent, status) — accepted first (accepted), open / malformed (open) — and never offer its skipped (rejected) entries; report them, and every warnings line (malformed decision files). With only rejected live mocks pending, ask nothing and move nothing.
4. Adopt each chosen entry with the mechanics of the explore-mockup-adoption requirement (canonical, same as rules.proposal): File cell must resolve to an entry directly under mockups/ (else skip + report); mkdir -p <changeDir>/mockups; refuse if <changeDir>/mockups/<entry> already exists; git mv (tracked) / mv (untracked), never copy — a live mock dir moves as ONE unit via node packages/mockup-loop/src/mock-site/cli.mjs move mockups/<entry> <changeDir>, untracked decision.json included, and a source dir left behind is a failed move; only after a successful move — recompute outward relative links, remove the row, add Mockup: mockups/<entry> (in this change) under What Changes in proposal.md. A failed move keeps its row.

An edited proposal.md is "modified in this session" → Step 2 reviews it.

2. Doubt-review proposal.md + design.md (trigger: drafted or modified)

Whenever proposal.md or design.md is created or changed in this session, invoke doubt-driven-review on the changed artifact:

• Pass ARTIFACT + CONTRACT only — never the CLAIM, never your reasoning.
  • ARTIFACT = the proposal/design prose (decompose if large per doubt-review).
  • CONTRACT = the requirements/constraints the artifact must satisfy (the specs deltas, the non-goals, the invariants it asserts).
• Run the spec-collateral scan before each doubt-review cycle (the artifact changes between cycles): node scripts/spec-collateral.mjs --change <change>. Append its output to the CONTRACT under the heading "Candidate conflicting requirements (advisory scan) — check each". The candidates are facts about the corpus, not the CLAIM. If the scan cannot run or exits non-zero, report the failure and proceed with the cycle without candidates — the scan never blocks planning.
• Reviewer prompt hygiene — the reviewer verifies claims against the repository, writes unverified for any claim it cannot check instead of asserting it, and reports every listed candidate the artifact contradicts. A contradicted candidate is resolved by a MODIFIED/REMOVED delta or an artifact correction; "unaffected" is reserved for a verified false positive.
• Cross-model review — runs automatically when a @propose-review-N role resolves; surface the interactive cross-model offer only when none does.
• Reconcile every finding against the artifact text using doubt-review's precedence (contract-misread → actionable → trade-off → noise). When a finding is valid + actionable, PAUSE: the artifact is corrected before proceeding.

Do not fold scenarios until the doubt cycle reaches a stop condition (trivial findings, 3 cycles, or explicit "ship it").

3. scenario-design → category-routed fold into tasks.md (MANDATORY — never skip)

scenario-design is a required step, not an option. A change never reaches the worktree boundary without a test-plan.md manifest and its automated rows folded into tasks.md. Do not hand-author test tasks, infer scenarios from the proposal, or skip straight to the commit — always drive the tasks from the scenario-design output. Smoke-test-only tasks.md is a planning failure.

Run scenario-design for the change (proposal/design stage → HARD gate; it may ask_user and STOP on a spec gap — that is expected, answer and continue). It writes openspec/changes/<change>/test-plan.md — the manifest, carrying a level + disposition (automated | manual-only) per scenario row. If test-plan.md does not exist after this step, scenario-design did not run — re-invoke it before folding.

Then fold each row into tasks.md:

• automated rows → one vanilla - [ ] task each, routed to its category:

  manifest level	home	check-first (reuse infra)
  L1	packages/*/**/__tests__/*.test.ts (vitest)	sibling *.test.ts
  L2	qa/tests/*.sh | *.ps1	existing qa test for that OS
  L3	tests/e2e/*.spec.ts (docker harness)	existing spec for that surface
  electron	ci-electron.yml / _electron-build.yml	existing electron job
  ci	ci.yml / workflow-level	existing workflow assertion

  Before tasking new infra, scan for an existing test of that type to extend. Each folded test task MUST carry:

  1. a harness-exemplar pointer — the nearest existing spec/test of that category to copy harness glue from (e.g. see tests/e2e/reconnect.spec.ts). Bare "author X.spec.ts" tasks are forbidden — ship-it resolves the exemplar path into the task context it hands apply.
  2. the scenario Triple (input · trigger · observable) as plain text.
  3. a manifest reference as ordinary prose — either (test-plan #<id>) or an inline (test-plan: automated) — so ship-it/ship-change can map it back.

• manual-only rows → a plain manual task tagged (test-plan: manual-only); no test is folded. ship-change defers these post-merge (its manifest-aware defer rule).

Post-fold re-scan (before Step 4): folded tasks can introduce identifiers the doubt cycles never saw, so run node scripts/spec-collateral.mjs --change <change> once more after the fold and report every candidate not seen in the doubt-review cycles. A real conflict among them returns planning to Step 2; a contradicted candidate is resolved by a delta or an artifact correction — "unaffected" only for a verified false positive.

Fold-completeness gate (before Step 4): every automated row in test-plan.md MUST map to exactly one folded test task in tasks.md, and every manual-only row MUST map to one tagged manual task. Verify the count matches the manifest — if any scenario row has no corresponding task, the fold is incomplete; finish it before committing. Do not proceed to the boundary with an unfolded manifest.

Parser-safety (load-bearing): tasks.md MUST stay vanilla checkbox format. No custom token, no bracketed tag, no non-standard syntax on a task line — only - [ ] <text> where the manifest reference is ordinary prose. openspec status --json and the generated apply skill parse this file; a stray token could break them. Verify openspec status --change <change> --json reports the same task counts after folding as the plain checkboxes imply.

4. Commit planning artifacts + stop at the worktree boundary

Precondition: test-plan.md exists and the fold-completeness gate passed. Never commit without the manifest — a missing test-plan.md means Step 3 was skipped; go back and run scenario-design.

Commit proposal.md, design.md, specs/**, tasks.md, and test-plan.md to develop — plus dependencies.yaml when the change has one (the worktree and ship-it's dependency gate read it), plus the change's mockups/** whenever it exists (adopted or written there directly), and, when mockups were adopted, the adoption's root-side edits (mockups/AGENTS.md, the renamed-away sources), so the worktree ship-it builds in carries the mockup. The worktree is spawned from that commit via the existing worktree flow (dashboard "start work" / git worktree add).

Then STOP. plan-proposal does not enter the implementation phase. Report:

Planning complete for <change>. Artifacts committed to develop; worktree ready. Automated scenarios folded to tasks (manifest dispositions in test-plan.md). Next: run ship-it inside the worktree to build + ship. If a design issue surfaces during build, ship-it writes SHIP_IT_BLOCKED.md and hands back here.

Situation brief for ask_user

Every ask_user call this skill makes MUST carry a self-contained situation brief in its message — at least 240 characters (the dashboard's questions.minBriefChars default; shorter and the server generates a brief with the @fast model instead). The answer may be given from the global question stack by someone who has not seen this chat. State, in 2–4 lines:

1. Task — what change/step is in progress.
2. Why asking — what was found or blocked that needs a human.
3. Per-option outcome — what each option leads to (skip for free-text inputs).

A bare question ("Resume or hand back?") is never enough. See change: add-pending-question-stack.

Guardrails

• Main session only — refuse and surface if nested (see Hard constraint).
• Adopt pending mockups only via ask_user (Step 1b) — never move a mockup unasked, never re-offer a row declined this session, never copy.
• Never pass the CLAIM to the reviewer; ARTIFACT + CONTRACT only.
• Never fold before reconciling actionable doubt-review findings.
• tasks.md stays vanilla — the manifest (test-plan.md), not a task tag, is the automated-vs-manual source of truth.
• scenario-design is mandatory — no test-plan.md, no commit. Never hand-author test tasks or skip scenario design; the manifest is the sole source of the folded test tasks.
• Fold every manifest row — the boundary is blocked until every automated and manual-only row maps to a task.
• Never author test/app code here — folding writes tasks; ship-it authors the tests. This skill plans; it does not implement.
• Stop at the boundary — do not continue into implementation.

Composed skills

openspec-new-change / -ff / -continue · doubt-driven-review · scenario-design (+ its test-plan.md manifest) · handoff to ship-it.