v-planning

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

v-planning

You create implementation plans as a DAG of vertical steps — each step a complete, QA-able slice of value (DB + API + UI + tests for one feature). The DAG captures feature-level dependencies, so independent steps can be implemented in parallel by sub-agents.

Output is a plan directory at

thoughts/<username|shared>/plans/YYYY-MM-DD-description/

root.md            # Overview, mermaid DAG, step index, Global Verification
step-1.md          # frontmatter (id, name, depends_on) + Success Criteria
step-2.md
└── step-N.md

你需要创建垂直步骤的DAG形式的实现计划——每个步骤都是一个完整的、可进行QA的价值切片（某一功能的数据库+API+UI+测试）。DAG记录了功能级别的依赖关系，因此独立步骤可由子Agent并行实现。

输出为位于

thoughts/<username|shared>/plans/YYYY-MM-DD-description/

的计划目录：

root.md            # 概述、Mermaid DAG、步骤索引、全局验证
step-1.md          # 前置元数据（id、名称、depends_on）+ 成功标准
step-2.md
└── step-N.md

Setup (before starting)

准备工作（开始前）

Autonomy Mode — passed by the invoking command; default to Critical if unspecified.

Mode	Behavior
Autopilot	Research independently, write the full plan dir, present for final review only
Critical (Default)	After each research step, ask clarifying questions before drafting; surface design options especially at DAG decomposition
Verbose	Check in at every sub-step: validate understanding, confirm scope, surface unknowns, confirm before writing each step file

Commit preference — unless Autopilot, ask once via
```
AskUserQuestion
```
:
Question Options
"Create a commit after each step once manual verification passes?" 1. Yes (Recommended), 2. No, I'll handle commits
Prior learnings — OPTIONAL SUB-SKILL: if
```
~/.agentic-learnings.json
```
exists, run
```
/learning recall <topic>
```
first.

Question	Options
"Create a commit after each step once manual verification passes?"	1. Yes (Recommended), 2. No, I'll handle commits

自主模式——由调用命令传入；若未指定，默认设为Critical（关键）。

模式	行为
Autopilot（自动驾驶）	独立开展调研，编写完整计划目录，仅在最后呈现供审核
Critical（关键）（默认）	每完成一项调研步骤后，在起草前询问澄清问题；尤其是在DAG分解阶段，提供设计方案选项
Verbose（详细）	在每个子步骤都进行确认：验证理解、确认范围、提出未知问题、编写每个步骤文件前进行确认

提交偏好——除非是Autopilot模式，否则通过
```
AskUserQuestion
```
询问一次：
问题选项
"手动验证通过后，是否在每个步骤完成后创建一次提交？" 1. 是（推荐），2. 否，我会自行处理提交
过往经验——可选子技能：若
```
~/.agentic-learnings.json
```
存在，先运行
```
/learning recall <topic>
```
。

问题	选项
"手动验证通过后，是否在每个步骤完成后创建一次提交？"	1. 是（推荐），2. 否，我会自行处理提交

The 10 Rules

10条规则

Scaffold first — before any research, exit plan mode and create the plan directory with
```
root.md
```
from
```
cc-plugin/base/skills/v-planning/templates/root.md
```
. (Use the user's name when known, e.g.
```
taras
```
; fall back to
```
thoughts/shared/
```
otherwise.) Step files are added as the DAG emerges in rule 4. The directory grows incrementally; the user can correct course early.
Sub-agent everything heavy — file reads, research, validation. Default
```
run_in_background: true
```
. Keep raw tool output out of the main session. Sub-agent menu:
```
codebase-locator
```
(find files),
```
codebase-analyzer
```
(understand current implementation),
```
codebase-pattern-finder
```
(find similar features),
```
context7
```
MCP (library/framework specifics),
```
Explore
```
or
```
general-purpose
```
(read mentioned files).
Ask via
AskUserQuestion
— see
```
desplega:ask-user
```
for conventions. Never ask in chat as plain bullets.
Ask after each step (Critical/Verbose), then loop — work the plan section by section: Current State Analysis → Implementation Approach → DAG Decomposition → Per-Step Details. For each section: spawn sub-agents → synthesize findings (with
```
file:line
```
refs) → ask gaps via
```
AskUserQuestion
```
→ draft → next section.
- DAG Decomposition: identify vertical slices (each QA-able on its own), their dependencies, and any explicit integration step. Present the proposed step list + mermaid graph and confirm shape via
```
AskUserQuestion
```
  before drafting step files.
- Per-Step Details: create each
```
step-<n>.md
```
  from
```
cc-plugin/base/skills/v-planning/templates/step.md
```
  . Frontmatter
```
depends_on: [step-X, ...]
```
  is canonical;
```
root.md
```
  's mermaid graph + step-index table is a derived view — keep them in sync.
Concrete deliverable per step (vertical slice) — every step's Overview names what file/feature/output exists when it's done. Each step must be QA-able on its own. Layer-only steps ("DB migration", "just the endpoint") are smells — collapse them into vertical slices. "Improve X" and "refactor Y" are also smells.
Proof of work: maximize Automated Verification + Automated QA — push everything into runnable commands (low-level) and agent-driven QA (browser-use, screenshot diff, CLI walkthrough). Manual Verification is the exception. Each step has its own Success Criteria block;
```
root.md
```
has
```
## Global Verification
```
for cross-cutting checks that only fire after the whole DAG drains. A
```
### QA Spec (optional):
```
linking to a
```
desplega:qa
```
doc is reserved for cross-cutting / evidence-heavy QA — not routine per-step checks.
Propose splitting — when a step has >4 sub-steps or >2 distinct concerns, split into multiple DAG nodes (wire deps appropriately). When the whole DAG won't fit one parallel implementation session, split into multiple plans (e.g., contract → storage → UI). A linear DAG is accepted but worth flagging — the linear
```
planning
```
skill may fit better.
Push back with radical candor — use
```
radical-candor:feedback
```
when the plan is too big, vague, mixes concerns, or has obvious risks. Silence is Ruinous Empathy.
Validate structure with a Haiku sub-agent before showing the plan (
```
general-purpose
```
with
```
model: haiku
```
). Verify: every
```
step-<n>.md
```
has all three Success Criteria subsections (Automated Verification + Automated QA + Manual Verification); all items use
```
- [ ]
```
; automated checks are runnable commands; every step's
```
depends_on
```
references an existing step ID; no cycles in the DAG;
```
root.md
```
's mermaid graph + step-index table agree with step frontmatter; every step's frontmatter has
status: ready
(a fresh plan; transitions happen during
```
/v-implement
```
); referenced paths exist. Apply fixes before reveal.
Hand off to a fresh session — never implement here. Close-out:
1. Open
```
/file-review:file-review <plan-dir>/root.md
```
  (unless Autopilot); iterate on comments. Re-open with individual
```
step-<n>.md
```
  files if needed.
2. Optionally invoke
```
desplega:reviewing
```
  for gap analysis (offer via
```
AskUserQuestion
```
  ).
3. OPTIONAL SUB-SKILL: if significant insights emerged, capture via
```
/learning capture
```
  .
4. If any step has a
  ### QA Spec (optional):
  block, generate the QA doc via
```
desplega:qa
```
  before handoff (
```
thoughts/<username|shared>/qa/YYYY-MM-DD-[feature].md
```
  ). Scenarios live in the doc, not the plan.
5. Ask via
```
AskUserQuestion
```
  :
  Question Options
  "Plan ready. What's next?" 1. Implement in a fresh session, 2. Run
  /review
  first, 3. Done for now (park the plan)
6. Tell them explicitly: "Open a new Claude Code session and run
```
/desplega:v-implement <plan-dir>
```
  . Starting fresh keeps the implementation context clean."

Question	Options
"Plan ready. What's next?"	1. Implement in a fresh session, 2. Run `/review` first, 3. Done for now (park the plan)

先搭建框架——在任何调研之前，退出计划模式，使用
```
cc-plugin/base/skills/v-planning/templates/root.md
```
中的模板创建计划目录及
```
root.md
```
文件。（若已知用户名称则使用，例如
```
taras
```
；否则默认使用
```
thoughts/shared/
```
）。步骤文件会在规则4的DAG形成过程中逐步添加。目录会逐步扩展，用户可以尽早修正方向。
所有繁重工作交由子Agent处理——文件读取、调研、验证。默认设置
```
run_in_background: true
```
。避免在主会话中显示原始工具输出。 子Agent菜单：
```
codebase-locator
```
（查找文件）、
```
codebase-analyzer
```
（理解当前实现）、
```
codebase-pattern-finder
```
（查找类似功能）、
```
context7
```
MCP（库/框架细节）、
```
Explore
```
或
```
general-purpose
```
（读取提及的文件）。
通过
AskUserQuestion
提问——遵循
```
desplega:ask-user
```
的约定。切勿在聊天中以普通项目符号形式提问。
（Critical/Verbose模式下）每完成一个步骤后提问，然后循环——逐个部分处理计划：当前状态分析 → 实现方法 → DAG分解 → 每步细节。对于每个部分：生成子Agent → 整合调研结果（附带
```
file:line
```
引用）→ 通过
```
AskUserQuestion
```
询问信息缺口 → 起草 → 进入下一部分。
- DAG分解：识别垂直切片（每个均可独立进行QA）、它们的依赖关系，以及任何明确的集成步骤。在起草步骤文件前，先提交拟议的步骤列表+Mermaid图表，并通过
```
AskUserQuestion
```
  确认结构。
- 每步细节：使用
```
cc-plugin/base/skills/v-planning/templates/step.md
```
  模板创建每个
```
step-<n>.md
```
  文件。前置元数据中的
```
depends_on: [step-X, ...]
```
  是标准依据；
```
root.md
```
  中的Mermaid图表+步骤索引表是衍生视图——需保持两者同步。
每个步骤对应具体交付物（垂直切片）——每个步骤的概述需说明完成后将存在的文件/功能/输出。每个步骤必须可独立进行QA。仅涉及单一层级的步骤（如“数据库迁移”、“仅实现端点”）是不合理的——应将其合并为垂直切片。“改进X”和“重构Y”同样不合理。
工作证明：最大化自动化验证+自动化QA——尽可能将内容转化为可运行命令（底层）和Agent驱动的QA（浏览器使用、截图对比、CLI演练）。手动验证仅作为例外情况。每个步骤都有自己的成功标准块；
```
root.md
```
中有
```
## 全局验证
```
部分，用于在整个DAG完成后才执行的跨领域检查。
```
### QA规范（可选）：
```
链接到
```
desplega:qa
```
文档，仅用于跨领域/需要大量证据的QA——而非常规的每步检查。
建议拆分——当一个步骤包含超过4个子步骤或2个不同关注点时，拆分为多个DAG节点（合理设置依赖关系）。当整个DAG无法在一个并行实现会话中完成时，拆分为多个计划（例如，契约→存储→UI）。线性DAG是可接受的，但值得指出——线性的
```
planning
```
技能可能更适合。
坦诚提出反对意见——当计划过大、模糊、混合关注点或存在明显风险时，使用
```
radical-candor:feedback
```
。沉默是有害的共情。
在展示计划前，使用Haiku子Agent验证结构（使用
```
general-purpose
```
并设置
```
model: haiku
```
）。验证内容包括：每个
```
step-<n>.md
```
都包含所有三个成功标准子部分（自动化验证+自动化QA+手动验证）；所有项均使用
```
- [ ]
```
格式；自动化检查是可运行的命令；每个步骤的
```
depends_on
```
引用了存在的步骤ID；DAG中无循环；
```
root.md
```
的Mermaid图表+步骤索引表与步骤前置元数据一致；每个步骤的前置元数据都有
status: ready
（新计划；状态转换在
```
/v-implement
```
期间进行）；引用的路径存在。在展示前应用修复。
移交至新会话——切勿在此处实现。收尾步骤：
1. 打开
```
/file-review:file-review <plan-dir>/root.md
```
  （Autopilot模式除外）；根据评论迭代。必要时单独打开
```
step-<n>.md
```
  文件。
2. 可选调用
```
desplega:reviewing
```
  进行缺口分析（通过
```
AskUserQuestion
```
  提供选项）。
3. 可选子技能：若产生重要见解，通过
```
/learning capture
```
  记录。
4. 若任何步骤包含
  ### QA规范（可选）：
  块，在移交前通过
```
desplega:qa
```
  生成QA文档（路径为
```
thoughts/<username|shared>/qa/YYYY-MM-DD-[feature].md
```
  ）。场景记录在文档中，而非计划中。
5. 通过
```
AskUserQuestion
```
  询问：
  问题选项
  "计划已准备就绪。下一步是什么？" 1. 在新会话中实现，2. 先运行
  /review
  ，3. 暂时完成（搁置计划）
6. 明确告知用户："打开一个新的Claude Code会话并运行
```
/desplega:v-implement <plan-dir>
```
  。重新开始可保持实现环境的整洁。"

问题	选项
"计划已准备就绪。下一步是什么？"	1. 在新会话中实现，2. 先运行 `/review` ，3. 暂时完成（搁置计划）

DAG Specifics

DAG细节

Frontmatter is canonical for deps.
```
root.md
```
's mermaid graph is derived. If they disagree, frontmatter wins.
Self-contained steps. A sub-agent handed only one
```
step-<n>.md
```
(plus plan-level context from
```
root.md
```
) should be able to implement it without reading sibling steps.
Frontmatter carries execution state. Initial
```
status: ready
```
on every step;
```
desplega:step-running
```
transitions it through
```
claimed
```
→
```
done
```
(or back to
```
ready
```
on retry-able failure) and writes
```
assignee
```
/
```
claimed_at
```
while claimed. This makes the same plan dir safe to drive from multiple orchestrator instances. The body of the step (Changes Required, Success Criteria) is immutable during execution — only frontmatter and checkbox state change.
Integration steps are explicit when needed. If parallel siblings need non-trivial stitching (cross-cutting e2e, shared-surface reconciliation), add an explicit
```
step-N
```
with
```
depends_on: [step-X, step-Y, ...]
```
whose work is "stitch + e2e". Otherwise the DAG just terminates at its leaves.

前置元数据是依赖关系的标准依据。
```
root.md
```
中的Mermaid图表是衍生内容。若两者不一致，以前置元数据为准。
步骤独立完整。仅拿到一个
```
step-<n>.md
```
（加上
```
root.md
```
中的计划级上下文）的子Agent应无需读取同级步骤即可实现该步骤。
前置元数据记录执行状态。每个步骤初始状态为
```
status: ready
```
；
```
desplega:step-running
```
会将其状态转换为
```
claimed
```
→
```
done
```
（或在可重试失败时转回
```
ready
```
），并在认领时写入
```
assignee
```
/
```
claimed_at
```
。这使得同一计划目录可安全地由多个编排器实例驱动。步骤的主体内容（所需更改、成功标准）在执行期间不可变——仅前置元数据和复选框状态会变化。
必要时明确设置集成步骤。若并行的同级步骤需要非 trivial 的拼接（跨端e2e、共享界面协调），添加一个明确的
```
step-N
```
，其
```
depends_on: [step-X, step-Y, ...]
```
，工作内容为“拼接+e2e”。否则DAG在叶节点处终止即可。

Commit Integration

提交集成

If commit-per-step was enabled in Setup:

After each step's manual verification passes, commit with format
```
[step-N] <brief description>
```
.
Only commit after explicit confirmation that manual verification passed.
Otherwise, skip — the user handles commits.

若在准备工作中启用了每步提交：

每个步骤的手动验证通过后，以
```
[step-N] <简要描述>
```
的格式提交。
仅在明确确认手动验证通过后才提交。
否则跳过——由用户自行处理提交。

Success Criteria Format (MANDATORY)

成功标准格式（强制要求）

Canonical format and heading hierarchy live in:

cc-plugin/base/skills/v-planning/templates/root.md

(

## Global Verification

)

cc-plugin/base/skills/v-planning/templates/step.md

(per-step three-bucket Success Criteria)

Structure validation runs automatically (rule 9, Haiku sub-agent).

标准格式和标题层级位于：

cc-plugin/base/skills/v-planning/templates/root.md

（

## 全局验证

部分）

cc-plugin/base/skills/v-planning/templates/step.md

（每步的三分类成功标准）

结构验证会自动运行（规则9，Haiku子Agent）。