Codewalkers/.planning/ROADMAP.md

# Roadmap: Codewalk District

## Overview

Multi-agent orchestration system built in six phases: foundation infrastructure, then data persistence, then git worktrees for isolation, then agent lifecycle management, then task dispatch and queuing, and finally coordination/merge handling. Each phase delivers a coherent capability that later phases depend on.

## Domain Expertise

None

## Milestones

- ✅ **v1.0 Core System** - Phases 1-6 (shipped 2026-01-30)
- ✅ **v1.1 Test Infrastructure** - Phases 7-9 (shipped 2026-01-31)
- 🚧 **v1.2 Architect & Multi-Question** - Phases 10-13 (in progress)

## Phases

**Phase Numbering:**
- Integer phases (1, 2, 3): Planned milestone work
- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED)

<details>
<summary>✅ v1.0 Core System (Phases 1-6) - SHIPPED 2026-01-30</summary>

### Phase 1: Core Infrastructure
**Goal**: CLI binary (`cw`) with server mode, process management, graceful shutdown, and logging
**Depends on**: Nothing (first phase)
**Requirements**: INFRA-01, INFRA-02, INFRA-03, INFRA-04, INFRA-05
**Research**: Unlikely (Node.js process patterns well-documented)
**Plans**: 5 plans

Plans:
- [x] 01-01: Project Foundation
- [x] 01-02: CLI Entry Point
- [x] 01-03: Process Management
- [x] 01-04: Logging Infrastructure
- [x] 01-05: Coordination Server & Shutdown

### Phase 1.1: Hexagonal Architecture (INSERTED)
**Goal**: Retrofit Phase 1 with hexagonal architecture, event-based inter-module communication, unit/integration tests, and tRPC for client communication
**Depends on**: Phase 1
**Requirements**: None (architectural refactor)
**Research**: Unlikely (patterns well-documented)
**Plans**: 6 plans

Plans:
- [x] 01.1-01: Event Bus Foundation
- [x] 01.1-02: tRPC Foundation
- [x] 01.1-03: Process Module Tests + Events
- [x] 01.1-04: Logging Module Tests + Events
- [x] 01.1-05: Server Module Tests + Events
- [x] 01.1-06: CLI tRPC Integration

### Phase 2: Data Layer
**Goal**: SQLite database with Drizzle ORM, task hierarchy schema (initiative → phase → plan → task)
**Depends on**: Phase 1
**Requirements**: TASK-02, TASK-03
**Research**: Unlikely (Drizzle/SQLite well-documented)
**Plans**: 2 plans

Plans:
- [x] 02-01: SQLite Database Setup
- [x] 02-02: Repository Layer

### Phase 3: Git Integration
**Goal**: Git worktree management — create isolated worktrees per agent, preview diffs, integrate changes, cleanup
**Depends on**: Phase 2
**Requirements**: GIT-01, GIT-02, GIT-03, GIT-04
**Research**: Unlikely (Git worktree well-documented)
**Plans**: 2 plans

Plans:
- [x] 03-01: Git Events & WorktreeManager Port
- [x] 03-02: WorktreeManager Adapter

### Phase 4: Agent Lifecycle
**Goal**: Spawn, stop, list Claude Code agents with session persistence and background mode
**Depends on**: Phase 3
**Requirements**: AGENT-01, AGENT-02, AGENT-03, AGENT-04, AGENT-05, AGENT-07
**Research**: Likely (MCP protocol / Claude Code CLI integration needs validation)
**Research topics**: Claude Code CLI -p flag behavior, JSON output schema, STDIO MCP transport, process tree management with execa
**Plans**: 4 plans

Plans:
- [x] 04-01: Agent Schema & Repository
- [x] 04-02: AgentManager Port & Events
- [x] 04-03: AgentManager Adapter
- [x] 04-04: tRPC Integration & CLI Commands

### Phase 5: Task Dispatch
**Goal**: Task status visibility, dependency-ordered dispatch, work queue, agent message queue
**Depends on**: Phase 4
**Requirements**: AGENT-06, TASK-01, TASK-04, TASK-05
**Research**: Unlikely (standard queue patterns)
**Plans**: 5 plans

Plans:
- [x] 05-01: Message Schema & Repository
- [x] 05-02: Task tRPC & CLI
- [x] 05-03: Dispatch Port & Events
- [x] 05-04: Dispatch Adapter
- [x] 05-05: Message & Dispatch CLI

### Phase 6: Coordination
**Goal**: Merge agent outputs into integration branch in dependency order, bounce conflicts back to agents
**Depends on**: Phase 5
**Requirements**: COORD-01, COORD-02
**Research**: Unlikely (programmatic coordination)
**Plans**: 3 plans

Plans:
- [x] 06-01: Coordination Events & Port
- [x] 06-02: CoordinationManager Adapter
- [x] 06-03: tRPC & CLI Integration

</details>

<details>
<summary>✅ v1.1 Test Infrastructure (Phases 7-9) - SHIPPED 2026-01-31</summary>

**Milestone Goal:** E2E test coverage with mocked agents proving all dispatch/coordination scenarios work end-to-end

**Full details:** [milestones/v1.1-ROADMAP.md](milestones/v1.1-ROADMAP.md)

### Phase 7: Mock Agent & Test Harness
- [x] 07-01: MockAgentManager Adapter
- [x] 07-02: Test Harness with Database Fixtures

### Phase 8: E2E Scenario Tests
- [x] 08-01: Happy Path E2E Tests
- [x] 08-02: Edge Case E2E Tests

### Phase 8.1: Agent Output Schema (INSERTED)
- [x] 08.1-01: Agent Output Schema & ClaudeAgentManager
- [x] 08.1-02: MockAgentManager Schema Alignment

### Phase 9: Extended Scenarios
- [x] 09-01: Conflict & Parallel E2E Tests
- [x] 09-02: Recovery & Resume E2E Tests

</details>

### 🚧 v1.2 Architect & Multi-Question (In Progress)

**Milestone Goal:** Enable structured planning workflow with Architect agent and efficient multi-question Q&A

#### 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)
**Research**: Unlikely (extends existing schema patterns)
**Plans**: 4

Plans:
- [x] 10-01: Schema & Type Updates
- [x] 10-02: Manager Implementation
- [x] 10-03: TestHarness & Test Updates
- [x] 10-04: E2E Test Updates

#### Phase 11: Architect Agent
**Goal**: Agent modes for concept refinement (questioning) and phase breakdown (persisting to ROADMAP.md)
**Depends on**: Phase 10
**Research**: Unlikely (internal workflow patterns)
**Plans**: 8

Plans:
- [x] 11-01: Agent Mode Schema Extension
- [x] 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

#### Phase 12: Phase-Task Decomposition
**Goal**: Agents break phases into individual tasks with ability to ask questions during breakdown
**Depends on**: Phase 11
**Research**: Unlikely (internal coordination patterns)
**Plans**: TBD

Plans:
- [ ] 12-01: TBD

#### 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
**Research**: Likely (validating Claude CLI --json-schema with multi-question arrays)
**Research topics**: Claude CLI behavior with array-typed questions, response parsing, error handling for real agent failures
**Plans**: TBD

Plans:
- [ ] 13-01: TBD

## Progress

**Execution Order:**
Phases execute in numeric order: 1 → 1.1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 8.1 → 9

| Phase | Milestone | Plans Complete | Status | Completed |
|-------|-----------|----------------|--------|-----------|
| 1. Core Infrastructure | v1.0 | 5/5 | Complete | 2026-01-30 |
| 1.1. Hexagonal Architecture | v1.0 | 6/6 | Complete | 2026-01-30 |
| 2. Data Layer | v1.0 | 2/2 | Complete | 2026-01-30 |
| 3. Git Integration | v1.0 | 2/2 | Complete | 2026-01-30 |
| 4. Agent Lifecycle | v1.0 | 4/4 | Complete | 2026-01-30 |
| 5. Task Dispatch | v1.0 | 5/5 | Complete | 2026-01-30 |
| 6. Coordination | v1.0 | 3/3 | Complete | 2026-01-30 |
| 7. Mock Agent & Test Harness | v1.1 | 2/2 | Complete | 2026-01-31 |
| 8. E2E Scenario Tests | v1.1 | 2/2 | Complete | 2026-01-31 |
| 8.1. Agent Output Schema | v1.1 | 2/2 | Complete | 2026-01-31 |
| 9. Extended Scenarios | v1.1 | 2/2 | Complete | 2026-01-31 |
| 10. Multi-Question Schema | v1.2 | 4/4 | Complete | 2026-01-31 |
| 11. Architect Agent | v1.2 | 1/8 | In progress | - |
| 12. Phase-Task Decomposition | v1.2 | 0/? | Not started | - |
| 13. Real Claude E2E Tests | v1.2 | 0/? | Not started | - |

---
*Roadmap created: 2026-01-30*
*v1.0 shipped: 2026-01-30 (27 plans, 6 phases)*
*v1.1 shipped: 2026-01-31 (8 plans, 3 phases)*