roadmap-with-file

## Auto Mode When `--yes` or `-y`: Auto-confirm strategy selection, use recommended mode, skip interactive refinement rounds. **This skill is planning-only — it NEVER executes code or modifies source files. Output is the roadmap + issues for user review.** # Roadmap-with-file Skill ## Usage ```bash $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" ``` **Flags**: - `-y, --yes`: Skip all confirmations (auto mode) - `-c, --continue`: Continue existing session - `-m, --mode`: Strategy selection (progressive / direct / auto) **Context Source**: cli-explore-agent (optional) + requirement analysis **Output Directory**: `.workflow/.roadmap/{session-id}/` **Core Output**: `roadmap.md` (single source, human-readable) + `issues.jsonl` (global, machine-executable) --- ## Subagent API Reference ### spawn_agent Create a new subagent with task assignment. ```javascript 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 Get results from subagent (only way to retrieve results). ```javascript 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 Assign new work to active subagent (for clarification or follow-up). ```javascript followup_task({ target: agentId, message: ` ## CLARIFICATION ANSWERS ${answers} ## NEXT STEP Continue with plan generation. ` }) ``` ### close_agent Clean up subagent resources (irreversible). ```javascript close_agent({ target: agentId }) ``` --- ## Output Artifacts ### Single Source of Truth | Artifact | Purpose | Consumer | |----------|---------|----------| | `roadmap.md` | ⭐ Human-readable strategic roadmap with all context | Human review, csv-wave-pipeline handoff | | `.workflow/issues/issues.jsonl` | Global issue store (appended) | csv-wave-pipeline, issue commands | ### Why No Separate JSON Files? | Original File | Why Removed | Where Content Goes | |---------------|-------------|-------------------| | `strategy-assessment.json` | Duplicates roadmap.md content | Embedded in `roadmap.md` Strategy Assessment section | | `exploration-codebase.json` | Single-use intermediate | Embedded in `roadmap.md` Codebase Context appendix | --- ## Overview Strategic requirement roadmap with **iterative decomposition**. Creates a single `roadmap.md` that evolves through discussion, with issues persisted to global `issues.jsonl` for execution. **Core workflow**: Understand → Decompose → Iterate → Validate → Handoff **Key features**: - **roadmap.md**: Single source of truth — strategy, roadmap, convergence, iteration history - **Dual decomposition**: Progressive (MVP→Optimized) or Direct (topological tasks) - **External research**: Web search for architecture patterns and best practices via `web.run` - **Issue creation**: Issues persisted to global `issues.jsonl` for execution pipeline - **Progress tracking**: `functions.update_plan` for real-time phase progress visibility - **Decision recording**: Structured decision trail with context and rationale - **Structured handoff**: Terminal gate with execution planning, issue viewing, or completion ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └─────────────────────────────────────────────────────────────────────────┘ ``` --- ## Dual Modes | Mode | Strategy | Best For | Decomposition | |------|----------|----------|---------------| | **Progressive** | MVP → Usable → Refined → Optimized | High uncertainty, need validation | 2-4 layers, each with full convergence | | **Direct** | Topological task sequence | Clear requirements, confirmed tech | Tasks with explicit inputs/outputs | **Auto-selection logic**: - ≥3 high uncertainty factors → Progressive - ≥3 low uncertainty factors → Direct - Otherwise → Ask user preference --- ## Output Structure ``` .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 Template ```markdown # 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 Specification ### Location & Format ``` Path: .workflow/issues/issues.jsonl Format: JSONL (one complete JSON object per line) Encoding: UTF-8 Mode: Append-only (new issues appended to end) ``` ### Record Schema ```json { "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" } } ``` ### Query Interface ```bash # 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 ``` > **Note**: Issues are tagged with `wave-N` in `tags[]` field for filtering. Use `--brief` for programmatic parsing. --- ## Implementation ### Session Initialization ```javascript 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)