From a315b286fdcd26570a100ea82616ea60f37435aa Mon Sep 17 00:00:00 2001 From: Lukas May Date: Fri, 30 Jan 2026 12:55:55 +0100 Subject: [PATCH] docs: create roadmap (7 phases, 27 requirements) Multi-agent workspace for orchestrating Claude Code agents. Phases: 1. Core Infrastructure: INFRA-01 through INFRA-05 2. Data Layer: TASK-02, TASK-03 3. Git Integration: GIT-01 through GIT-04 4. Agent Lifecycle: AGENT-01 through AGENT-07 (except AGENT-06) 5. Task Dispatch: AGENT-06, TASK-01, TASK-04, TASK-05 6. Coordination: COORD-01, COORD-02 7. File System UI: FSUI-01 through FSUI-04 All v1 requirements mapped to phases. --- .planning/REQUIREMENTS.md | 60 +++++++++---------- .planning/ROADMAP.md | 122 ++++++++++++++++++++++++++++++++++++++ .planning/STATE.md | 57 ++++++++++++++++++ 3 files changed, 209 insertions(+), 30 deletions(-) create mode 100644 .planning/ROADMAP.md create mode 100644 .planning/STATE.md diff --git a/.planning/REQUIREMENTS.md b/.planning/REQUIREMENTS.md index bffef5c..f68c5f3 100644 --- a/.planning/REQUIREMENTS.md +++ b/.planning/REQUIREMENTS.md @@ -98,39 +98,39 @@ 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 | +| INFRA-01 | Phase 1 | Pending | +| INFRA-02 | Phase 1 | Pending | +| INFRA-03 | Phase 1 | Pending | +| INFRA-04 | Phase 1 | Pending | +| INFRA-05 | Phase 1 | Pending | +| GIT-01 | Phase 3 | Pending | +| GIT-02 | Phase 3 | Pending | +| GIT-03 | Phase 3 | Pending | +| GIT-04 | Phase 3 | Pending | +| AGENT-01 | Phase 4 | Pending | +| AGENT-02 | Phase 4 | Pending | +| AGENT-03 | Phase 4 | Pending | +| AGENT-04 | Phase 4 | Pending | +| AGENT-05 | Phase 4 | Pending | +| AGENT-06 | Phase 5 | Pending | +| AGENT-07 | Phase 4 | Pending | +| TASK-01 | Phase 5 | Pending | +| TASK-02 | Phase 2 | Pending | +| TASK-03 | Phase 2 | Pending | +| TASK-04 | Phase 5 | Pending | +| TASK-05 | Phase 5 | Pending | +| COORD-01 | Phase 6 | Pending | +| COORD-02 | Phase 6 | Pending | +| FSUI-01 | Phase 7 | Pending | +| FSUI-02 | Phase 7 | Pending | +| FSUI-03 | Phase 7 | Pending | +| FSUI-04 | Phase 7 | Pending | **Coverage:** - v1 requirements: 27 total -- Mapped to phases: 0 -- Unmapped: 27 ⚠️ +- Mapped to phases: 27 +- Unmapped: 0 ✓ --- *Requirements defined: 2026-01-30* -*Last updated: 2026-01-30 after initial definition* +*Last updated: 2026-01-30 after roadmap creation* diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md new file mode 100644 index 0000000..8f5a581 --- /dev/null +++ b/.planning/ROADMAP.md @@ -0,0 +1,122 @@ +# Roadmap: Codewalk District + +## Overview + +Multi-agent orchestration system built in seven phases: foundation infrastructure, then data persistence, then git worktrees for isolation, then agent lifecycle management, then task dispatch and queuing, then coordination/merge handling, and finally the file system UI for developer interaction. Each phase delivers a coherent capability that later phases depend on. + +## Domain Expertise + +None + +## Phases + +**Phase Numbering:** +- Integer phases (1, 2, 3): Planned milestone work +- Decimal phases (2.1, 2.2): Urgent insertions (marked with INSERTED) + +- [ ] **Phase 1: Core Infrastructure** - CLI binary, server mode, process lifecycle, graceful shutdown +- [ ] **Phase 2: Data Layer** - SQLite database with task hierarchy schema +- [ ] **Phase 3: Git Integration** - Worktree isolation per agent with proper lifecycle +- [ ] **Phase 4: Agent Lifecycle** - Spawn, stop, list agents with session persistence +- [ ] **Phase 5: Task Dispatch** - Task visibility, dependency dispatch, work queue +- [ ] **Phase 6: Coordination** - Merge agent outputs, handle conflicts +- [ ] **Phase 7: File System UI** - Bidirectional SQLite/filesystem sync + +## Phase Details + +### Phase 1: Core Infrastructure +**Goal**: CLI binary (`cw`) with server mode, process management, graceful shutdown, and logging +**Depends on**: Nothing (first phase) +**Requirements**: INFRA-01, INFRA-02, INFRA-03, INFRA-04, INFRA-05 +**Research**: Unlikely (Node.js process patterns well-documented) +**Plans**: TBD + +Plans: +- [ ] 01-01: TBD +- [ ] 01-02: TBD + +### Phase 2: Data Layer +**Goal**: SQLite database with Drizzle ORM, task hierarchy schema (initiative → phase → plan → task) +**Depends on**: Phase 1 +**Requirements**: TASK-02, TASK-03 +**Research**: Unlikely (Drizzle/SQLite well-documented) +**Plans**: TBD + +Plans: +- [ ] 02-01: TBD + +### Phase 3: Git Integration +**Goal**: Git worktree management — create isolated worktrees per agent, preview diffs, integrate changes, cleanup +**Depends on**: Phase 2 +**Requirements**: GIT-01, GIT-02, GIT-03, GIT-04 +**Research**: Unlikely (Git worktree well-documented) +**Plans**: TBD + +Plans: +- [ ] 03-01: TBD +- [ ] 03-02: TBD + +### Phase 4: Agent Lifecycle +**Goal**: Spawn, stop, list Claude Code agents with session persistence and background mode +**Depends on**: Phase 3 +**Requirements**: AGENT-01, AGENT-02, AGENT-03, AGENT-04, AGENT-05, AGENT-07 +**Research**: Likely (MCP protocol / Claude Code CLI integration needs validation) +**Research topics**: Claude Code CLI -p flag behavior, JSON output schema, STDIO MCP transport, process tree management with execa +**Plans**: TBD + +Plans: +- [ ] 04-01: TBD +- [ ] 04-02: TBD +- [ ] 04-03: TBD + +### Phase 5: Task Dispatch +**Goal**: Task status visibility, dependency-ordered dispatch, work queue, agent message queue +**Depends on**: Phase 4 +**Requirements**: AGENT-06, TASK-01, TASK-04, TASK-05 +**Research**: Unlikely (standard queue patterns) +**Plans**: TBD + +Plans: +- [ ] 05-01: TBD +- [ ] 05-02: TBD + +### Phase 6: Coordination +**Goal**: Merge agent outputs into integration branch in dependency order, bounce conflicts back to agents +**Depends on**: Phase 5 +**Requirements**: COORD-01, COORD-02 +**Research**: Unlikely (git merge patterns, but conflict detection needs care) +**Plans**: TBD + +Plans: +- [ ] 06-01: TBD + +### Phase 7: File System UI +**Goal**: Bidirectional sync between SQLite state and filesystem — agent messages as files, user responds via files +**Depends on**: Phase 6 +**Requirements**: FSUI-01, FSUI-02, FSUI-03, FSUI-04 +**Research**: Likely (bidirectional sync patterns may need prototyping) +**Research topics**: File watcher race conditions, atomic file operations, sync conflict resolution +**Plans**: TBD + +Plans: +- [ ] 07-01: TBD +- [ ] 07-02: TBD + +## Progress + +**Execution Order:** +Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 + +| Phase | Plans Complete | Status | Completed | +|-------|----------------|--------|-----------| +| 1. Core Infrastructure | 0/? | Not started | - | +| 2. Data Layer | 0/? | Not started | - | +| 3. Git Integration | 0/? | Not started | - | +| 4. Agent Lifecycle | 0/? | Not started | - | +| 5. Task Dispatch | 0/? | Not started | - | +| 6. Coordination | 0/? | Not started | - | +| 7. File System UI | 0/? | Not started | - | + +--- +*Roadmap created: 2026-01-30* +*v1 requirements: 27 mapped across 7 phases* diff --git a/.planning/STATE.md b/.planning/STATE.md new file mode 100644 index 0000000..d889799 --- /dev/null +++ b/.planning/STATE.md @@ -0,0 +1,57 @@ +# Project State + +## Project Reference + +See: .planning/PROJECT.md (updated 2026-01-30) + +**Core value:** Coordinate multiple Claude Code agents without losing track or stepping on each other. +**Current focus:** Phase 1 — Core Infrastructure + +## Current Position + +Phase: 1 of 7 (Core Infrastructure) +Plan: Not started +Status: Ready to plan +Last activity: 2026-01-30 — Project initialized + +Progress: ░░░░░░░░░░ 0% + +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: — +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| — | — | — | — | + +**Recent Trend:** +- Last 5 plans: — +- Trend: — + +## Accumulated Context + +### Decisions + +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +(None yet) + +### Pending Todos + +None yet. + +### Blockers/Concerns + +None yet. + +## Session Continuity + +Last session: 2026-01-30 +Stopped at: Project initialization complete +Resume file: None