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
• 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
• inbox-cli.md
• orch-cli.md
• worktree-execution.md
• 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.