// Planning engine that decomposes a locked Spec into atomic TDD-ready tasks. Use when user runs `/forge plan` / has a locked spec / needs actionable task breakdown before build.
[HINT] Download the complete skill directory including SKILL.md and all related files
| name | forge-plan |
| description | Plan a locked Spec into atomic TDD-ready tasks with full research, file mapping, and self-check validation. Use when running `/forge plan`, a spec is locked, or an actionable task breakdown is needed before build. |
| skeleton_exempt_legacy | true |
| disable-model-invocation | true |
触发方式：标准路径的第一步，全量路径的第三步，或用户直接输入
/forge plan职责：将锁定的 Spec 拆解为包含 TDD 步骤的原子任务，生成可直接执行的开发计划 输出路径：.forge/plans/<topic>.md
五步流程（Research → File Mapping → Task Breakdown → Self-Check → User Approval）将锁定的 Spec 转化为原子任务列表。每个任务包含文件路径、TDD 步骤、完整代码、验证命令和提交信息。
核心原则：计划中不允许任何模糊内容。写不出完整代码说明还没想清楚，回去重新研究。
Not For：轻量路径任务（≤1 文件 ≤20 行）、Spec 已包含完整任务拆解的情况。
搜索历史经验和项目上下文。强制步骤：搜索 knowledge/、读取 instincts.md、读取锁定 Spec、派发 explore agent 扫描代码库。可选：metrics.md（偏差率 > 1.2 时预估时间乘系数）、tool-health.md（退化命令注入警告）。
列出所有需创建/修改的文件。标注 CREATE 或 MODIFY，说明原因。测试文件与源文件成对。
根据是否有 design.md 选择格式：
拆解规则：Granularity（2-5 min）、Independence（独立可验证）、Ordering（按依赖排序）、Completeness（不留空白）。
任务命名优先使用 .forge/glossary.md 定义的规范术语；如发现同义词/别名，自动替换为 canonical term，保持跨 skill 命名一致。
| Check | Criteria |
|---|---|
| Spec Coverage | 每个需求至少被一个任务覆盖 |
| Placeholder Scan | 零占位符 → 详见 references/prohibited-content.md |
| Type Consistency | 所有引用有定义（full）/ Design Reference 有效（lightweight） |
| Dependencies | 无循环依赖，拓扑排序正确 |
| Plan Structure | Split_Trigger 任一命中 → 警告 + 等待用户选择 → 详见 references/plan-split-wizard.md |
未通过则自动修正并重新自检。
IF Plan_Structure_Check 触发（checkPlanStructure 返回 triggered: true）且 plan frontmatter 不含 monolith_acknowledged: true：
输出结构化警告：
⚠️ Plan Structure Warning
本 plan 触发以下拆分建议条件：
- [已命中的条件列表]
建议将 plan 按 Sprint 拆成 N 个独立 plan，每个 plan 对应一次完整的 build → review → test → ship 周期。
继续使用当前 plan 请输入 "acknowledge-monolith"；拆分请输入 "split"。
acknowledge-monolith（或任何非 split 输入）→ plan frontmatter 追加 monolith_acknowledged: true，继续到 Step 5split → 进入拆分向导（→ 详见 references/plan-split-wizard.md）monolith_acknowledged: true → 跳过此检查批准 → status: approved；修改意见 → 回到 Self-Check；拒绝 → 保持 draft。
Plan frontmatter 可含 monolith_acknowledged: true（用户明确知悉未拆分风险），此字段由 Step 4a 自动追加。
→ 详见 references/atomic-task-format.md
→ 详见 references/prohibited-content.md
/forge build→ 遵循 CLAUDE.md §2.2 前置检查（Plan 批准门禁）。轻量路径不要求批准。
输出路径：.forge/plans/<topic>.md（kebab-case）
Frontmatter 字段：topic, status (draft/approved), date, spec_ref, format (lightweight/full)
两种格式模板（Lightweight + Full）的完整结构 → 详见 references/plan-document-format.md
.forge/ 存在？Spec 状态？Skill(skill="forge", args="build")。不输出"是否继续？""开始build？"等确认文本。仅输出 ✅ plan 完成 → 自动进入 build，然后直接调用 Skill。（→ 详见 shared/next-step-protocol.md）Pre-check 详情：.forge/ 不存在 → prompt forge init。Full path 要求 Spec locked；Standard path 无 Spec 时直接生成 Plan（spec_ref: "none"）。
| Case | Handling |
|---|---|
| Spec not locked (full path) | Block, prompt /forge spec |
| No Spec (standard path) | 直接生成 Plan，跳过 Spec 对齐检查 |
| Existing plan (draft) | 以已有 plan 为基础修改 |
| Existing plan (approved) | 提示先改 status 为 draft |
| Self-check fails 3 times | 停止自动修正，呈现给用户 |
| No knowledge/ history | 跳过，输出提示 |
No .forge/ directory | Prompt forge init |
→ 详见 references/examples.md
| # | Failure Mode | Correct Approach |
|---|---|---|
| 1 | Task granularity too large | 一个任务 = 一个独立可验证的行为变更 → references/atomic-task-format.md |
| 2 | Missing dependencies | 画依赖图，确保引用在先前任务中定义 |
| 3 | Placeholders not replaced | 每步必须含完整可执行代码 → references/prohibited-content.md |
| 4 | Breakdown without reading Spec | Step 1 Research 强制执行 |
| 合理化 | 反驳 |
|---|---|
| "边做边想更高效" | 10 分钟规划节省数小时调试 |
| "任务很明显不需要拆解" | 显式任务列表暴露隐藏依赖和边界情况 |
| "规划是额外开销" | 没有计划的实现只是在打字 |