0ff65b0b02
Update all user-facing strings (HTML title, manifest, header logo, browser title updater), code comments, and documentation references. Folder name retained as-is.
13 KiB
Roadmap: Codewalkers
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 (shipped 2026-02-02)
- ✅ v1.3 Parallel Execution & UI Design - Phases 14-15 (shipped 2026-02-02)
- ✅ v2.0 Frontend - Phases 16-21 (shipped 2026-02-05)
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 (Phases 7-9) - SHIPPED 2026-01-31
Milestone Goal: E2E test coverage with mocked agents proving all dispatch/coordination scenarios work end-to-end
Full details: milestones/v1.1-ROADMAP.md
Phase 7: Mock Agent & Test Harness
- 07-01: MockAgentManager Adapter
- 07-02: Test Harness with Database Fixtures
Phase 8: E2E Scenario Tests
- 08-01: Happy Path E2E Tests
- 08-02: Edge Case E2E Tests
Phase 8.1: Agent Output Schema (INSERTED)
- 08.1-01: Agent Output Schema & ClaudeAgentManager
- 08.1-02: MockAgentManager Schema Alignment
Phase 9: Extended Scenarios
- 09-01: Conflict & Parallel E2E Tests
- 09-02: Recovery & Resume E2E Tests
✅ v1.2 Architect & Multi-Question (Phases 10-13) - SHIPPED 2026-02-02
Milestone Goal: Enable structured planning workflow with Architect agent and efficient multi-question Q&A
Full details: milestones/v1.2-ROADMAP.md
Full details: milestones/v1.2-ROADMAP.md
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:
- 10-01: Schema & Type Updates
- 10-02: Manager Implementation
- 10-03: TestHarness & Test Updates
- 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:
- 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
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: 8
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
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: 1
Plans:
- 13-01: Real Claude CLI Integration Tests
✅ v1.3 Parallel Execution & UI Design (Phases 14-15) - SHIPPED 2026-02-02
Milestone Goal: Enable parallel phase execution and design the frontend UI with markdown wireframes
Phase 14: Parallel Phase Execution
Goal: Add dependencies to phases (same pattern as tasks), enable concurrent execution of independent phases Depends on: Phase 13 (v1.2 complete) Research: Unlikely (extends existing task dependency patterns) Plans: 8
Plans:
- 14-01: Phase Dependencies Schema & Repository
- 14-02: Phase Domain Events
- 14-03: PhaseDispatchManager Port Interface
- 14-04: PhaseDispatchManager Adapter
- 14-05: tRPC Procedures
- 14-06: CLI Commands
- 14-07: Unit Tests
- 14-08: E2E Tests
Phase 15: Frontend Wireframes
Goal: Markdown diagrams for initiative dashboard, phase/task breakdown, and agent inbox UI screens Depends on: Phase 14 Research: Unlikely (markdown documentation) Plans: 3
Plans:
- 15-01: Initiative Dashboard Wireframe
- 15-02: Initiative Detail Wireframe
- 15-03: Agent Inbox Wireframe
✅ v2.0 Frontend (SHIPPED 2026-02-05)
Milestone Goal: Build the web UI from v1.3 wireframes using React + Vite with real-time tRPC subscriptions
Phase 16: Frontend Scaffold
Goal: Vite project setup, tRPC client wiring, router, shared type exports, shadcn/ui config Depends on: Phase 15 (v1.3 complete) Research: Likely (new tech stack setup) Research topics: Vite monorepo setup, @trpc/react-query client configuration, shadcn/ui installation Plans: 5 plans
Plans:
- 16-01: Vite + React + Tailwind + shadcn/ui
- 16-02: Shared Types Package
- 16-03: tRPC Client Wiring
- 16-04: React Router Setup
- 16-05: Dev Server Integration
Phase 17: Initiative Dashboard
Goal: List view with status badges, progress bars, filtering, architect spawn dropdown Depends on: Phase 16 Research: Unlikely (internal patterns, components from wireframes) Plans: 4 plans
Plans:
- 17-01: StatusBadge & ProgressBar Components
- 17-02: InitiativeCard & InitiativeList Components
- 17-03: Interactive Dialog & Dropdown Components
- 17-04: Dashboard Page Assembly
Phase 18: Initiative Detail
Goal: Phase/task hierarchy accordion, dependency indicators, agent assignments, queue actions Depends on: Phase 17 Research: Unlikely (internal patterns, components from wireframes) Plans: 4 plans
Plans:
- 18-01: InitiativeHeader & ProgressPanel Components
- 18-02: PhaseAccordion, TaskRow & DependencyIndicator Components
- 18-03: DecisionList & TaskDetailModal Components
- 18-04: Initiative Detail Page Assembly
Phase 19: Agent Inbox
Goal: Message list, multi-question forms (radio/checkbox/free-text), answer submission, notifications Depends on: Phase 18 Research: Unlikely (internal patterns, form handling from wireframes) Plans: 4 plans
Plans:
- 19-01: Backend API for Agent Questions
- 19-02: InboxList & MessageCard Components
- 19-03: QuestionForm & Input Components
- 19-04: Inbox Page Assembly
Phase 20: Real-time Subscriptions
Goal: SSE streaming on tRPC server, subscription hooks, live status updates Depends on: Phase 19 Research: Likely (tRPC SSE subscriptions) Research topics: tRPC v11 async generator subscriptions, SSE streaming, httpSubscriptionLink Plans: 2 plans
Plans:
- 20-01: SSE Streaming & Subscription Procedures
- 20-02: Frontend SSE Subscription Hooks
Phase 21: Polish & Integration
Goal: Cross-screen navigation, error states, loading states, responsive layout, integration testing Depends on: Phase 20 Research: Unlikely (polish and integration of existing screens) Plans: 6 plans
Plans:
- 21-01: Error Boundary & Toast Notifications
- 21-02: Skeleton Loading States
- 21-03: Cross-Screen Navigation & Mobile Responsive
- 21-04: Subscription Error Handling
- 21-05: Code Splitting & Performance
- 21-06: Integration Smoke Test
Progress
Execution Order: Phases execute in numeric order: 1 → 1.1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 8.1 → 9 → 10 → 11 → 12 → 13 → 14 → 15 → 16 → 17 → 18 → 19 → 20 → 21
| 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 | 8/8 | Complete | 2026-01-31 |
| 12. Phase-Task Decomposition | v1.2 | 8/8 | Complete | 2026-02-01 |
| 13. Real Claude E2E Tests | v1.2 | 1/1 | Complete | 2026-02-02 |
| 14. Parallel Phase Execution | v1.3 | 8/8 | Complete | 2026-02-02 |
| 15. Frontend Wireframes | v1.3 | 3/3 | Complete | 2026-02-02 |
| 16. Frontend Scaffold | v2.0 | 5/5 | Complete | 2026-02-04 |
| 17. Initiative Dashboard | v2.0 | 4/4 | Complete | 2026-02-04 |
| 18. Initiative Detail | v2.0 | 4/4 | Complete | 2026-02-04 |
| 19. Agent Inbox | v2.0 | 4/4 | Complete | 2026-02-04 |
| 20. Real-time Subscriptions | v2.0 | 2/2 | Complete | 2026-02-04 |
| 21. Polish & Integration | v2.0 | 6/6 | Complete | 2026-02-05 |
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) v1.2 shipped: 2026-02-02 (21 plans, 4 phases) v1.3 shipped: 2026-02-02 (11 plans, 2 phases) v2.0 shipped: 2026-02-05 (27 plans, 6 phases)