Add design docs and gitignore
This commit is contained in:
@@ -0,0 +1,315 @@
|
||||
# Implementation Roadmap
|
||||
|
||||
## Purpose
|
||||
|
||||
This document is the handoff-oriented implementation plan for the project. It is intentionally short and execution-focused.
|
||||
|
||||
A new agent should be able to read this file, understand the current project state, and immediately know what to build next without re-deriving the whole design.
|
||||
|
||||
## Current Status
|
||||
|
||||
As of now:
|
||||
|
||||
- architecture and workflow docs are written
|
||||
- CLI surfaces for `inbox`, `orch`, worktree execution, and `council-review` are defined
|
||||
- SQLite schema drafts exist in the docs
|
||||
- JSON output shapes are defined for the major flows
|
||||
- Go module and initial command skeletons exist
|
||||
- `inbox` and `orch` both compile
|
||||
- shared SQLite schema initialization exists
|
||||
- `inbox init` works and creates the database schema
|
||||
- `orch` currently exists as a command skeleton only
|
||||
- no higher-level inbox or orch workflows have been implemented yet
|
||||
|
||||
This means the project is past design discovery and ready for code implementation.
|
||||
|
||||
## Source Of Truth
|
||||
|
||||
Read these docs first:
|
||||
|
||||
- [architecture.md](/home/kurihada/project/ai-workflow-skill/docs/architecture.md)
|
||||
- [inbox-cli.md](/home/kurihada/project/ai-workflow-skill/docs/inbox-cli.md)
|
||||
- [orch-cli.md](/home/kurihada/project/ai-workflow-skill/docs/orch-cli.md)
|
||||
- [worktree-execution.md](/home/kurihada/project/ai-workflow-skill/docs/worktree-execution.md)
|
||||
- [council-review.md](/home/kurihada/project/ai-workflow-skill/docs/council-review.md)
|
||||
|
||||
Use this roadmap for implementation order, not for protocol design.
|
||||
|
||||
## Project Goal
|
||||
|
||||
Build a Go-based local agent orchestration stack with:
|
||||
|
||||
- `inbox`: worker-facing durable coordination bus
|
||||
- `orch`: leader-facing scheduler and control plane
|
||||
- strict worktree-backed execution for code-writing task attempts
|
||||
- `council-review`: a user-facing three-reviewer brainstorm workflow implemented on top of `orch`
|
||||
|
||||
## Implementation Principles
|
||||
|
||||
- Do not redesign the protocol unless implementation reveals a real contradiction.
|
||||
- Keep `inbox` and `orch` as separate CLIs or command groups, but share one SQLite file.
|
||||
- Prefer one small working path over broad unfinished scaffolding.
|
||||
- Make JSON output stable early.
|
||||
- Implement the happy path first, then add wait/retry/cleanup.
|
||||
|
||||
## Recommended v1 Order
|
||||
|
||||
## Progress Snapshot
|
||||
|
||||
Current implementation status:
|
||||
|
||||
- `Milestone 1: Go Skeleton` is complete
|
||||
- `Milestone 2: Shared DB Layer` is partially complete
|
||||
- `Milestone 3: Inbox Happy Path` has started only through `inbox init`
|
||||
|
||||
The next practical coding target is the rest of the inbox happy path.
|
||||
|
||||
### Milestone 1: Go Skeleton
|
||||
|
||||
Goal:
|
||||
|
||||
- initialize the Go module
|
||||
- choose CLI framework and SQLite driver
|
||||
- create package layout
|
||||
- make empty commands compile
|
||||
|
||||
Recommended shape:
|
||||
|
||||
- `cmd/inbox`
|
||||
- `cmd/orch`
|
||||
- `internal/db`
|
||||
- `internal/store`
|
||||
- `internal/protocol`
|
||||
- `internal/cli`
|
||||
|
||||
Definition of done:
|
||||
|
||||
- `go build ./...` succeeds
|
||||
- `inbox --help` works
|
||||
- `orch --help` works
|
||||
|
||||
Status:
|
||||
|
||||
- completed
|
||||
|
||||
### Milestone 2: Shared DB Layer
|
||||
|
||||
Goal:
|
||||
|
||||
- create the SQLite connection layer
|
||||
- enable required pragmas
|
||||
- add schema initialization and migration mechanism
|
||||
|
||||
Minimum scope:
|
||||
|
||||
- communication tables for `inbox`
|
||||
- scheduling tables for `orch`
|
||||
- shared `events` table
|
||||
|
||||
Definition of done:
|
||||
|
||||
- `inbox init` initializes the database
|
||||
- `orch` can open the same database successfully
|
||||
|
||||
Status:
|
||||
|
||||
- partially completed
|
||||
|
||||
Completed so far:
|
||||
|
||||
- shared DB open layer exists
|
||||
- required SQLite pragmas are applied
|
||||
- embedded schema files exist
|
||||
- `inbox init` applies schema successfully
|
||||
|
||||
Remaining:
|
||||
|
||||
- decide whether `orch` should gain an explicit DB bootstrap check or reuse `inbox init`
|
||||
|
||||
### Milestone 3: Inbox Happy Path
|
||||
|
||||
Goal:
|
||||
|
||||
- implement worker-facing coordination primitives first
|
||||
|
||||
First commands:
|
||||
|
||||
- `inbox init`
|
||||
- `inbox send`
|
||||
- `inbox fetch`
|
||||
- `inbox claim`
|
||||
- `inbox update`
|
||||
- `inbox reply`
|
||||
- `inbox done`
|
||||
- `inbox fail`
|
||||
- `inbox show`
|
||||
|
||||
Delay if needed:
|
||||
|
||||
- `watch`
|
||||
- `wait-reply`
|
||||
- `cancel`
|
||||
- `list`
|
||||
|
||||
Definition of done:
|
||||
|
||||
- one thread can be created, claimed, updated, replied to, and completed
|
||||
- all major commands support `--json`
|
||||
|
||||
Status:
|
||||
|
||||
- not complete
|
||||
|
||||
Completed so far:
|
||||
|
||||
- `inbox init`
|
||||
|
||||
Next commands to implement:
|
||||
|
||||
- `inbox send`
|
||||
- `inbox fetch`
|
||||
- `inbox claim`
|
||||
- `inbox update`
|
||||
- `inbox done`
|
||||
- `inbox show`
|
||||
|
||||
### Milestone 4: Orch Core Scheduling
|
||||
|
||||
Goal:
|
||||
|
||||
- implement run/task/dependency/attempt orchestration on top of `inbox`
|
||||
|
||||
First commands:
|
||||
|
||||
- `orch run init`
|
||||
- `orch task add`
|
||||
- `orch dep add`
|
||||
- `orch ready`
|
||||
- `orch dispatch`
|
||||
- `orch reconcile`
|
||||
- `orch blocked`
|
||||
- `orch answer`
|
||||
- `orch status`
|
||||
|
||||
Delay if needed:
|
||||
|
||||
- `retry`
|
||||
- `reassign`
|
||||
- `cancel`
|
||||
- `cleanup`
|
||||
- `wait`
|
||||
|
||||
Definition of done:
|
||||
|
||||
- a leader can create a run
|
||||
- add tasks and dependencies
|
||||
- dispatch a task through `orch`
|
||||
- see worker state reflected back after `reconcile`
|
||||
|
||||
### Milestone 5: Strict Worktree Support
|
||||
|
||||
Goal:
|
||||
|
||||
- ensure code-writing tasks execute in isolated worktrees
|
||||
|
||||
First scope:
|
||||
|
||||
- `orch dispatch` resolves `base_ref`
|
||||
- strict mode fails when the repo is dirty and no explicit base is provided
|
||||
- worktree path and branch name are stored on the attempt
|
||||
|
||||
Definition of done:
|
||||
|
||||
- a code task dispatch creates a real worktree
|
||||
- the assigned worktree path appears in attempt metadata and inbox payload
|
||||
|
||||
### Milestone 6: Waiting Primitives
|
||||
|
||||
Goal:
|
||||
|
||||
- replace blind polling with blocking CLI waits
|
||||
|
||||
Commands:
|
||||
|
||||
- `orch wait`
|
||||
- `inbox wait-reply`
|
||||
|
||||
Definition of done:
|
||||
|
||||
- leader can block on new task events
|
||||
- blocked worker can block on reply events
|
||||
|
||||
### Milestone 7: Council Review
|
||||
|
||||
Goal:
|
||||
|
||||
- implement the user-facing three-reviewer brainstorming workflow
|
||||
|
||||
First commands:
|
||||
|
||||
- `orch council start`
|
||||
- `orch council wait`
|
||||
- `orch council tally`
|
||||
- `orch council report`
|
||||
|
||||
Definition of done:
|
||||
|
||||
- one council run can dispatch three reviewers
|
||||
- tally grouped recommendations into `consensus`, `majority`, and `minority`
|
||||
- produce stable JSON and a markdown report artifact
|
||||
|
||||
## Immediate Next Task
|
||||
|
||||
If a new agent is taking over now, the next concrete step should be:
|
||||
|
||||
1. implement `inbox send`
|
||||
2. implement `inbox fetch`
|
||||
3. implement `inbox claim`
|
||||
4. add a small integration test covering `init -> send -> fetch -> claim`
|
||||
|
||||
This is the smallest meaningful slice because the project already has a compiling skeleton and working schema initialization.
|
||||
|
||||
## Recommended Driver Choices
|
||||
|
||||
Current recommendation:
|
||||
|
||||
- CLI framework: `Cobra`
|
||||
- SQLite driver: pure-Go driver
|
||||
|
||||
Reason:
|
||||
|
||||
- command surfaces are already command-group heavy
|
||||
- pure-Go SQLite keeps distribution simpler
|
||||
|
||||
## Suggested Early Tests
|
||||
|
||||
Add these tests before the codebase grows too much:
|
||||
|
||||
- schema init test
|
||||
- inbox thread lifecycle test
|
||||
- single-task orch dispatch and reconcile test
|
||||
- worktree path generation test
|
||||
- council tally grouping test
|
||||
|
||||
## Out Of Scope For First Pass
|
||||
|
||||
Do not block v1 on these:
|
||||
|
||||
- distributed execution
|
||||
- advanced auth or permissions
|
||||
- patch-producing council mode
|
||||
- configurable reviewer counts beyond three
|
||||
- rich similarity engines for proposal grouping
|
||||
- background daemons beyond blocking CLI commands
|
||||
|
||||
## Handoff Notes For Future Agents
|
||||
|
||||
- The design phase is complete enough to start coding.
|
||||
- Avoid reopening major design questions unless implementation forces it.
|
||||
- The repository already has compiling binaries and working schema init.
|
||||
- Continue with inbox lifecycle commands before adding advanced orchestration.
|
||||
- Preserve the separation:
|
||||
- `inbox` handles communication
|
||||
- `orch` handles scheduling
|
||||
- `council-review` is a workflow on top of `orch`
|
||||
- Treat this file as the implementation entrypoint for new agents.
|
||||
Reference in New Issue
Block a user