# Requirements: Codewalkers

**Defined:** 2026-01-30
**Core Value:** Coordinate multiple Claude Code agents without losing track or stepping on each other.

## v1 Requirements

Requirements for initial release. Each maps to roadmap phases.

### Infrastructure

- [x] **INFRA-01**: CLI binary (`cw`) serves as single entry point for all commands
- [x] **INFRA-02**: Server mode (`cw --server`) runs background coordination server
- [x] **INFRA-03**: Process lifecycle supports start, stop, and restart of agents
- [x] **INFRA-04**: Graceful shutdown handles SIGTERM/SIGINT with cleanup
- [x] **INFRA-05**: Basic logging captures stdout/stderr per agent to files

### Git Integration

- [x] **GIT-01**: Each agent works in isolated git worktree
- [x] **GIT-02**: User can preview git diff of agent's changes
- [x] **GIT-03**: Agents integrate changes into designated feature branch on local repo
- [x] **GIT-04**: Worktree cleanup removes worktree when agent stops

### Agent Management

- [x] **AGENT-01**: User can spawn new agent with task assignment
- [x] **AGENT-02**: User can stop running agent
- [x] **AGENT-03**: User can list all agents with status
- [x] **AGENT-04**: Agent sessions persist across terminal close/reopen
- [x] **AGENT-05**: Background mode runs agents without interactive terminal
- [x] **AGENT-06**: Agents can surface questions back to user via message queue
- [x] **AGENT-07**: Agents run via Claude Code CLI mode (-p flag) with JSON output schema

### Task System

- [x] **TASK-01**: User can see status of all tasks at a glance
- [x] **TASK-02**: Tasks persist in SQLite database
- [x] **TASK-03**: Task hierarchy supports initiative → phase → plan → task breakdown
- [x] **TASK-04**: Task dispatch respects dependency ordering (don't start B until A completes)
- [x] **TASK-05**: Task queue dispatches work to available agents

### Coordination

- [x] **COORD-01**: System merges agent outputs into integration branch in dependency order
- [x] **COORD-02**: Non-trivial merge conflicts bounce work back to agent for resolution

## v2 Requirements

Deferred to future release. Tracked but not in current roadmap.

### File System UI

- **FSUI-01**: SQLite state syncs bidirectionally with filesystem representation
- **FSUI-02**: Agent messages appear as files in designated directory
- **FSUI-03**: User can respond to agents by editing/creating files
- **FSUI-04**: File watcher detects user edits and updates SQLite state

### Observability

- **OBS-01**: Token/cost tracking shows usage per agent
- **OBS-02**: Rich terminal UI dashboard with agent status overview

### Git Integration (Enhanced)

- **GIT-05**: Automatic PR generation from merged feature branch
- **GIT-06**: Merge conflict prediction warns before conflicts happen

### Coordination (Enhanced)

- **COORD-03**: File-level coordination tracks which agent touches which files
- **COORD-04**: Review-first workflow integration with review queue

### Agent Management (Enhanced)

- **AGENT-08**: tmux session per agent for interactive debugging
- **AGENT-09**: Cross-agent context summarization (Agent B learns from Agent A's work)

## Out of Scope

Explicitly excluded. Documented to prevent scope creep.

| Feature | Reason |
|---------|--------|
| Web dashboard | CLI + fsui is MVP interface; editor is user's home |
| Devcontainer preview | Future feature for visual verification |
| Browser automation | Future feature for agent self-verification |
| Knowledge capture suggestions | Future feature for auto-extending CLAUDE.md |
| Multi-user support | Solo developer first; stub for future |
| Cloud sync | Local-first; git is the collaboration layer |
| Plugin system | Premature; learn what users want first |
| Real-time collaboration | Solo developer focus |
| AI task decomposition | Unpredictable; manual breakdown with templates |

## Traceability

Which phases cover which requirements. Updated by create-roadmap.

| Requirement | Phase | Status |
|-------------|-------|--------|
| INFRA-01 | Phase 1 | Complete |
| INFRA-02 | Phase 1 | Complete |
| INFRA-03 | Phase 1 | Complete |
| INFRA-04 | Phase 1 | Complete |
| INFRA-05 | Phase 1 | Complete |
| GIT-01 | Phase 3 | Complete |
| GIT-02 | Phase 3 | Complete |
| GIT-03 | Phase 3 | Complete |
| GIT-04 | Phase 3 | Complete |
| AGENT-01 | Phase 4 | Complete |
| AGENT-02 | Phase 4 | Complete |
| AGENT-03 | Phase 4 | Complete |
| AGENT-04 | Phase 4 | Complete |
| AGENT-05 | Phase 4 | Complete |
| AGENT-06 | Phase 5 | Complete |
| AGENT-07 | Phase 4 | Complete |
| TASK-01 | Phase 5 | Complete |
| TASK-02 | Phase 2 | Complete |
| TASK-03 | Phase 2 | Complete |
| TASK-04 | Phase 5 | Complete |
| TASK-05 | Phase 5 | Complete |
| COORD-01 | Phase 6 | Complete |
| COORD-02 | Phase 6 | Complete |

**Coverage:**
- v1 requirements: 23 total
- Mapped to phases: 23
- Unmapped: 0 ✓
- All complete ✓

---
*Requirements defined: 2026-01-30*
*Last updated: 2026-01-30 — Phase 7 (FSUI) deferred to v2*