# Requirements: Codewalk District

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

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

### Git Integration

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

### Agent Management

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

### Task System

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

### Coordination

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

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

## v2 Requirements

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

### 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 | 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 | — | Pending |
| INFRA-02 | — | Pending |
| INFRA-03 | — | Pending |
| INFRA-04 | — | Pending |
| INFRA-05 | — | Pending |
| GIT-01 | — | Pending |
| GIT-02 | — | Pending |
| GIT-03 | — | Pending |
| GIT-04 | — | Pending |
| AGENT-01 | — | Pending |
| AGENT-02 | — | Pending |
| AGENT-03 | — | Pending |
| AGENT-04 | — | Pending |
| AGENT-05 | — | Pending |
| AGENT-06 | — | Pending |
| AGENT-07 | — | Pending |
| TASK-01 | — | Pending |
| TASK-02 | — | Pending |
| TASK-03 | — | Pending |
| TASK-04 | — | Pending |
| TASK-05 | — | Pending |
| COORD-01 | — | Pending |
| COORD-02 | — | Pending |
| FSUI-01 | — | Pending |
| FSUI-02 | — | Pending |
| FSUI-03 | — | Pending |
| FSUI-04 | — | Pending |

**Coverage:**
- v1 requirements: 27 total
- Mapped to phases: 0
- Unmapped: 27 ⚠️

---
*Requirements defined: 2026-01-30*
*Last updated: 2026-01-30 after initial definition*