392 lines
10 KiB
Markdown
392 lines
10 KiB
Markdown
# 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
|
|
- embedded SQLite schema and migrations exist in code
|
|
- 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` is implemented end-to-end, including send/fetch/claim/renew/update/reply/done/fail/cancel/list/show/watch/wait-reply
|
|
- `inbox` supports blocking waits, lease renewal, unread fetches backed by per-agent read cursors, `--body-file`, artifact attachments, and structured JSON errors with stable exit codes
|
|
- integration tests cover the main inbox lifecycle, wait/watch flows, artifact persistence, and JSON error contracts
|
|
- a human-readable inbox command test-plan set has not been authored yet
|
|
- `orch` currently exists as a command skeleton only
|
|
- no scheduler workflows have been implemented yet
|
|
|
|
This means the project is past design discovery and ready for `orch` 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 complete enough for both CLIs
|
|
- `Milestone 3: Inbox Happy Path` is complete
|
|
- `Milestone 6: Waiting Primitives` is partially complete through `inbox wait-reply`
|
|
|
|
The next practical coding target is `Milestone 4: Orch Core Scheduling`.
|
|
|
|
### 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:
|
|
|
|
- completed for current inbox needs
|
|
|
|
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 continue to rely on `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:
|
|
|
|
- completed
|
|
|
|
Completed so far:
|
|
|
|
- `inbox init`
|
|
- `inbox send`
|
|
- `inbox fetch`
|
|
- `inbox claim`
|
|
- `inbox renew`
|
|
- `inbox update`
|
|
- `inbox reply`
|
|
- `inbox done`
|
|
- `inbox fail`
|
|
- `inbox cancel`
|
|
- `inbox list`
|
|
- `inbox show`
|
|
- `inbox watch`
|
|
- `inbox wait-reply`
|
|
|
|
### 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. create the inbox test documentation tree under `docs/tests/inbox/`
|
|
2. write the shared testing conventions in `docs/tests/inbox/README.md`
|
|
3. add `_shared/README.md` for common fixtures and assertion rules
|
|
4. add command-level `README.md` files for the implemented inbox commands
|
|
5. add `workflows/README.md` for cross-command cases such as unread, wait, and reply flows
|
|
|
|
This is the smallest meaningful documentation slice because the inbox implementation is already present and stable enough to document in detail before `orch` work begins.
|
|
|
|
## 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
|
|
|
|
## Inbox Test Documentation Roadmap
|
|
|
|
Goal:
|
|
|
|
- make inbox behavior easy for a new agent to understand and convert into automated tests without re-reading all code paths
|
|
|
|
Directory layout:
|
|
|
|
- `docs/tests/inbox/README.md`
|
|
- `docs/tests/inbox/_shared/README.md`
|
|
- `docs/tests/inbox/workflows/README.md`
|
|
- `docs/tests/inbox/<command>/README.md`
|
|
|
|
Initial command folders:
|
|
|
|
- `init`
|
|
- `send`
|
|
- `fetch`
|
|
- `claim`
|
|
- `renew`
|
|
- `update`
|
|
- `reply`
|
|
- `done`
|
|
- `fail`
|
|
- `cancel`
|
|
- `list`
|
|
- `show`
|
|
- `watch`
|
|
- `wait-reply`
|
|
|
|
Documentation rules:
|
|
|
|
- organize by folder and `README.md`, not one file per test case
|
|
- do not use numeric test case IDs
|
|
- identify cases by file path plus a stable case title or `slug`
|
|
- keep one command per directory, plus `workflows/` for cross-command behavior
|
|
- use `_shared/` for common fixtures, database conventions, exit-code rules, and shared JSON assertions
|
|
|
|
Required per-case structure:
|
|
|
|
- `用例意义`
|
|
- `前置条件`
|
|
- `输入`
|
|
- `预期输出`
|
|
- `断言结论`
|
|
|
|
Recommended case-title pattern:
|
|
|
|
- `## case: <stable-slug>`
|
|
|
|
Authoring order:
|
|
|
|
1. global conventions in `docs/tests/inbox/README.md`
|
|
2. shared fixtures and assertion helpers in `docs/tests/inbox/_shared/README.md`
|
|
3. lifecycle flow in `docs/tests/inbox/workflows/README.md`
|
|
4. core command docs: `send`, `fetch`, `claim`, `reply`, `done`, `show`
|
|
5. secondary command docs: `renew`, `update`, `fail`, `cancel`, `list`
|
|
6. waiting and read-state docs: `watch`, `wait-reply`, unread and mark-read workflow cases
|
|
|
|
Definition of done:
|
|
|
|
- every implemented inbox command has a dedicated document directory
|
|
- every documented case contains concrete input and expected output
|
|
- shared assumptions are centralized instead of copied into each command file
|
|
- a new agent can pick any case and implement it as an automated test with minimal additional discovery
|
|
|
|
## 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.
|
|
- Finish the inbox test-plan docs before starting broad `orch` implementation.
|
|
- Preserve the separation:
|
|
- `inbox` handles communication
|
|
- `orch` handles scheduling
|
|
- `council-review` is a workflow on top of `orch`
|
|
- When writing inbox test docs, use the folder-per-command structure described above and keep cross-command cases inside `docs/tests/inbox/workflows/`.
|
|
- Treat this file as the implementation entrypoint for new agents.
|