plan-generator

プランジェネレーター スキル

プランジェネレーター スキル - 専門エージェントと連携し、包括的な計画成果物を生成して、要件から構造化された検証済みの計画を作成します。 - 新機能の計画作成 - リファクタリングの計画 - システム移行の計画 - アーキテクチャ変更の計画 - 複雑な要件の分解 - 既存計画の検証

ステップ 0：前回のタスク情報（タスク間のコンテキスト）

新しい計画を作成する前に、重複を避け、過去の決定を踏まえて計画を立てるため、最近の作業に関するコンテキストを収集します。

1. 最近のコミット：git log --oneline -5 を実行して、最近リリースされた内容を確認します
2. 最近のタスク：TaskList() を呼び出し、関連するメタデータを持つ完了済みタスクを確認します
3. 最近の決定：.claude/context/memory/decisions.md を読み、この計画を制約するアーキテクチャ上の選択を確認します
4. 最近の問題：.claude/context/memory/issues.md を読み、既知のブロッカーや回避策を確認します

このコンテキストを次の目的に活用します。

• 最近リリースされた機能を再実装しない
• すでに行われたアーキテクチャ上の決定を尊重する（エスカレーションせずに矛盾させない）
• ゼロから始めるのではなく、完了済みの作業を基盤にする
• 関連する場合は、具体的なコミットハッシュやタスク ID を参照する

ステップ 1：要件を分析する

ユーザー要件を解析します。

• 明示的な要件を抽出する
• 暗黙的な要件を特定する
• 計画の範囲を定める
• 複雑さを評価する

ステップ 2：専門家と連携する

関連するエージェントに計画への意見を求めます。

• アナリスト：ビジネス要件と市場の背景
• 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]
```

リスク

リスク	影響	軽減策	ロールバック
[リスク]	[H/M/L]	[戦略]	[コマンド]

タイムラインの概要

フェーズ	タスク	推定時間	並列実行？
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 が出力するすべての計画には、次の 6 つのトップレベルセクションを、この順序どおりに必ず含めてください。

1. ## Problem — この作業が重要な理由。解決する課題や不足点
2. ## Decision — 実施する内容。選択したアプローチ（手順ではなく、選択した内容のみ）
3. ## Scope — 対象範囲。対象外の内容を明示的に列挙する
4. ## Risks — 想定される問題。軽減策とロールバックコマンドを含める
5. ## Steps — - [ ] タスク形式で記述する、順序付きの実装チェックリスト
6. ## Done Criteria — 完了を証明する、客観的な受け入れ基準

ルール：

• 6 つのセクションすべてが必須です。いずれかを欠く計画は無効です
• セクションは上記の順序で記述してください。順序の入れ替えは無効です
• 各セクションには具体的な内容が必要です（「TBD」のようなプレースホルダーは不可）
• 各セクション内にサブセクションや追加の詳細を含めてもかまいません
• タスク完了時には、pre-completion-validation フックがこの順序を強制します（重大度：警告）

順序を固定する理由： AI が生成する計画では、セクションの順序が入れ替わったり、スコープやリスクが省略されたりすることが頻繁にあり、実行が不完全になるためです。順序を固定することで自動検証が可能になり、AI が粗雑に生成した計画が実行に移される前に検出できます。

絶対厳守事項

1. 必ずすべてのタスクに実行可能なコマンドを含めてください。コマンドのないタスクは、行動ではなく願望です。実行するものがなく、エージェントが作業を進められないため、そのような計画は実行段階で停滞します。
2. 決して 1 つのフェーズに 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 に設定してください。」
• このタスクは任意ではありません。複雑さにかかわらず、すべての計画に含めてください。
• パイプライン後のフックを実行するため、このタスクでは metadata.isFinalTask = 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

中断されることを前提にしてください。コンテキストがリセットされる可能性があります。メモリに記録されていなければ、実行されていないのと同じです。