plan

name

plan

description

Persist a structured exec-plan with prior-art check, atomic role-tagged steps, and blocking reviewer sign-off, written to `.bdc/plans/<proj>-<MMDD>-<topic>.md`. Use only when explicitly invoked as `/plan` or when builder names the skill by name (`plan`, `走 plan`). Do not auto-trigger from planning discussion (`做计划`, `plan 一下`) — empirical eval (Haiku 4.5 + Opus 4.7, both 0/3) showed description-level triggering is unreliable for this skill; manual gate is intentional.

/plan — Persist a structured plan

Step 0: Escape Hatch

If builder says 别走流程, 直接做, 简单点, or 不走地图, do not force /plan. Acknowledge once and do the smallest direct action.

Exception: do not bypass safety gates for destructive changes, secret access, public upload, deploy, database migration, force push, or irreversible writes.

Step 0.5: Project Goal Check

If PROJECT_GOAL.md exists in the current project root, read it before writing the plan. If the request conflicts with current_phase, exit_criteria, or out_of_scope, stop and ask whether to update the goal or narrow the request. Do not edit PROJECT_GOAL.md automatically.

Contract

Each invocation produces one .bdc/plans/<proj>-<MMDD>-<topic>.md in the format specified by ${BDC_HOME:-$HOME/.bdc}/standards/plan-management.md (exec-plan + 7 role labels + atomic granularity), and spawns a reviewer to review the plan.

Use /plan when the work has any planning trigger: 3+ steps, cross-module changes, non-binary success criteria, or interface contract changes. Create the plan even if the user did not explicitly ask for one.

Prerequisites

Read once: ${BDC_HOME:-$HOME/.bdc}/standards/plan-management.md (format + 8 rules) + ${BDC_HOME:-$HOME/.bdc}/standards/model-router.md (role definitions) + ${BDC_HOME:-$HOME/.bdc}/standards/first-principles.md (constraint pass for non-trivial plans). Do not copy rules into the plan — reference them.

6-Step Process

1. Positioning (CLAUDE.md § Planning Discipline step 0)

One sentence: what is this? Let builder confirm. If unstable, stop and ask — do not drill into details.

2. Challenge premise

State what you believe the problem to be + why you believe that. Is this actually the right problem?

3. Prior-art check (CLAUDE.md north star + Planning Discipline step 2)

Use configured prior-art sources:

• configured local notes, docs, or knowledge tools when the builder has explicitly set them up
• current repo search with rg, find, and source reads
• relevant project docs such as README, architecture notes, ADRs, plans, or issue references

Write findings into the plan's ## Background & Judgment section. Write even if 0 results: "configured prior-art sources + repo search: no relevant prior art found."

4. builder pacing (Planning Discipline step 4)

Ask builder for preference: Expansion (dream bigger) / Hold (rigor on current scope) / Reduction (strip to MVP). Implicit response ("sounds good" / "let's do it") → default to Hold.

5. Write to disk (per plan-management.md format)

Filename: {project}-{MMDD}-{topic}.md, 2-4 word English slug. Example: bdc-0425-workflow-skills.md.

Required sections (plan-management.md § Exec-Plan Format):

• # <Title>
• Top-of-file granularity declaration > Granularity: each Step = at most one production file/function (+ at most one directly paired test file). Independently verifiable.
• > Target root: <absolute path> — required, single line, immediately after granularity declaration. The repo root where this plan's code changes will land. /execute reads this to scope all step packets and Codex -C invocations. Examples: <repo>, <agent-home> (for BDC self-modification), <repo>. Must be resolvable by git -C <path> rev-parse --show-toplevel.
• ## Spec 0
  • Objective:
  • Boundaries:
  • Success criteria:
  • Non-goals:
  • Open questions:
• ## Goal (1-2 sentences)
• ## Background & Judgment (current local facts + prior-art search result; 0 results must be explicit)
  • Include a short first-principles pass for non-trivial plans: Desired invariant:, Hard constraints:, Removable parts:, Attack point:, and the execution decision boundary. Use ${BDC_HOME:-$HOME/.bdc}/standards/first-principles.md for the field meanings.
  • Include Frozen decisions: for choices already made before execution. /execute must not reopen these choices inside atomic execution.
  • Include Deferred decisions: for choices intentionally outside this plan.
• ## Assumptions (at least one concrete assumption; do not write only "none")
• ## Alternatives Considered (at least one real alternative unless the task is a tiny one-step fix)
• ## Task Sizing
  • Table columns: Step | Size | Why
  • Sizes: XS, S, M, L
  • L means split unless the row explicitly includes Why not split: <reason>.
• ## Delivery Plan (local phases/checkpoints; for local-only work write local phases, not PR split)
• ## Commit Policy (default 1 Step = 1 commit + checkbox flip; list exceptions or none)
• ## Success Conditions (observable success evidence for each feature/phase)
• ## Falsification / Stop Conditions (when to stop, return to planning, or escalate)
• ## Features (each as ### F00N: <name> — todo)
  • Each Step: - [ ] <action> ← verify: <cmd> — <role> (role uses one of the 7 fixed words from plan-management.md § Role Labels)
• ## Per-step oracle_source when the plan has any coding/test step
  • Each coding/test step needs a combined-id row (F001.S1) with a backtick-wrapped external source for the expected behavior.
  • Empty values, "none", "TBD", and "inferred from implementation" are invalid.
• ## Per-step stop conditions when the plan has coding or other risky steps
  • Required for coding steps in atomic-plan-core-v1.
  • Add rows for security, migration, and interface-risk steps when continuing after a false premise would be unsafe.
• ## Decision Log (decision + rationale + date)
• ## Open Questions (each with a recommendation)

Sub-skill tags:

• Tags appear after the step description and before ← verify:.
• Allowed tags: [source-driven], [security-sensitive], [interface], [adr], [deprecation], [simplify-required], [debug-required].
• Tag decisions:
  • framework/library/API/SDK → [source-driven]
  • auth/token/PII/secrets/SQL/shell exec/sanitize → [security-sensitive]
  • public API/protocol/schema/interface/module boundary → [interface]
  • architecture/storage/protocol decision → [adr]
  • remove/delete/replace/migrate/deprecate/sunset → [deprecation]
  • complex/refactor/coordinator/orchestrator → [simplify-required]
  • bug/debug/regression/root-cause fix → [debug-required]
• Review routing tags:
  • [debug-required] means the plan must ask for RED evidence before implementation when a behavior/regression is being fixed; unresolved proof gaps route to /verify --deep test review.
  • [security-sensitive] means the plan must ask for security review before /ship; unresolved findings route to /verify --deep security review.
  • [interface] means the plan must ask for review of downstream contract compatibility before closure.

Append one line to INDEX.md: | {proj} | {MMDD} | {file} | {title} | active |

Pre-reviewer lint (mandatory): run bash ${BDC_HOME:-$HOME/.bdc}/scripts/plan-lint.sh <new-plan> immediately after writing the plan. If lint reports any hard-fail (exit 1), fix the plan and re-lint. Soft warnings (verify-grep alignment / gitignore-sequence) are advisory — review and address before continuing if relevant. Only proceed to Step 6 reviewer once plan-lint exits 0.

6. Reviewer review (plan-management.md Rule 6) — blocking, foreground

spawn feature-dev:code-architect
  model: opus
  run_in_background: false   # foreground — builder wants the verdict in-line, not追加 5 分钟后
  prompt: Review the plan file itself. Check the 4 items listed in plan-management.md Rule 6:
    - Self-contradictions
    - Missing dependencies
    - Over-engineering
    - Verify command executability
  + Role label correctness + atomicity compliance (see plan-management.md § 8 atomicity rule)
  + **Target root sanity** (v8 Bug 3): plan must contain `> Target root: <abs path>` line near the top; the path must be resolvable by `git -C <path> rev-parse --show-toplevel`. If missing or invalid, flag P0.
  + **Delivery / commit policy sanity**: plan must have a concrete `## Delivery Plan` and `## Commit Policy`; local-only plans should use local phases/checkpoints instead of PR split.
  + **Success / stop-condition sanity**: plan must have concrete `## Success Conditions` and `## Falsification / Stop Conditions`; empty or vague stop conditions ("none", "TBD", "vague placeholder") are a P1.
  + **Frozen-decision sanity**: `## Background & Judgment` must include `Frozen decisions:` and `Deferred decisions:`. If `/execute` would need to reopen architecture, dependency, model-route, or safety-scope choices during execution, flag P1.
  + **First-principles sanity**: for non-trivial plans, `## Background & Judgment` must include a compact first-principles pass with Desired invariant, Hard constraints, Removable parts, and Attack point. If it reads like generic philosophy instead of concrete constraints, flag P1.
  + **Oracle-source sanity**: if any coding/test step lacks a non-empty `## Per-step oracle_source` row keyed by combined id (`F001.S1`), flag P1. The source must point to a user request, bug report, spec, prior implementation, fixture, public documentation, or another artifact outside the implementing agent's own judgment.
  + **Per-step stop-condition sanity**: flag risky steps without a `## Per-step stop conditions` row. Coding steps are risky by default; security, migration, and interface-risk steps are risky when continuing on a false premise could cause bad writes, broken contracts, or irreversible changes.
  + **Assumption / alternative sanity**: non-trivial plans must state concrete assumptions and alternatives considered.
  Output: verdict table + P0/P1/P2 + issues specific to Feature/Step (terse — appended verbatim into builder prompt below)

Wait for the reviewer to return. Append its verdict to the plan's ## Decision Log section. Then present the combined plan + reviewer verdict to builder in the Output block below — builder sees one coherent package, not "plan first, reviewer arrives 5 minutes later."

Why blocking instead of background: builder explicitly chose the串行 path on 2026-04-26 — he wants to read a fully-reviewed plan before saying go, not be asked "执行吗" while the reviewer is still working.

Output (presented after reviewer returns)

✅ Plan written + reviewer 审完
📁 zed <agent-home>/plans/{file}.md

Reviewer 结论：<verdict 一句话总结，例如 LGTM / 1 个 P1 / 2 个 P0>
{reviewer report 精简版 — P0/P1 issue 列表，去掉 verdict table 标题等冗余}

下一步选一个：
  1) 说 "go" / "开始做" / "执行" → AI 自动接 /execute 开干
  2) 直接说要改哪里 → AI 改 plan + 重审
  3) 不做了 → AI 把 plan 状态改成 deferred

Anti-patterns

• Do not skip prior-art / knowledge-source prior art check before writing the plan. Because: missing prior art makes the plan re-solve known problems.
• Do not omit verify commands from Steps (writing "done" is not a verify command). Because: /execute needs executable evidence, not narrative completion.
• Do not exceed the atomicity hard limit (1 production file/function + at most 1 directly paired test file — see plan-management.md § 8). Because: larger steps hide scope drift and make rollback expensive.
• Do not write verify as a description rather than a command ("check code is correct" ❌ vs pytest -x ✅). Because: descriptions cannot be executed or audited.
• Do not write specific model versions in the plan ("dispatch to GPT-5.5") — write roles only, models are resolved by router. Because: routing can change without rewriting approved plans.
• Do not skip reviewer review (even if the plan looks simple). Because: plan errors are cheapest to catch before execution.
• Do not omit ## Per-step oracle_source for coding/test steps. Because: expected behavior must come from outside the implementing agent's own judgment.
• Do not omit ## Delivery Plan, ## Commit Policy, ## Success Conditions, or ## Falsification / Stop Conditions for executable plans. Because: /execute needs delivery boundaries and stop rules before execution starts.
• Do not write empty or vague stop conditions; stop conditions must say exactly what failure or ambiguity halts execution. Because: vague stops do not interrupt a failing atomic window.

Related

• Format rules: ${BDC_HOME:-$HOME/.bdc}/standards/plan-management.md
• Role definitions: ${BDC_HOME:-$HOME/.bdc}/standards/model-router.md
• builder approves → /execute

Verification

• Run bash ${BDC_HOME:-$HOME/.bdc}/scripts/plan-lint.sh <new-plan> before reviewer handoff.
• Confirm the reviewer verdict is appended or summarized before presenting the plan.
• Confirm INDEX.md has an active row for the plan.

Red Flags

• The plan has coding steps but no ## Per-step oracle_source.
• The plan has no executable verify command for a step.
• The plan requires /execute to make a dependency, architecture, or model-route decision during execution.

Common Rationalizations

Rationalization	Response
"The verify grep is obvious; I can type it from memory."	Do not. Incident: standards/debugging.md 2026-04-27 says a plan verify grep missed because the plan pattern did not match the actual file content. Derive literal grep patterns from the target file.
"This can be one large step because it is one feature."	Do not. Incident: standards/debugging.md 2026-04-27 records aggregate-grep and gitignore sequencing failures caused by coarse plan steps. Split until each step has one executable verify.