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 now cover each implemented inbox command, plus the main inbox workflows, wait/watch flows, artifact persistence, unread behavior, and JSON error contracts
• a human-readable inbox command test-plan set has been authored under docs/tests/inbox/
• a reusable Codex skill package for inbox now exists under skills/inbox/, with a formal SKILL.md, agents/openai.yaml, and a bundled CLI binary asset
• an inbox skill forward-test plan directory now exists under docs/tests/inbox-skill/, with a shared execution template and multiple scenario cases
• an execution-roadmap workflow now exists under docs/roadmaps/active/ and docs/roadmaps/archive/ for agent-level work traces and completion archives
• orch now implements run init/show, task add, dep add, ready, dispatch, reconcile, blocked, answer, and status
• orch can create runs, gate tasks through dependencies, dispatch work through inbox, reconcile worker thread state back into task state, answer blocked tasks, and create per-attempt Git worktrees during strict dispatch
• orch dispatch now supports --repo-path, --workspace-root, and --strict-worktree, resolves committed base revisions, records workspace metadata on attempts, and writes that metadata into inbox task payloads
• automated integration tests now cover the main orch scheduler slice, including dependency gating, dispatch, blocked-answer flow, reconcile, strict worktree creation, and dirty-repo rejection rules

This means the project now has a working orch core scheduler plus strict worktree-backed dispatch, and is ready for leader-side wait/retry/reassign follow-on work.

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 4: Orch Core Scheduling is complete for the current non-worktree scheduler scope
• Milestone 5: Strict Worktree Support is complete for the current explicit dispatch worktree mode
• Milestone 6: Waiting Primitives is partially complete through inbox wait-reply

The next practical coding target is Milestone 6: Waiting Primitives.

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

Status:

• completed for the current non-worktree scheduling scope

Completed so far:

• orch run init
• orch run show
• orch task add
• orch dep add
• orch ready
• orch dispatch
• orch reconcile
• orch blocked
• orch answer
• orch status
• CLI integration tests cover single-task dispatch/reconcile, dependency gating, blocked-answer flow, and non-ready dispatch rejection

Remaining:

• orch wait
• retry, reassign, cancel, and cleanup workflows

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

Status:

• completed for the current explicit orch dispatch worktree mode

Completed so far:

• orch dispatch can use --repo-path to target a source Git repository without relying on the caller's current working directory
• orch dispatch --strict-worktree resolves base_ref to a concrete commit, defaults to HEAD on clean repositories, and rejects dirty repositories when --base-ref is omitted
• dispatch creates a fresh branch and Git worktree per attempt and persists base_ref, base_commit, branch_name, worktree_path, and workspace_status
• dispatch writes workspace metadata into the inbox task payload for worker runtimes
• reconcile now advances workspace_status from created to active, completed, or abandoned based on thread state
• CLI integration tests cover strict worktree creation, explicit-base dispatch on dirty repos, and strict dirty-repo rejection

Remaining:

• automatic code-task detection so worktree mode can be selected without explicit flags
• orch cleanup for removing completed or abandoned worktrees

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. start Milestone 6: Waiting Primitives
2. implement orch wait over the run-scoped event stream
3. keep the authored inbox test-plan set in docs/tests/inbox/ synchronized if CLI behavior changes during further orch work

The inbox implementation and its human-readable test-plan set are already in place, and orch now supports strict worktree-backed dispatch, so the next meaningful project step is to give the leader a blocking wait primitive and finish the remaining scheduler controls.

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

Completed so far:

• schema init test
• inbox command-level CLI integration coverage aligned to docs/tests/inbox/
• inbox workflow lifecycle coverage
• orch scheduler lifecycle coverage for run/task/dependency/dispatch/reconcile
• orch blocked-question and answer coverage
• orch strict worktree creation and dirty-repo policy coverage

Still recommended before the codebase grows too much:

• worktree path generation test
• orch wait event wake test
• council tally grouping test

Inbox Test Documentation Roadmap

Status:

• completed for the current inbox CLI surface
• command-level and workflow Markdown documents exist under docs/tests/inbox/
• future updates should revise this section only when new inbox commands or materially new CLI-visible behavior are added

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
• docs/tests/inbox/<command>/<case-slug>.md

Initial command folders:

• init
• send
• fetch
• claim
• renew
• update
• reply
• done
• fail
• cancel
• list
• show
• watch
• wait-reply

Documentation rules:

• organize by folder with a README.md entrypoint
• command folders use README.md as an index only
• each command case lives in its own Markdown file named after the case slug
• do not use numeric test case IDs
• identify command cases by concrete file path
• 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:

• 用例意义
• 前置条件
• 输入
• 预期输出
• 断言结论

Case file naming pattern:

• <stable-slug>.md

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.
• The inbox test-plan docs are in place; keep them synchronized before and during broad orch implementation.
• inbox command test-plan folders use README.md as an index plus one file per case; keep any further structural changes consistent with the documented rules above.
• 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.