workflow-plan

4 フェーズの計画ワークフロー、計画品質の検証、対話型の再計画を統合した計画スキルです。IMPL_PLAN.md、タスク JSON、検証レポートを生成し、セッションレベルの成果物を更新して計画のライフサイクルを管理します。モード（plan | verify | replan）に応じて処理を振り分け、純粋なオーケストレーターとしてフェーズを実行し、出力を解析してコンテキストを引き継ぎます。

1. アーキテクチャの概要

┌──────────────────────────────────────────────────────────────────┐
│  Workflow Plan Orchestrator (SKILL.md)                            │
│  → Route by mode: plan | verify | replan                         │
│  → Pure coordinator: Execute phases, parse outputs, pass context │
└──────────────────────────────────┬───────────────────────────────┘
                                │
        ┌───────────────────────┼───────────────────────┐
        ↓                       ↓                       ↓
  ┌───────────┐          ┌───────────┐           ┌───────────┐
  │ Plan Mode │          │  Verify   │           │  Replan   │
  │ (default) │          │   Mode    │           │   Mode    │
  │ Phase 1-4 │          │  Phase 5  │           │  Phase 6  │
  └─────┬─────┘          └───────────┘           └───────────┘
        │
    ┌───┼───┬───┐
    ↓   ↓   ↓   ↓
  ┌───┐┌───┐┌───┐┌───┐
  │ 1 ││ 2 ││ 3 ││ 4 │
  │Ses││Ctx││Con││Gen│
  └───┘└───┘└───┘└─┬─┘
                    ↓
              ┌───────────┐
              │ Confirm   │─── Verify ──→ Phase 5
              │ (choice)  │─── Execute ─→ Skill("workflow-execute")
              └───────────┘─── Review ──→ Display session status inline

2. 主な設計原則

1. 純粋なオーケストレーター：SKILL.md はルーティングと調整のみを担当し、実行の詳細はフェーズファイルに記載します
2. 段階的なフェーズ読み込み：フェーズの実行直前に、そのフェーズのドキュメントのみを読み込みます
3. 複数モードのルーティング：単一のスキルでモードを検出し、plan／verify／replan を処理します
4. タスクアタッチメントモデル：サブコマンドのタスクをアタッチして順次実行し、その後折りたたみます
5. 自動継続：各フェーズの完了後、次の保留中フェーズを自動的に実行します
6. 状態の蓄積：planning-notes.md がフェーズ間のコンテキストを保持し、N+1 の判断に活用します

3. 対話による設定の収集

フェーズの実行に振り分ける前に、AskUserQuestion を使ってワークフローの設定を収集します：

// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) {
  // 自动模式：跳过所有询问，使用默认值
  workflowPreferences = { autoYes: true, interactive: false }
} else {
  const prefResponse = AskUserQuestion({
    questions: [
      {
        question: "是否跳过所有确认步骤（自动模式）？",
        header: "Auto Mode",
        multiSelect: false,
        options: [
          { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" },
          { label: "Auto", description: "跳过所有确认，自动执行" }
        ]
      }
    ]
  })

  workflowPreferences = {
    autoYes: prefResponse.autoMode === 'Auto'
  }

  // For replan mode, also collect interactive preference
  if (mode === 'replan') {
    const replanPref = AskUserQuestion({
      questions: [
        {
          question: "是否使用交互式澄清模式？",
          header: "Replan Mode",
          multiSelect: false,
          options: [
            { label: "Standard (Recommended)", description: "使用安全默认值" },
            { label: "Interactive", description: "通过提问交互式澄清修改范围" }
          ]
        }
      ]
    })
    workflowPreferences.interactive = replanPref.replanMode === 'Interactive'
  }
}

workflowPreferences はコンテキスト変数としてフェーズの実行に渡され、各フェーズ内では workflowPreferences.autoYes、workflowPreferences.interactive として参照されます。

4. モードの検出

const args = $ARGUMENTS
const mode = detectMode(args)

function detectMode(args) {
  // Skill trigger determines mode
  if (skillName === 'workflow-plan-verify') return 'verify'
  if (skillName === 'workflow:replan') return 'replan'
  return 'plan'  // default: workflow-plan
}

5. コンパクト化からの復旧（フェーズの永続化）

複数フェーズの計画（Phase 1-4/5/6）は長い会話にまたがります。二重の保護策を使用します。TodoWrite でアクティブなフェーズを追跡してコンパクト化から保護し、sentinel を予備策として使用します。

⚠️ COMPACT DIRECTIVE：コンテキストをコンパクト化する際は、必ず TodoWrite のフェーズ状態を確認してください。 現在 in_progress としてマークされているフェーズが実行中のフェーズです。その内容はすべて保持してください。 completed または pending としてマークされたフェーズのみをコンパクト化してください。

6. 実行フロー

Plan モード（デフォルト）

Input Parsing:
   └─ Convert user input to structured format (GOAL/SCOPE/CONTEXT)

Phase 1: Session Discovery
   └─ Ref: Read("phases/01-session-discovery.md")
      └─ Output: sessionId (WFS-xxx), planning-notes.md

Phase 2: Context Gathering
   └─ Ref: Read("phases/02-context-gathering.md")
      ├─ Tasks attached: Analyze structure → Identify integration → Generate package
      └─ Output: contextPath + conflictRisk

Phase 3: Conflict Resolution (conditional: conflictRisk ≥ medium)
   └─ Decision (conflictRisk check):
      ├─ conflictRisk ≥ medium → Ref: Read("phases/03-conflict-resolution.md")
      │   ├─ Tasks attached: Detect conflicts → Present to user → Apply strategies
      │   └─ Output: Modified brainstorm artifacts
      └─ conflictRisk < medium → Skip to Phase 4

Phase 4: Task Generation
   └─ Ref: Read("phases/04-task-generation.md")
      └─ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md

Plan Confirmation (User Decision Gate):
   └─ Decision (user choice):
      ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5 (plan-verify)
      ├─ "Start Execution" → Skill(skill="workflow-execute")
      └─ "Review Status Only" → Display session status inline

Verify モード

Phase 5: Plan Verification
   └─ Ref: Read("phases/05-plan-verify.md")
      └─ Output: PLAN_VERIFICATION.md with quality gate recommendation

Replan モード

Phase 6: Interactive Replan
   └─ Ref: Read("phases/06-replan.md")
      └─ Output: Updated IMPL_PLAN.md, task JSONs, TODO_LIST.md

フェーズ参照ドキュメント（フェーズの実行時に必要に応じて読み込みます）：

フェーズ	ドキュメント	目的	モード	コンパクト化
1	phases/01-session-discovery.md	ワークフローセッションの作成または検出	plan	TodoWrite 駆動
2	phases/02-context-gathering.md	プロジェクトのコンテキストを収集し、コードベースを分析	plan	TodoWrite 駆動
3	phases/03-conflict-resolution.md	競合を検出して解決（条件付き）	plan	TodoWrite 駆動
4	phases/04-task-generation.md	実装計画とタスク JSON を生成	plan	TodoWrite 駆動 + 🔄 sentinel
5	phases/05-plan-verify.md	品質ゲートを備えた読み取り専用の検証	verify	TodoWrite 駆動
6	phases/06-replan.md	境界を明確化しながら対話型で再計画	replan	TodoWrite 駆動

コンパクト化のルール：

1. TodoWrite in_progress → 内容をすべて保持し、コンパクト化しない
2. TodoWrite completed → 要約にコンパクト化可能
3. 🔄 sentinel の予備策 → Phase 4 にはコンパクト化用 sentinel が含まれます。コンパクト化後に sentinel のみが残り、完全な Step プロトコルが残っていない場合は、ただちに Read("phases/04-task-generation.md") を実行して復元してください

7. 基本ルール

1. ただちに開始：最初のアクションでモード検出と TodoWrite の初期化を行い、2 番目のアクションでフェーズを実行します
2. 事前分析を行わない：Phase 1 より前にファイルを読み込んだり、構造を分析したり、コンテキストを収集したりしないでください
3. すべての出力を解析：各フェーズの出力から必要なデータを抽出し、次のフェーズに渡してください
4. TodoList による自動継続：TodoList の状態を確認し、次の保留中フェーズを自動的に実行してください
5. 進捗を追跡：タスクのアタッチ／折りたたみパターンに応じて、TodoWrite を動的に更新してください
6. タスクアタッチメントモデル：スキルの実行時にサブタスクを現在のワークフローにアタッチします。オーケストレーター自身がアタッチされたタスクを実行し、完了後に折りたたみます
7. 段階的なフェーズ読み込み：フェーズの実行直前に、そのフェーズのドキュメントのみを読み込みます
8. 停止しない：複数フェーズのワークフローを継続します。アタッチされたタスクをすべて実行したら、ただちにそれらを折りたたみ、次のフェーズを実行してください

## 8. 入力処理

ユーザー入力を構造化形式に変換：

1. シンプルなテキスト → 構造化します：

   User: "Build authentication system"
   
   Structured:
   GOAL: Build authentication system
   SCOPE: Core authentication features
   CONTEXT: New implementation
   

2. 詳細なテキスト → 要素を抽出します：

   User: "Add JWT authentication with email/password login and token refresh"
   
   Structured:
   GOAL: Implement JWT-based authentication
   SCOPE: Email/password login, token generation, token refresh endpoints
   CONTEXT: JWT token-based security, refresh token rotation
   

3. ファイル参照（例：requirements.md）→ 読み取って構造化します：

   • ファイルの内容を読み取る
   • 目標、範囲、要件を抽出する
   • 構造化された説明に整形する

9. データフロー

計画モード

User Input (task description)
    ↓
[Convert to Structured Format]
    ↓ Structured Description:
    ↓   GOAL: [objective]
    ↓   SCOPE: [boundaries]
    ↓   CONTEXT: [background]
    ↓
Phase 1: session:start --auto "structured-description"
    ↓ Output: sessionId
    ↓ Write: planning-notes.md (User Intent section)
    ↓
Phase 2: context-gather --session sessionId "structured-description"
    ↓ Input: sessionId + structured description
    ↓ Output: contextPath (context-package.json) + conflictRisk
    ↓ Update: planning-notes.md (Context Findings + Consolidated Constraints)
    ↓
Phase 3: conflict-resolution [conditional: conflictRisk ≥ medium]
    ↓ Input: sessionId + contextPath + conflictRisk
    ↓ Output: Modified brainstorm artifacts
    ↓ Update: planning-notes.md (Conflict Decisions + Consolidated Constraints)
    ↓ Skip if conflictRisk is none/low → proceed directly to Phase 4
    ↓
Phase 4: task-generate-agent --session sessionId
    ↓ Input: sessionId + planning-notes.md + context-package.json + brainstorm artifacts
    ↓ Output: IMPL_PLAN.md, task JSONs, TODO_LIST.md
    ↓
Plan Confirmation (User Decision Gate):
    ├─ "Verify Plan Quality" (Recommended) → Route to Phase 5
    ├─ "Start Execution" → Skill(skill="workflow-execute")
    └─ "Review Status Only" → Display session status inline

セッションメモリのフロー：各フェーズにはセッション ID が渡され、次の情報にアクセスできます：

• 以前のタスクの要約
• 既存のコンテキストと分析
• ブレインストーミングの成果物（フェーズ 3 によって変更されている可能性があります）
• セッション固有の設定

検証モード

Input: --session sessionId (or auto-detect)
    ↓
Phase 5: Load artifacts → Agent-driven verification → Generate report
    ↓ Output: PLAN_VERIFICATION.md with quality gate

再計画モード

Input: [--session sessionId] [task-id] "requirements"
    ↓
Phase 6: Mode detection → Clarification → Impact analysis → Backup → Apply → Verify
    ↓ Output: Updated artifacts + change summary

10. TodoWrite パターン

基本概念：タスクを動的に追加・折りたたむことで、ワークフローの実行状況をリアルタイムに確認できます。

主な原則

1. タスクの追加（フェーズ実行時）：

   • サブタスクをオーケストレーターの TodoWrite に追加します
   • フェーズ 2、3：複数のサブタスクを追加します
   • フェーズ 1、4：単一のタスク（アトミック）です
   • 最初に追加したタスクを in_progress に、残りを pending に設定します
   • オーケストレーターが追加されたタスクを順番に実行します

2. タスクの折りたたみ（サブタスク完了後）：

   • フェーズ 2、3 に適用：詳細なサブタスクを TodoWrite から削除します
   • 高レベルのフェーズ概要に折りたたみます
   • フェーズ 1、4：単一のタスクなので、折りたたむ必要はありません。完了としてマークするだけです
   • オーケストレーターの表示を簡潔に保ちます

3. 継続的な実行：完了後、次の保留中のフェーズに自動的に進みます

ライフサイクル：初期状態は pending → フェーズ実行（タスクを追加）→ サブタスクを実行 → フェーズ完了（フェーズ 2、3 はタスクを折りたたみ、フェーズ 1、4 は完了としてマーク）→ 次のフェーズ → 繰り返し

フェーズ 2（タスク追加済み）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "in_progress"},
  {"content": "  → Analyze codebase structure", "status": "in_progress"},
  {"content": "  → Identify integration points", "status": "pending"},
  {"content": "  → Generate context package", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

フェーズ 2（折りたたみ後）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

フェーズ 3（タスク追加済み、条件付き）：

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Conflict Resolution", "status": "in_progress"},
  {"content": "  → Detect conflicts with CLI analysis", "status": "in_progress"},
  {"content": "  → Present conflicts to user", "status": "pending"},
  {"content": "  → Apply resolution strategies", "status": "pending"},
  {"content": "Phase 4: Task Generation", "status": "pending"}
]

注：TodoWrite の更新例の詳細については、各フェーズの説明を参照してください。

11. フェーズ後の更新

各フェーズの完了後、planning-notes.md を更新します：

• フェーズ 1 の後：ユーザーの意図（GOAL、KEY_CONSTRAINTS）で初期化する
• フェーズ 2 の後：コンテキストの調査結果（CRITICAL_FILES、ARCHITECTURE、CONFLICT_RISK、CONSTRAINTS）を追加する
• フェーズ 3 の後：実行された場合、競合に関する判断（RESOLVED、MODIFIED_ARTIFACTS、CONSTRAINTS）を追加する
• メモリ状態の確認：負荷の高いフェーズ（フェーズ 2～3）の後、コンテキストウィンドウの使用量を評価します。使用量が多い場合（>120K トークン）、compact を実行します

更新コードの詳細については、各フェーズのファイルを参照してください。

12. エラー処理

• 解析失敗：出力の解析に失敗した場合は、コマンドを 1 回再試行してからエラーを報告します
• 検証失敗：検証に失敗した場合は、不足しているファイルまたはデータを報告します
• コマンド失敗：フェーズを in_progress のままにし、エラーをユーザーに報告して、次のフェーズには進みません
• セッションが見つからない（検証／再計画）：利用可能なセッションの一覧とともにエラーを報告します
• タスクが見つからない（再計画）：利用可能なタスクの一覧とともにエラーを報告します

13. コーディネーターのチェックリスト

計画モード

• 事前フェーズ：ユーザー入力を構造化形式（GOAL/SCOPE/CONTEXT）に変換します
• すべてのコマンドの前に TodoWrite を初期化します（フェーズ 2 の後にフェーズ 3 が動的に追加されます）
• フェーズ 1 を構造化された説明とともに直ちに実行します
• フェーズ 1 の出力からセッション ID を解析し、メモリに保存します
• セッションの整合性：既存のセッションを再利用する場合は、ステップ 1.2.5 の sessionIntegrity を確認します。不完全なブレインストーミングの成果物がある場合は、警告を記録します
• セッション ID と構造化された説明をフェーズ 2 のコマンドに渡します
• フェーズ 2 の出力からコンテキストパスを解析し、メモリに保存します
• context-package.json から conflictRisk を抽出します：フェーズ 3 を実行するかどうかを判断します
• conflictRisk ≥ medium の場合：sessionId と contextPath を指定して、フェーズ 3 の競合解決を開始します
• フェーズ 3 が実行された場合は、その完了を待ち、conflict-resolution.json が作成されたことを確認します
• conflictRisk が none/low の場合：フェーズ 3 をスキップし、フェーズ 4 に直接進みます
• セッション ID をフェーズ 4 のコマンドに渡します
• フェーズ 4 のすべての出力を確認します
• 計画確認ゲート：ユーザーに選択肢を提示します（検証 → フェーズ 5／実行／ステータスを確認）
• ユーザーが検証を選択した場合：phases/05-plan-verify.md を読み込み、フェーズ 5 をプロセス内で実行します
• ユーザーが実行を選択した場合：Skill(skill="workflow-execute")
• ユーザーが確認を選択した場合：セッションのステータスをインラインで表示します
• 自動モード（workflowPreferences.autoYes）：「計画の品質を検証」を自動選択し、PROCEED の場合は実行に自動で続行します
• 各フェーズの後に TodoWrite を更新します
• 各フェーズの後、TodoList のステータスに基づいて次のフェーズに自動で続行します

検証モード

• セッションを検出／検証します（アクティブなセッションから自動検出します）
• 1 つの検証タスクで TodoWrite を初期化します
• フェーズ 5 の検証エージェントを実行します
• 品質ゲートの結果と次のステップの選択肢を提示します

再計画モード

• $ARGUMENTS からタスク ID を解析します（該当する場合は IMPL-N 形式）
• 操作モード（タスクまたはセッション）を検出します
• 再計画専用のタスクで TodoWrite を初期化します
• フェーズ 6 のすべてのサブフェーズ（明確化 → 影響評価 → バックアップ → 適用 → 検証）を実行します

14. 構造テンプレートの参照

最小構成：

GOAL: [What to achieve]
SCOPE: [What's included]
CONTEXT: [Relevant info]

詳細な構成（コンテキストがより多くある場合は任意）：

GOAL: [Primary objective]
SCOPE: [Included features/components]
CONTEXT: [Existing system, constraints, dependencies]
REQUIREMENTS: [Specific technical requirements]
CONSTRAINTS: [Limitations or boundaries]

15. 関連スキル

前提スキル:

• brainstorm スキル - 任意: 計画前にロールベースの分析を生成します
• brainstorm スキル - 任意: 明確化を通じてブレインストーム分析を洗練します

Plan モードから呼び出されるもの (4 フェーズ):

• /workflow:session:start - フェーズ 1: ワークフローセッションを作成または検出します
• phases/02-context-gathering.md - フェーズ 2: プロジェクトコンテキストを収集し、コードベースを分析します (インライン)
• phases/03-conflict-resolution.md - フェーズ 3: 競合を検出して解決します (インライン、条件付き)
• memory-capture スキル - フェーズ 3: メモリ最適化 (コンテキストが制限に近づいている場合)
• phases/04-task-generation.md - フェーズ 4: タスク JSON ファイルを生成します (インライン)

フォローアップスキル:

• workflow-plan スキル (plan-verify フェーズ) - 計画の品質を検証します (verify モードからも呼び出せます)
• セッションステータスをインラインで表示 - タスクの内訳と現在の進捗を確認します
• Skill(skill="workflow-execute") - 生成されたタスクの実装を開始します (skill: workflow-execute)
• workflow-plan スキル (replan フェーズ) - 計画を変更します (replan モードからも呼び出せます)

<auto_mode> workflowPreferences.autoYes が true の場合 (-y または --yes フラグによるトリガー、またはユーザーが「Auto」モードを選択した場合):

• すべての確認プロンプトをスキップし、デフォルト値を使用します
• Plan Confirmation Gate で「Verify Plan Quality」を自動選択します
• 検証が PROCEED を返した場合、自動的に実行へ進みます
• replan モードでの対話的な明確化をスキップします (安全なデフォルトを使用) </auto_mode>

<success_criteria>

• スキルトリガーからモードを正しく検出する (plan / verify / replan)
• TodoWrite を初期化し、attachment/collapse パターンで各フェーズ後に更新する
• すべてのフェーズを順番に実行し、フェーズ間で適切にデータを渡す
• フェーズドキュメントは、フェーズの実行直前にのみ Read() を介して段階的にロードする
• planning-notes.md を各フェーズ後に更新し、コンテキストを蓄積する
• フェーズ 3 は conflictRisk の評価に基づいて条件付きで実行する
• フェーズ 4 の後に正しい選択肢を提示して Plan Confirmation Gate を表示する
• すべての出力成果物を生成する: IMPL_PLAN.md、タスク JSON、TODO_LIST.md
• コンパクトリカバリが機能する: in_progress フェーズは保持され、completed フェーズは圧縮可能
• エラーハンドリングが解析失敗、検証失敗、セッション/タスクの欠落をカバーする </success_criteria>