workflow-multi-cli-plan

複数 CLI による共同プランニング

自動モード

workflowPreferences.autoYes が true の場合：プランを自動承認し、推奨される解決策と実行方法（Agent、レビューをスキップ）を使用します。

コンテキストソース：ACE セマンティック検索 + 複数 CLI による分析 出力ディレクトリ：.workflow/.multi-cli-plan/{session-id}/ デフォルトの最大ラウンド数：3（収束すれば、より早く完了する場合があります） CLI ツール：@cli-discuss-agent（分析）、@cli-lite-planning-agent（プラン生成） 実行：プラン承認後、自動的に workflow-lite-execute に引き継ぎます

オーケストレーターの境界（重要）

• 複数 CLI による共同プランニングの唯一のコマンド
• 管理対象：セッション状態、ユーザーの決定、エージェントへの委任、フェーズ遷移
• 委任先：CLI の実行は @cli-discuss-agent、プラン生成は @cli-lite-planning-agent

実行フロー

Phase 1: Context Gathering
   └─ ACE semantic search, extract keywords, build context package

Phase 2: Multi-CLI Discussion (Iterative, via @cli-discuss-agent)
   ├─ Round N: Agent executes Gemini + Codex + Claude
   ├─ Cross-verify findings, synthesize solutions
   ├─ Write synthesis.json to rounds/{N}/
   └─ Loop until convergence or max rounds

Phase 3: Present Options
   └─ Display solutions with trade-offs from agent output

Phase 4: User Decision
   ├─ Select solution approach
   ├─ Select execution method (Agent/Codex/Auto)
   ├─ Select code review tool (Skip/Gemini/Codex/Agent)
   └─ Route:
      ├─ Approve → Phase 5
      ├─ Need More Analysis → Return to Phase 2
      └─ Cancel → Save session

Phase 5: Plan Generation & Execution Handoff
   ├─ Generate plan.json + .task/*.json (via @cli-lite-planning-agent, two-layer output)
   ├─ Build executionContext with user selections and taskFiles
   └─ Execute via workflow-lite-execute

エージェントの役割

エージェント	責任
オーケストレーター	セッション管理、ACE コンテキスト、ユーザーの決定、フェーズ遷移、executionContext の構築
@cli-discuss-agent	複数 CLI の実行（Gemini/Codex/Claude）、相互検証、解決策の統合、synthesis.json の出力
@cli-lite-planning-agent	タスクの分解、2 層の出力：plan.json（task_ids[] を含む概要）+ .task/*.json（タスクファイル）

主な役割

フェーズ 1：コンテキストの収集

セッションの初期化：

const sessionId = `MCP-${taskSlug}-${date}`
const sessionFolder = `.workflow/.multi-cli-plan/${sessionId}`
Bash(`mkdir -p ${sessionFolder}/rounds`)

ACE コンテキストのクエリ：

const aceQueries = [
  `Project architecture related to ${keywords}`,
  `Existing implementations of ${keywords[0]}`,
  `Code patterns for ${keywords} features`,
  `Integration points for ${keywords[0]}`
]
// Execute via mcp__ace-tool__search_context

コンテキストパッケージ（エージェントに渡す）：

• relevant_files[] - ACE が特定したファイル
• detected_patterns[] - 見つかったコードパターン
• architecture_insights - 構造の把握

フェーズ 2：エージェントへの委任

基本原則：オーケストレーターは委任と出力の読み取りのみを行い、CLI を直接実行しません。CLI 呼び出しでは必ず Bash を run_in_background: true とともに使用し、フックのコールバックを待ちます。TaskOutput によるポーリングは行わないでください。

エージェントの呼び出し：

Agent({
  subagent_type: "cli-discuss-agent",
  run_in_background: false,
  description: `Discussion round ${currentRound}`,
  prompt: `
## Input Context
- task_description: ${taskDescription}
- round_number: ${currentRound}
- session: { id: "${sessionId}", folder: "${sessionFolder}" }
- ace_context: ${JSON.stringify(contextPackage)}
- previous_rounds: ${JSON.stringify(analysisResults)}
- user_feedback: ${userFeedback || 'None'}
- cli_config: { tools: ["gemini", "codex"], mode: "parallel", fallback_chain: ["gemini", "codex", "claude"] }

## Execution Process
1. Parse input context (handle JSON strings)
2. Check if ACE supplementary search needed
3. Build CLI prompts with context
4. Execute CLIs (parallel or serial per cli_config.mode)
5. Parse CLI outputs, handle failures with fallback
6. Perform cross-verification between CLI results
7. Synthesize solutions, calculate scores
8. Calculate convergence, generate clarification questions
9. Write synthesis.json

## Output
Write: ${sessionFolder}/rounds/${currentRound}/synthesis.json

## Completion Checklist
- [ ] All configured CLI tools executed (or fallback triggered)
- [ ] Cross-verification completed with agreements/disagreements
- [ ] 2-3 solutions generated with file:line references
- [ ] Convergence score calculated (0.0-1.0)
- [ ] synthesis.json written with all Primary Fields
`
})

エージェント出力の読み取り：

const synthesis = JSON.parse(Read(`${sessionFolder}/rounds/${round}/synthesis.json`))
// Access top-level fields: solutions, convergence, cross_verification, clarification_questions

収束の判断：

if (synthesis.convergence.recommendation === 'converged') {
  // Proceed to Phase 3
} else if (synthesis.convergence.recommendation === 'user_input_needed') {
  // Collect user feedback, return to Phase 2
} else {
  // Continue to next round if new_insights && round < maxRounds
}

フェーズ 3：選択肢の提示

synthesis.solutions[] の解決策を表示します。表示内容：名前、ソース CLI、工数／リスク、長所／短所、影響を受けるファイル（file:line）。相互検証での合意数／不一致数も表示します。

フェーズ 4：ユーザーの決定

AskUserQuestion({
  questions: [
    {
      question: "Which solution approach?",
      header: "Solution",
      multiSelect: false,
      options: solutions.map((s, i) => ({
        label: `Option ${i+1}: ${s.name}`,
        description: `${s.effort} effort, ${s.risk} risk`
      })).concat([
        { label: "Need More Analysis", description: "Return to Phase 2" }
      ])
    },
    {
      question: "Execution method:",
      header: "Execution",
      multiSelect: false,
      options: [
        { label: "Agent", description: "@code-developer agent" },
        { label: "Codex", description: "codex CLI tool" },
        { label: "Auto", description: "Auto-select based on complexity" }
      ]
    },
    {
      question: "Code review after execution?",
      header: "Review",
      multiSelect: false,
      options: [
        { label: "Skip", description: "No review" },
        { label: "Gemini Review", description: "Gemini CLI tool" },
        { label: "Codex Review", description: "Codex CLI: prompt-based code quality review (--mode analysis)" },
        { label: "Agent Review", description: "Current agent review" }
      ]
    }
  ]
})

振り分け：

• 承認 + 実行方法 → フェーズ 5
• さらに分析が必要 → フィードバックを添えてフェーズ 2 へ
• キャンセル → 再開できるようセッションを保存

TodoWrite の更新（フェーズ 4 の決定）：

const executionLabel = userSelection.execution_method  // "Agent" / "Codex" / "Auto"

TodoWrite({ todos: [
  { content: "Phase 1: Context Gathering", status: "completed", activeForm: "Gathering context" },
  { content: "Phase 2: Multi-CLI Discussion", status: "completed", activeForm: "Running discussion" },
  { content: "Phase 3: Present Options", status: "completed", activeForm: "Presenting options" },
  { content: `Phase 4: User Decision [${executionLabel}]`, status: "completed", activeForm: "Decision recorded" },
  { content: `Phase 5: Plan Generation [${executionLabel}]`, status: "in_progress", activeForm: `Generating plan [${executionLabel}]` }
]})

フェーズ 5：プラン生成と実行への引き継ぎ

ステップ 1：コンテキストパッケージを作成（オーケストレーターの責任）：

const contextPackage = {
  solution: {
    name: selectedSolution.name,
    source_cli: selectedSolution.source_cli,
    feasibility: selectedSolution.feasibility,
    effort: selectedSolution.effort,
    risk: selectedSolution.risk,
    summary: selectedSolution.summary
  },
  implementation_plan: selectedSolution.implementation_plan,
  dependencies: selectedSolution.dependencies || { internal: [], external: [] },
  technical_concerns: selectedSolution.technical_concerns || [],
  consensus: {
    agreements: synthesis.cross_verification.agreements,
    resolved_conflicts: synthesis.cross_verification.resolution
  },
  constraints: userConstraints || [],
  task_description: taskDescription,
  session_id: sessionId
}
Write(`${sessionFolder}/context-package.json`, JSON.stringify(contextPackage, null, 2))

ステップ 2：プランニングエージェントを呼び出す：

Agent({
  subagent_type: "cli-lite-planning-agent",
  run_in_background: false,
  description: "Generate implementation plan",
  prompt: `
## Schema Reference
Execute: cat ~/.ccw/workflows/cli-templates/schemas/plan-overview-base-schema.json
Execute: cat ~/.ccw/workflows/cli-templates/schemas/task-schema.json

## Output Format: Two-Layer Structure
- plan.json: Overview with task_ids[] referencing .task/ files (NO tasks[] array)
- .task/TASK-*.json: Independent task files following task-schema.json

plan.json required: summary, approach, task_ids, task_count, _metadata (with plan_type)
Task files required: id, title, description, depends_on, convergence (with criteria[])
Task fields: files[].change (not modification_points), convergence.criteria (not acceptance), test (not verification)

## Context-Package (from orchestrator)
${JSON.stringify(contextPackage, null, 2)}

## Execution Process
1. Read plan-overview-base-schema.json + task-schema.json for output structure
2. Read project-tech.json and specs/*.md
3. Parse context-package fields:
   - solution: name, feasibility, summary
   - implementation_plan: tasks[], execution_flow, milestones
   - dependencies: internal[], external[]
   - technical_concerns: risks/blockers
   - consensus: agreements, resolved_conflicts
   - constraints: user requirements
4. Use implementation_plan.tasks[] as task foundation
5. Preserve task dependencies (depends_on) and execution_flow
6. Expand tasks with convergence.criteria (testable completion conditions)
7. Create .task/ directory and write individual TASK-*.json files
8. Generate plan.json with task_ids[] referencing .task/ files

## Output
- ${sessionFolder}/plan.json (overview with task_ids[])
- ${sessionFolder}/.task/TASK-*.json (independent task files)

## Completion Checklist
- [ ] plan.json has task_ids[] and task_count (NO embedded tasks[])
- [ ] .task/*.json files preserve task dependencies from implementation_plan
- [ ] Task execution order follows execution_flow
- [ ] Key_points reflected in task descriptions
- [ ] User constraints applied to implementation
- [ ] convergence.criteria are testable
- [ ] plan.json follows plan-overview-base-schema.json
- [ ] Task files follow task-schema.json
`
})

ステップ 3：executionContext を構築：

const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
const taskFiles = plan.task_ids.map(id => `${sessionFolder}/.task/${id}.json`)

// Build executionContext (same structure as lite-plan)
executionContext = {
  planObject: plan,
  taskFiles: taskFiles,                              // Paths to .task/*.json files (two-layer format)
  explorationsContext: null,                          // Multi-CLI doesn't use exploration files
  explorationAngles: [],
  explorationManifest: null,
  clarificationContext: null,                         // Store user feedback from Phase 2 if exists
  executionMethod: userSelection.execution_method,    // From Phase 4
  codeReviewTool: userSelection.code_review_tool,     // From Phase 4
  originalUserInput: taskDescription,
  executorAssignments: null,
  session: {
    id: sessionId,
    folder: sessionFolder,
    artifacts: {
      explorations: [],                              // No explorations in multi-CLI workflow
      explorations_manifest: null,
      plan: `${sessionFolder}/plan.json`,
      task_dir: plan.task_ids ? `${sessionFolder}/.task/` : null,
      synthesis_rounds: Array.from({length: currentRound}, (_, i) =>
        `${sessionFolder}/rounds/${i+1}/synthesis.json`
      ),
      context_package: `${sessionFolder}/context-package.json`
    }
  }
}

ステップ 4：実行に引き継ぐ：

Skill({
  skill: "workflow-lite-execute",
  args: "--in-memory"
})
// executionContext is passed via global variable to workflow-lite-execute (Mode 1: In-Memory Plan)

synthesis.json スキーマ

{
  "round": 1,
  "solutions": [{
    "name": "Solution Name",
    "source_cli": ["gemini", "codex"],
    "feasibility": 0.85,
    "effort": "low|medium|high",
    "risk": "low|medium|high",
    "summary": "Brief analysis summary",
    "implementation_plan": {
      "approach": "High-level technical approach",
      "tasks": [
        {"id": "T1", "name": "Task", "depends_on": [], "files": [], "key_point": "..."}
      ],
      "execution_flow": "T1 → T2 → T3",
      "milestones": ["Checkpoint 1", "Checkpoint 2"]
    },
    "dependencies": {"internal": [], "external": []},
    "technical_concerns": ["Risk 1", "Blocker 2"]
  }],
  "convergence": {
    "score": 0.85,
    "new_insights": false,
    "recommendation": "converged|continue|user_input_needed"
  },
  "cross_verification": {
    "agreements": [],
    "disagreements": [],
    "resolution": "..."
  },
  "clarification_questions": []
}

TodoWrite パターン

初期化（フェーズ 1 の開始時）：

TodoWrite({ todos: [
  { content: "Phase 1: Context Gathering", status: "in_progress", activeForm: "Gathering context" },
  { content: "Phase 2: Multi-CLI Discussion", status: "pending", activeForm: "Running discussion" },
  { content: "Phase 3: Present Options", status: "pending", activeForm: "Presenting options" },
  { content: "Phase 4: User Decision", status: "pending", activeForm: "Awaiting decision" },
  { content: "Phase 5: Plan Generation", status: "pending", activeForm: "Generating plan" }
]})

出力ファイル構成

.workflow/.multi-cli-plan/{MCP-task-slug-YYYY-MM-DD}/
├── session-state.json          # Session tracking (orchestrator)
├── rounds/
│   ├── 1/synthesis.json        # Round 1 analysis (cli-discuss-agent)
│   ├── 2/synthesis.json        # Round 2 analysis (cli-discuss-agent)
│   └── .../
├── context-package.json        # Extracted context for planning (orchestrator)
├── plan.json                   # Plan overview with task_ids[] (NO embedded tasks[])
└── .task/                      # Independent task files
    ├── TASK-001.json            # Task file following task-schema.json
    ├── TASK-002.json
    └── ...

エラー処理

エラー	解決方法
ACE 検索に失敗	ファイルの検索には Glob/Grep にフォールバック
エージェントの実行に失敗	1 回再試行し、その後は部分的な結果を提示
CLI がタイムアウト（エージェント内）	エージェントがフォールバックを使用：gemini → codex → claude
収束しない	最良の選択肢を提示し、不確実性を明示
synthesis.json の解析エラー	エージェントに再試行を依頼
ユーザーがキャンセル	後で再開できるようセッションを保存

設定

フラグ	デフォルト	説明
--max-rounds	3	ディスカッションの最大ラウンド数
--tools	gemini,codex	分析に使用する CLI ツール
--mode	parallel	実行モード：parallel または serial
--auto-execute	false	承認後に自動実行