Codewalkers/.planning/PROJECT.md

Codewalk District

What This Is

A multi-agent workspace for orchestrating multiple Claude Code agents. Manages task breakdown, work coordination, and git worktrees so agents don't collide. Replaces manually juggling terminal sessions where you lose track of what each agent is doing.

Core Value

Coordinate multiple Claude Code agents without losing track or stepping on each other.

If everything else fails, this must work: spawn agents, assign work, know what's happening, don't corrupt the repo.

Requirements

Validated

• ✓ CLI cw — single binary, server mode via --server, commands for tasks/initiatives/agents — v1.0
• ✓ Task breakdown system — initiative → phases → plans → tasks with SQLite backing — v1.0
• ✓ Orchestration layer — spawn Claude Code agents, track running work, dispatch tasks from queue — v1.0
• ✓ Worktree management — isolated git worktrees per agent; automatic setup/teardown — v1.0
• ✓ Coordination layer — merge agent outputs in dependency order, detect conflicts, hand back for resolution — v1.0
• ✓ E2E test coverage — MockAgentManager, TestHarness, 34 E2E tests proving dispatch/coordination works — v1.1
• ✓ Multi-question Q&A — batched questions with id-based answer correlation, efficient agent pauses — v1.2
• ✓ Architect agent modes — discuss, breakdown, decompose for structured planning workflow — v1.2
• ✓ Real CLI validation — integration tests confirming Claude CLI JSON schema handling — v1.2
• ✓ Parallel phase execution — phase dependencies with concurrent dispatch of independent phases — v1.3
• ✓ Frontend wireframes — initiative dashboard, detail view, and agent inbox UI designs — v1.3

Active

• File system UI (fsui) — bidirectional sync between SQLite and filesystem; agent messages appear as files, user responds by editing files
• Production hardening — error handling, logging improvements, graceful degradation
• Frontend implementation — build React UI from wireframe specifications

Out of Scope

• Web dashboard — fsui is the MVP interface, web UI comes later
• Devcontainer preview instances — future feature for visual verification
• Browser automation for agents — future feature for agents to verify their own work
• Knowledge capture suggestions — future feature to auto-extend CLAUDE.md
• Multi-user support — solo developer first, stub for future

Current State

Shipped: v1.3 Parallel Execution & UI Design (2026-02-02)

• Full orchestration system: CLI, database, git worktrees, agent lifecycle, dispatch, coordination
• Parallel phase execution with dependency-ordered dispatch
• 40+ E2E tests with MockAgentManager proving all scenarios work
• Architect agent with discuss/breakdown/decompose modes for planning
• Multi-question Q&A with batched answers
• Frontend wireframes for 3 core screens (dashboard, detail, inbox)
• ~29,900 LOC TypeScript across 160+ files

Tech stack: TypeScript, tRPC, SQLite/Drizzle, Vitest, Hexagonal architecture

Context

Pain point: Running multiple Claude Code agents in separate terminals. Losing track of what each is doing. Hard to parallelize work. Agents collide on the same files. No central coordination.

Reference implementations:

• reference/gastown/ — Go-based agent workspace with worktree management, session handling
• reference/get-shit-done/ — Planning system with initiative → phase → plan → task breakdown

Existing design docs: Extensive documentation in docs/ covering:

• Task and initiative modules with SQLite schemas
• Agent roles (Orchestrator, Worker, Architect, Verifier)
• Context engineering (quality degrades predictably with context fill)
• Deviation rules for agent autonomy
• Verification patterns

User workflow: Solo developer orchestrating Claude Code for all implementation work. Needs to parallelize without chaos.

Constraints

• Language: TypeScript — aligns with tRPC/React ecosystem, user preference
• API: tRPC — type-safe API layer between CLI/agents and server
• Database: SQLite — single file, no setup, sufficient for solo/small team
• Architecture: Hexagonal with modular monolith — clear boundaries, swappable adapters
• Agent communication: STDIO-based MCP — agents communicate via cw mcp
• CLI design: Single cw binary serves as both CLI and server (cw --server)

Key Decisions

Decision	Rationale	Outcome
File system UI before web UI	Faster to build, editor is already the user's home, no frontend work for MVP	— Pending
SQLite over distributed Git (beads)	All agents share same workspace, no need for distributed sync	— Pending
TypeScript over Go	tRPC ecosystem, user preference, reference impl in Go is for learning not porting	— Pending
Terminal inbox via fsui, not TUI	Less code, leverage existing editor, bidirectional fs sync already planned	— Pending
Phase deps mirror task deps	Same FK patterns, cascade delete, in-memory queue — consistency over novelty	✓ Good
Remove Plan layer from UI	Simplified hierarchy to Initiative → Phase → Task; plans are internal concept	✓ Good

---

Last updated: 2026-02-04 after v1.3 milestone