diff --git a/AGENTS.md b/AGENTS.md index 449877a..429ea26 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,36 +6,25 @@ This file applies to the entire repository. ## Read First -Before starting substantial work, read the roadmap that matches the task: +Before starting substantial work, read the source-of-truth docs that match the task: -- implementation work: [docs/implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) +- implementation and repository-structure work: [docs/architecture.md](/home/kurihada/project/ai-workflow-skill/docs/architecture.md), [docs/skill-workspace-monorepo.md](/home/kurihada/project/ai-workflow-skill/docs/skill-workspace-monorepo.md) - inbox Markdown test-plan work: [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/docs/tests/inbox/ROADMAP.md) -- execution-trace workflow: [docs/roadmaps/README.md](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/README.md) -## Roadmap Update Rule +## Documentation Update Rule -Updating the relevant roadmap is part of the definition of done. +Updating the relevant source-of-truth documentation is part of the definition of done. -Do not finish a task and leave its roadmap stale. +Do not finish a task and leave its documentation stale. Required behavior: -- if you complete or materially change implementation progress, update [docs/implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) in the same change +- if you complete or materially change implementation behavior, architecture, runtime ownership, or product structure, update the relevant source-of-truth docs in the same change - if you add, remove, or materially revise inbox Markdown test cases or test-plan documents, update [docs/tests/inbox/ROADMAP.md](/home/kurihada/project/ai-workflow-skill/docs/tests/inbox/ROADMAP.md) in the same change - when a test-plan document is created, update document progress - when a test case is written, update authored-case tracking and pending backlog - when a planned item is no longer needed, mark it as removed or deferred instead of silently dropping it -For substantial multi-step work, also keep an execution roadmap under [docs/roadmaps/active/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/active/) while the work is in progress, then move it to [docs/roadmaps/archive/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/archive/) when the work is complete. - -Required behavior for execution roadmaps: - -- before starting substantial multi-step work, create or adopt one roadmap file under [docs/roadmaps/active/](/home/kurihada/project/ai-workflow-skill/docs/roadmaps/active/) -- write the intended task as checklist items and keep them updated as work progresses -- if work is unfinished, blocked, or paused, leave the roadmap in `active/` with current status and next step -- when all checklist items are complete, add a completion summary and move the file to `archive/` in the same change -- use stable slug filenames and prefer one roadmap file per workstream rather than one file per tiny action - ## Inbox Test-Plan Specific Rule For `docs/tests/inbox/`: @@ -53,7 +42,7 @@ For `skills/`: - keep each skill self-contained around `SKILL.md`; add `agents/openai.yaml` and bundled assets only when they directly support real invocation - if a skill depends on an executable or other runtime asset, prefer bundling the required artifact with the skill instead of relying on ad hoc rebuild instructions as the primary workflow - when updating an existing skill, keep `SKILL.md`, `agents/openai.yaml`, and bundled assets consistent with each other -- if you add or materially change a project skill, update [docs/implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md) in the same change +- if you add or materially change a project skill, update the relevant source-of-truth docs in the same change ## Frontend UI Reuse diff --git a/docs/architecture.md b/docs/architecture.md index 8fb0f09..ba7932e 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -149,8 +149,7 @@ Do not put these into `orch`: - [orch-cli.md](/home/kurihada/project/ai-workflow-skill/docs/orch-cli.md): leader-facing scheduler and task graph control plane - [worktree-execution.md](/home/kurihada/project/ai-workflow-skill/docs/worktree-execution.md): strict worktree model for code-writing task attempts - [council-review.md](/home/kurihada/project/ai-workflow-skill/docs/council-review.md): user-facing three-reviewer brainstorm and voting workflow -- [implementation-roadmap.md](/home/kurihada/project/ai-workflow-skill/docs/implementation-roadmap.md): handoff-oriented implementation order and next steps -- [blog-project-example.md](/home/kurihada/project/ai-workflow-skill/docs/blog-project-example.md): concrete example using both layers +- [skill-workspace-monorepo.md](/home/kurihada/project/ai-workflow-skill/docs/skill-workspace-monorepo.md): repository structure, package ownership, and skill workspace layout ## Skills diff --git a/docs/blog-project-example.md b/docs/blog-project-example.md deleted file mode 100644 index bbec4b9..0000000 --- a/docs/blog-project-example.md +++ /dev/null @@ -1,281 +0,0 @@ -# Blog Project Example - -## Goal - -This document simulates how a leader should use `orch` and how workers should use `inbox` for a blog MVP. - -Assumptions: - -- stack: `Next.js + PostgreSQL + Prisma` -- features: public blog pages, admin login, post CRUD, tags, basic tests -- leader owns planning, architecture, dependency decisions, and final integration - -## Task Graph - -The leader decomposes the work into these tasks: - -- `T1`: project skeleton and base wiring -- `T2`: data model and migrations -- `T3`: auth and API contract -- `T4`: backend post and tag APIs -- `T5`: admin UI -- `T6`: public blog UI -- `T7`: QA and acceptance -- `T8`: final integration and user-facing handoff - -Dependencies: - -- `T2` depends on `T1` -- `T3` depends on `T2` -- `T4` depends on `T3` -- `T5` depends on `T3` -- `T6` depends on `T3` -- `T7` depends on `T4`, `T5`, and `T6` -- `T8` depends on `T7` - -## Who Uses What - -- leader uses the `orch` skill and `orch` CLI -- workers use the `inbox` skill and `inbox` CLI -- `orch` is the leader's main interface -- `inbox` is the worker's main interface - -## Simulated Leader Flow - -### 1. Create the Run - -```bash -orch run init --db .agents/coord.db --run blog_mvp_001 --goal "Build blog MVP" --summary "Public blog plus admin CRUD" --json -``` - -### 2. Register Tasks - -```bash -orch task add --run blog_mvp_001 --task T1 --title "Project skeleton" --summary "Initialize app structure, env template, and DB wiring" --default-to foundation-worker --json -orch task add --run blog_mvp_001 --task T2 --title "Data model and migrations" --summary "Create users, posts, tags, and post_tags schema" --default-to db-worker --json -orch task add --run blog_mvp_001 --task T3 --title "Auth and API contract" --summary "Define admin auth flow and CRUD contract" --default-to backend-worker --json -orch task add --run blog_mvp_001 --task T4 --title "Backend APIs" --summary "Implement post and tag CRUD" --default-to backend-worker --json -orch task add --run blog_mvp_001 --task T5 --title "Admin UI" --summary "Implement login and post management pages" --default-to admin-ui-worker --json -orch task add --run blog_mvp_001 --task T6 --title "Public blog UI" --summary "Implement homepage, post detail, and tag page" --default-to frontend-worker --json -orch task add --run blog_mvp_001 --task T7 --title "QA and acceptance" --summary "Run smoke tests and verify MVP acceptance" --default-to qa-worker --json -orch task add --run blog_mvp_001 --task T8 --title "Final integration" --summary "Leader verifies final system and prepares handoff" --json -``` - -### 3. Register Dependencies - -```bash -orch dep add --run blog_mvp_001 --task T2 --depends-on T1 --json -orch dep add --run blog_mvp_001 --task T3 --depends-on T2 --json -orch dep add --run blog_mvp_001 --task T4 --depends-on T3 --json -orch dep add --run blog_mvp_001 --task T5 --depends-on T3 --json -orch dep add --run blog_mvp_001 --task T6 --depends-on T3 --json -orch dep add --run blog_mvp_001 --task T7 --depends-on T4 --json -orch dep add --run blog_mvp_001 --task T7 --depends-on T5 --json -orch dep add --run blog_mvp_001 --task T7 --depends-on T6 --json -orch dep add --run blog_mvp_001 --task T8 --depends-on T7 --json -``` - -### 4. Ask What Is Ready - -```bash -orch ready --run blog_mvp_001 --json -``` - -Expected result: - -```json -{ - "ready": ["T1"] -} -``` - -### 5. Dispatch `T1` - -```bash -orch dispatch --run blog_mvp_001 --task T1 --to foundation-worker --body "Set up the app skeleton, env.example, Prisma initialization, base routes, and startup instructions." --json -``` - -The leader does not hand-write `inbox send`. `orch dispatch` does that under the hood. - -If nothing else is actionable after dispatch, the leader should block on `orch wait` instead of sleeping: - -```bash -orch wait --run blog_mvp_001 --for task_blocked,task_done,task_failed --after-event 0 --timeout-seconds 900 --json -``` - -## Simulated Worker Flow - -### 6. Foundation Worker Polls Inbox - -```bash -inbox fetch --db .agents/coord.db --agent foundation-worker --status pending --json -inbox claim --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --lease-seconds 1800 --json -inbox update --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --status in_progress --summary "Initializing project and wiring Prisma" --json -``` - -### 7. Foundation Worker Finishes - -```bash -inbox done --db .agents/coord.db --agent foundation-worker --thread thr_t1_attempt1 --summary "Project skeleton complete" --body "Project starts locally, DB wiring exists, and env template is present." --json -``` - -## Leader Reconciliation Loop - -### 8. Leader Reconciles - -```bash -orch reconcile --run blog_mvp_001 --json -orch ready --run blog_mvp_001 --json -``` - -Expected result after reconciliation: - -```json -{ - "ready": ["T2"] -} -``` - -### 9. Leader Dispatches `T2` - -```bash -orch dispatch --run blog_mvp_001 --task T2 --to db-worker --body "Create the blog schema with users, posts, tags, and post_tags. Include migration files and keep the schema MVP-scoped." --json -``` - -### 10. Worker Gets Blocked - -The database worker discovers a missing product decision. - -```bash -inbox update --db .agents/coord.db --agent db-worker --thread thr_t2_attempt1 --status blocked --summary "Need post status values" --payload-json '{"question":"Should MVP support only draft and published, or more states?"}' --json -inbox wait-reply --db .agents/coord.db --thread thr_t2_attempt1 --after-event 0 --timeout-seconds 1800 --json -``` - -### 11. Leader Reviews Blocked Work Through `orch` - -```bash -orch reconcile --run blog_mvp_001 --json -orch blocked --run blog_mvp_001 --json -``` - -Expected result: - -```json -{ - "blocked": [ - { - "task_id": "T2", - "thread_id": "thr_t2_attempt1", - "question": "Should MVP support only draft and published, or more states?" - } - ] -} -``` - -### 12. Leader Answers Without Leaving the Scheduler - -```bash -orch answer --run blog_mvp_001 --task T2 --body "Use only draft and published for the MVP. Do not add archived or soft delete yet." --json -``` - -`orch answer` writes the response back into the mapped inbox thread. - -### 13. `T2` Completes, Then `T3` Runs - -The worker resumes and finishes through `inbox done`. - -The leader continues the same loop: - -```bash -orch reconcile --run blog_mvp_001 --json -orch ready --run blog_mvp_001 --json -orch dispatch --run blog_mvp_001 --task T3 --to backend-worker --body "Define admin auth and the API contract for posts and tags. Output the contract as a project artifact and keep UI workers unblocked." --json -``` - -## Parallel Stage - -### 14. `T3` Finishes and Unblocks `T4`, `T5`, and `T6` - -```bash -orch reconcile --run blog_mvp_001 --json -orch ready --run blog_mvp_001 --json -``` - -Expected result: - -```json -{ - "ready": ["T4", "T5", "T6"] -} -``` - -### 15. Leader Dispatches Three Tasks - -```bash -orch dispatch --run blog_mvp_001 --task T4 --to backend-worker --body "Implement the post and tag APIs exactly as defined by the contract." --json -orch dispatch --run blog_mvp_001 --task T5 --to admin-ui-worker --body "Build the admin login and post management UI against the published API contract." --json -orch dispatch --run blog_mvp_001 --task T6 --to frontend-worker --body "Build the public blog pages against the published API contract." --json -``` - -### 16. Another Block Arrives - -The admin UI worker asks whether to use a rich text editor. - -```bash -inbox update --db .agents/coord.db --agent admin-ui-worker --thread thr_t5_attempt1 --status blocked --summary "Editor choice undecided" --payload-json '{"question":"Should the admin editor use a rich text editor or plain textarea in MVP?"}' --json -``` - -Leader response: - -```bash -orch reconcile --run blog_mvp_001 --json -orch blocked --run blog_mvp_001 --json -orch answer --run blog_mvp_001 --task T5 --body "Use a plain textarea in MVP. Avoid adding a rich text dependency in this phase." --json -``` - -The worker then resumes after `inbox wait-reply` wakes with the leader's answer. No side uses blind `sleep` loops. - -## QA and Follow-Up Fix - -### 17. QA Runs After `T4`, `T5`, and `T6` - -```bash -orch reconcile --run blog_mvp_001 --json -orch ready --run blog_mvp_001 --json -orch dispatch --run blog_mvp_001 --task T7 --to qa-worker --body "Verify login, post CRUD, public blog pages, and tag filtering. Return minimal repro steps for any failures." --json -``` - -### 18. QA Finds a Contract Mismatch - -QA reports that deleting a post returns an unexpected response shape. - -The leader can create a follow-up fix task: - -```bash -orch task add --run blog_mvp_001 --task T7a --title "Fix delete post response mismatch" --summary "Align delete response with the published API contract" --default-to backend-worker --json -orch dep add --run blog_mvp_001 --task T7a --depends-on T7 --json -orch reconcile --run blog_mvp_001 --json -orch ready --run blog_mvp_001 --json -orch dispatch --run blog_mvp_001 --task T7a --to backend-worker --body "Fix the delete post response so it matches the contract used by QA and admin UI." --json -``` - -## Final Leader Responsibilities - -The leader still owns: - -- keeping the run coherent -- answering blocked questions -- deciding scope reductions such as textarea instead of rich text -- adding fix tasks after QA -- verifying final acceptance before handoff - -The workers do not own those cross-task decisions. - -## What This Example Shows - -- leader planning and dispatch happen through `orch` -- worker execution happens through `inbox` -- blocked handling stays leader-controlled -- `inbox` is the durable bus -- `orch` is the actual scheduling surface -- leader and workers wait on blocking CLI primitives rather than manual sleeps diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md deleted file mode 100644 index e722899..0000000 --- a/docs/implementation-roadmap.md +++ /dev/null @@ -1,690 +0,0 @@ -# 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 human-readable `orch` test-plan set has now been authored under `docs/tests/orch/`, with a `ROADMAP.md`, shared conventions, workflow scenarios, per-command indexes, and concrete case documents aligned to the current CLI surface, including supplemental coverage for key flag validation, ordering/limit behavior, payload-only answers, cleanup errors, and council report default/error contracts -- 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 -- reusable Codex skill packages for `orch` and `council-review` now exist under `skills/orch/` and `skills/council-review/`, both using bundled copies of the `orch` 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 orch skill forward-test plan directory now exists under `docs/tests/orch-skill/`, with a shared execution contract and eight leader-side workflow scenarios -- a repo-local replay runner now exists at `scripts/run_orch_skill_forward_tests.sh`, and all eight `docs/tests/orch-skill/` cases now include recorded example runs from bundled-CLI replays captured on `2026-03-19`, including added coverage for dependency-gated ready sequencing, active task cancellation, and payload-only blocked answers -- the original five `docs/tests/orch-skill/` cases also include recorded real subagent-forward runs captured on `2026-03-19`, with spawned leader and worker agents using the packaged `skills/orch/` and `skills/inbox/` bundles -- a council-review skill forward-test plan directory now exists under `docs/tests/council-review-skill/`, with a shared execution contract and nine council workflow scenarios covering end-to-end flow, unanimous-only defaults, timeout/before-tally errors, explicit minority reporting, invalid report filters, strict tally semantics, malformed reviewer JSON, and target-file inputs -- an execution-roadmap workflow now exists under `docs/roadmaps/active/` and `docs/roadmaps/archive/` for agent-level work traces and completion archives -- a forward-looking web product monorepo plan now exists under `docs/web-product-monorepo.md`, defining the recommended React frontend, `chi` HTTP service, and the package-owned `operator-api` runtime path for future web work -- the Phase 1 web-product skeleton is now in place, including root `pnpm` workspace files, a standalone React app under `apps/web`, an initial OpenAPI/events contract under `api/`, and the package-owned `operator-api` backend runtime -- the operator API now serves a minimal read-only web API with `chi`, including `/health`, runs list/detail, run task list, blocked-task list, and thread detail endpoints backed by the existing SQLite state -- HTTP tests now cover the initial read-only operator API slice, and the new frontend workspace builds successfully with `pnpm run web:build` -- Phase 2 frontend work has now started by bootstrapping `apps/web` with copied-in `cadence-ui` tokens and foundational components for button, input, textarea, dialog, form, tabs, card, badge, and alert, with the shared token stylesheet loaded from the frontend entrypoint -- the first real Phase 2 read-only operator UI is now implemented in `apps/web`, including routed runs list, run detail, blocked queue, and thread timeline views backed by the existing operator API, plus Tailwind v4 consumer wiring so the source-owned Cadence UI components render correctly in the app -- a repository-level skill workspace monorepo migration plan now exists under `docs/skill-workspace-monorepo.md`, defining the target split between runtime packages under `packages/`, agent-facing skill bundles under `skills/`, support apps under `apps/`, and package-based skill packaging flows -- the first migration phase for the skill workspace monorepo is now complete: root `go.work` exists, `pnpm-workspace.yaml` now discovers `packages/*`, empty runtime module roots now exist under `packages/`, and a declarative `scripts/skill-bundles.json` plus `scripts/package_skill_runtimes.sh` scaffold now define package-oriented skill bundle metadata from the repo root -- `packages/coord-core` now exists as the first real extracted runtime package, containing shared coordination DB/schema, protocol, and store code, and the active coordination runtimes now import `coord-core` instead of root `internal/db`, `internal/store`, and `internal/protocol` -- `packages/inbox-runtime` and `packages/orch-runtime` now exist as package-owned runtimes with their own `cmd/` entrypoints and package-local CLI wiring/tests, and the root skill packaging flow now builds `skills/inbox`, `skills/orch`, and `skills/council-review` from package entrypoints instead of root `cmd/` paths -- `packages/operator-api` now exists as the package-owned HTTP/query/web backend runtime, with package-local `cmd/operator-api`, app, query, and HTTP transport code plus passing package-local tests -- `packages/repo-memory-runtime` now exists as the package-owned `briefdb` runtime imported from the exploratory prototype, `skills/repo-memory` now exists as an agent-facing skill bundle, and the declarative root packaging flow now builds a bundled `skills/repo-memory/assets/briefdb` binary from the package runtime -- a repo-local declarative packaging flow now builds bundled skill CLI assets for `inbox`, `orch`, `council-review`, and `repo-memory` -- `orch` now implements `run init/show`, `task add`, `dep add`, `ready`, `dispatch`, `reconcile`, `wait`, `blocked`, `answer`, `retry`, `reassign`, `cancel`, `cleanup`, 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, retry or reassign work, cancel tasks or runs, clean attempt worktrees, and create per-attempt Git worktrees during strict dispatch -- `orch dispatch` now supports `--repo-path`, `--workspace-root`, and `--strict-worktree`, auto-enables strict worktree mode for code-like tasks inferred from task metadata, resolves committed base revisions, records workspace metadata on attempts, and writes that metadata into inbox task payloads -- `orch wait` now blocks on run-scoped task events and reconciles inbox state while polling so leader waits can wake on worker progress without manual sleep loops -- `orch council start` now creates a dedicated council run, persists council target input metadata, and dispatches the three fixed reviewer roles through the existing scheduler -- `orch council wait` now blocks until the three reviewer tasks reach terminal states or a timeout is reached -- `orch council tally` now parses completed reviewer outputs, persists `council_findings`, groups recommendations into `consensus`, `majority`, and `minority`, and persists `council_groups` -- `orch council report` now reads persisted `council_groups`, renders human-readable markdown reports, writes markdown artifacts, and persists final report metadata in `council_reports` -- automated integration tests now cover the main `orch` scheduler slice, including dependency gating, dispatch, blocked-answer flow, retry, reassign, cancel, cleanup, strict worktree creation, automatic code-task worktree enablement, dirty-repo rejection rules, wait wake/timeout behavior, and council start/wait/tally/report behavior -- additional `orch` command and workflow contract tests now cover the full documented Markdown case set under `docs/tests/orch/`, including `run init/show`, `task add` validation, ready ordering, dispatch attempt/thread contracts, blocked latest-question output, answer payload-only and empty-input rejection, cleanup selector and no-match errors, status summaries, reconcile failed-state mapping, strict-worktree dispatch-to-cleanup, and council report default/error behavior - -This means the project now has a working `orch` core scheduler with automatic worktree selection for code-like tasks, strict worktree-backed dispatch, the main leader-side control loop, and the full v1 council workflow from start through final report generation. - -## 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) -- [web-product-monorepo.md](/home/kurihada/project/ai-workflow-skill/docs/web-product-monorepo.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 -- `Milestone 6: Waiting Primitives` is complete -- `Milestone 7: Council Review` is complete -- `Milestone 8: Web Product Phase 1 Skeleton` is complete -- `Milestone 9: Web Product Phase 2 Read-Only Operator UI` is complete for the initial operator surface -- `Milestone 10: Skill Workspace Monorepo Migration` is complete - -The council review v1 surface is complete, the first web-product skeleton now exists as a separate monorepo workspace plus read-only HTTP backend slice, the first real operator-facing Phase 2 read-only web views now exist on top of the internal Cadence UI component library, and the repository has now completed the migration into a package-owned skill workspace monorepo for the current runtime set. - -### Milestone 1: Go Skeleton - -Goal: - -- initialize the Go module -- choose CLI framework and SQLite driver -- create package layout -- make empty commands compile - -Recommended shape: - -- `packages/coord-core` -- `packages/inbox-runtime` -- `packages/orch-runtime` -- compatibility shims only at the root if still needed temporarily - -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 wait` -- `orch blocked` -- `orch answer` -- `orch retry` -- `orch reassign` -- `orch cancel` -- `orch cleanup` -- `orch status` -- CLI integration tests cover dispatch/reconcile, dependency gating, blocked-answer flow, wait wake/timeout, retry, reassign, cancel, cleanup, and non-ready dispatch rejection - -Remaining: - -- none for the current scheduler control surface - -### 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 - -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 -- `orch dispatch` auto-selects worktree mode for code-like tasks inferred from existing task metadata such as worker role and acceptance markers -- 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 -- `orch cleanup` removes completed or abandoned worktrees and marks attempt workspace state as `cleaned` -- CLI integration tests cover strict worktree creation, auto-enabled worktrees for code-like tasks, explicit-base dispatch on dirty repos, strict dirty-repo rejection, and cleanup - -Remaining: - -- none - -### 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 - -Status: - -- completed - -Completed so far: - -- `orch wait` -- `inbox wait-reply` -- `orch wait` reconciles inbox state while polling and wakes on matching run-scoped `task_*` events -- CLI integration tests cover wait wake and timeout behavior - -### 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 - -Status: - -- completed - -Completed so far: - -- council-specific storage now includes run metadata, reviewer assignment rows, reviewer findings/groups tables, persisted council input references, and final report metadata -- `orch council start` -- `orch council wait` -- `orch council tally` -- `orch council report` -- council start creates a dedicated run, stores council target input metadata, creates reviewer tasks `CR1` through `CR3`, and dispatches the fixed reviewer roles `architecture-reviewer`, `implementation-reviewer`, and `risk-reviewer` -- council wait blocks until all three reviewer tasks reach terminal states or timeout -- council tally parses structured reviewer outputs from completed reviewer result messages and persists grouped recommendations -- council report reads grouped recommendations from persisted `council_groups`, supports `--show` bucket filtering, renders markdown report artifacts, and persists report metadata plus artifact paths -- CLI integration tests cover council start dispatch, metadata persistence, council wait wake/timeout behavior, council tally grouping in `normal` and `strict` modes, and council report default/all/JSON rendering behavior - -Remaining: - -- none for the v1 council workflow - -### Milestone 8: Web Product Phase 1 Skeleton - -Goal: - -- create the first durable web-product backbone without replacing the existing CLI workflows - -Add: - -- root `pnpm` workspace files -- `apps/web` -- `api/openapi.yaml` -- `api/events.md` -- `packages/operator-api` - -Definition of done: - -- the repository contains the agreed monorepo skeleton -- `orchd` can serve a small read-only HTTP API against the existing database -- the frontend workspace builds and can evolve independently in later milestones - -Status: - -- completed - -Completed so far: - -- root `package.json`, `pnpm-workspace.yaml`, and `pnpm-lock.yaml` now define the monorepo JS workspace -- `apps/web` now contains a Vite + React + TypeScript + TanStack Router + TanStack Query frontend shell -- `packages/operator-api/cmd/operator-api` now opens the shared SQLite database, applies migrations, and serves a `chi` router with graceful shutdown handling -- `packages/operator-api/internal/query` now exposes run list/detail, run tasks, blocked-task, and thread-detail read models for the web surface -- `packages/operator-api/internal/app` now provides a thin web-service boundary over the new read service -- `packages/operator-api/internal/httpapi` now owns HTTP routing, JSON/error helpers, and the initial read-only endpoints -- `api/openapi.yaml` now documents the implemented read-only endpoints and response shapes -- `api/events.md` now captures the planned SSE contract for the next realtime slice -- `go test ./...` covers the new HTTP slice, and `pnpm run web:build` succeeds for the frontend workspace - -Remaining: - -- Phase 2 should turn the frontend shell into actual run, task-board, blocked-queue, and thread-detail pages using the new HTTP contract - -### Milestone 9: Web Product Phase 2 Read-Only Operator UI - -Goal: - -- implement the first real operator-facing read-only web UI on top of the Phase 1 shell and current operator API contract - -Add: - -- copied-in `cadence-ui` primitives and token CSS under `apps/web/src/cadence-ui` -- Tailwind v4 consumer setup so the copied-in Cadence UI source renders correctly in the app -- routed screens for runs list, run detail, blocked queue, and thread timeline -- typed frontend read helpers for the current operator API endpoints - -Definition of done: - -- `apps/web` imports the shared Cadence token stylesheet from the frontend entrypoint -- the Cadence UI source-owned components render correctly inside the consumer app -- the first routed read-only operator screens ship against the existing operator API contract -- future web screens can compose from `cadence-ui` primitives instead of raw one-off HTML controls - -Status: - -- completed for the first read-only operator slice - -Completed so far: - -- `apps/web/src/cadence-ui/` now contains copied-in Cadence UI tokens plus foundational components for button, input, textarea, dialog, form, tabs, card, badge, and alert -- `apps/web/package.json` now includes the required Radix, `react-hook-form`, `motion`, and utility dependencies for the copied-in components -- `apps/web/src/main.tsx` now imports `./cadence-ui/tokens/styles.css` -- `apps/web` now includes Tailwind v4 consumer wiring in Vite and the global stylesheet so the copied-in Cadence UI utility classes render correctly -- `apps/web` now includes a typed frontend read layer for runs, run detail, blocked queue aggregation, and thread detail -- `apps/web` now ships routed runs list, run detail, blocked queue, and thread timeline pages using Cadence UI source-owned components for cards, tabs, alerts, inputs, badges, buttons, dialogs, and textareas -- the run detail view now includes grouped task boards and blocked-task summaries, while the thread timeline view now shows message payload and artifact metadata inspectors -- `pnpm run web:build` succeeds for the new operator UI, and local Vite-to-`orchd` proxy smoke checks confirm the frontend can read the seeded runs, blocked, and thread endpoints through the dev server - -Remaining: - -- add operator write actions such as answer, retry, reassign, and cancel on top of the new read-only screens -- add council result/report views and realtime event handling on top of the current routed UI -- install additional `cadence-ui` components on demand as the product surface expands - -### Milestone 10: Skill Workspace Monorepo Migration - -Goal: - -- restructure the repository into a true multi-package monorepo whose primary deliverables are skills and skill runtimes - -Add: - -- `packages/` as the source of truth for Go and future runtime implementations -- `skills/` as the source of truth for agent-facing skill bundles and bundled assets -- a shared coordination kernel package for the `inbox` / `orch` / `orchd` stack only -- a package-based skill packaging flow driven by workspace metadata rather than root-path assumptions - -Definition of done: - -- `inbox`, `orch`, and other runtime-backed skills build from `packages/` rather than root-owned runtime code -- root `skills/` bundles package from declarative bundle metadata -- root runtime ownership under `cmd/` and `internal/` is removed or reduced to workspace orchestration only -- support apps such as `apps/web` remain usable without being treated as the primary deliverable - -Status: - -- completed - -Completed so far: - -- the repository-level migration design is captured in `docs/skill-workspace-monorepo.md` -- the target package split now distinguishes `coord-core`, runtime packages, skill bundles, and support apps -- the migration plan now defines phased extraction for `coord-core`, `inbox-runtime`, `orch-runtime`, `operator-api`, and `repo-memory-runtime` -- root `go.work` now includes the package-owned runtime module roots under `packages/` -- `pnpm-workspace.yaml` now includes `packages/*`, and root `package.json` now exposes monorepo bundle planning, validation, and Go package test scripts -- initial module roots now exist for `packages/coord-core`, `packages/inbox-runtime`, `packages/orch-runtime`, `packages/operator-api`, and `packages/repo-memory-runtime` -- `scripts/skill-bundles.json` now records the first package-oriented skill bundle metadata, including the future `repo-memory` runtime mapping -- `scripts/package_skill_runtimes.sh` now provides a declarative bundle plan/validate scaffold that targets package paths rather than hardcoded root runtime paths -- `packages/coord-core/db` now owns the shared SQLite open, pragmas, migrations, and coordination schema files -- `packages/coord-core/protocol` now owns the shared JSON and CLI error helpers used across the coordination stack -- `packages/coord-core/store` now owns the shared inbox, orch, and council store logic plus its coordination-domain tests -- package-owned coordination runtimes now depend on `packages/coord-core` instead of root `internal/db`, `internal/store`, or root `internal/protocol` -- package-oriented Go validation now runs through the workspace runtime packages, and `packages/coord-core` passes `go test ./...` -- `packages/inbox-runtime/cmd/inbox` plus `packages/inbox-runtime/internal/cli/inbox` now provide a package-owned inbox runtime and pass `go test ./...` -- `packages/orch-runtime/cmd/orch` plus `packages/orch-runtime/internal/cli/orch` now provide a package-owned orch runtime and pass `go test ./...` -- `scripts/skill-bundles.json` now marks `inbox`, `orch`, and `council-review` as ready package-backed bundles -- `scripts/package_skill_runtimes.sh package` now builds and installs `skills/inbox/assets/inbox`, `skills/orch/assets/orch`, and `skills/council-review/assets/orch` from package entrypoints -- the legacy `scripts/package_skill_clis.sh` entrypoint now delegates to the declarative package-oriented packaging flow instead of hardcoding root `cmd/` paths -- `packages/operator-api/cmd/operator-api` plus `packages/operator-api/internal/{app,httpapi,query}` now provide a package-owned web backend runtime and pass `go test ./...` -- `packages/repo-memory-runtime/cmd/briefdb` plus its package-local `internal/brief` and `internal/store` now provide a package-owned repo-memory runtime and pass `go test ./...` -- `skills/repo-memory/` now exists with `SKILL.md`, `agents/openai.yaml`, and a bundled `assets/briefdb` binary produced by the declarative packaging flow -- `docs/tests/repo-memory-skill/` now exists with a README plus an initial forward-test case covering search-before-add and durable entry retrieval through the bundled skill -- legacy root runtime implementation directories under `internal/` have been removed now that package-owned runtimes and package-backed skill bundles are in place -- legacy root `cmd/` compatibility shims have also been removed, so package-owned runtimes under `packages/*/cmd/*` are now the only maintained Go entrypoints - -Remaining: - -- none for the current migration slice -- optional follow-up: archive or delete the external `../tmp/briefdb` prototype once the imported runtime is treated as the sole maintained source - -## Immediate Next Task - -If a new agent is taking over now, the next concrete step should be: - -1. treat `Milestone 10: Skill Workspace Monorepo Migration` as complete for the current runtime set and keep new runtime work inside `packages/` plus `skills/` rather than recreating root-owned implementations -2. resume product-facing work on top of the new workspace, beginning with the next highest-priority feature slice rather than more repository reshuffling -3. keep the authored skill forward-test plans under `docs/tests/*-skill/` synchronized as new skills or runtime-backed bundles are added -4. optionally archive or delete the external `../tmp/briefdb` prototype after confirming no remaining workflow depends on it - -The inbox implementation and its human-readable test-plan set are already in place, `orch` supports the main scheduler loop plus the complete council start/wait/tally/report workflow, the web product now has its first real operator-facing read surfaces, and the repository now uses package-owned runtimes plus agent-facing skill bundles as its primary structure, so the next step should be feature work and incremental new skill additions on top of that workspace rather than further structural churn. - -## 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 -- orch wait wake and timeout coverage -- orch retry, reassign, cancel, and cleanup coverage -- orch council start dispatch and persistence coverage -- orch council wait wake and timeout coverage -- orch council tally grouping coverage -- orch council report default markdown, `--show all`, and JSON shape coverage - -Still recommended before the codebase grows too much: - -- worktree path generation 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//README.md` -- `docs/tests/inbox//.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: - -- `.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 - -## Orch Test Documentation Roadmap - -Status: - -- current planned `orch` Markdown test-plan set is authored under `docs/tests/orch/` -- global conventions, shared fixtures, workflow scenarios, per-command indexes, and concrete case documents now exist -- `docs/tests/orch/ROADMAP.md` now tracks authored counts, document progress, and future additions in the same style used for `docs/tests/inbox/ROADMAP.md` -- supplemental command-visible cases now cover high-value gaps in `task add`, `ready`, `answer`, `cleanup`, and `council report` - -Goal: - -- make `orch` behavior easy for a new agent to understand and convert into automated tests or manual validation steps without re-reading all scheduler code paths - -Directory layout: - -- `docs/tests/orch/README.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/tests/orch/_shared/README.md` -- `docs/tests/orch/workflows/README.md` -- `docs/tests/orch//README.md` -- `docs/tests/orch//.md` - -Current document model: - -- one folder per implemented leaf command -- each command folder uses `README.md` as an index only -- workflow cases live in `docs/tests/orch/workflows/README.md` -- detailed case backlog and authored-case register are tracked centrally in `docs/tests/orch/ROADMAP.md` - -Next documentation step: - -- keep `docs/tests/orch/ROADMAP.md` synchronized when new `orch` CLI behavior or workflow cases are added, removed, or materially revised - -## Out Of Scope For First Pass - -Do not block v1 on these: - -- advanced auth or permissions -- 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. diff --git a/docs/roadmaps/README.md b/docs/roadmaps/README.md deleted file mode 100644 index 5cb3daa..0000000 --- a/docs/roadmaps/README.md +++ /dev/null @@ -1,64 +0,0 @@ -# Execution Roadmaps - -## Purpose - -This directory tracks agent execution roadmaps for substantial multi-step work. - -These files are not project-level design roadmaps. -They are execution traces that make active work, partial progress, and unfinished state visible to the next agent. - -## Directory Layout - -- `active/`: in-progress, blocked, or paused workstreams -- `archive/`: completed workstreams kept for historical traceability -- `TEMPLATE.md`: starting point for new roadmap files - -## Workflow - -1. Before starting substantial multi-step work, create or adopt one roadmap file under `active/`. -2. Write the intended work as checklist items. -3. Update the checklist and status as work progresses. -4. If the work pauses or remains unfinished, leave the file in `active/` with the latest next step. -5. When the work is complete, add a completion summary and move the file to `archive/`. - -## Naming - -- use stable slug filenames -- prefer one roadmap file per workstream -- avoid creating a new roadmap file for trivial single-step actions - -Example filename: - -```text -docs/roadmaps/active/add-inbox-skill-tests.md -``` - -## Required Sections - -Each roadmap file should include: - -- `Title` -- `Status` -- `Owner` -- `Started At` -- `Goal` -- `Scope` -- `Checklist` -- `Files` -- `Decisions` -- `Blockers` -- `Next Step` -- `Completion Summary` - -## Checklist Rule - -- use Markdown checkboxes -- break work into concrete verifiable steps -- mark completed items with `- [x]` -- leave incomplete items visible rather than deleting them silently - -## Relationship To Other Roadmaps - -- use [../implementation-roadmap.md](../implementation-roadmap.md) for project-level implementation state -- use [../tests/inbox/ROADMAP.md](../tests/inbox/ROADMAP.md) for inbox test-plan state -- use this directory for per-workstream execution tracking diff --git a/docs/roadmaps/TEMPLATE.md b/docs/roadmaps/TEMPLATE.md deleted file mode 100644 index 4a91492..0000000 --- a/docs/roadmaps/TEMPLATE.md +++ /dev/null @@ -1,50 +0,0 @@ -# Title - -## Status - -- `in_progress` - -## Owner - -- agent or workstream owner - -## Started At - -- `YYYY-MM-DD` - -## Goal - -- one or two sentences describing the intended outcome - -## Scope - -- what is in scope -- what is explicitly out of scope if needed - -## Checklist - -- [ ] define the concrete work items -- [ ] implement or document the next step -- [ ] validate the result -- [ ] update any required project-level roadmap - -## Files - -- list the primary files expected to change - -## Decisions - -- record key decisions and why they were taken - -## Blockers - -- list current blockers -- write `none` if there are no blockers - -## Next Step - -- describe the next action another agent should take - -## Completion Summary - -- fill this in when moving the file to `archive/` diff --git a/docs/roadmaps/active/.gitkeep b/docs/roadmaps/active/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/roadmaps/active/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/roadmaps/archive/.gitkeep b/docs/roadmaps/archive/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/docs/roadmaps/archive/.gitkeep +++ /dev/null @@ -1 +0,0 @@ - diff --git a/docs/roadmaps/archive/add-execution-roadmap-workflow.md b/docs/roadmaps/archive/add-execution-roadmap-workflow.md deleted file mode 100644 index 8bf4036..0000000 --- a/docs/roadmaps/archive/add-execution-roadmap-workflow.md +++ /dev/null @@ -1,61 +0,0 @@ -# Add Execution Roadmap Workflow - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- introduce a repository-level execution-roadmap workflow so substantial agent work leaves a durable trace while active and a completion record after archiving - -## Scope - -- update `AGENTS.md` with active/archive roadmap rules -- create `docs/roadmaps/README.md` -- create `docs/roadmaps/TEMPLATE.md` -- create tracked `active/` and `archive/` directories -- update `docs/implementation-roadmap.md` - -## Checklist - -- [x] define the execution-roadmap workflow and naming rules -- [x] update `AGENTS.md` to require active roadmap files for substantial multi-step work -- [x] add `docs/roadmaps/README.md` -- [x] add `docs/roadmaps/TEMPLATE.md` -- [x] create tracked `docs/roadmaps/active/` and `docs/roadmaps/archive/` -- [x] update `docs/implementation-roadmap.md` - -## Files - -- `AGENTS.md` -- `docs/roadmaps/README.md` -- `docs/roadmaps/TEMPLATE.md` -- `docs/roadmaps/active/.gitkeep` -- `docs/roadmaps/archive/.gitkeep` -- `docs/implementation-roadmap.md` - -## Decisions - -- use `docs/roadmaps/active/` and `docs/roadmaps/archive/` rather than a single mixed directory -- keep project-level roadmaps separate from per-workstream execution traces -- require one roadmap file per substantial workstream rather than one file per tiny action - -## Blockers - -- none - -## Next Step - -- use `docs/roadmaps/TEMPLATE.md` as the starting point for the next substantial multi-step task - -## Completion Summary - -- the repository now has a documented execution-roadmap workflow, tracked directories for active and archived workstreams, and a reusable template for future agents diff --git a/docs/roadmaps/archive/council-review-skill-direct-replay.md b/docs/roadmaps/archive/council-review-skill-direct-replay.md deleted file mode 100644 index b35c753..0000000 --- a/docs/roadmaps/archive/council-review-skill-direct-replay.md +++ /dev/null @@ -1,62 +0,0 @@ -# Title - -Direct Replay Of Council Review Skill Forward Tests - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Execute the documented `docs/tests/council-review-skill/` forward-test scenarios with real subagents and bundled skill assets. -- Collect pass/fail outcomes and concrete evidence for the current skill bundle behavior. - -## Scope - -- Run the current council-review skill test-plan cases against isolated temp DBs. -- Use `skills/council-review/` for the leader and `skills/inbox/` for reviewers where the case requires reviewer completion. -- Validate outcomes from the main thread with bundled CLI commands. - -## Checklist - -- [x] Review the council-review skill test-plan directory and choose execution order. -- [x] Run `council-report-rejects-before-tally-through-bundled-cli`. -- [x] Run `council-wait-timeout-through-bundled-cli`. -- [x] Run `council-brainstorm-end-to-end-through-bundled-cli`. -- [x] Run `council-unanimous-only-default-report-through-bundled-cli`. -- [x] Summarize results and archive this execution roadmap. - -## Files - -- `docs/tests/council-review-skill/README.md` -- `docs/tests/council-review-skill/*.md` -- `docs/roadmaps/archive/council-review-skill-direct-replay.md` - -## Decisions - -- Start with the single-agent error/timeout cases to verify the leader skill behavior before spending time on four-agent end-to-end runs. -- Keep each case in its own temp directory and DB for isolation. - -## Blockers - -- none - -## Next Step - -- If desired, append `Recorded Example Run` sections to the council-review skill case docs using the captured run ids and temp paths from this replay. - -## Completion Summary - -- `council-report-rejects-before-tally-through-bundled-cli`: passed on `/tmp/council-skill-report-before-tally.AXZn2p/coord.db`; main-thread replay returned exit code `30` with `invalid_state` and the expected “run council tally first” message. -- `council-wait-timeout-through-bundled-cli`: passed on `/tmp/council-skill-wait-timeout.csirvt/coord.db`; main-thread replay returned `woke == false`, `all_complete == false`, and three visible reviewer statuses while `orch status` showed the run still `running`. -- `council-brainstorm-end-to-end-through-bundled-cli`: passed on `/tmp/council-skill-e2e.DLaTj6/coord.db`; main-thread validation confirmed `run.status == done`, three reviewer tasks `done`, default report `show == ["consensus","majority"]`, summary counts `1/1/1`, and markdown artifact `/tmp/council-skill-e2e.DLaTj6/.orch/reports/council_skill_001.md`. -- `council-unanimous-only-default-report-through-bundled-cli`: passed on `/tmp/council-skill-unanimous.MzF1lp/coord.db`; main-thread validation confirmed `run.status == done`, default report `show == ["consensus"]`, preserved summary counts `1/1/1`, and markdown artifact `/tmp/council-skill-unanimous.MzF1lp/.orch/reports/council_skill_002.md`. -- One reviewer agent in the unanimous-only run had an initial thread-id parsing misstep, but it retried through the bundled inbox CLI and finished successfully; the case still passed under independent main-thread validation. diff --git a/docs/roadmaps/archive/council-review-skill-gap-fill-real-forward-test.md b/docs/roadmaps/archive/council-review-skill-gap-fill-real-forward-test.md deleted file mode 100644 index 264b9f5..0000000 --- a/docs/roadmaps/archive/council-review-skill-gap-fill-real-forward-test.md +++ /dev/null @@ -1,65 +0,0 @@ -# Title - -Replay New Council Review Skill Gap-Fill Cases With Sub-Agents - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Execute the five newly added `docs/tests/council-review-skill/` gap-fill cases with real sub-agents and bundled skill assets. -- Capture concrete pass/fail evidence for each case and record the outcome in the workstream trace. - -## Scope - -- Run the five new `council-review-skill` case docs with sub-agents rather than direct CLI replay alone. -- Use `skills/council-review/` for leader roles and `skills/inbox/` for reviewer roles where the case requires reviewer completion. -- Validate outcomes from the main thread with bundled CLI commands and temp-path evidence. - -## Checklist - -- [x] Review the relevant roadmap and case docs before execution. -- [x] Launch sub-agent runners for the five new council-review skill cases. -- [x] Collect final evidence and determine pass/fail for each case. -- [x] Update docs or recorded evidence as needed and archive this execution roadmap. - -## Files - -- `docs/tests/council-review-skill/README.md` -- `docs/tests/council-review-skill/council-report-show-all-includes-minority-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-report-rejects-invalid-show-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-tally-strict-keeps-distinct-proposals-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-reviewer-output-invalid-json-fails-tally-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-start-with-target-file-through-bundled-cli.md` -- `docs/roadmaps/archive/council-review-skill-gap-fill-real-forward-test.md` - -## Decisions - -- Use sub-agents as the execution surface because the user explicitly asked for sub-agent-based testing. -- Group the five cases into a few parallel runners to balance throughput against coordination overhead. -- Prefer the documented forward-test model first; use main-thread validation commands to independently confirm the reported outcome. - -## Blockers - -- initial double-case runners were too broad: leader sub-agents spent time on repository process discovery instead of immediately running the documented bundled-CLI steps -- nested role-agent shell startup needed the narrower `codex exec --dangerously-bypass-approvals-and-sandbox` workaround before the local bundled CLI commands could start reliably - -## Next Step - -- Commit or otherwise preserve the recorded real-forward evidence if the user wants the updated case docs saved in Git history. - -## Completion Summary - -- All five newly added `council-review-skill` cases passed under real sub-agent execution with isolated temp DBs and bundled skill assets. -- Main-thread validation independently confirmed the critical assertions for `target-file`, `show all`, invalid `--show`, `strict` tally semantics, and malformed-reviewer JSON failure at tally time. -- Added `Recorded Real Forward Run` sections to the five case docs with concrete temp paths, run ids, thread ids, and validation summaries. -- The final successful runs used narrower role prompts that explicitly forbade repo discovery or roadmap work before executing the bundled CLI workflow steps. diff --git a/docs/roadmaps/archive/council-review-skill-gap-fill.md b/docs/roadmaps/archive/council-review-skill-gap-fill.md deleted file mode 100644 index 9992632..0000000 --- a/docs/roadmaps/archive/council-review-skill-gap-fill.md +++ /dev/null @@ -1,62 +0,0 @@ -# Title - -Expand Council Review Skill Test Plan Coverage - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add the next batch of high-value `docs/tests/council-review-skill/` forward-test cases to cover important council workflow gaps beyond the initial smoke suite. - -## Scope - -- Update `docs/tests/council-review-skill/README.md` with the expanded case index. -- Add five new council-review skill case documents. -- Update `docs/implementation-roadmap.md` to reflect the broader skill test-plan coverage. - -## Checklist - -- [x] Identify the highest-value uncovered council-review skill scenarios. -- [x] Update the council-review skill README case index. -- [x] Author the five new case documents. -- [x] Update implementation roadmap and archive this execution roadmap. - -## Files - -- `docs/tests/council-review-skill/README.md` -- `docs/tests/council-review-skill/council-report-show-all-includes-minority-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-report-rejects-invalid-show-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-tally-strict-keeps-distinct-proposals-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-reviewer-output-invalid-json-fails-tally-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-start-with-target-file-through-bundled-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/council-review-skill-gap-fill.md` - -## Decisions - -- Prioritize skill-level scenarios that add real workflow coverage rather than mechanically duplicating every lower-level `orch council` contract. -- Focus the gap fill on explicit report filtering, strict tally semantics, malformed reviewer output, and non-prompt target context. - -## Blockers - -- none - -## Next Step - -- Capture recorded example runs or direct CLI replays for the new council-review skill cases when execution evidence is needed. - -## Completion Summary - -- Expanded `docs/tests/council-review-skill/README.md` so the shared execution contract now explicitly covers target-file fixtures and indexes the five new gap-fill cases. -- Added five forward-test case documents covering explicit `--show all` minority reporting, invalid `--show` rejection, strict tally semantics, malformed reviewer JSON at tally time, and target-file council start inputs. -- Updated `docs/implementation-roadmap.md` to record that the council-review skill test-plan directory now covers nine workflow scenarios rather than only the initial smoke suite. diff --git a/docs/roadmaps/archive/council-review-skill-test-plan.md b/docs/roadmaps/archive/council-review-skill-test-plan.md deleted file mode 100644 index 55ca37f..0000000 --- a/docs/roadmaps/archive/council-review-skill-test-plan.md +++ /dev/null @@ -1,63 +0,0 @@ -# Title - -Add Council Review Skill Test Plan Documents - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add a human-readable forward-test plan directory for the packaged `skills/council-review/` bundle under `docs/tests/`. -- Mirror the structure used by `docs/tests/inbox-skill/` and `docs/tests/orch-skill/` while adapting it to the high-level `orch council ...` workflow and reviewer coordination model. - -## Scope - -- Create `docs/tests/council-review-skill/README.md`. -- Author an initial set of `council-review` skill scenario cases as separate Markdown files. -- Update implementation progress docs to record the new test-plan directory. - -## Checklist - -- [x] Review `docs/tests/orch-skill/`, `skills/council-review/`, and the current council workflow surface. -- [x] Create `docs/tests/council-review-skill/README.md` with shared execution contract and case index. -- [x] Author initial `council-review-skill` case documents. -- [x] Update implementation roadmap and archive this execution roadmap. - -## Files - -- `docs/tests/council-review-skill/README.md` -- `docs/tests/council-review-skill/council-brainstorm-end-to-end-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-unanimous-only-default-report-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-wait-timeout-through-bundled-cli.md` -- `docs/tests/council-review-skill/council-report-rejects-before-tally-through-bundled-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/council-review-skill-test-plan.md` - -## Decisions - -- Keep `council-review-skill` separate from `orch-skill`, because `council-review` is a distinct project-local skill package with its own user-facing semantics. -- Use the same forward-test style as the other skill test-plan directories, but inject `skills/council-review/` only into the leader and `skills/inbox/` into reviewer agents. -- Treat shared DB bootstrap through `inbox init` as part of the test-runner setup contract rather than pretending `council-review` owns schema initialization. - -## Blockers - -- none - -## Next Step - -- Capture one or more real recorded example runs for the end-to-end and unanimous-only cases after the packaged council-review skill is exercised in practice. - -## Completion Summary - -- Added `docs/tests/council-review-skill/README.md` as the shared execution contract and index for council-review skill validation. -- Added four initial forward-test scenario documents covering end-to-end brainstorm/report, unanimous-only default reporting, wait timeout, and report-before-tally invalid-state behavior. -- Updated `docs/implementation-roadmap.md` to record that the separate `council-review` skill now has a dedicated forward-test plan directory under `docs/tests/council-review-skill/`. diff --git a/docs/roadmaps/archive/orch-auto-code-worktree.md b/docs/roadmaps/archive/orch-auto-code-worktree.md deleted file mode 100644 index 4677420..0000000 --- a/docs/roadmaps/archive/orch-auto-code-worktree.md +++ /dev/null @@ -1,59 +0,0 @@ -# Orch Auto Code Worktree - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- automatically select worktree mode for code-like `orch` tasks so leaders do not need to pass worktree flags for common code-writing dispatches - -## Scope - -- extend dispatch-time worktree selection to infer code-like tasks from existing task metadata -- keep explicit worktree flags authoritative when provided -- add integration tests for automatic worktree enablement and non-code fallback behavior -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect current dispatch/worktree code and the remaining roadmap item -- [x] implement automatic code-task detection for worktree selection -- [x] add integration coverage for auto-enable and non-code fallback -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-auto-code-worktree.md` -- `docs/implementation-roadmap.md` -- `internal/cli/orch/worktree.go` -- `internal/cli/orch/integration_test.go` - -## Decisions - -- infer code-like tasks from existing metadata instead of introducing a new required task field in this slice -- prioritize explicit worktree flags over automatic detection so users can still force or shape dispatch behavior - -## Blockers - -- none - -## Next Step - -- move to `Milestone 7: Council Review` - -## Completion Summary - -- `orch dispatch` now auto-enables strict worktree mode for code-like tasks inferred from existing task metadata when explicit worktree flags are omitted -- explicit worktree flags remain authoritative and non-code tasks still fall back to ordinary non-worktree dispatch -- integration tests now cover both auto-enabled worktree dispatch and non-code fallback behavior diff --git a/docs/roadmaps/archive/orch-core-scheduling.md b/docs/roadmaps/archive/orch-core-scheduling.md deleted file mode 100644 index 9c50d33..0000000 --- a/docs/roadmaps/archive/orch-core-scheduling.md +++ /dev/null @@ -1,64 +0,0 @@ -# Orch Core Scheduling - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement the first usable `orch` scheduling slice on top of the existing shared SQLite schema and `inbox` transport -- deliver a leader workflow that can create a run, add tasks and dependencies, dispatch ready work, reconcile inbox state, and answer blocked tasks - -## Scope - -- add `orch` store primitives for runs, tasks, dependencies, attempts, readiness, dispatch, reconcile, blocked lookup, and run status views -- add CLI commands for the first Milestone 4 surface -- add automated tests for the happy-path scheduler workflow and core state transitions -- update the implementation roadmap with the new progress state - -## Checklist - -- [x] inspect the current `orch` skeleton, schema, and project roadmaps -- [x] implement `orch` store types and DB operations for runs, tasks, dependencies, attempts, and task-state transitions -- [x] add CLI commands for `run init`, `run show`, `task add`, `dep add`, `ready`, `dispatch`, `reconcile`, `blocked`, `answer`, and `status` -- [x] add automated tests covering run creation, dependency gating, dispatch, blocked-answer flow, and reconcile -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary when the workstream is complete - -## Files - -- `docs/roadmaps/active/orch-core-scheduling.md` -- `docs/implementation-roadmap.md` -- `cmd/orch/main.go` -- `internal/cli/orch/root.go` -- `internal/cli/orch/*.go` -- `internal/store/orch.go` -- `internal/cli/orch/*_test.go` - -## Decisions - -- start with the scheduler loop that reuses existing `inbox` behavior rather than attempting worktree orchestration in the same slice -- keep JSON response style aligned with `inbox` so both CLIs expose consistent machine-readable contracts - -## Blockers - -- none - -## Next Step - -- start `Milestone 5: Strict Worktree Support` by extending `orch dispatch` to resolve a concrete base commit and create real worktree metadata - -## Completion Summary - -- `orch` now has a usable core scheduler loop backed by shared SQLite state and `inbox` -- the implemented CLI surface covers `run init/show`, `task add`, `dep add`, `ready`, `dispatch`, `reconcile`, `blocked`, `answer`, and `status` -- integration tests now verify dispatch/reconcile lifecycle, dependency gating, blocked-question answers, and non-ready dispatch rejection diff --git a/docs/roadmaps/archive/orch-council-report.md b/docs/roadmaps/archive/orch-council-report.md deleted file mode 100644 index e6f0dad..0000000 --- a/docs/roadmaps/archive/orch-council-report.md +++ /dev/null @@ -1,65 +0,0 @@ -# Orch Council Report - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement `orch council report` so persisted grouped recommendations can be rendered as a final council report in human-readable markdown and stable JSON output - -## Scope - -- add `orch council report` with `--run`, `--show`, and `--json` -- read grouped recommendations from persisted `council_groups` -- render a markdown report for the requested buckets and persist report metadata if needed by the existing design -- add integration coverage for default output, `--show all`, and JSON shape -- run `go test ./...`, update the implementation roadmap, and archive this workstream when complete - -## Checklist - -- [x] inspect council report requirements, current council store, and CLI/test patterns -- [x] implement council report store and CLI command -- [x] add integration coverage for default buckets, `--show all`, and JSON output -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-council-report.md` -- `docs/implementation-roadmap.md` -- `docs/council-review.md` -- `internal/store/council.go` -- `internal/cli/orch/council.go` -- `internal/cli/orch/council_report.go` -- `internal/cli/orch/integration_test.go` -- `internal/db/schema/007_council_reports.sql` - -## Decisions - -- keep the scope limited to report rendering on top of existing persisted council data -- persist final report metadata in a dedicated `council_reports` table so the last rendered report artifact path can be recovered without re-reading files -- place markdown artifacts under a `.orch/reports/` tree rooted next to the active database context so tests and non-default databases do not dirty the repository root - -## Blockers - -- none - -## Next Step - -- none - -## Completion Summary - -- added `orch council report` with `--run`, `--show`, and `--json` on top of persisted `council_groups` -- report rendering now produces human-readable markdown, writes a markdown artifact, and persists final report metadata in `council_reports` -- integration coverage now verifies default `consensus,majority` output, `--show all`, and the JSON response shape diff --git a/docs/roadmaps/archive/orch-council-skills.md b/docs/roadmaps/archive/orch-council-skills.md deleted file mode 100644 index 9a86400..0000000 --- a/docs/roadmaps/archive/orch-council-skills.md +++ /dev/null @@ -1,74 +0,0 @@ -# Title - -Add Orch And Council Review Skills With Bundled CLI Assets - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add project-local skill packages for `orch` and `council-review`. -- Add a repeatable packaging flow that builds the `orch` CLI binary and installs it into both skills as bundled assets. - -## Scope - -- Create `skills/orch/` with `SKILL.md`, `agents/openai.yaml`, and bundled `assets/orch`. -- Create `skills/council-review/` with `SKILL.md`, `agents/openai.yaml`, and bundled `assets/orch`. -- Add a repo-local packaging script for building and copying the `orch` CLI binary into both skill asset directories. -- Update implementation progress docs to reflect the new skill packages and packaging flow. - -## Checklist - -- [x] Review current skill structure, embedded skill drafts, and bundling expectations. -- [x] Create `orch` skill package files. -- [x] Create `council-review` skill package files. -- [x] Add and validate the CLI packaging script. -- [x] Build bundled `orch` binaries into both skills and smoke-check them. -- [x] Update roadmap docs and archive this execution roadmap. - -## Files - -- `skills/orch/SKILL.md` -- `skills/orch/agents/openai.yaml` -- `skills/orch/assets/orch` -- `skills/council-review/SKILL.md` -- `skills/council-review/agents/openai.yaml` -- `skills/council-review/assets/orch` -- `scripts/package_skill_clis.sh` -- `docs/architecture.md` -- `docs/blog-project-example.md` -- `docs/inbox-cli.md` -- `docs/orch-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/orch-council-skills.md` - -## Decisions - -- Use one underlying `orch` binary for both skills, because `council` is an `orch` subcommand rather than a separate executable. -- Keep each skill self-contained by bundling its own copy of the `orch` binary asset. -- Keep the packaging script able to refresh the existing `inbox` skill binary as well, so all bundled CLIs can be rebuilt through one entrypoint. -- Standardize on the actual implemented skill name `orch` rather than the older draft term `orchestrator`. - -## Blockers - -- none - -## Next Step - -- none - -## Completion Summary - -- Added `skills/orch/` and `skills/council-review/`, each with `SKILL.md`, `agents/openai.yaml`, and a bundled `assets/orch` binary. -- Added `scripts/package_skill_clis.sh` to rebuild bundled skill CLIs for `inbox`, `orch`, and `council-review`. -- Built and smoke-checked the new `orch` skill assets with `./skills/orch/assets/orch --help` and `./skills/council-review/assets/orch council --help`. -- Updated implementation and reference docs to use the actual `orch` skill name and to record the new skill packages and packaging flow. diff --git a/docs/roadmaps/archive/orch-council-start.md b/docs/roadmaps/archive/orch-council-start.md deleted file mode 100644 index 36e233f..0000000 --- a/docs/roadmaps/archive/orch-council-start.md +++ /dev/null @@ -1,62 +0,0 @@ -# Orch Council Start - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement the first Milestone 7 slice by adding council input storage and `orch council start` - -## Scope - -- persist council run metadata plus target input references -- add `orch council start` to create a council run and dispatch three reviewer tasks -- add integration tests for council start dispatch behavior -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect council docs, schema, and existing orch dispatch primitives -- [x] implement council storage and `orch council start` -- [x] add integration coverage for council start -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-council-start.md` -- `docs/implementation-roadmap.md` -- `internal/db/schema/*.sql` -- `internal/store/council.go` -- `internal/cli/orch/root.go` -- `internal/cli/orch/council*.go` -- `internal/cli/orch/integration_test.go` - -## Decisions - -- treat `orch council start` as creating a dedicated run id rather than attaching to a pre-existing ordinary run -- persist target prompt/file/repo/task references in a separate council input table instead of overloading the existing `runs` table - -## Blockers - -- none - -## Next Step - -- continue Milestone 7 with `orch council wait`, then add tally and report on top of the persisted reviewer data - -## Completion Summary - -- council input references are now persisted separately from council run metadata -- `orch council start` creates a dedicated council run, dispatches the three fixed reviewer roles, and records reviewer assignment rows for downstream wait/tally/report steps -- integration tests now cover council start dispatch behavior and stored council metadata diff --git a/docs/roadmaps/archive/orch-council-tally.md b/docs/roadmaps/archive/orch-council-tally.md deleted file mode 100644 index 708b9a4..0000000 --- a/docs/roadmaps/archive/orch-council-tally.md +++ /dev/null @@ -1,64 +0,0 @@ -# Orch Council Tally - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement `orch council tally` so completed reviewer outputs can be parsed, grouped, and persisted as council findings and grouped recommendations - -## Scope - -- parse reviewer output JSON from completed council reviewer threads -- persist parsed findings into `council_findings` -- group recommendations into `consensus`, `majority`, and `minority` buckets and persist them into `council_groups` -- add integration tests for normal and strict similarity modes -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect council tally docs and current council storage -- [x] implement council tally store and CLI command -- [x] add integration coverage for normal and strict tally behavior -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-council-tally.md` -- `docs/implementation-roadmap.md` -- `docs/council-review.md` -- `internal/store/council.go` -- `internal/cli/orch/council.go` -- `internal/cli/orch/council_tally.go` -- `internal/cli/orch/integration_test.go` - -## Decisions - -- read reviewer outputs from the latest `result` message on each reviewer thread -- require reviewer outputs to be valid structured JSON before tallying -- use a simple normalized proposal grouping strategy for v1, with `strict` preserving wording differences and `normal` grouping by normalized intent tokens - -## Blockers - -- none - -## Next Step - -- move on to `orch council report` - -## Completion Summary - -- `orch council tally` now parses structured reviewer output JSON from completed reviewer result messages -- parsed reviewer findings are persisted into `council_findings`, and grouped recommendations are persisted into `council_groups` -- tally supports `normal` and `strict` similarity modes and computes `consensus`, `majority`, and `minority` buckets diff --git a/docs/roadmaps/archive/orch-council-wait.md b/docs/roadmaps/archive/orch-council-wait.md deleted file mode 100644 index be8e283..0000000 --- a/docs/roadmaps/archive/orch-council-wait.md +++ /dev/null @@ -1,61 +0,0 @@ -# Orch Council Wait - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement `orch council wait` so the leader can block until all three reviewer tasks finish or a timeout is reached - -## Scope - -- add council wait status queries and blocking wait behavior on top of existing council reviewer rows -- add CLI support for `orch council wait` -- add integration tests for wake and timeout behavior -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect council wait docs and current council storage -- [x] implement council wait store and CLI command -- [x] add integration coverage for council wait wake and timeout -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-council-wait.md` -- `docs/implementation-roadmap.md` -- `internal/store/council.go` -- `internal/cli/orch/council.go` -- `internal/cli/orch/council_wait.go` -- `internal/cli/orch/integration_test.go` - -## Decisions - -- treat reviewer completion as all council reviewer tasks reaching terminal task states -- reuse the existing `orch wait`/reconcile polling model rather than introducing a separate push mechanism for councils - -## Blockers - -- none - -## Next Step - -- implement `orch council tally` by parsing completed reviewer outputs into `council_findings` and grouping similar proposals - -## Completion Summary - -- `orch council wait` now blocks until all council reviewer tasks reach terminal task states or a timeout is reached -- wait responses return reviewer task statuses on both wake and timeout paths -- integration tests now cover council wait wake and timeout behavior diff --git a/docs/roadmaps/archive/orch-markdown-test-cases.md b/docs/roadmaps/archive/orch-markdown-test-cases.md deleted file mode 100644 index d2d42fd..0000000 --- a/docs/roadmaps/archive/orch-markdown-test-cases.md +++ /dev/null @@ -1,65 +0,0 @@ -# Orch Markdown Test Cases - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- author the first complete wave of human-readable Markdown test-plan cases for `orch`, using the existing `docs/tests/inbox/` structure and writing style as the reference model - -## Scope - -- add concrete command-case Markdown files under `docs/tests/orch//` -- add concrete workflow cases under `docs/tests/orch/workflows/README.md` -- update each affected command index `README.md` -- keep `docs/tests/orch/ROADMAP.md` synchronized with authored files, authored-case counts, and remaining backlog -- update `docs/implementation-roadmap.md` if the documentation progress materially changes - -## Checklist - -- [x] create or adopt an execution roadmap for the workstream -- [x] inspect representative `inbox` Markdown case files and map `orch` cases from current backlog -- [x] author core scheduler command cases and update their indexes -- [x] author interactive leader command cases and update their indexes -- [x] author council command cases and update their indexes -- [x] author workflow cases and synchronize `docs/tests/orch/ROADMAP.md` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-markdown-test-cases.md` -- `docs/implementation-roadmap.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/tests/orch/workflows/README.md` -- `docs/tests/orch//README.md` -- `docs/tests/orch//.md` - -## Decisions - -- use the existing `docs/tests/inbox/` case structure and tone as the immediate template for `orch` -- keep shared index/count integration in the main thread, while delegating disjoint command-directory write scopes to sub-agents -- keep `docs/tests/orch/ROADMAP.md` aligned with the richer `docs/tests/inbox/ROADMAP.md` format by tracking individual case files in `Document Progress` and `Authored Case Register` - -## Blockers - -- none - -## Next Step - -- no further step in this workstream; future changes should start from `docs/tests/orch/ROADMAP.md` if new cases are added - -## Completion Summary - -- authored the current planned `orch` Markdown test-plan set across workflow, core scheduler, interactive control, and council command surfaces -- synchronized `docs/tests/orch/ROADMAP.md` with real files on disk, authored-case counts, and a completed authored-case register -- updated `docs/implementation-roadmap.md` so future agents see `docs/tests/orch/` as an authored test-plan set rather than only a skeleton diff --git a/docs/roadmaps/archive/orch-markdown-test-gap-fill.md b/docs/roadmaps/archive/orch-markdown-test-gap-fill.md deleted file mode 100644 index 2082999..0000000 --- a/docs/roadmaps/archive/orch-markdown-test-gap-fill.md +++ /dev/null @@ -1,71 +0,0 @@ -# Orch Markdown Test Gap Fill - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- fill the five highest-priority Markdown test-plan gaps in `docs/tests/orch/` so the current `orch` CLI has better coverage for key flag validation, non-default output behavior, and error contracts - -## Scope - -- add or update `docs/tests/orch/task-add/` for invalid `acceptance-json` and invalid `priority` -- add or update `docs/tests/orch/ready/` for priority ordering and `--limit` -- add or update `docs/tests/orch/answer/` for payload-only or empty-input validation -- add or update `docs/tests/orch/cleanup/` for invalid-input or no-matching-work cleanup behavior -- add or update `docs/tests/orch/council-report/` for pre-tally/invalid-show/only-unanimous report behavior as needed -- keep `docs/tests/orch/ROADMAP.md` and `docs/implementation-roadmap.md` synchronized - -## Checklist - -- [x] create an execution roadmap for the workstream -- [x] add missing `task add` and `ready` cases and update indexes -- [x] add missing `answer` and `cleanup` cases and update indexes -- [x] add missing `council report` cases and update indexes -- [x] synchronize `docs/tests/orch/ROADMAP.md` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-markdown-test-gap-fill.md` -- `docs/implementation-roadmap.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/tests/orch/task-add/README.md` -- `docs/tests/orch/task-add/*.md` -- `docs/tests/orch/ready/README.md` -- `docs/tests/orch/ready/*.md` -- `docs/tests/orch/answer/README.md` -- `docs/tests/orch/answer/*.md` -- `docs/tests/orch/cleanup/README.md` -- `docs/tests/orch/cleanup/*.md` -- `docs/tests/orch/council-report/README.md` -- `docs/tests/orch/council-report/*.md` - -## Decisions - -- use focused follow-up case files instead of broad rewrites to keep the current authored set stable -- keep shared tracking files in the main thread and delegate only disjoint command directories - -## Blockers - -- none - -## Next Step - -- no further step in this workstream; future follow-up should start from the updated `docs/tests/orch/ROADMAP.md` - -## Completion Summary - -- added 10 supplemental `orch` Markdown test-plan cases covering high-priority gaps in `task add`, `ready`, `answer`, `cleanup`, and `council report` -- synchronized the relevant command index `README.md` files, the shared `docs/tests/orch/ROADMAP.md` ledger, and the project-level implementation roadmap -- used sub-agents for three disjoint directory slices while keeping shared tracking files in the main thread diff --git a/docs/roadmaps/archive/orch-markdown-test-plan-skeleton.md b/docs/roadmaps/archive/orch-markdown-test-plan-skeleton.md deleted file mode 100644 index f4ee5e9..0000000 --- a/docs/roadmaps/archive/orch-markdown-test-plan-skeleton.md +++ /dev/null @@ -1,60 +0,0 @@ -# Orch Markdown Test Plan Skeleton - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- create an inbox-style human-readable Markdown test-plan skeleton for `orch` so future agents can add command and workflow cases without rediscovering the documentation structure - -## Scope - -- add `docs/tests/orch/README.md` and `docs/tests/orch/ROADMAP.md` -- add shared and workflow entrypoint documents under `docs/tests/orch/` -- add one directory per `orch` leaf command with an index `README.md` -- update the implementation roadmap and archive this execution roadmap when complete - -## Checklist - -- [x] read the existing inbox Markdown test-plan roadmap and directory conventions -- [x] define the `orch` leaf-command directory model -- [x] add the `docs/tests/orch/` skeleton files and per-command indexes -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-markdown-test-plan-skeleton.md` -- `docs/implementation-roadmap.md` -- `docs/tests/orch/README.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/tests/orch/_shared/README.md` -- `docs/tests/orch/workflows/README.md` - -## Decisions - -- mirror the inbox test-plan structure at the directory and index level, but model `orch` by leaf commands rather than command groups -- seed the new roadmap with a concrete pending-case backlog derived from existing `internal/cli/orch/integration_test.go` coverage so later authoring can proceed without rediscovery - -## Blockers - -- none - -## Next Step - -- start writing the highest-value `orch` case documents from the new backlog, beginning with the happy-path scheduler workflow and strict worktree dispatch cases - -## Completion Summary - -- created `docs/tests/orch/` with a top-level `README.md`, `ROADMAP.md`, shared conventions, workflow entrypoint, and one index `README.md` per implemented leaf command -- documented the initial `orch` Markdown test-plan model as leaf-command directories instead of command groups -- updated the project implementation roadmap so future agents can discover the new `orch` test-plan skeleton from the main handoff document diff --git a/docs/roadmaps/archive/orch-markdown-test-review.md b/docs/roadmaps/archive/orch-markdown-test-review.md deleted file mode 100644 index 88eaa76..0000000 --- a/docs/roadmaps/archive/orch-markdown-test-review.md +++ /dev/null @@ -1,59 +0,0 @@ -# Orch Markdown Test Review - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- review the authored `docs/tests/orch/` command directories and case files for completeness against the current `orch` CLI and identify any missing or weakly specified test-plan coverage - -## Scope - -- inspect each `docs/tests/orch//` directory -- compare current Markdown cases against the implemented CLI and existing automated integration tests -- identify missing command-visible contracts, edge cases, or unclear assertions -- summarize findings without expanding scope into unrelated implementation changes - -## Checklist - -- [x] create an execution roadmap for the review -- [x] inspect current `docs/tests/orch/` files and split the review by command area -- [x] collect findings for core scheduler command directories -- [x] collect findings for interactive leader/control command directories -- [x] collect findings for council command directories -- [x] summarize whether any command directories need supplemental cases or edits -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-markdown-test-review.md` -- `docs/tests/orch/README.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/tests/orch//README.md` -- `docs/tests/orch//.md` - -## Decisions - -- treat this as a review task first: surface gaps before proposing edits - -## Blockers - -- none - -## Next Step - -- none; future follow-up should start from the review findings and add only the missing case files or constraints that were called out - -## Completion Summary - -- completed a read-only coverage review of the authored `docs/tests/orch/` command directories against the current `orch` CLI and automated integration tests -- identified the highest-value missing or weakly specified command-visible cases so follow-up authoring can target concrete gaps instead of re-auditing the whole tree diff --git a/docs/roadmaps/archive/orch-remaining-controls.md b/docs/roadmaps/archive/orch-remaining-controls.md deleted file mode 100644 index 2d4b04b..0000000 --- a/docs/roadmaps/archive/orch-remaining-controls.md +++ /dev/null @@ -1,60 +0,0 @@ -# Orch Remaining Controls - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement the remaining leader-side scheduler control commands: `retry`, `reassign`, `cancel`, and `cleanup` - -## Scope - -- add store and CLI support for retrying failed tasks, reassigning blocked or failed tasks, cancelling a task or full run, and cleaning up attempt worktrees -- add integration tests that exercise the new control flows on top of the existing scheduler/worktree implementation -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect docs and current attempt/thread/worktree helpers -- [x] implement `retry`, `reassign`, `cancel`, and `cleanup` store operations and CLI commands -- [x] add integration coverage for the new control flows -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-remaining-controls.md` -- `docs/implementation-roadmap.md` -- `internal/cli/orch/root.go` -- `internal/cli/orch/*.go` -- `internal/cli/orch/integration_test.go` -- `internal/store/orch.go` - -## Decisions - -- `retry` and `reassign` will reuse the existing dispatch pipeline so new attempts keep the same attempt/worktree semantics as normal dispatch -- `cleanup` will remove worktree directories and mark attempt workspace state as `cleaned`, but will not delete attempt branches in this slice - -## Blockers - -- none - -## Next Step - -- decide whether worktree mode should be selected automatically for code tasks, then either implement that ergonomics layer or defer it before moving into council workflows - -## Completion Summary - -- `orch` now supports the remaining leader-side control commands: `retry`, `reassign`, `cancel`, and `cleanup` -- retry and reassign reuse the normal dispatch pipeline, including per-attempt worktree allocation when the previous attempt was worktree-backed -- cleanup removes eligible worktree paths and marks attempt workspace state as `cleaned` diff --git a/docs/roadmaps/archive/orch-skill-direct-replay.md b/docs/roadmaps/archive/orch-skill-direct-replay.md deleted file mode 100644 index 0cfe146..0000000 --- a/docs/roadmaps/archive/orch-skill-direct-replay.md +++ /dev/null @@ -1,66 +0,0 @@ -# Title - -Direct Replay For Orch Skill Cases - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- Execute the documented `docs/tests/orch-skill/` scenarios against the bundled `skills/orch/assets/orch` and `skills/inbox/assets/inbox` binaries, capture concrete evidence, and sync the repo docs with the observed results. - -## Scope - -- add a reusable local runner for the five documented orch-skill scenarios -- run the scenarios and capture per-case evidence -- update the orch-skill docs with recorded runs and note the execution mode -- update the implementation roadmap to reflect the new replay coverage - -## Checklist - -- [x] Review the orch-skill case docs and bundled CLI surfaces. -- [x] Add a reusable direct replay runner for the five orch-skill scenarios. -- [x] Execute the runner and collect evidence for all five cases. -- [x] Update the orch-skill docs with recorded example runs and execution notes. -- [x] Update the implementation roadmap and archive this execution roadmap. - -## Files - -- `scripts/run_orch_skill_forward_tests.sh` -- `docs/tests/orch-skill/README.md` -- `docs/tests/orch-skill/leader-run-dispatch-reconcile-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-blocked-answer-resume-through-bundled-cli.md` -- `docs/tests/orch-skill/strict-worktree-dispatch-to-cleanup-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-retries-failed-task-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-reassigns-blocked-task-through-bundled-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/orch-skill-direct-replay.md` - -## Decisions - -- Use direct bundled-CLI replay instead of spawning Codex role agents in this turn, because the current session does not permit sub-agent delegation unless the user explicitly asks for it. -- Keep the replay runner repo-local so the same scenarios can be rerun later without reconstructing the command flow by hand. - -## Blockers - -- none - -## Next Step - -- rerun `scripts/run_orch_skill_forward_tests.sh` when the bundled skill binaries or orch-skill case docs change, and add true multi-agent forward coverage later if explicit sub-agent execution is needed - -## Completion Summary - -- Added `scripts/run_orch_skill_forward_tests.sh` as a reusable direct bundled-CLI replay runner for the five documented orch-skill scenarios. -- Executed the runner on `2026-03-19`; all five scenarios passed and produced per-case JSON evidence under a temporary output root. -- Updated `docs/tests/orch-skill/README.md` plus all five case files with recorded example runs and explicit execution-mode notes. -- Updated `docs/implementation-roadmap.md` to record the new replay runner and captured orch-skill execution evidence. diff --git a/docs/roadmaps/archive/orch-skill-gap-fill.md b/docs/roadmaps/archive/orch-skill-gap-fill.md deleted file mode 100644 index fa73ad3..0000000 --- a/docs/roadmaps/archive/orch-skill-gap-fill.md +++ /dev/null @@ -1,66 +0,0 @@ -# Title - -Add Missing Orch Skill Forward-Test Cases - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add three missing `docs/tests/orch-skill/` forward-test cases covering dependency-gated ready sequencing, direct task cancellation, and payload-only blocked answers. -- Extend the bundled-CLI replay runner so the new cases can be executed and recorded with concrete evidence. - -## Scope - -- update `docs/tests/orch-skill/README.md` with the new case index entries -- add three new case documents under `docs/tests/orch-skill/` -- extend `scripts/run_orch_skill_forward_tests.sh` to execute the new scenarios -- run the replay suite and record the new example-run evidence -- update `docs/implementation-roadmap.md` - -## Checklist - -- [x] Review the current orch skill docs, runner, and CLI coverage to identify the missing skill-side cases. -- [x] Add the active orch-skill gap-fill case documents and README updates. -- [x] Extend the orch-skill replay runner for the new scenarios. -- [x] Execute the replay coverage and capture recorded example-run evidence. -- [x] Update implementation progress docs and archive this roadmap. - -## Files - -- `docs/tests/orch-skill/README.md` -- `docs/tests/orch-skill/leader-dispatches-dependent-task-after-prerequisite-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-cancels-active-task-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-answers-blocked-task-with-payload-json-through-bundled-cli.md` -- `scripts/run_orch_skill_forward_tests.sh` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/orch-skill-gap-fill.md` - -## Decisions - -- Keep the new coverage in `orch-skill` rather than `docs/tests/orch/`, because the gap is leader-side skill usage, not raw CLI contract coverage. -- Use the direct bundled-CLI replay path for immediate recorded evidence, consistent with the existing orch-skill case documents. - -## Blockers - -- none - -## Next Step - -- rerun the direct replay suite when the orch skill bundle or any orch-skill case document changes, and add real subagent-forward evidence for the three new gap-fill cases when that coverage is needed. - -## Completion Summary - -- Added three new `docs/tests/orch-skill/` cases covering dependency-gated ready sequencing, direct active-task cancellation, and payload-only blocked answers. -- Extended `scripts/run_orch_skill_forward_tests.sh` so the replay runner now executes all eight documented orch-skill scenarios. -- Ran the full replay suite at `/tmp/orch-skill-forward-gap-fill` and recorded passing example-run evidence for the three new cases. -- Updated `docs/tests/orch-skill/README.md` and `docs/implementation-roadmap.md` to reflect the expanded orch-skill coverage and evidence status. diff --git a/docs/roadmaps/archive/orch-skill-real-forward-test.md b/docs/roadmaps/archive/orch-skill-real-forward-test.md deleted file mode 100644 index 8d87ff4..0000000 --- a/docs/roadmaps/archive/orch-skill-real-forward-test.md +++ /dev/null @@ -1,67 +0,0 @@ -# Title - -Real Subagent Forward Tests For Orch Skill - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- Execute the documented `docs/tests/orch-skill/` scenarios using real spawned role agents with injected `skills/orch/` and `skills/inbox/`, then record concrete pass/fail evidence and sync the repository docs. - -## Scope - -- validate subagent skill injection for project-local orch and inbox skills -- run the five documented orch-skill forward cases with real leader and worker subagents -- collect main-thread validation evidence and agent summaries -- update the orch-skill docs and implementation roadmap with the real forward-test results - -## Checklist - -- [x] Re-read the orch-skill shared execution contract and worker skill constraints. -- [x] Validate project-local skill injection with a small spawned-agent probe. -- [x] Execute the five orch-skill cases with real spawned role agents and collect evidence. -- [x] Update the orch-skill docs and implementation roadmap with the real forward-test results. -- [x] Archive this execution roadmap with a completion summary. - -## Files - -- `docs/tests/orch-skill/README.md` -- `docs/tests/orch-skill/leader-run-dispatch-reconcile-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-blocked-answer-resume-through-bundled-cli.md` -- `docs/tests/orch-skill/strict-worktree-dispatch-to-cleanup-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-retries-failed-task-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-reassigns-blocked-task-through-bundled-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/orch-skill-real-forward-test.md` - -## Decisions - -- Use real spawned role agents per case instead of the direct replay runner, because the user explicitly asked for true tests with subagents. -- Keep the main thread responsible for DB setup, fixture creation, and independent validation so the final judgment does not rely only on role-agent self-reporting. -- Fall back from `fork_context: true` to `fork_context: false` for the real case runs after the first wider-context attempt stalled and mis-executed the worker-side contract in this repo. -- For the longer `retry` and `reassign` cases, keep one leader agent active across staged prompts instead of one long monolithic prompt, because staged execution proved more reliable while still preserving a real agent-owned `orch` flow. - -## Blockers - -- none - -## Next Step - -- rerun the same five cases when the packaged skill binaries or case docs change, and consider adding the same real subagent coverage for `council-review` if that surface needs parity - -## Completion Summary - -- Verified both project-local skill bundles with spawned-agent help-command probes before the real runs. -- Collected successful real subagent evidence for all five orch-skill cases under `/tmp/orch-skill-subagents.J1XWgs`. -- Main-thread validation confirmed all five final successful runs reached the expected `orch` and `inbox` states. -- Updated `docs/tests/orch-skill/README.md`, all five case files, and `docs/implementation-roadmap.md` to record the new real forward-test coverage. diff --git a/docs/roadmaps/archive/orch-skill-test-plan.md b/docs/roadmaps/archive/orch-skill-test-plan.md deleted file mode 100644 index 0ef4365..0000000 --- a/docs/roadmaps/archive/orch-skill-test-plan.md +++ /dev/null @@ -1,64 +0,0 @@ -# Title - -Add Orch Skill Test Plan Documents - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add a human-readable forward-test plan directory for the packaged `skills/orch/` bundle under `docs/tests/`. -- Mirror the proven structure of `docs/tests/inbox-skill/` while adapting it to leader-side `orch` workflows and `inbox`-backed worker coordination. - -## Scope - -- Create `docs/tests/orch-skill/README.md`. -- Author an initial set of `orch` skill scenario cases as separate Markdown files. -- Update implementation progress docs to record the new test-plan directory. - -## Checklist - -- [x] Review `docs/tests/inbox-skill/`, `skills/orch/`, and current `orch` workflow surface. -- [x] Create `docs/tests/orch-skill/README.md` with shared execution contract and case index. -- [x] Author initial `orch-skill` case documents. -- [x] Update implementation roadmap and archive this execution roadmap. - -## Files - -- `docs/tests/orch-skill/README.md` -- `docs/tests/orch-skill/leader-run-dispatch-reconcile-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-blocked-answer-resume-through-bundled-cli.md` -- `docs/tests/orch-skill/strict-worktree-dispatch-to-cleanup-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-retries-failed-task-through-bundled-cli.md` -- `docs/tests/orch-skill/leader-reassigns-blocked-task-through-bundled-cli.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/archive/orch-skill-test-plan.md` - -## Decisions - -- Keep `orch-skill` separate from `council-review` skill docs, because `council-review` is a distinct project-local skill package. -- Use the same forward-test style as `inbox-skill`, but inject `skills/orch/` only into the leader and `skills/inbox/` into workers. -- Treat shared DB bootstrap through `inbox init` as part of the test-runner setup contract rather than pretending `orch` owns schema initialization. - -## Blockers - -- none - -## Next Step - -- Add a parallel `docs/tests/council-review-skill/` directory when the separate council skill test surface is ready to be documented. - -## Completion Summary - -- Added `docs/tests/orch-skill/README.md` as the shared execution contract and index for leader-side skill validation. -- Added five initial forward-test scenario documents covering happy-path orchestration, blocked-answer resume, strict worktree cleanup, retry after failure, and reassignment from one worker to another. -- Updated `docs/implementation-roadmap.md` to record that the `orch` skill now has a dedicated forward-test plan directory under `docs/tests/orch-skill/`. diff --git a/docs/roadmaps/archive/orch-strict-worktree-support.md b/docs/roadmaps/archive/orch-strict-worktree-support.md deleted file mode 100644 index 6b05c30..0000000 --- a/docs/roadmaps/archive/orch-strict-worktree-support.md +++ /dev/null @@ -1,63 +0,0 @@ -# Orch Strict Worktree Support - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement dispatch-time strict worktree support so `orch` can resolve a committed base, create a branch and worktree per attempt, and persist workspace metadata into attempt storage and inbox payload - -## Scope - -- extend `orch dispatch` to support Git-backed worktree creation -- enforce strict-mode base resolution and dirty-repo checks -- persist `base_ref`, `base_commit`, `branch_name`, `worktree_path`, and `workspace_status` -- add integration tests for successful worktree dispatch and strict-mode rejection on dirty repositories -- update project-level implementation roadmap after the work is validated - -## Checklist - -- [x] inspect current worktree design docs and dispatch constraints -- [x] implement git helpers for repo discovery, base resolution, branch naming, and worktree creation -- [x] wire worktree metadata into `orch dispatch` attempt storage and inbox payload -- [x] add integration coverage for strict worktree success and dirty-repo failure -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with completion summary - -## Files - -- `docs/roadmaps/archive/orch-strict-worktree-support.md` -- `docs/implementation-roadmap.md` -- `internal/cli/orch/dispatch.go` -- `internal/cli/orch/integration_test.go` -- `internal/cli/orch/worktree.go` -- `internal/store/orch.go` - -## Decisions - -- use the current working directory as the default source repo for `orch dispatch`, with an explicit override flag only if implementation needs it -- keep worktree creation tied to dispatch so failed workspace creation cannot silently leave a task marked as dispatched - -## Blockers - -- none - -## Next Step - -- implement `orch wait`, then continue with retry/reassign/cancel/cleanup on top of the now worktree-aware dispatch model - -## Completion Summary - -- `orch dispatch` now supports strict Git-backed worktree provisioning with repo discovery, committed base resolution, branch naming, and per-attempt worktree paths -- dispatch persists workspace metadata on attempts and includes the same metadata in inbox task payloads for worker runtimes -- integration tests now cover successful strict worktree creation, dirty-repo rejection without `--base-ref`, and explicit-base dispatch on dirty repositories diff --git a/docs/roadmaps/archive/orch-test-case-implementation.md b/docs/roadmaps/archive/orch-test-case-implementation.md deleted file mode 100644 index e4d9ee1..0000000 --- a/docs/roadmaps/archive/orch-test-case-implementation.md +++ /dev/null @@ -1,70 +0,0 @@ -# Title - -Implement Orch Markdown Test Cases As Automated Tests - -## Status - -- `completed` - -## Owner - -- Codex main agent - -## Started At - -- `2026-03-19` - -## Goal - -- Add automated `orch` coverage for the command-level cases documented under `docs/tests/orch/`. -- Keep roadmap and implementation status synchronized while the work is in progress. - -## Scope - -- Add or expand Go tests for currently undocumented automation gaps under `internal/cli/orch/`. -- Update `docs/implementation-roadmap.md` to reflect the broader `orch` automated coverage. -- Update `docs/tests/orch/ROADMAP.md` to reflect the alignment between Markdown cases and automated coverage. - -## Checklist - -- [x] Review repository instructions, implementation roadmap, and `docs/tests/orch/` case inventory. -- [x] Map Markdown cases to existing `orch` automated coverage and identify missing scenarios. -- [x] Implement missing non-council command tests. -- [x] Implement missing council/report command tests. -- [x] Run targeted and full `orch` test validation. -- [x] Update roadmap documents and archive this execution roadmap. - -## Files - -- `internal/cli/orch/command_contracts_core_test.go` -- `internal/cli/orch/command_contracts_edges_test.go` -- `internal/cli/orch/command_contracts_remaining_test.go` -- `internal/cli/orch/council_report_contracts_test.go` -- `docs/implementation-roadmap.md` -- `docs/tests/orch/ROADMAP.md` -- `docs/roadmaps/archive/orch-test-case-implementation.md` - -## Decisions - -- Start from the existing `internal/cli/orch/integration_test.go` suite instead of creating a second parallel harness. -- Use sub-agents with isolated write scopes where practical, while keeping shared roadmap and final integration in the main thread. -- Split the missing coverage into four focused test files: - - `command_contracts_core_test.go` for `run show`, `task add`, and `ready` - - `command_contracts_edges_test.go` for `answer` and `cleanup` - - `command_contracts_remaining_test.go` for the remaining command and workflow gaps - - `council_report_contracts_test.go` for council report edge/default behavior - -## Blockers - -- none - -## Next Step - -- none - -## Completion Summary - -- Added 19 focused `orch` tests across four new test files to close the documented Markdown-case gaps under `docs/tests/orch/`. -- Covered the remaining command contracts for `run init/show`, `task add`, `ready`, `dispatch`, `blocked`, `answer`, `cleanup`, `status`, `reconcile`, and council report edge/default behavior. -- Added explicit workflow coverage for strict-worktree dispatch-to-cleanup and council-review end-to-end. -- Validation passed with `go test ./internal/cli/orch` and `go test ./...`. diff --git a/docs/roadmaps/archive/orch-wait.md b/docs/roadmaps/archive/orch-wait.md deleted file mode 100644 index 9af64d7..0000000 --- a/docs/roadmaps/archive/orch-wait.md +++ /dev/null @@ -1,60 +0,0 @@ -# Orch Wait - -## Status - -- `completed` - -## Owner - -- codex - -## Started At - -- `2026-03-19` - -## Goal - -- implement `orch wait` so the leader can block on run-scoped task events instead of manual sleep loops - -## Scope - -- add store support for waiting on run-scoped events with event-type filters and timeout behavior -- make `orch wait` reconcile inbox state while polling so worker transitions can surface as `task_*` events -- add integration tests for wake and timeout behavior -- update the implementation roadmap and archive this workstream when complete - -## Checklist - -- [x] inspect `orch wait` docs and current event/reconcile behavior -- [x] implement `orch wait` store and CLI layers -- [x] add integration coverage for wake and timeout paths -- [x] run `go test ./...` -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary - -## Files - -- `docs/roadmaps/archive/orch-wait.md` -- `docs/implementation-roadmap.md` -- `internal/cli/orch/root.go` -- `internal/cli/orch/wait.go` -- `internal/cli/orch/integration_test.go` -- `internal/store/orch.go` - -## Decisions - -- let `orch wait` perform reconcile while polling so a leader can wait directly on `task_*` events without a separate manual reconcile loop - -## Blockers - -- none - -## Next Step - -- implement the remaining leader-side scheduler controls: `retry`, `reassign`, `cancel`, and `cleanup` - -## Completion Summary - -- `orch wait` now blocks on run-scoped `task_*` events with `--for`, `--after-event`, and timeout support -- the wait loop reconciles inbox state while polling, so worker thread transitions can wake the leader without a separate manual reconcile step -- integration tests now cover both wake-on-blocked and timeout behavior diff --git a/docs/roadmaps/archive/remove-root-cmd-compat-shims.md b/docs/roadmaps/archive/remove-root-cmd-compat-shims.md deleted file mode 100644 index 26cd86a..0000000 --- a/docs/roadmaps/archive/remove-root-cmd-compat-shims.md +++ /dev/null @@ -1,60 +0,0 @@ -# Remove Root Cmd Compatibility Shims - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Remove the legacy root `cmd/` compatibility shims now that package-owned runtimes are the source of truth, and clean up the remaining current docs and test indexes that still point at deleted root runtime paths. - -## Scope - -- remove root `cmd/inbox`, `cmd/orch`, and `cmd/orchd` -- update current docs and test-plan indexes that still reference removed root runtime paths -- keep package-owned runtime workflows and skill packaging validated after the cleanup - -## Checklist - -- [x] inspect remaining references to root `cmd/` and deleted root `internal/` runtime paths -- [x] update current docs and test indexes to point at package-owned runtime paths -- [x] remove the root `cmd/` files and any now-unneeded root shim wiring -- [x] validate package-owned runtime and skill packaging workflows after the cleanup -- [x] update roadmap state and archive this workstream if complete - -## Files - -- `docs/roadmaps/archive/remove-root-cmd-compat-shims.md` -- `cmd/` -- `docs/implementation-roadmap.md` -- `docs/tests/` -- `docs/skill-workspace-monorepo.md` -- `docs/web-product-monorepo.md` -- `go.mod` - -## Decisions - -- treat archived roadmaps as historical records; fix only current source-of-truth docs and current test indexes unless a broken archived reference blocks real workflows - -## Blockers - -- none - -## Next Step - -- continue routine feature work on top of the package-owned runtime workspace without recreating root-owned Go entrypoints - -## Completion Summary - -- updated the current inbox and orch test-plan indexes so they now point at package-owned runtime test files instead of deleted root `internal/cli/*` paths -- removed the root `cmd/` compatibility shims and the now-unneeded root Go module files so package-owned runtimes under `packages/*/cmd/*` are the only maintained Go entrypoints -- added a root `pnpm run go:test` script that validates package-owned Go runtimes directly, replacing reliance on a root Go module -- synchronized the current implementation and web monorepo docs with the package-owned runtime layout after the cleanup diff --git a/docs/roadmaps/archive/rename-orchd-runtime-to-operator-api.md b/docs/roadmaps/archive/rename-orchd-runtime-to-operator-api.md deleted file mode 100644 index 51762f6..0000000 --- a/docs/roadmaps/archive/rename-orchd-runtime-to-operator-api.md +++ /dev/null @@ -1,59 +0,0 @@ -# Rename Operator API Runtime - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Rename the package-owned web backend runtime from `packages/orchd-runtime` to `packages/operator-api` and rename its command entrypoint from `cmd/orchd` to `cmd/operator-api` so the current workspace no longer carries the ambiguous `orchd` name. - -## Scope - -- rename the package directory and module path -- update imports, workspace metadata, and current docs -- validate the package-oriented build and test flows after the rename - -## Checklist - -- [x] inspect current `orchd-runtime` references -- [x] rename the package directory and module path to `operator-api` -- [x] update workspace metadata, imports, and current docs -- [x] validate package-oriented Go tests and frontend build after the rename -- [x] archive this roadmap and commit the completed rename - -## Files - -- `docs/roadmaps/archive/rename-orchd-runtime-to-operator-api.md` -- `go.work` -- `packages/operator-api/` -- `docs/implementation-roadmap.md` -- `docs/skill-workspace-monorepo.md` -- `docs/web-product-monorepo.md` - -## Decisions - -- rename both the package and the command entrypoint together so current source-of-truth code no longer carries the `orchd` name - -## Blockers - -- none - -## Next Step - -- continue feature work with `packages/operator-api` as the backend runtime name and avoid reintroducing the old `orchd` label - -## Completion Summary - -- renamed the package-owned backend runtime from `packages/orchd-runtime` to `packages/operator-api` -- renamed the package-owned daemon entrypoint from `cmd/orchd` to `cmd/operator-api` -- updated current imports, workspace metadata, frontend copy, and current architecture docs to the new operator API name -- validated the renamed runtime through package-oriented Go tests, skill bundle packaging, and frontend build checks diff --git a/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md b/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md deleted file mode 100644 index 9814fc8..0000000 --- a/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md +++ /dev/null @@ -1,63 +0,0 @@ -# Skill Workspace Monorepo Migration Design - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Design a full migration plan that turns this repository from a single-root implementation repo with bundled skill wrappers into a true multi-package monorepo whose primary deliverables are skills and their runtimes. - -## Scope - -- create an execution trace for the migration-design workstream -- inspect the current Go, JS, skill-packaging, docs, and test boundaries that constrain the migration -- define the target monorepo package layout, including shared coordination core, runtime packages, and agent-facing skill bundles -- define the rollout sequence, compatibility rules, and packaging/test implications -- capture the resulting design in-repo and keep roadmap state synchronized - -## Checklist - -- [x] create the active execution roadmap for the skill-workspace monorepo migration design workstream -- [x] inspect current repository structure, packaging scripts, and skill boundaries -- [x] define the target package layout and ownership boundaries -- [x] define the migration phases, compatibility strategy, and validation plan -- [x] capture the migration design in-repo -- [x] update `docs/implementation-roadmap.md` if the design materially changes the repository roadmap -- [x] archive this execution roadmap with a completion summary if the design slice is complete - -## Files - -- `docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md` -- `docs/implementation-roadmap.md` -- `docs/skill-workspace-monorepo.md` -- `scripts/` -- `skills/` -- `cmd/` -- `internal/` - -## Decisions - -- treat this work as architecture design rather than implementation so the output should be a concrete migration blueprint, not partial directory churn - -## Blockers - -- none - -## Next Step - -- start the actual workspace bootstrap phase by adding `go.work`, expanding workspace manifests, and creating the first package roots described by the migration plan - -## Completion Summary - -- inspected the current root-owned runtime model, including `cmd/`, `internal/`, skill asset packaging, skill forward-test plans, and the JS workspace boundaries -- produced `docs/skill-workspace-monorepo.md`, which defines the target repository model, package layout, ownership rules, packaging flow, testing model, and phased migration plan -- updated `docs/implementation-roadmap.md` so the repository now explicitly tracks the monorepo migration as the next major milestone rather than continuing to grow root-owned runtimes diff --git a/docs/roadmaps/archive/skill-workspace-monorepo-migration.md b/docs/roadmaps/archive/skill-workspace-monorepo-migration.md deleted file mode 100644 index 1be8819..0000000 --- a/docs/roadmaps/archive/skill-workspace-monorepo-migration.md +++ /dev/null @@ -1,65 +0,0 @@ -# Skill Workspace Monorepo Migration - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Execute `Milestone 10: Skill Workspace Monorepo Migration` by moving the repository toward a true multi-package monorepo whose primary deliverables are skills and skill runtimes. - -## Scope - -- bootstrap the shared workspace structure described in `docs/skill-workspace-monorepo.md` -- complete migration phases incrementally, committing after each completed phase -- keep packaging, roadmap, and validation flows synchronized as the migration proceeds - -## Checklist - -- [x] create or adopt an active execution roadmap for the migration workstream -- [x] Phase 1: bootstrap `go.work`, expanded workspace manifests, package roots, and declarative skill bundle metadata -- [x] Phase 2: extract shared coordination code into `packages/coord-core` -- [x] Phase 3: extract `inbox-runtime` and `orch-runtime` -- [x] Phase 4: extract `orchd-runtime` -- [x] Phase 5: import `repo-memory-runtime` and add `skills/repo-memory` -- [x] Phase 6: remove root runtime ownership and normalize package-based packaging - -## Files - -- `docs/roadmaps/archive/skill-workspace-monorepo-migration.md` -- `docs/skill-workspace-monorepo.md` -- `docs/implementation-roadmap.md` -- `go.work` -- `pnpm-workspace.yaml` -- `package.json` -- `packages/` -- `scripts/` - -## Decisions - -- keep one long-lived active roadmap for the full migration rather than opening a new execution trace for every individual phase -- complete and commit one migration phase at a time so the workspace remains bisectable - -## Blockers - -- none - -## Next Step - -- resume product work on top of the package-owned runtime workspace, starting with whichever user-facing feature slice has priority next - -## Completion Summary - -- bootstrapped the repository as a multi-package workspace with `go.work`, expanded JS workspace discovery, and declarative skill bundle metadata -- extracted the shared coordination kernel into `packages/coord-core` -- extracted package-owned runtimes for `inbox`, `orch`, `orchd`, and `repo-memory` -- switched the root skill packaging flow to build from package entrypoints, including the new `repo-memory` bundle -- removed the legacy root runtime implementation directories under `internal/`, leaving root `cmd/*` as compatibility shims while package-owned runtimes remain the source of truth diff --git a/docs/roadmaps/archive/web-frontend-cadence-ui-bootstrap.md b/docs/roadmaps/archive/web-frontend-cadence-ui-bootstrap.md deleted file mode 100644 index 0e6c2a6..0000000 --- a/docs/roadmaps/archive/web-frontend-cadence-ui-bootstrap.md +++ /dev/null @@ -1,62 +0,0 @@ -# Web Frontend Cadence UI Bootstrap - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Bootstrap the `apps/web` frontend with copied-in `cadence-ui` components and shared token styles so Phase 2 web UI work can build on the project component library instead of the bare Vite scaffold. - -## Scope - -- create an execution trace for this frontend bootstrap slice -- install the initial `cadence-ui` component set into `apps/web` -- wire the Cadence token stylesheet into the frontend entrypoint -- validate the frontend workspace build after the component copy-in -- keep `docs/implementation-roadmap.md` synchronized with the new frontend state - -## Checklist - -- [x] create the active execution roadmap for the Cadence UI frontend bootstrap workstream -- [x] install the initial `cadence-ui` component set into `apps/web` -- [x] wire `apps/web/src/main.tsx` to load `cadence-ui` token styles -- [x] validate the frontend workspace build and resolve any dependency gaps -- [x] update `docs/implementation-roadmap.md` -- [x] archive this execution roadmap with a completion summary if the slice is fully complete - -## Files - -- `docs/roadmaps/archive/web-frontend-cadence-ui-bootstrap.md` -- `docs/implementation-roadmap.md` -- `apps/web/package.json` -- `apps/web/src/main.tsx` -- `apps/web/src/cadence-ui/` -- `pnpm-lock.yaml` - -## Decisions - -- start Phase 2 frontend work by copying in the shared component library instead of building bespoke primitives inside `apps/web` - -## Blockers - -- none - -## Next Step - -- build the first Phase 2 product screens in `apps/web` on top of the copied-in Cadence UI primitives, installing additional registry components only when those screens need them - -## Completion Summary - -- ran the `cadence-ui` registry installer from `/Users/xd/project/cadence-ui` and copied the initial component set into `apps/web/src/cadence-ui`, including shared tokens plus button, input, textarea, dialog, form, tabs, card, badge, and alert primitives -- wired `apps/web/src/main.tsx` to import `./cadence-ui/tokens/styles.css` so the copied-in components share the library token base from app startup -- installed the newly required frontend dependencies into the workspace, refreshed `pnpm-lock.yaml`, and verified the result with `pnpm run web:build` -- synchronized `docs/implementation-roadmap.md` so Phase 2 frontend work now explicitly continues from the Cadence UI foundation diff --git a/docs/roadmaps/archive/web-phase2-read-only-ui.md b/docs/roadmaps/archive/web-phase2-read-only-ui.md deleted file mode 100644 index 190d8ad..0000000 --- a/docs/roadmaps/archive/web-phase2-read-only-ui.md +++ /dev/null @@ -1,70 +0,0 @@ -# Web Phase 2 Read-Only UI - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Implement the first real Phase 2 operator UI in `apps/web` by shipping the read-only runs list, run detail, blocked queue, and thread timeline views on top of the existing `orchd` HTTP API and Cadence UI source-owned components. - -## Scope - -- create an execution trace for the Phase 2 read-only UI workstream -- wire the frontend to the existing read-only API contract -- implement routed views for runs list, run detail, blocked queue, and thread timeline -- reuse Cadence UI source-owned components instead of introducing new foundational UI primitives -- validate the frontend build and keep `docs/implementation-roadmap.md` synchronized - -## Checklist - -- [x] create the active execution roadmap for the Phase 2 read-only UI workstream -- [x] inspect the current frontend shell and backend read contract -- [x] add the frontend data layer and route structure for the Phase 2 read-only views -- [x] implement the runs list, run detail, blocked queue, and thread timeline screens -- [x] ensure Cadence UI styles render correctly in the consumer app -- [x] validate the frontend build and fix any type or integration issues -- [x] update `docs/implementation-roadmap.md` -- [x] archive this roadmap with a completion summary if the slice is fully complete - -## Files - -- `docs/roadmaps/archive/web-phase2-read-only-ui.md` -- `docs/implementation-roadmap.md` -- `apps/web/package.json` -- `apps/web/src/app.tsx` -- `apps/web/src/features/operator-console.tsx` -- `apps/web/src/lib/api.ts` -- `apps/web/src/lib/format.ts` -- `apps/web/src/styles.css` -- `apps/web/src/vite-env.d.ts` -- `apps/web/vite.config.ts` -- `pnpm-lock.yaml` - -## Decisions - -- keep the first Phase 2 UI slice read-only and route it against the existing HTTP API instead of coupling UI delivery to new backend mutations -- prefer composition from the copied-in Cadence UI source over new hand-rolled UI primitives - -## Blockers - -- none - -## Next Step - -- build the next web slice on top of the shipped read-only screens by adding operator write actions, council views, and realtime event handling without replacing the new routed operator shell - -## Completion Summary - -- replaced the placeholder `apps/web` landing screen with a routed read-only operator UI that now ships runs list, run detail, blocked queue, and thread timeline pages backed by the existing `orchd` API -- added a typed frontend read layer for the current HTTP contract, including client-side blocked queue aggregation across runs and thread timeline payload/artifact rendering -- wired Tailwind v4 into the consumer app so the copied-in Cadence UI source-owned components render correctly, and used those components throughout the new pages instead of introducing new foundational UI primitives -- validated the slice with `pnpm run web:build`, seeded a local demo run/thread dataset through the existing `orch` and `inbox` CLIs, and verified the Vite dev server can proxy the runs, run detail, and thread endpoints through to `orchd` diff --git a/docs/roadmaps/archive/web-product-monorepo-doc.md b/docs/roadmaps/archive/web-product-monorepo-doc.md deleted file mode 100644 index 58443d6..0000000 --- a/docs/roadmaps/archive/web-product-monorepo-doc.md +++ /dev/null @@ -1,56 +0,0 @@ -# Web Product Monorepo Doc - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-19` - -## Goal - -- Capture the agreed monorepo skeleton and web-product backend/frontend direction in a durable project document under `docs/`. -- Keep the implementation roadmap synchronized so future agents can pick up the web milestone without rediscovering the repository shape. - -## Scope - -- add a new planning document for the web-product monorepo direction -- update the implementation roadmap to reference the new document -- archive this execution roadmap when the documentation work is complete - -## Checklist - -- [x] create an active execution roadmap for this documentation workstream -- [x] add the web-product monorepo planning document under `docs/` -- [x] update the implementation roadmap to reference the new document -- [x] validate the changed docs for consistency -- [x] archive this execution roadmap with a completion summary - -## Files - -- `docs/web-product-monorepo.md` -- `docs/implementation-roadmap.md` -- `docs/roadmaps/active/web-product-monorepo-doc.md` - -## Decisions - -- keep the work scoped to documentation and roadmap sync rather than implementation -- treat the current repository as the future backend monorepo root rather than proposing an immediate backend repo split - -## Blockers - -- none - -## Next Step - -- use `docs/web-product-monorepo.md` as the planning reference when implementation starts for `cmd/orchd`, `apps/web`, and the shared application/query layers - -## Completion Summary - -- added `docs/web-product-monorepo.md` to capture the agreed monorepo skeleton, React frontend direction, `chi` backend direction, and phased migration plan -- updated `docs/implementation-roadmap.md` so future agents can discover and use the new web-product planning document as the next milestone entrypoint diff --git a/docs/roadmaps/archive/web-product-phase1-skeleton.md b/docs/roadmaps/archive/web-product-phase1-skeleton.md deleted file mode 100644 index ae91033..0000000 --- a/docs/roadmaps/archive/web-product-phase1-skeleton.md +++ /dev/null @@ -1,74 +0,0 @@ -# Web Product Phase 1 Skeleton - -## Status - -- `completed` - -## Owner - -- Codex - -## Started At - -- `2026-03-20` - -## Goal - -- Implement the first web-product milestone slice described in `docs/web-product-monorepo.md` by creating the monorepo skeleton, a minimal `orchd` HTTP service, and the first read-oriented backend boundaries. - -## Scope - -- add an active execution trace for this web implementation workstream -- add the initial monorepo workspace files and `apps/web` scaffold -- add `cmd/orchd`, `internal/httpapi`, `internal/app`, and `internal/query` -- expose a small read-only HTTP API for health, runs, run detail, blocked tasks, and thread detail -- add initial API contract docs under `api/` -- keep `docs/implementation-roadmap.md` synchronized with the new implementation state - -## Checklist - -- [x] create the active execution roadmap for the Phase 1 web skeleton workstream -- [x] scaffold the monorepo workspace files and `apps/web` -- [x] add `cmd/orchd` with a minimal `chi`-based HTTP server -- [x] introduce initial shared app/query boundaries for read-only web endpoints -- [x] add initial API contract documents under `api/` -- [x] validate the new slice with builds or targeted tests -- [x] update `docs/implementation-roadmap.md` -- [x] archive this execution roadmap with a completion summary if the slice is fully complete - -## Files - -- `docs/roadmaps/active/web-product-phase1-skeleton.md` -- `docs/implementation-roadmap.md` -- `docs/web-product-monorepo.md` -- `cmd/orchd/main.go` -- `internal/httpapi/` -- `internal/app/` -- `internal/query/` -- `internal/store/` -- `api/openapi.yaml` -- `api/events.md` -- `apps/web/` -- `package.json` -- `pnpm-workspace.yaml` - -## Decisions - -- implement a narrow read-only backend slice first instead of starting with frontend pages -- keep the first HTTP layer thin and let query/app packages own the web-facing backend boundary -- preserve the existing CLI entrypoints while introducing the new service - -## Blockers - -- none - -## Next Step - -- start Phase 2 on top of the new `apps/web` and `orchd` skeleton by wiring real runs, run-detail, blocked-queue, and thread-detail screens to the read-only API - -## Completion Summary - -- added the first web-product skeleton described in `docs/web-product-monorepo.md`, including root `pnpm` workspace files, a standalone React frontend shell under `apps/web`, initial API contract documents under `api/`, and a new `cmd/orchd` HTTP service -- introduced `internal/app`, `internal/query`, and `internal/httpapi` so the web backend has an explicit read-oriented boundary instead of letting handlers query storage ad hoc -- implemented and validated the first read-only HTTP endpoints for health, runs, run detail, run tasks, blocked tasks, and thread detail -- verified the slice with `go test ./...` and `pnpm run web:build`, then synchronized `docs/implementation-roadmap.md` diff --git a/docs/skill-workspace-monorepo.md b/docs/skill-workspace-monorepo.md index 05dda94..ea2136b 100644 --- a/docs/skill-workspace-monorepo.md +++ b/docs/skill-workspace-monorepo.md @@ -337,7 +337,6 @@ Keep documentation split by concern: - runtime/package docs live under the owning package when tightly tied to implementation - cross-workspace architecture docs stay in root `docs/` - skill forward-test plans stay in `docs/tests/*-skill/` -- execution traces stay in `docs/roadmaps/` This document becomes the repository-level source of truth for the workspace split. @@ -349,8 +348,6 @@ split. Deliverables: - this migration plan -- execution roadmap -- implementation roadmap update Exit criteria: diff --git a/docs/web-product-monorepo.md b/docs/web-product-monorepo.md deleted file mode 100644 index 6665dbd..0000000 --- a/docs/web-product-monorepo.md +++ /dev/null @@ -1,427 +0,0 @@ -# Web Product Monorepo Plan - -## Purpose - -This document defines the recommended repository shape and implementation direction for evolving the current local CLI-based coordination stack into a formal web product. - -The target shape is: - -- a React frontend for leaders and operators -- a Go HTTP backend built with `chi` -- continued reuse of the existing `inbox` and `orch` domain logic -- one monorepo rather than separate frontend and backend repositories - -This is an implementation-oriented planning document. -It does not replace the current protocol and workflow documents for `inbox`, `orch`, worktrees, or council review. - -## Decision Summary - -The recommended direction is: - -- keep a single monorepo -- add a standalone frontend app under `apps/web` -- add a standalone HTTP backend entrypoint, now owned under `packages/operator-api/cmd/operator-api` -- keep the current Go repository as the backend source of truth -- evolve the backend by introducing shared application services and UI-oriented query layers -- avoid building the web backend by shelling out to the existing CLIs - -This gives the product a front/back runtime split without creating a second backend codebase. - -## Why Monorepo - -For the current project stage, a monorepo is the most practical choice. - -Benefits: - -- the current domain model, scheduler logic, and SQLite schema already live in this repository -- frontend and backend changes will often move together while the web product is still forming -- API contracts, event contracts, and backend changes can be versioned together -- the existing CLI tools can stay in the same repo as operator and debugging surfaces -- shared scripts, fixtures, and docs remain simple - -## Why The Backend Should Stay In This Repo - -The backend should become a first-class HTTP service, but it should not start as a brand new repo. - -Reasons: - -- the existing state machine and storage behavior already live here -- duplicating `store` and schema logic into a second backend codebase would create unnecessary drift -- wrapping the CLIs from a web server would produce an unstable and hard-to-test integration boundary -- the fastest safe path is to let both the CLI and HTTP service call the same Go services - -The backend may be split into another repo later only after the application-service boundary is stable and intentionally extracted. - -## Product Direction - -The target product is not just a local dashboard. -It should be able to evolve into a formal multi-user web application. - -That means the backend should be designed for: - -- stable HTTP APIs -- authenticated users -- eventual organization and membership concepts -- server-pushed run and thread updates -- UI-oriented read models for task boards, blocked queues, and timelines -- eventual migration away from SQLite if write concurrency or deployment shape requires it - -## Recommended Repository Layout - -The recommended monorepo shape is: - -```text -. -├─ apps/ -│ └─ web/ # React frontend application -├─ api/ -│ ├─ openapi.yaml # HTTP API contract -│ └─ events.md # SSE or websocket event contract -├─ cmd/ -│ ├─ inbox/ # existing worker-facing CLI -│ ├─ orch/ # existing leader-facing CLI -│ └─ orchd/ # new HTTP backend entrypoint -├─ internal/ -│ ├─ app/ # shared application services used by CLI and HTTP -│ ├─ httpapi/ # chi router, handlers, middleware, SSE -│ ├─ query/ # frontend-oriented read models and aggregate queries -│ ├─ store/ # existing persistence and orchestration state logic -│ ├─ db/ # existing SQLite open and migration layer -│ └─ protocol/ # shared DTO and response helpers where appropriate -├─ docs/ -├─ scripts/ -├─ package.json -├─ pnpm-workspace.yaml -├─ go.mod -└─ Makefile -``` - -## Layout Decisions - -### `apps/web` - -The frontend should live under `apps/web`. - -Recommended stack: - -- React -- Vite -- TypeScript -- TanStack Router -- TanStack Query - -The frontend should consume only HTTP APIs and event streams from the backend. -It should never read SQLite directly and should not depend on CLI output parsing. - -### `packages/operator-api` - -The backend HTTP service should live in a package-owned runtime with its Go binary under `packages/operator-api/cmd/operator-api`. - -Responsibilities: - -- expose REST or RPC-style HTTP endpoints for the web frontend -- expose SSE or websocket updates for run and thread activity -- load the same database as the CLI tools -- use shared application services rather than reimplementing logic - -The existing orch and inbox runtimes should remain available as operator and debugging tools through their package-owned binaries under `packages/orch-runtime/cmd/orch` and `packages/inbox-runtime/cmd/inbox`. - -### `packages/operator-api/internal/app` - -This package should become the shared application-service layer. - -It should own business actions that currently sit mostly in CLI command handlers, such as: - -- dispatch -- reconcile -- answer -- retry -- reassign -- cancel -- council start, wait, tally, and report orchestration entrypoints - -Both CLI commands and HTTP handlers should call into this layer. - -### `packages/operator-api/internal/query` - -This package should hold read models specifically shaped for the web UI. - -Examples: - -- run overview with task counts and recent event summaries -- kanban-style task board grouped by status -- blocked queue with latest question details -- thread timeline including artifacts and lease state -- council run summaries and grouped recommendation views - -These should be query-oriented models rather than raw database table mirrors. - -### `packages/operator-api/internal/httpapi` - -This package should hold the web transport layer. - -Recommended contents: - -- `router.go` -- handler packages by domain -- auth and request middleware -- error mapping -- SSE handlers -- request validation and response serialization - -The HTTP layer should stay thin. -It should not own business rules or embed SQL-heavy logic. - -## Why `chi` - -`chi` is the recommended HTTP router for this product direction. - -Reasons: - -- it stays close to standard `net/http` -- it provides cleaner routing and middleware composition than a bare `ServeMux` -- it avoids the heavier framework lock-in of `gin` -- it fits a backend that is expected to grow into a real product API - -The decision here is not about raw performance. -It is about long-term code organization and maintainable HTTP structure. - -## Why Not Build The Backend Around The Existing CLIs - -The new web backend should not execute `orch` or `inbox` binaries as subprocesses. - -That approach would create avoidable problems: - -- duplicate input validation paths -- harder error mapping -- unstable process-level integration points -- slower request handling -- more difficult testing -- awkward transaction and context handling - -The CLIs should become alternate entrypoints into shared services, not the implementation boundary for the web product. - -## API Contract Direction - -The monorepo should add an explicit API contract under `api/`. - -Recommended starting files: - -- `api/openapi.yaml` -- `api/events.md` - -`openapi.yaml` should define: - -- runs list and detail endpoints -- task list and task action endpoints -- blocked queue endpoints -- thread detail endpoints -- council report endpoints - -`events.md` should define: - -- event stream transport choice -- cursoring model -- payload shapes for run, task, thread, and council events - -The web frontend should generate a typed client from the HTTP contract where practical. - -## Frontend Direction - -The frontend should be a standalone app in the monorepo, not embedded templates. - -Recommended responsibilities: - -- run dashboard -- task board -- blocked queue -- thread detail and timeline -- council result and report views -- operator actions such as answer, retry, reassign, and cancel - -Recommended development model: - -- local dev server from `apps/web` -- proxy API requests to `orchd` -- consume typed API clients instead of hand-written fetch calls where possible - -## Backend Evolution Plan - -The current project already has strong backend assets: - -- durable schema and migrations -- store-layer logic for `inbox` and `orch` -- stable JSON conventions -- working CLI surfaces - -The backend should therefore evolve in-place: - -1. keep the current store and schema as the persistence foundation -2. extract shared application actions into the orchd runtime app layer -3. add UI-oriented read models in the orchd runtime query layer -4. add the orchd runtime package and its HTTP transport layer -5. attach the React frontend after the API contract stabilizes - -This is safer than first attempting a large repo split or backend rewrite. - -## Suggested Initial Endpoint Set - -The first useful web slice should remain narrow. - -Recommended read endpoints: - -- `GET /api/runs` -- `GET /api/runs/{runID}` -- `GET /api/runs/{runID}/tasks` -- `GET /api/runs/{runID}/blocked` -- `GET /api/threads/{threadID}` -- `GET /api/council/runs/{runID}` - -Recommended write endpoints: - -- `POST /api/runs/{runID}/tasks/{taskID}/answer` -- `POST /api/runs/{runID}/tasks/{taskID}/retry` -- `POST /api/runs/{runID}/tasks/{taskID}/reassign` -- `POST /api/runs/{runID}/tasks/{taskID}/cancel` - -Recommended realtime endpoint: - -- `GET /api/events/stream` - -The first UI should prioritize observation over broad mutation. - -## Realtime Direction - -The current system already has a shared `events` table for monotonic activity tracking. -That makes SSE a good first realtime transport. - -Recommended approach: - -- begin with SSE rather than websockets -- stream cursor-based events from the backend -- let the frontend use events to invalidate or refresh query results -- keep the server-side event payloads close to run, task, thread, and council activity - -Websockets can be reconsidered later if bidirectional session behavior becomes necessary. - -## Database Direction - -SQLite remains appropriate for the current CLI-focused local workflow and can also support early web product development in controlled environments. - -However, if the product becomes truly multi-user or centrally hosted, the backend should expect a later database transition. - -Recommended position: - -- keep SQLite during the first web API and frontend milestone -- avoid SQLite-specific assumptions in the new application-service and query layers -- plan for a future Postgres migration if concurrency, deployment, or tenancy requirements grow - -The goal is to avoid rewriting product boundaries just because the storage engine changes later. - -## Implementation Phases - -### Phase 1: Monorepo Skeleton And Backend Service - -Add: - -- `apps/web` -- `packages/operator-api/cmd/operator-api` -- `packages/operator-api/internal/httpapi` -- `packages/operator-api/internal/app` -- `packages/operator-api/internal/query` -- `api/openapi.yaml` -- `api/events.md` -- root JS workspace files such as `package.json` and `pnpm-workspace.yaml` - -Deliverable: - -- the repository builds with the new monorepo structure in place -- the backend can serve a small read-only API - -### Phase 2: Read-Only Web UI - -Build: - -- runs page -- run detail view -- task board -- blocked queue -- thread detail - -Deliverable: - -- the React frontend can inspect live orchestration state through `orchd` - -### Phase 3: Realtime Updates - -Add: - -- SSE event endpoint -- frontend subscription and refresh behavior - -Deliverable: - -- run and thread views update without manual reload loops - -### Phase 4: Write Operations - -Add: - -- answer -- retry -- reassign -- cancel - -Deliverable: - -- the web UI becomes a practical operator surface rather than read-only reporting - -### Phase 5: Product Hardening - -Add: - -- auth -- user and organization concepts -- audit trails -- deployment configuration -- database migration planning beyond SQLite if needed - -Deliverable: - -- the system can evolve beyond a local operator tool into a formal product backend - -## Non-Goals For The First Web Milestone - -Do not treat these as part of the initial skeleton task: - -- a full permissions model -- background job infrastructure -- multi-tenant isolation -- websocket-first architecture -- immediate database migration -- full replacement of the CLI workflows - -The first milestone should create a durable path, not solve every product concern at once. - -## Migration Notes For Existing Code - -The current codebase should be adapted incrementally. - -Recommended rules: - -- keep the package-owned `orch` and `inbox` binaries working while the HTTP layer is introduced -- move business logic out of command handlers only when the shared service abstraction is clear -- do not rewrite `store` just to match HTTP names -- let the frontend shape drive the orchd runtime query layer, not the table layout alone -- avoid introducing duplicate orchestration logic between CLI and HTTP - -## Immediate Recommended Next Step - -If the project begins this web-product milestone, the first implementation slice should be: - -1. scaffold the monorepo workspace files and `apps/web` -2. add the `orchd` runtime package with a `chi` router and a minimal health or runs endpoint -3. introduce the first shared application or query boundary rather than letting handlers call storage ad hoc -4. write the initial API contract in `api/openapi.yaml` - -This gives the project a clean backbone before deeper UI work begins. diff --git a/docs/worktree-execution.md b/docs/worktree-execution.md index 6a4449d..0d65158 100644 --- a/docs/worktree-execution.md +++ b/docs/worktree-execution.md @@ -223,4 +223,3 @@ Suggested flags: - [architecture.md](/home/kurihada/project/ai-workflow-skill/docs/architecture.md): high-level separation of inbox and orch - [orch-cli.md](/home/kurihada/project/ai-workflow-skill/docs/orch-cli.md): scheduling commands that create and manage attempts -- [blog-project-example.md](/home/kurihada/project/ai-workflow-skill/docs/blog-project-example.md): example of dispatch creating a worktree-backed attempt diff --git a/skills/repo-memory/assets/.gitkeep b/skills/repo-memory/assets/.gitkeep deleted file mode 100644 index 8b13789..0000000 --- a/skills/repo-memory/assets/.gitkeep +++ /dev/null @@ -1 +0,0 @@ -