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 (in progress)

Phases

Phase Numbering:

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

✅ v1.0 Core System (Phases 1-6) - SHIPPED 2026-01-30

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:

• 01-01: Project Foundation
• 01-02: CLI Entry Point
• 01-03: Process Management
• 01-04: Logging Infrastructure
• 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:

• 01.1-01: Event Bus Foundation
• 01.1-02: tRPC Foundation
• 01.1-03: Process Module Tests + Events
• 01.1-04: Logging Module Tests + Events
• 01.1-05: Server Module Tests + Events
• 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:

• 02-01: SQLite Database Setup
• 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:

• 03-01: Git Events & WorktreeManager Port
• 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:

• 04-01: Agent Schema & Repository
• 04-02: AgentManager Port & Events
• 04-03: AgentManager Adapter
• 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:

• 05-01: Message Schema & Repository
• 05-02: Task tRPC & CLI
• 05-03: Dispatch Port & Events
• 05-04: Dispatch Adapter
• 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:

• 06-01: Coordination Events & Port
• 06-02: CoordinationManager Adapter
• 06-03: tRPC & CLI Integration

🚧 v1.1 Test Infrastructure (In Progress)

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

Phase 7: Mock Agent & Test Harness

Goal: Mock agent adapter with configurable scenarios + test harness foundation with DB-seeded fixtures Depends on: v1.0 complete Research: Unlikely (internal test patterns, vitest already in codebase) Plans: TBD

Plans:

• 07-01: MockAgentManager Adapter
• 07-02: Test Harness with Database Fixtures

Phase 8: E2E Scenario Tests

Goal: Happy path tests (basic flow, dependencies, merging) + edge case tests (conflicts, interrupts, token limits) Depends on: Phase 7 Research: Unlikely (testing existing functionality) Plans: 2 plans

Plans:

• 08-01: Happy Path E2E Tests
• 08-02: Edge Case E2E Tests

Phase 8.1: Agent Output Schema (INSERTED)

Goal: Define structured agent output schema (done/question/error discriminated union) and update ClaudeAgentManager to use --json-schema flag for validated output parsing Depends on: Phase 8 Research: Unlikely (Zod schemas, Claude CLI flags documented) Plans: 2 plans

Plans:

• 08.1-01: Agent Output Schema & ClaudeAgentManager
• 08.1-02: MockAgentManager Schema Alignment

Phase 9: Extended Scenarios

Goal: Extended E2E scenario coverage — conflict hand-back round-trip, multi-agent parallel work, recovery/resume flows Depends on: Phase 8.1 Research: Unlikely (testing existing functionality) Plans: 2 plans

Plans:

• 09-01: Conflict & Parallel E2E Tests
• 09-02: Recovery & Resume E2E Tests

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	0/2	Not started	-
9. Extended Scenarios	v1.1	0/2	Not started	-

---

Roadmap created: 2026-01-30 v1.0 shipped: 2026-01-30 (27 plans, 6 phases) v1.1 started: 2026-01-30