# 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:
- [x] 10-01: Schema & Type Updates
- [x] 10-02: Manager Implementation
- [x] 10-03: TestHarness & Test Updates
- [x] 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:
- [x] 11-01: Agent Mode Schema Extension
- [x] 11-02: Initiative & Phase Repositories
- [x] 11-03: ClaudeAgentManager Mode Support
- [x] 11-04: Initiative & Phase tRPC Procedures
- [x] 11-05: Architect Spawn Procedures
- [x] 11-06: CLI Commands
- [x] 11-07: Unit Tests
- [x] 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:
- [x] 12-01: Decompose Mode Schema
- [x] 12-02: PlanRepository Extensions
- [x] 12-03: ClaudeAgentManager Decompose Support
- [x] 12-04: Plan & Task tRPC Procedures
- [x] 12-05: Decompose Prompts & Spawn Procedure
- [x] 12-06: CLI Commands
- [x] 12-07: Unit Tests
- [x] 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:
- [x] 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*