- name
SKILL.md
Le fichier du skill reste dans le dépôt de l'éditeur.
Collez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a cursor -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a claude-code -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a codex -yCollez la commande copiée dans un terminal. Elle installe ce SKILL.md dans cet agent.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a grok -yEnvoyez le message copié dans un chat Grok Bot. Le Bot récupère ce SKILL.md sur GitHub et l'ajoute aux skills que partagent tous vos Bots.
Install this skill: https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/HEAD/.pi/skills/plan-proposalDe l'éditeur
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
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.
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).<change> (override with /plan-proposal <other>)."Bring the change to a drafted state using the existing generated skills — do not hand-roll the directory:
openspec-new-change (or -ff for the fast path).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.
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.
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).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.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.
Whenever proposal.md or design.md is created or changed in this session,
invoke doubt-driven-review on the changed artifact:
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.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.@propose-review-N role
resolves; surface the interactive cross-model offer only when none does.Do not fold scenarios until the doubt cycle reaches a stop condition (trivial findings, 3 cycles, or explicit "ship it").
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:
Before tasking new infra, scan for an existing test of that type to extend. Each folded test task MUST carry:
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.input · trigger · observable) as plain text.(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.
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 todevelop; worktree ready. Automated scenarios folded to tasks (manifest dispositions intest-plan.md). Next: runship-itinside the worktree to build + ship. If a design issue surfaces during build,ship-itwritesSHIP_IT_BLOCKED.mdand hands back here.
ask_userEvery 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:
A bare question ("Resume or hand back?") is never enough. See change:
add-pending-question-stack.
ask_user (Step 1b) — never move a mockup
unasked, never re-offer a row declined this session, never copy.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.automated
and manual-only row maps to a task.ship-it authors
the tests. This skill plans; it does not implement.openspec-new-change / -ff / -continue · doubt-driven-review ·
scenario-design (+ its test-plan.md manifest) · handoff to ship-it.
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 boundar
---name: plan-proposaldescription: Develop-side planning orchestrator for an OpenSpec change: artifact creation → doubt-driven-review →…---# .pi/skills/plan-proposal/SKILL.mdVue d'ensemble
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".
FAQ
Téléchargez .pi/skills/plan-proposal/SKILL.md auprès de l'éditeur, ou copiez le chemin et ouvrez le dépôt. PlugMCP répertorie le skill et n'héberge pas le fichier.
L'éditeur le maintient sur https://github.com/BlackBeltTechnology/pi-agent-dashboard.
Claude, Cursor, Codex et Grok Build peuvent lire un SKILL.md que vous ajoutez depuis le dépôt de l'éditeur. Grok Bot l'installe lorsque vous envoyez dans un chat le lien du dossier GitHub du skill.