plan-proposal
Develop-side planning orchestrator for an OpenSpec change: artifact creation → doubt-driven-review → scenario-design → fold of automated scenarios into tasks.md, then STOPS at the git-worktree boundary. Main interactive session only; never a subagent. Triggers: "plan this change", "draft the proposal and plan", "scaffold + review + fold", "prep a change for building".
BlackBeltTechnology · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal技能说明
name: plan-proposal description: 'Develop-side planning orchestrator for an OpenSpec change: artifact creation → doubt-driven-review → scenario-design → fold of automated scenarios into tasks.md, then STOPS at the git-worktree boundary. Main interactive session only; never a subagent. Triggers: "plan this change", "draft the proposal and plan", "scaffold + review + fold", "prep a change for building".' metadata: version: "1.0" scope: project
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 interactively a
second cross-model reviewer — 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
developbranch (planning happens on develop; the worktree is spawned from the planning commit). openspecCLI available; resolve the change name from--change <name>, the conversation, oropenspec 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-fffor the fast path). - Partial artifacts →
openspec-continue-change.
Artifacts live at openspec/changes/<change>/: proposal.md, design.md (when
the change warrants one), specs/**/spec.md, tasks.md.
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).
- Surface the cross-model offer — this is an interactive session, so the offer is mandatory (doubt-review Step 3 "always offer, never silently skip").
- 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:
-
automatedrows → one vanilla- [ ]task each, routed to its category:manifest levelhome check-first (reuse infra) L1 packages/*/**/__tests__/*.test.ts(vitest)sibling *.test.tsL2 qa/tests/*.sh|*.ps1existing qa test for that OS L3 tests/e2e/*.spec.ts(docker harness)existing spec for that surface electron ci-electron.yml/_electron-build.ymlexisting electron job ci ci.yml/ workflow-levelexisting workflow assertion Before tasking new infra, scan for an existing test of that type to extend. Each folded test task MUST carry:
- 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-itresolves the exemplar path into the task context it handsapply. - the scenario Triple (
input · trigger · observable) as plain text. - a manifest reference as ordinary prose — either
(test-plan #<id>)or an inline(test-plan: automated)— soship-it/ship-changecan map it back.
- a harness-exemplar pointer — the nearest existing spec/test of that
category to copy harness glue from (e.g.
-
manual-onlyrows → a plain manual task tagged(test-plan: manual-only); no test is folded.ship-changedefers these post-merge (its mani