5ff63c1991
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.
4.8 KiB
4.8 KiB
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