Codewalkers/.planning/milestones/v1.2-ROADMAP.md

Milestone v1.2: Architect & Multi-Question

Status: ✅ SHIPPED 2026-02-02 Phases: 10-13 Total Plans: 21

Overview

Enable structured planning workflow with Architect agent and efficient multi-question Q&A. Agents can now ask multiple questions at once with batched answers, run in discuss/breakdown/decompose modes to generate phases and tasks, and real Claude CLI integration tests validate the schema handling.

Phases

Phase 10: Multi-Question Schema

Goal: Extend agent output schema to return multiple questions; resume agent with all answers batched Depends on: Phase 9 (v1.1 complete) Plans: 4 plans

Plans:

• 10-01: Schema & Type Updates
• 10-02: Manager Implementation
• 10-03: TestHarness & Test Updates
• 10-04: E2E Test Updates

Key deliverables:

• Questions array schema with id field for answer correlation
• Batched answers via resume() with Record<string, string> mapping
• AgentWaitingEvent with questions array payload
• Multi-question E2E test validating full flow

Phase 11: Architect Agent

Goal: Agent modes for concept refinement (questioning) and phase breakdown (persisting to ROADMAP.md) Depends on: Phase 10 Plans: 8 plans

Plans:

• 11-01: Agent Mode Schema Extension
• 11-02: Initiative & Phase Repositories
• 11-03: ClaudeAgentManager Mode Support
• 11-04: Initiative & Phase tRPC Procedures
• 11-05: Architect Spawn Procedures
• 11-06: CLI Commands
• 11-07: Unit Tests
• 11-08: E2E Tests

Key deliverables:

• AgentMode type (execute, discuss, breakdown, decompose)
• Discuss mode outputs decisions array
• Breakdown mode outputs phases array with dependencies
• Initiative and Phase repositories with tRPC procedures
• Agent prompts module for mode-specific prompts
• Full workflow E2E test (discuss -> breakdown -> phases)

Phase 12: Phase-Task Decomposition

Goal: Agents break phases into individual tasks with ability to ask questions during breakdown Depends on: Phase 11 Plans: 8 plans

Plans:

• 12-01: Decompose Mode Schema
• 12-02: PlanRepository Extensions
• 12-03: ClaudeAgentManager Decompose Support
• 12-04: Plan & Task tRPC Procedures
• 12-05: Decompose Prompts & Spawn Procedure
• 12-06: CLI Commands
• 12-07: Unit Tests
• 12-08: E2E Tests

Key deliverables:

• Decompose mode schema with TaskBreakdown array
• Task dependencies via integer references
• PlanRepository with getNextNumber for auto-numbering
• createTasksFromDecomposition tRPC procedure
• Full workflow E2E test (initiative -> phase -> plan -> decompose -> tasks)

Phase 13: Real Claude E2E Tests

Goal: Verify multi-question and architect flows with actual Claude CLI; replace with mocks after verification Depends on: Phase 12 Plans: 1 plan

Plans:

• 13-01: Real Claude CLI Integration Tests

Key deliverables:

• Integration tests for all agent modes (execute, discuss, breakdown, decompose)
• Fixed structured_output parsing in ClaudeAgentManager
• Documentation of Claude CLI response structure with --json-schema flag
• Validation that MockAgentManager accurately simulates real CLI behavior

---

Milestone Summary

Key Decisions:

• Status 'questions' (plural) for array-based question payload
• Each question has id field for matching answers in batched resume
• AgentMode stored in database with 'execute' default for backwards compatibility
• Separate handler methods per mode (handleExecuteOutput, handleDiscussOutput, etc.)
• Use structured_output field (not result) when --json-schema is used
• Integration tests skipped by default (REAL_CLAUDE_TESTS=1 to enable)

Issues Resolved:

• Single question per pause was inefficient — now batched questions
• No planning workflow — Architect agent with discuss/breakdown/decompose modes
• JSON schema validation untested with real CLI — integration tests confirm behavior
• structured_output parsing incorrect — fixed to read correct field

Issues Deferred:

• None

Technical Debt Incurred:

• None

---

For current project status, see .planning/ROADMAP.md