docs: define v1 requirements

27 requirements across 6 categories.
8 requirements deferred to v2.

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

.planning/REQUIREMENTS.md

@@ -0,0 +1,136 @@
+# 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*