- name
SKILL.md
Файл навыка остаётся в репозитории издателя.
Вставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a cursor -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a claude-code -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a codex -yВставьте скопированную команду в терминал. Она установит этот SKILL.md в выбранного агента.
npx skills add BlackBeltTechnology/pi-agent-dashboard --skill plan-proposal -a grok -yОтправьте скопированное сообщение в чат Grok Bot. Бот загрузит этот SKILL.md с GitHub и добавит его к навыкам, общим для всех ваших ботов.
Install this skill: https://github.com/BlackBeltTechnology/pi-agent-dashboard/tree/HEAD/.pi/skills/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
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.mdОбзор
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
Скачайте .pi/skills/plan-proposal/SKILL.md у издателя или скопируйте путь и откройте репозиторий. PlugMCP только показывает навык в каталоге и не хранит файл.
Издатель хранит его в https://github.com/BlackBeltTechnology/pi-agent-dashboard.
Claude, Cursor, Codex и Grok Build могут читать SKILL.md, который вы добавляете из репозитория издателя. Grok Bot устанавливает его, когда вы отправляете в чат ссылку на папку навыка на GitHub.