plan-generator

计划生成器技能

计划生成器技能 - 通过协调专业 Agent 并生成全面的规划文档，根据需求创建结构化且经过验证的计划。 - 为新功能制定计划 - 规划重构工作 - 规划系统迁移 - 规划架构变更 - 分解复杂需求 - 验证现有计划

步骤 0：以往任务情报（跨任务上下文）

创建新计划前，先收集近期工作的上下文，以避免重复并基于先前决策推进：

1. 近期提交：运行 git log --oneline -5，查看近期已交付的内容
2. 近期任务：调用 TaskList()，检查带有相关元数据的已完成任务
3. 近期决策：阅读 .claude/context/memory/decisions.md，了解会影响此计划的架构选择
4. 近期问题：阅读 .claude/context/memory/issues.md，了解已知阻碍或变通方案

使用这些上下文来：

• 避免重新实现近期已交付的功能
• 遵循已做出的架构决策（未经升级处理，不要与之矛盾）
• 基于已完成的工作继续推进，而非从头开始
• 在适当时引用具体的提交哈希或任务 ID

步骤 1：分析需求

解析用户需求：

• 提取明确需求
• 识别隐含需求
• 确定规划范围
• 评估复杂度

步骤 2：协调专业人员

向相关 Agent 请求规划意见：

• 分析师：业务需求和市场背景
• PM：产品需求和用户故事
• 架构师：技术架构和设计
• 数据库架构师：数据需求
• UX 专家：界面需求

步骤 3：生成计划结构

按照以下可执行结构创建计划：

# Plan: [Title]

## Executive Summary

[2-3 sentence overview]

## Objectives

- [Objective 1]
- [Objective 2]

## Phases

### Phase N: [Phase Title]

**Dependencies**: [Phase numbers or 'None']
**Parallel OK**: [Yes/No - can tasks run concurrently?]

#### Tasks

- [ ] **N.1** [Task description] (~X min)
  - **Command**: `actual shell command here`
  - **Verify**: `command to verify success`
  - **Rollback**: `command to undo if needed`

- [ ] **N.2** [Task description] (~X min) [⚡ parallel OK]
  - **Command**: `...`
  - **Verify**: `...`

#### Phase N Error Handling

If any task fails:

1. Run rollback commands for completed tasks (reverse order)
2. Document error: `echo "Phase N failed: [error]" >> .claude/context/memory/issues.md`
3. Do NOT proceed to Phase N+1

#### Phase N Verification Gate

```bash
# All must pass before proceeding
[verification commands]
```

风险

风险	影响	缓解措施	回滚
[风险]	[高/中/低]	[策略]	[命令]

时间线摘要

阶段	任务	预计时间	是否并行？
1	5	30 分钟	部分
2	3	20 分钟	否

### The Executable Task Format (MANDATORY)

Every task MUST include:
1. **Checkbox** - `- [ ]` for progress tracking
2. **ID** - `N.M` format for reference
3. **Time estimate** - `(~X min)`
4. **Command** - Actual executable command
5. **Verify** - Command to confirm success
6. **Rollback** - Command to undo (if applicable)
7. **Parallel marker** - `[⚡ parallel OK]` if can run concurrently

**Enhanced task format with structured completion fields** (verify/done/files are OPTIONAL — omit for backward compatibility):

```markdown
- [ ] **N.1** [Task description] (~X min)
  - **Command**: `actual shell command here`
  - **Verify**: `pnpm test -- --grep "pattern"` (command proving task is done)
  - **Done**: [measurable criteria for "done" — e.g. "All tests pass, lint clean, file exists"]
  - **Files**: [`path/to/file1`, `path/to/file2`] (files this task creates or modifies)
  - **Rollback**: `command to undo if needed`
```

> **Schema**: Full task structure is documented in `.claude/schemas/plan-format.schema.json`.
> The `verify`, `done`, and `files` fields are optional — existing plans without them remain valid.

### Guidelines
- Define clear objectives
- Break down into phases (<=7 phases total)
- Each phase has <=7 tasks
- Every task has executable commands
- Include verification gates between phases
- For **HIGH** or **EPIC** complexity tasks, invoke `discuss-phase` skill BEFORE generating the plan to surface ambiguities and resolve scope, architecture, and acceptance criteria questions with the user

### Step 4: Assess Risks

Identify risks and mitigation:

- Technical risks
- Resource risks
- Timeline risks
- Dependency risks
- Mitigation strategies

### Step 5: Validate Plan

Validate plan completeness:

- All requirements addressed
- Dependencies mapped
- Success criteria defined
- Risks identified
- Plan is feasible

### Step 6: Generate Artifacts

Create plan artifacts using the template-renderer skill:

**Using Template-Renderer**:
After creating plan data structure, invoke template-renderer to generate formatted output:

```javascript
// Map plan data to template tokens
const planTokens = {
  PLAN_TITLE: plan.title,
  DATE: new Date().toISOString().split('T')[0],
  FRAMEWORK_VERSION: 'Agent-Studio v3.1.0',
  STATUS: plan.status || 'Phase 0 - Research',
  EXECUTIVE_SUMMARY: plan.executiveSummary,
  TOTAL_TASKS: `${plan.totalTasks} atomic tasks`,
  FEATURES_COUNT: plan.features.length,
  ESTIMATED_TIME: plan.estimatedTime,
  STRATEGY: plan.strategy,
  KEY_DELIVERABLES_LIST: plan.keyDeliverables.map(d => `- ${d}`).join('\n'),
  // Phase-specific tokens
  PHASE_0_PURPOSE: plan.phases[0].purpose,
  PHASE_0_DURATION: plan.phases[0].duration,
  PHASE_1_NAME: plan.phases[1].name,
  PHASE_1_PURPOSE: plan.phases[1].purpose,
  PHASE_1_DURATION: plan.phases[1].duration,
  DEPENDENCIES: plan.phases[1].dependencies,
  PARALLEL_OK: plan.phases[1].parallelOk ? 'Yes' : 'No',
  VERIFICATION_COMMANDS: plan.phases[1].verificationCommands,
  // Add more phase tokens as needed
};

// Invoke template-renderer skill
Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'plan-template',
    outputPath: `.claude/context/plans/${planId}.md`,
    tokens: planTokens
  }
});
```

**Output Locations**:
- Plan markdown (from template): `.claude/context/plans/<plan-id>.md`
- Plan JSON (structured data): `.claude/context/plans/<plan-id>.json`
- Plan summary (for quick reference)
</execution_process>

<plan_types>
**Feature Development Plan**:

- Objectives: Feature goals
- Steps: Analysis -> Design -> Implementation -> Testing
- Agents: Analyst -> PM -> Architect -> Developer -> QA

**Refactoring Plan**:

- Objectives: Code quality goals
- Steps: Analysis -> Planning -> Implementation -> Validation
- Agents: Code Reviewer -> Refactoring Specialist -> Developer -> QA

**Migration Plan**:

- Objectives: Migration goals
- Steps: Analysis -> Planning -> Execution -> Validation
- Agents: Architect -> Legacy Modernizer -> Developer -> QA

**Architecture Plan**:

- Objectives: Architecture goals
- Steps: Analysis -> Design -> Validation -> Documentation
- Agents: Architect -> Database Architect -> Security Architect -> Technical Writer
</plan_types>

<integration>
**Integration with Planner Agent**:
Planner agent uses this skill to:
- Generate plans from requirements
- Coordinate specialist input
- Validate plan completeness
- Track plan execution
</integration>

<best_practices>

1. **Coordinate Early**: Get specialist input before finalizing plan
2. **Keep Steps Focused**: <=7 steps per plan section
3. **Map Dependencies**: Clearly identify prerequisites
4. **Assess Risks**: Identify and mitigate risks proactively
5. **Validate Thoroughly**: Ensure plan is complete and feasible
</best_practices>
</instructions>

<examples>
<formatting_example>
**Example Plan Output**

**Command**: "Generate plan for user authentication feature"

**Generated Plan**:

```markdown
# Plan: User Authentication Feature

## Executive Summary
Add JWT-based authentication with login/logout endpoints. Includes password hashing, session management, and security testing.

## Objectives
- Implement JWT-based authentication
- Support login, logout, and session management
- Provide secure password handling

## Phases

### Phase 1: Setup & Design
**Dependencies**: None
**Parallel OK**: Partial

#### Tasks
- [ ] **1.1** Create feature branch (~2 min)
  - **Command**: `git checkout -b feature/auth`
  - **Verify**: `git branch --show-current | grep feature/auth`

- [ ] **1.2** Create auth module directory (~1 min) [⚡ parallel OK]
  - **Command**: `mkdir -p src/auth`
  - **Verify**: `ls -d src/auth`

- [ ] **1.3** Design auth architecture (~15 min)
  - **Command**: `Task({ task_id: 'task-1', agent: "architect", prompt: "Design JWT auth..." })`
  - **Verify**: `ls .claude/context/artifacts/auth-design.md`

#### Phase 1 Verification Gate
```bash
git branch --show-current | grep feature/auth && ls src/auth && ls .claude/context/artifacts/auth-design.md

阶段 2：实施

依赖项：阶段 1
可以并行：否（顺序 TDD）

任务

• 2.1 编写身份验证端点测试（约 10 分钟）

  • 命令：Task({ task_id: 'task-2', agent: "developer", prompt: "TDD: Write failing tests for /login endpoint" })
  • 验证：npm test -- --grep "login" 2>&1 | grep -E "failing|FAIL"
  • 回滚：git checkout -- src/auth/__tests__/

• 2.2 实现登录端点（约 15 分钟）

  • 命令：Task({ task_id: 'task-3', agent: "developer", prompt: "Implement login to pass tests" })
  • 验证：npm test -- --grep "login" 2>&1 | grep -E "passing|PASS"

• 2.3 实现登出端点（约 10 分钟）

  • 命令：Task({ task_id: 'task-4', agent: "developer", prompt: "TDD: logout endpoint" })
  • 验证：npm test -- --grep "logout" 2>&1 | grep -E "passing|PASS"

阶段 2 错误处理

如果任何任务失败：

1. 运行：git stash && git checkout -- src/auth/
2. 记录：echo "Phase 2 failed: $(date)" >> .claude/context/memory/issues.md
3. 不要继续进入阶段 3

阶段 2 验证关卡

npm test -- --grep "auth" && echo "All auth tests passing"

阶段 3：安全审查

依赖项：阶段 2
可以并行：是

任务

• 3.1 安全审计（约 20 分钟）[⚡ 可以并行]

  • 命令：Task({ task_id: 'task-5', agent: "security-architect", prompt: "Audit auth implementation" })
  • 验证：ls .claude/context/reports/security/security-audit.md

• 3.2 运行安全测试（约 5 分钟）[⚡ 可以并行]

  • 命令：npm run test:security
  • 验证：echo $?（退出代码为 0）

风险

风险	影响	缓解措施	回滚
JWT 密钥泄露	高	使用环境变量	立即轮换密钥
SQL 注入	高	使用参数化查询	git revert HEAD

时间线摘要

阶段	任务数	预计耗时	可并行？
1	3	18 分钟	部分
2	3	35 分钟	否
3	2	25 分钟	是
总计	8	约 78 分钟

**After plan generation**, invoke template-renderer:

```javascript
// Map plan data to tokens
const tokens = {
  PLAN_TITLE: 'User Authentication Feature',
  DATE: '2026-01-28',
  FRAMEWORK_VERSION: 'Agent-Studio v3.1.0',
  STATUS: 'Phase 0 - Research',
  EXECUTIVE_SUMMARY: 'Add JWT-based authentication with login/logout endpoints...',
  TOTAL_TASKS: '8 atomic tasks',
  FEATURES_COUNT: '1',
  ESTIMATED_TIME: '~78 minutes',
  STRATEGY: 'Foundation-first → Core features → Security review',
  KEY_DELIVERABLES_LIST: '- Authentication module\n- Login/logout endpoints\n- Security audit',
  PHASE_1_NAME: 'Setup & Design',
  PHASE_1_PURPOSE: 'Create feature branch and design architecture',
  PHASE_1_DURATION: '18 minutes',
  DEPENDENCIES: 'None',
  PARALLEL_OK: 'Partial',
  VERIFICATION_COMMANDS: 'git branch --show-current | grep feature/auth && ls src/auth',
};

// Render plan using template
Skill({
  skill: 'template-renderer',
  args: {
    templateName: 'plan-template',
    outputPath: '.claude/context/plans/user-auth-plan.md',
    tokens: tokens
  }
});

</formatting_example>

规范章节顺序（铁律）

plan-generator 生成的每份计划都 MUST 恰好包含以下 6 个顶级章节，并严格按照此顺序排列：

1. ## Problem — 为什么这项工作很重要；要解决的痛点或差距
2. ## Decision — 要做什么；选定的方法（不是步骤，而是选择）
3. ## Scope — 范围内的内容；明确列出范围外的内容
4. ## Risks — 可能出现的问题；包含缓解措施和回滚命令
5. ## Steps — 按顺序排列的实施检查清单，使用 - [ ] 任务格式
6. ## Done Criteria — 验收标准；证明工作已完成的客观条件

规则：

• 必须包含全部 6 个章节 — 缺少任何章节的计划均无效
• 章节必须按照上述顺序排列 — 调整顺序无效
• 每个章节都必须包含实质性内容（不能使用“TBD”之类的占位内容）
• 每个章节内允许添加子章节和更多细节
• 任务完成时，pre-completion-validation 钩子会强制检查此顺序（严重性：警告）

为什么要固定顺序？ AI 生成的计划经常会调整章节顺序或遗漏范围／风险，导致执行不完整。固定顺序便于自动验证，并能在 AI 草率生成的计划进入执行阶段前发现问题。

铁律

1. 始终在每项任务中包含一条可执行命令 — 没有命令的任务只是愿望，而非行动；包含愿望的计划在执行时会停滞，因为 Agent 无事可做。
2. 绝不创建任务数超过 7 个的阶段 — 任务数超过 7 个的阶段会造成认知负担过重、错失并行机会，并使回滚范围难以界定。
3. 始终在每个阶段之间设置验证关卡 — 未经验证就继续执行，会导致第 N 阶段的问题直到第 N+3 阶段才被发现，使回滚复杂度呈指数级增加。
4. 绝不在未明确列出破坏性操作的回滚命令时生成计划 — 没有回滚路径的计划无法恢复；必须在尝试操作前指定回滚方案。
5. 始终在最终确定计划前协调专家意见（Analyst、PM、Architect）— 未经领域专家审查就生成的计划，常常会遗漏隐含要求，导致执行路径不完整。
6. 始终在每份计划中将强制任务“最终：自我审查 + 令牌报告”作为最后一项任务 — 缺少此任务时，流水线完成后将无法了解成本或进行质量自评，并且流水线后的钩子永远不会触发。
7. 始终严格按照此顺序输出 6 个规范章节（Problem → Decision → Scope → Risks → Steps → Done Criteria）— 缺少章节或调整顺序的计划会被 pre-completion-validation 拒绝。

强制最终任务（铁律 — 绝不跳过）

每个计划都必须将此任务列为最后一项，并设置为依赖所有其他任务：

任务：“最终：自我审查 + 令牌报告”

• 描述：“运行 ccusage，显示今天的令牌用量/成本（npx ccusage@latest --model --today）。然后进行自我审查：我能否改进此工作流中的任何交付成果？如果可以，通过 reflection-spawn-request.json 创建一条反思。绝不将失败归咎于既有问题。在 TaskUpdate(completed) 中将 metadata.isFinalTask = true 和 metadata.pipelineComplete = true 标记为 true。”
• 此任务绝不可省略。无论计划复杂度如何，它都是每个计划的一部分。
• 此任务必须将 metadata.isFinalTask = true 设为 true，以触发流水线后置钩子。

规划器应输出的 TaskCreate 示例：

TaskCreate({
  subject: "Final: Self-review + token report",
  description: "1. Run: npx ccusage@latest --model --today — display token costs\n2. Self-review all deliverables: Can I improve this?\n3. If improvements found, queue reflection-spawn-request\n4. NEVER dismiss failures as pre-existing\n5. TaskUpdate(completed, { metadata: { isFinalTask: true, pipelineComplete: true } })",
  activeForm: "Running self-review and token report"
})

规则

规划铁律

EVERY TASK MUST HAVE AN EXECUTABLE COMMAND

没有命令的任务不算任务——只是愿望。

必备要素

• 每项任务都必须包含：复选框、ID、时间估算、命令、验证方式
• 每个阶段都必须包含：验证关卡、错误处理
• 每项风险都必须包含：回滚命令

反模式（请勿采用）

反模式	问题	修正
“安装 X”但不提供命令	无法执行	添加：cp -r source dest
“验证 Y 是否正常”	含糊不清	添加：npm test | grep PASS
“更新 Z”	是哪个文件？要做什么更改？	添加精确的 Edit 或 sed 命令
未估算时间	无法追踪进度	为每项任务添加 (~X min)
没有回滚方案	无法从失败中恢复	添加回滚命令

质量检查清单

完成计划前，请确认：

• 我能否复制粘贴每条命令并运行？
• 每条验证命令是否都有明确的通过/失败输出？
• 每项任务是否都有能客观证明其完成的 verify 命令？
• 每项任务是否都有可衡量且明确无歧义的 done 标准？
• 每项破坏性操作是否都有回滚方案？
• 时间估算是否现实且粒度合理？
• 并行任务是否标记了 ⚡？

模板集成

此技能使用 template-renderer 技能生成格式化计划：

集成流程：

1. plan-generator 创建结构化计划数据（JSON）
2. 将计划数据映射到模板令牌（见第 6 步）
3. 使用 plan-template 调用 template-renderer
4. 将渲染后的计划输出到 .claude/context/plans/

必需令牌（用于 plan-template）：

• 核心：PLAN_TITLE、DATE、FRAMEWORK_VERSION、STATUS
• 摘要：EXECUTIVE_SUMMARY、TOTAL_TASKS、ESTIMATED_TIME、STRATEGY
• 阶段：PHASE_N_NAME、PHASE_N_PURPOSE、DEPENDENCIES、PARALLEL_OK
• 验证：VERIFICATION_COMMANDS

完整令牌列表请参见 .claude/templates/plan-template.md。

相关技能

• template-renderer - 通过令牌替换渲染 plan-template
• writing-plans - 提供完整实现代码的精简任务计划
• discuss-phase - 在规划 HIGH/EPIC 任务之前消除需求歧义

记忆协议（强制）

开始前：

cat .claude/context/memory/learnings.md

完成后：

• 新模式 -> .claude/context/memory/learnings.md
• 发现问题 -> .claude/context/memory/issues.md
• 做出决策 -> .claude/context/memory/decisions.md

假设会发生中断：你的上下文可能会重置。如果没有记录在记忆中，就等于没有发生。