# Codewalkers

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