跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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 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.

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:

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

    manifest levelhomecheck-first (reuse infra)
    L1packages/*/**/__tests__/*.test.ts (vitest)sibling *.test.ts
    L2qa/tests/*.sh | *.ps1existing qa test for that OS
    L3tests/e2e/*.spec.ts (docker harness)existing spec for that surface
    electronci-electron.yml / _electron-build.ymlexisting electron job
    cici.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:

    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 mani

阅读完整来源 ↗