roadmap-with-file について
要件を反復可能なロードマップと、後続処理向けの機械可読な課題にまとめる計画専用スキルです。段階的または直接的な分解に対応し、コードベースの調査やユーザーによる調整も行えます。
主な機能
- 01段階的または直接的な計画モード
- 02ロードマップの反復的な調整
- 03JSONLでの課題保存
- 04任意のコードベース調査
- 05実行への構造化された引き継ぎ
活用シーン
- 01範囲が不確かな機能の計画
- 02明確な要件を依存タスクに分解
- 03後続の実行パイプライン向け課題の準備
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/roadmap-with-fileを入力して読み込まれたか確認します。
詳細
自動モード
--yes または -y を指定すると、戦略の選択を自動で確定し、推奨モードを使用して、対話型の改善ラウンドをスキップします。このスキルは計画のみを行います。コードを実行したり、ソースファイルを変更したりすることは決してありません。出力されるのは、ユーザーが確認するためのロードマップと課題です。
ファイル付きロードマップスキル
使用方法
$roadmap-with-file "Implement user authentication system with OAuth and 2FA"
$roadmap-with-file -m progressive "Build real-time notification system"
$roadmap-with-file -m direct "Refactor payment module"
$roadmap-with-file -m auto "Add data export feature"
$roadmap-with-file --continue "auth system"
$roadmap-with-file -y "Implement caching layer"
フラグ：
-y, --yes：すべての確認をスキップします（自動モード）-c, --continue：既存のセッションを続行します-m, --mode：戦略を選択します（progressive / direct / auto）
コンテキストソース：cli-explore-agent（任意）＋要件分析
出力ディレクトリ：.workflow/.roadmap/{session-id}/
主要な出力：roadmap.md（単一の信頼できる情報源、人間が読みやすい形式）＋issues.jsonl（グローバル、機械実行可能）
サブエージェント API リファレンス
spawn_agent
タスクを割り当てて新しいサブエージェントを作成します。
const agentId = spawn_agent({
agent_type: "{agent_type}",
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json
## TASK CONTEXT
${taskContext}
## DELIVERABLES
${deliverables}
`
})
wait_agent
サブエージェントから結果を取得します（結果を取得する唯一の方法です）。
const result = wait_agent({
timeout_ms: 1800000 // 30 minutes
})
if (result.timed_out) {
// Handle timeout via 4-step cascade: status probe → force finalize → close
}
followup_task
アクティブなサブエージェントに新しい作業を割り当てます（確認やフォローアップ用）。
followup_task({
target: agentId,
message: `
## CLARIFICATION ANSWERS
${answers}
## NEXT STEP
Continue with plan generation.
`
})
close_agent
サブエージェントのリソースをクリーンアップします（取り消せません）。
close_agent({ target: agentId })
出力成果物
単一の信頼できる情報源
| 成果物 | 目的 | 利用者 |
|---|---|---|
roadmap.md | ⭐ すべてのコンテキストを含む、人間が読みやすい戦略的ロードマップ | 人による確認、csv-wave-pipeline への引き継ぎ |
.workflow/issues/issues.jsonl | グローバルな課題ストア（追記形式） | csv-wave-pipeline、課題コマンド |
個別の JSON ファイルを作成しない理由
| 元のファイル | 削除した理由 | 内容の格納先 |
|---|---|---|
strategy-assessment.json | roadmap.md の内容と重複するため | roadmap.md の Strategy Assessment セクションに埋め込み |
exploration-codebase.json | 一度しか使わない中間ファイルのため | roadmap.md の Codebase Context 付録に埋め込み |
概要
反復的な分解を用いた、戦略的な要件ロードマップです。議論を通じて更新される単一の roadmap.md を作成し、実行用の課題はグローバルな issues.jsonl に保存します。
主要なワークフロー：把握 → 分解 → 反復 → 検証 → 引き継ぎ
主な機能：
- roadmap.md：単一の信頼できる情報源。戦略、ロードマップ、収束状況、反復履歴を記録します
- 二つの分解方式：段階的（MVP → 最適化）または直接的（トポロジカルなタスク）
- 外部調査：
web.runを通じて、アーキテクチャパターンやベストプラクティスをウェブ検索します - 課題の作成：実行パイプライン向けの課題をグローバルな
issues.jsonlに保存します - 進捗の追跡：リアルタイムでフェーズの進捗を確認できるよう、
functions.update_planを使用します - 意思決定の記録：コンテキストと根拠を含む、構造化された意思決定の履歴を記録します
- 構造化された引き継ぎ：実行計画の作成、課題の表示、または完了へ進むための最終ゲートを設けます
┌─────────────────────────────────────────────────────────────────────────┐
│ ROADMAP ITERATIVE WORKFLOW │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ Session Init │
│ ├─ Parse flags, generate session ID │
│ ├─ functions.exec_command (mkdir session folder) │
│ └─ functions.update_plan (5 phases: Understand → Decompose → │
│ Refine → Handoff → GATE) │
│ │
│ Phase 1: Requirement Understanding & Strategy │
│ ├─ Parse requirement: goal / constraints / stakeholders │
│ ├─ Assess uncertainty level → recommend mode │
│ ├─ User confirms strategy via functions.request_user_input │
│ └─ Initialize roadmap.md with Strategy Assessment │
│ │
│ Phase 2: Decomposition & Issue Creation │
│ ├─ Optional codebase exploration (functions.exec_command detection) │
│ ├─ cli-roadmap-plan-agent executes decomposition │
│ ├─ Progressive: 2-4 layers (MVP→Optimized) with convergence │
│ ├─ Direct: Topological task sequence with convergence │
│ ├─ Create issues via ccw issue create → issues.jsonl │
│ └─ Update roadmap.md with Roadmap table + Issue references │
│ │
│ Phase 3: Iterative Refinement (Multi-Round, Decision Recording) │
│ ├─ Present roadmap to user (Cumulative Context) │
│ ├─ Feedback via functions.request_user_input: │
│ │ Approve | Adjust Scope | Refine Criteria | Research/Re-decompose │
│ ├─ External research via web.run (optional — patterns, practices) │
│ ├─ Record decisions in Iteration History (Record-Before-Continue) │
│ └─ Repeat until approved (max 5 rounds) │
│ │
│ Phase 4: Handoff (PLANNING ENDS HERE) │
│ ├─ Final roadmap.md with Issue ID references │
│ └─ MANDATORY Terminal Gate: 执行计划 / 查看Issue / 完成 │
│ ├─ Execute Plan → display csv-wave-pipeline command │
│ ├─ View Issues → ccw issue list │
│ └─ Done → end workflow │
│ │
└─────────────────────────────────────────────────────────────────────────┘
二つのモード
| モード | 戦略 | 最適な用途 | 分解方式 |
|---|---|---|---|
| Progressive | MVP → 使用可能 → 洗練 → 最適化 | 不確実性が高く、検証が必要な場合 | 2～4層。各層で完全に収束させます |
| Direct | トポロジカルなタスクの順序 | 要件が明確で、技術が確定している場合 | 入力と出力を明示したタスク |
自動選択のロジック：
- 不確実性が高い要因が3つ以上 → Progressive
- 不確実性が低い要因が3つ以上 → Direct
- それ以外 → ユーザーに希望を確認
出力構成
.workflow/.roadmap/RMAP-{date}-{slug}/
└── roadmap.md # ⭐ Single source of truth
# - Strategy Assessment (embedded)
# - Roadmap Table
# - Convergence Criteria per Issue
# - Codebase Context (appendix, if applicable)
# - Iteration History
.workflow/issues/issues.jsonl # Global issue store (appended)
# - One JSON object per line
# - Consumed by csv-wave-pipeline, issue commands
roadmap.md テンプレート
# Requirement Roadmap
**Session**: RMAP-{date}-{slug}
**Requirement**: {requirement}
**Strategy**: {progressive|direct}
**Status**: {Planning|Refining|Ready}
**Created**: {timestamp}
---
## Strategy Assessment
- **Uncertainty Level**: {high|medium|low}
- **Decomposition Mode**: {progressive|direct}
- **Assessment Basis**: {factors summary}
- **Goal**: {extracted goal}
- **Constraints**: {extracted constraints}
- **Stakeholders**: {extracted stakeholders}
---
## Roadmap
### Progressive Mode
| Wave | Issue ID | Layer | Goal | Priority | Dependencies |
|------|----------|-------|------|----------|--------------|
| 1 | ISS-xxx | MVP | ... | 2 | - |
| 2 | ISS-yyy | Usable | ... | 3 | ISS-xxx |
### Direct Mode
| Wave | Issue ID | Title | Type | Dependencies |
|------|----------|-------|------|--------------|
| 1 | ISS-xxx | ... | infrastructure | - |
| 2 | ISS-yyy | ... | feature | ISS-xxx |
---
## Convergence Criteria
### ISS-xxx: {Issue Title}
- **Criteria**: [testable conditions]
- **Verification**: [executable steps/commands]
- **Definition of Done**: [business language, non-technical]
### ISS-yyy: {Issue Title}
...
---
## Risks
| Risk | Severity | Mitigation |
|------|----------|------------|
| ... | ... | ... |
---
## Iteration History
### Round 1 - {timestamp}
**User Feedback**: {feedback summary}
**Changes Made**: {adjustments}
**Status**: {approved|continue iteration}
---
## Codebase Context (Optional)
*Included when codebase exploration was performed*
- **Relevant Modules**: [...]
- **Existing Patterns**: [...]
- **Integration Points**: [...]
Issues JSONL 仕様
保存場所と形式
Path: .workflow/issues/issues.jsonl
Format: JSONL (one complete JSON object per line)
Encoding: UTF-8
Mode: Append-only (new issues appended to end)
レコードのスキーマ
{
"id": "ISS-YYYYMMDD-NNN",
"title": "[LayerName] goal or [TaskType] title",
"status": "pending",
"priority": 2,
"context": "Markdown with goal, scope, convergence, verification, DoD",
"source": "text",
"tags": ["roadmap", "progressive|direct", "wave-N", "layer-name"],
"extended_context": {
"notes": {
"session": "RMAP-{date}-{slug}",
"strategy": "progressive|direct",
"wave": 1,
"depends_on_issues": []
}
},
"lifecycle_requirements": {
"test_strategy": "unit",
"regression_scope": "affected",
"acceptance_type": "automated",
"commit_strategy": "per-issue"
}
}
クエリインターフェース
# By ID (detail view)
ccw issue list ISS-20260227-001
# List all with status filter
ccw issue list --status planned,queued
ccw issue list --brief # JSON minimal output
# Queue operations (wave-based execution)
ccw issue queue list # List all queues
ccw issue queue dag # Get dependency graph (JSON)
ccw issue next --queue <queue-id> # Get next task
# Execute
ccw issue queue add <issue-id> # Add to active queue
ccw issue done <item-id> # Mark completed
注：課題には、フィルタリング用に
tags[]フィールドでwave-Nのタグが付けられます。プログラムで解析する場合は--briefを使用してください。
実装
セッションの初期化
const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
// Parse flags
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const continueMode = $ARGUMENTS.includes('--continue') || $ARGUMENTS.includes('-c')
const modeMatch = $ARGUMENTS.match(/(?:--mode|-m)\s+(progressive|direct|auto)/)
const requestedMode = modeMatch ? modeMatch[1] : 'auto'
// Clean requirement text (remove flags)
const requirement = $ARGUMENTS
.replace(/--yes|-y|--continue|-c|--mode\s+\w+|-m\s+\w+/g, '')
.trim()
const slug = requirement.toLowerCase()
.replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-')
.substring(0, 40)
const dateStr = getUtc8ISOString().substring(0, 10)
const sessionId = `RMAP-${dateStr}-${slug}`
const sessionFolder = `.workflow/.roadmap/${sessionId}`
// Auto-detect continue mode
if (continueMode || file_exists(`${sessionFolder}/roadmap.md`)) {
// Resume existing session
const existingRoadmap = Read(`${sessionFolder}/roadmap.md`)
// Extract current phase and continue from there
}
functions.exec_command(`mkdir -p ${sessionFolder}`)
// Initialize progress tracking (MANDATORY)
functions.update_plan([
{ id: "phase-1", title: "Phase 1: Requirement Understanding & Strategy", status: "in_progress" },
{ id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "pending" },
{ id: "phase-3", title: "Phase 3: Iterative Refinement", status: "pending" },
{ id: "phase-4", title: "Phase 4: Handoff", status: "pending" },
{ id: "next-step", title: "GATE: Post-Completion Next Step", status: "pending" }
])
フェーズ 1：要件の理解と戦略
目的：要件を解析し、不確実性を評価し、分解戦略を選択して、roadmap.md を初期化します。
手順：
-
要件の解析
- 抽出項目：目標、制約、ステークホルダー、キーワード
-
不確実性の評価
const uncertaintyFactors = { scope_clarity: 'low|medium|high', technical_risk: 'low|medium|high', dependency_unknown: 'low|medium|high', domain_familiarity: 'low|medium|high', requirement_stability: 'low|medium|high' } // Calculate recommendation const highCount = Object.values(uncertaintyFactors).filter(v => v === 'high').length const lowCount = Object.values(uncertaintyFactors).filter(v => v === 'low').length let recommendedMode if (highCount >= 3) recommendedMode = 'progressive' else if (lowCount >= 3) recommendedMode = 'direct' else recommendedMode = 'progressive' // default safer choice -
戦略の選択（
-mが指定されている場合、または AUTO_YES の場合はスキップ）let selectedMode if (requestedMode !== 'auto') { selectedMode = requestedMode } else if (AUTO_YES) { selectedMode = recommendedMode } else { const answer = functions.request_user_input({ questions: [{ header: "Strategy", // max 12 chars question: `Decomposition strategy: Uncertainty=${uncertaintyLevel}, Recommended=${recommendedMode}`, multiSelect: false, options: [ { label: recommendedMode === 'progressive' ? "Progressive (Recommended)" : "Progressive", description: "MVP → Usable → Refined → Optimized layers" }, { label: recommendedMode === 'direct' ? "Direct (Recommended)" : "Direct", description: "Topological task sequence" } ] }] }) selectedMode = answer // parsed from user selection } -
roadmap.md の初期化
const roadmapContent = `# Requirement Roadmap
Session: ${sessionId} Requirement: ${requirement} Strategy: ${selectedMode} Status: Planning Created: ${getUtc8ISOString()}
Strategy Assessment
- Uncertainty Level: ${uncertaintyLevel}
- Decomposition Mode: ${selectedMode}
- Assessment Basis: ${factorsSummary}
- Goal: ${extractedGoal}
- Constraints: ${extractedConstraints}
- Stakeholders: ${extractedStakeholders}
Roadmap
To be populated after Phase 2 decomposition
Convergence Criteria Details
To be populated after Phase 2 decomposition
Risks
To be populated after Phase 2 decomposition
Iteration History
To be populated during Phase 3 refinement
Codebase Context (Optional)
To be populated if codebase exploration was performed `
Write(${sessionFolder}/roadmap.md, roadmapContent)
**成功条件**：
- 戦略評価を含む roadmap.md が作成されている
- 戦略（段階的または直接）が選択されている
- 不確実性の要因が記録されている
---
### フェーズ 2：分解と Issue の作成
**目的**：`cli-roadmap-plan-agent` を使用して分解を実行し、Issue を作成して、roadmap.md を更新します。
**手順**：
1. **任意のコードベース調査**（コードベースが検出された場合）
```javascript
// Update progress
functions.update_plan([{ id: "phase-2", title: "Phase 2: Decomposition & Issue Creation", status: "in_progress" }])
const hasCodebase = functions.exec_command(`
test -f package.json && echo "nodejs" ||
test -f go.mod && echo "golang" ||
test -f Cargo.toml && echo "rust" ||
test -f pyproject.toml && echo "python" ||
test -d src && echo "generic" ||
echo "none"
`).trim()
let codebaseContext = null
if (hasCodebase !== 'none') {
const exploreAgentId = spawn_agent({
agent_type: "cli_explore_agent",
message: `
## TASK ASSIGNMENT
### MANDATORY FIRST STEPS (Agent Execute)
1. Read: .workflow/project-tech.json
2. Read: .workflow/project-guidelines.json
---
## Exploration Context
- **Requirement**: ${requirement}
- **Strategy**: ${selectedMode}
- **Project Type**: ${hasCodebase}
- **Session**: ${sessionFolder}
## Exploration Focus
- Identify modules/components related to the requirement
- Find existing patterns that should be followed
- Locate integration points for new functionality
- Assess current architecture constraints
## Output
Return findings as JSON with schema:
{
"project_type": "${hasCodebase}",
"relevant_modules": [{name, path, relevance}],
"existing_patterns": [{pattern, files, description}],
"integration_points": [{location, description, risk}],
"architecture_constraints": [string],
"tech_stack": {languages, frameworks, tools}
}
`
})
const exploreResult = wait_agent({
timeout_ms: 1800000 // 30 minutes
})
close_agent({ target: exploreAgentId })
if (exploreResult.status[exploreAgentId].completed) {
codebaseContext = exploreResult.status[exploreAgentId].completed
}
}
- 分解エージェントの実行
const decompositionAgentId = spawn_agent({ agent_type: "cli_roadmap_plan_agent", message: `
TASK ASSIGNMENT
MANDATORY FIRST STEPS (Agent Execute)
- Read: .workflow/project-tech.json
- Read: .workflow/project-guidelines.json
Roadmap Decomposition Task
Input Context
- Requirement: ${requirement}
- Selected Mode: ${selectedMode}
- Session ID: ${sessionId}
- Session Folder: ${sessionFolder}
Strategy Assessment
${JSON.stringify(strategyAssessment, null, 2)}
Codebase Context
${codebaseContext ? JSON.stringify(codebaseContext, null, 2) : 'No codebase detected - pure requirement decomposition'}
Mode-Specific Requirements
${selectedMode === 'progressive' ? `Progressive Mode:
- 2-4 layers from MVP to full implementation
- Each layer: id (L0-L3), name, goal, scope, excludes, convergence, risks, effort, depends_on
- L0 (MVP) must be a self-contained closed loop with no dependencies
- Scope: each feature belongs to exactly ONE layer (no overlap)
- Layer names: MVP / Usable / Refined / Optimized` :
`Direct Mode:
- Topologically-sorted task sequence
- Each task: id (T1-Tn), title, type, scope, inputs, outputs, convergence, depends_on, parallel_group
- Inputs must come from preceding task outputs or existing resources
- Tasks in same parallel_group must be truly independent`}
Convergence Quality Requirements
- criteria[]: MUST be testable (can write assertions or manual verification steps)
- verification: MUST be executable (command, script, or explicit steps)
- definition_of_done: MUST use business language (non-technical person can judge)
Expected Output
- Update ${sessionFolder}/roadmap.md with Roadmap table + Convergence sections
- Create issues via ccw issue create - append to .workflow/issues/issues.jsonl
Issue Format (for ccw issue create)
- id: ISS-YYYYMMDD-NNN (auto-generated)
- title: [LayerName] goal or [TaskType] title
- context: Markdown with goal, scope, convergence criteria, verification, DoD
- priority: small→4, medium→3, large→2
- tags: ["roadmap", mode, wave-N, layer-name]
- extended_context.notes: {session, strategy, wave, depends_on_issues}
Execution Steps
-
Analyze requirement and build decomposition context
-
Execute decomposition (internal reasoning)
-
Validate records, check convergence quality
-
For each decomposed item:
- Run: ccw issue create --title "..." --context "..." --tags "..." --priority N
- Record returned Issue ID
-
Update roadmap.md with Issue ID references
-
Return brief completion summary with Issue IDs ` })
const decompositionResult = wait_agent({ timeout_ms: 1800000 // 30 minutes for complex decomposition })
close_agent({ target: decompositionAgentId })
if (!decompositionResult.status[decompositionAgentId].completed) { throw new Error('Decomposition agent failed to complete') }
const issueIds = decompositionResult.status[decompositionAgentId].completed.issueIds || []
成功条件：
.workflow/issues/issues.jsonlに Issue が作成されている- Issue の参照情報を含むよう roadmap.md が更新されている
- 循環依存がない
- 収束基準がテスト可能である
フェーズ 3：反復的な改善
目的：複数回にわたるユーザーフィードバックを受けて、ロードマップを改善します。
累積コンテキストのルール：各回の提示には、これまでのすべてのフィードバックと変更を必ず含めてください。個別に提示してはならず、常に累積した状態を示してください。
判断の記録：ユーザーからの各フィードバックの選択と、それによって生じた変更を、判断記録形式で反復履歴に必ず記録してください。
> **Decision**: [Description]
> - **Context**: [What triggered this]
> - **Options**: [What was considered]
> - **Chosen**: [Selected] — **Reason**: [Why]
> - **Impact**: [What changed in roadmap]
手順：
-
現在のロードマップを表示
- ロードマップの表と主要な収束基準を読み込み、表示します
- Issue 数とウェーブの内訳を示します
-
フィードバックループ（AUTO_YES の場合はスキップ）
// Update progress functions.update_plan([{ id: "phase-3", title: "Phase 3: Iterative Refinement", status: "in_progress" }]) let round = 0 let approved = false while (!approved && round < 5) { round++ // Dynamic options — include research if not yet done const baseOptions = [ { label: "Approve", description: "Proceed to handoff" }, { label: "Adjust Scope", description: "Modify issue scopes" }, { label: "Refine Criteria", description: "Improve convergence criteria/verification" } ] // Add research option if architecture decisions need external validation if (!researchDone) { baseOptions.push({ label: "Research", description: "Search for architecture patterns and best practices" }) } else { baseOptions.push({ label: "Re-decompose", description: "Change strategy/layering" }) } const feedback = functions.request_user_input({ questions: [{ header: "Validate", // max 12 chars question: `Roadmap round ${round}: ${issueIds.length} issues across ${waveCount} waves. Your decision:`, multiSelect: false, options: baseOptions }] }) if (feedback === 'Approve') { approved = true } else if (feedback === 'Research') { // Execute web.run for architecture patterns and best practices const researchQueries = generateResearchQueries(requirement, selectedMode) researchQueries.forEach(query => { const results = web.run({ search_query: query }) // Extract: architecture patterns, best practices, risk mitigations }) researchDone = true // Record research findings in roadmap.md Iteration History } else { // For Adjust Scope, Refine Criteria, Re-decompose: // Collect details via functions.request_user_input or free text // CONSTRAINT: All modifications ONLY touch roadmap.md and issues.jsonl // NEVER modify source code or project files during interactive rounds // Record decision in Iteration History using Decision Record format } // Update Iteration History in roadmap.md (Record-Before-Continue) const iterationEntry = `
Round ${round} - ${getUtc8ISOString()}
User Feedback: ${feedback} Changes Made: ${changesMade} Decision: ${decisionRecord} Status: ${approved ? 'approved' : 'continue iteration'} ` // Append to Iteration History section in roadmap.md }
3. **反復履歴を確定**
```javascript
// Update final status in roadmap.md
Edit({
path: `${sessionFolder}/roadmap.md`,
old_string: "**Status**: Planning",
new_string: "**Status**: Ready"
})
成功条件：
- ユーザーが承認している、または最大反復回数に達している
- すべての変更が反復履歴に記録されている
- roadmap.md に最終状態が反映されている
フェーズ 4：引き継ぎ
目的：最終ロードマップを提示し、次のステップを選択するための必須のターミナルゲートを実行します。
手順：
-
概要の表示
## Roadmap Complete - **Session**: RMAP-{date}-{slug} - **Strategy**: {progressive|direct} - **Issues Created**: {count} across {waves} waves - **Roadmap**: .workflow/.roadmap/RMAP-{date}-{slug}/roadmap.md | Wave | Issue Count | Layer/Type | |------|-------------|------------| | 1 | 2 | MVP / infrastructure | | 2 | 3 | Usable / feature | -
必須のターミナルゲート（重大 — 必ず実行してください。これを行わずにワークフローを終了してはなりません）
// Update progress functions.update_plan([ { id: "phase-4", title: "Phase 4: Handoff", status: "completed" }, { id: "next-step", title: "GATE: Post-Completion Next Step", status: "in_progress" } ]) const nextStep = functions.request_user_input({ questions: [{ header: "Next Step", // max 12 chars question: `${issueIds.length} issues ready in roadmap. What would you like to do next?`, multiSelect: false, options: [ { label: "Execute Plan", description: "Hand off to execution pipeline (csv-wave-pipeline)" }, { label: "View Issues", description: "Display issue details before deciding" }, { label: "Done", description: "Planning complete, all artifacts saved" } ] }] }) // Handle next step if (nextStep === "Execute Plan") { // Display execution command for user to run manually // "Run: $csv-wave-pipeline '${requirement}'" or "/issue:execute" // This skill is planning-only — NEVER auto-launch execution } else if (nextStep === "View Issues") { functions.exec_command(`ccw issue list --session ${sessionId}`) // After viewing, show execution commands } // "Done" → end workflow // Mark terminal gate complete functions.update_plan([ { id: "next-step", title: "GATE: Post-Completion Next Step", status: "completed" } ])
成功条件：
- ユーザーの選択が実行されている
- セッションが完了している
- すべての成果物にアクセスできる
エラー処理
| エラー | 解決方法 |
|---|---|
| cli-explore-agent の失敗 | コード調査をスキップし、要件のみを使った分解に進みます |
| cli-roadmap-plan-agent の失敗 | 1 回再試行し、失敗した場合は手動分解プロンプトに切り替えます |
| コードベースがない | 通常のフローで進み、調査ステップをスキップします |
| ウェブ調査の失敗 | 外部の調査結果なしで続行し、インライン分析に頼ります |
| 調査結果と計画が矛盾 | 競合する根拠として提示し、方針はユーザーに判断してもらいます |
| 循環依存の検出 | ユーザーに確認し、再分解します |
| フィードバックループ中のユーザータイムアウト | roadmap.md を保存し、--continue コマンドを表示します |
| 最大反復回数に到達 | 現在のロードマップで続行します |
| セッションフォルダーの競合 | タイムスタンプのサフィックスを追加します |
コアルール
- すぐに開始する：最初のアクションはセッションの初期化とし、その後フェーズ 1 を実行します
- 単一の情報源：すべてのコンテキストを roadmap.md に埋め込み、個別の JSON ファイルは使用しません
- ロードマップを反復する：作り直すのではなく、フィードバックを重ねて改善します
- テスト可能な収束：基準はアサーション、DoD はビジネス用語で記述します
- ライフサイクルを明示する：待機が完了したら、リソースを解放するため必ず close_agent を実行します
- 計画専用のスキル：このスキルが作成するのはロードマップと issue のみです。コードの実行、ソースファイルの作成、実装の実行は決して行いません。すべてのコード変更は、ユーザーが手動で実行した後、別の実行スキルを通じて行われます
- 計画のみを変更する：対話形式のフィードバック（フェーズ 3）では、
roadmap.mdとissues.jsonlのみを更新しなければなりません。いずれのフェーズでも、ソースコード、設定ファイル、その他のプロジェクトファイルを変更してはいけません。コード変更は、引き継ぎ後にユーザーが$csv-wave-pipelineまたはその他の実行スキルを手動で実行した場合にのみ行われます - 必須の確認ゲート：フェーズ 2 の分解が完了したら、必ずロードマップをユーザーに提示し、引き継ぎに進む前に確認（フェーズ 3）を待たなければなりません。フェーズ 3 のユーザー検証を省略してはいけません
ベストプラクティス
- 要件を明確にする：詳細な説明により、より適切に分解できます
- ロードマップを反復する：フィードバックを重ねて収束基準を改善します
- テスト可能な収束：基準はアサーション、DoD はビジネス用語で記述します
- Continue モードを使用する：既存のロードマップを引き継いで反復します
- ウェーブ実行：本格的な実行の前に検証できるよう、wave-1（MVP）から開始します
使用に関する推奨事項
ロードマップと他のスキルの使い分け：
| シナリオ | 推奨スキル |
|---|---|
| 戦略的な計画、issue の追跡が必要 | $roadmap-with-file |
| 手早いタスクの分解、すぐに実行 | $lite-plan |
| 複数エージェントによる共同計画 | $collaborative-plan-with-file |
| 完全な仕様書 | $spec-generator |
| 既存の計画に基づくコードの実装 | $workflow-lite-plan |
ロードマップを計画する対象：$ARGUMENTS
コメント
Markdown 対応