# Roadmap: Codewalk District

## Overview

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

## Domain Expertise

None

## Phases

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

- [x] **Phase 1: Core Infrastructure** - CLI binary, server mode, process lifecycle, graceful shutdown
- [x] **Phase 1.1: Hexagonal Architecture** (INSERTED) - Tests, events, ports/adapters, tRPC
- [x] **Phase 2: Data Layer** - SQLite database with task hierarchy schema
- [x] **Phase 3: Git Integration** - Worktree isolation per agent with proper lifecycle
- [x] **Phase 4: Agent Lifecycle** - Spawn, stop, list agents with session persistence
- [ ] **Phase 5: Task Dispatch** - Task visibility, dependency dispatch, work queue
- [ ] **Phase 6: Coordination** - Merge agent outputs, handle conflicts
- [ ] **Phase 7: File System UI** - Bidirectional SQLite/filesystem sync

## Phase Details

### 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 in 3 waves

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

### 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 in 3 waves

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

**Scope:**
- Unit + integration tests for existing Phase 1 code
- Event bus for inter-module communication (extensible, swappable for external systems)
- tRPC router for server-to-client communication (CLI, future WebUI)

### 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 (Wave 1)
- [x] 02-02: Repository Layer (Wave 2)

### 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**: TBD

Plans:
- [x] 03-01: Git Events & WorktreeManager Port (Wave 1)
- [x] 03-02: WorktreeManager Adapter (Wave 2)

### 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**: TBD

Plans:
- [x] 04-01: Agent Schema & Repository (Wave 1)
- [x] 04-02: AgentManager Port & Events (Wave 1)
- [x] 04-03: AgentManager Adapter (Wave 2)
- [x] 04-04: tRPC Integration & CLI Commands (Wave 3)

### 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**: TBD

Plans:
- [ ] 05-01: TBD
- [ ] 05-02: TBD

### 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 (git merge patterns, but conflict detection needs care)
**Plans**: TBD

Plans:
- [ ] 06-01: TBD

### Phase 7: File System UI
**Goal**: Bidirectional sync between SQLite state and filesystem — agent messages as files, user responds via files
**Depends on**: Phase 6
**Requirements**: FSUI-01, FSUI-02, FSUI-03, FSUI-04
**Research**: Likely (bidirectional sync patterns may need prototyping)
**Research topics**: File watcher race conditions, atomic file operations, sync conflict resolution
**Plans**: TBD

Plans:
- [ ] 07-01: TBD
- [ ] 07-02: TBD

## Progress

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

| Phase | Plans Complete | Status | Completed |
|-------|----------------|--------|-----------|
| 1. Core Infrastructure | 5/5 | Complete | 2026-01-30 |
| 1.1. Hexagonal Architecture | 6/6 | Complete | 2026-01-30 |
| 2. Data Layer | 2/2 | Complete | 2026-01-30 |
| 3. Git Integration | 2/2 | Complete | 2026-01-30 |
| 4. Agent Lifecycle | 4/4 | Complete | 2026-01-30 |
| 5. Task Dispatch | 0/? | Not started | - |
| 6. Coordination | 0/? | Not started | - |
| 7. File System UI | 0/? | Not started | - |

---
*Roadmap created: 2026-01-30*
*v1 requirements: 27 mapped across 7 phases*