ai-workflow-skill/docs/implementation-roadmap.md

# 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
- `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. 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.