Codewalkers/.planning/ROADMAP.md

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)

• Phase 1: Core Infrastructure - CLI binary, server mode, process lifecycle, graceful shutdown

• Phase 1.1: Hexagonal Architecture (INSERTED) - Tests, events, ports/adapters, tRPC

• Phase 2: Data Layer - SQLite database with task hierarchy schema

• Phase 3: Git Integration - Worktree isolation per agent with proper lifecycle

• 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:

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

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

• 02-01: SQLite Database Setup (Wave 1)
• 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:

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

• 04-01: Agent Schema & Repository (Wave 1)
• 04-02: AgentManager Port & Events (Wave 1)
• 04-03: AgentManager Adapter (Wave 2)
• 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: 5 plans in 3 waves

Plans:

• 05-01: Message Schema & Repository (Wave 1)
• 05-02: Task tRPC & CLI (Wave 1)
• 05-03: Dispatch Port & Events (Wave 1)
• 05-04: Dispatch Adapter (Wave 2)
• 05-05: Message & Dispatch CLI (Wave 3)

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	1/5	In progress	-
6. Coordination	0/?	Not started	-
7. File System UI	0/?	Not started	-

---

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