diff --git a/docs/implementation-roadmap.md b/docs/implementation-roadmap.md index 0399781..129f7f8 100644 --- a/docs/implementation-roadmap.md +++ b/docs/implementation-roadmap.md @@ -36,6 +36,7 @@ As of now: - HTTP tests now cover the initial read-only `orchd` 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 `orchd` HTTP 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 - a repo-local `scripts/package_skill_clis.sh` packaging flow now builds bundled skill CLI assets for `inbox`, `orch`, and `council-review` - `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 @@ -95,8 +96,9 @@ Current implementation status: - `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 planned -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, and the first real operator-facing Phase 2 read-only web views now exist on top of the internal Cadence UI component library. +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 now has an explicit migration plan for becoming a true skill workspace monorepo. ### Milestone 1: Go Skeleton @@ -458,19 +460,56 @@ Remaining: - 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: + +- planned + +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`, `orchd-runtime`, and `repo-memory-runtime` + +Remaining: + +- bootstrap `go.work` plus expanded workspace configuration +- extract shared coordination code into `packages/coord-core` +- extract `inbox`, `orch`, and `orchd` into package-owned runtimes +- import `repo-memory` as its own runtime package and add the corresponding skill bundle +- replace the hardcoded skill packaging script with declarative bundle metadata + ## Immediate Next Task If a new agent is taking over now, the next concrete step should be: -1. treat `Milestone 8: Web Product Phase 1 Skeleton` as complete unless a new user request reopens the backend skeleton itself -2. keep the authored inbox test-plan set in `docs/tests/inbox/` synchronized if future `orch` or web work changes shared CLI-visible behavior -3. treat `Milestone 9: Web Product Phase 2 Read-Only Operator UI` as complete for the initial operator surface and build the next web slice on top of the shipped read pages rather than replacing them -4. start the next web phase by wiring operator write actions such as answer, retry, reassign, and cancel into the existing runs, blocked, and thread views -5. add council result/report screens and realtime event handling after the operator write path is clear -6. install additional `cadence-ui` components on demand when those screens need them, instead of reintroducing bespoke primitives into `apps/web` -7. keep `api/openapi.yaml`, `api/events.md`, and `docs/web-product-monorepo.md` synchronized as the web surface expands +1. treat `Milestone 9: Web Product Phase 2 Read-Only Operator UI` as complete for the initial operator surface and do not expand web feature scope further until the workspace split is decided package-by-package +2. start `Milestone 10: Skill Workspace Monorepo Migration` by bootstrapping `go.work`, expanding workspace metadata, and creating the first empty `packages/` roots +3. extract the shared coordination kernel into `packages/coord-core` before moving `inbox`, `orch`, or `orchd` into package-owned runtimes +4. keep the authored skill forward-test plans under `docs/tests/*-skill/` synchronized as runtime ownership moves from root paths to package paths +5. replace the hardcoded skill packaging flow with declarative bundle metadata before adding `repo-memory` +6. import `repo-memory` only after the package-based runtime and skill packaging pattern exists -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, and the web product now has its first real operator-facing read surfaces, so the next step should be write-capable operator workflows and council/realtime expansion rather than reopening the frontend shell or basic read pages. +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 has an explicit plan to become a skill workspace monorepo, so the next step should be repository restructuring rather than continuing to accrete new root-owned runtimes. ## Recommended Driver Choices diff --git a/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md b/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md new file mode 100644 index 0000000..9814fc8 --- /dev/null +++ b/docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md @@ -0,0 +1,63 @@ +# 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/skill-workspace-monorepo.md b/docs/skill-workspace-monorepo.md new file mode 100644 index 0000000..d6576b2 --- /dev/null +++ b/docs/skill-workspace-monorepo.md @@ -0,0 +1,458 @@ +# Skill Workspace Monorepo Migration Plan + +## Purpose + +This document defines the repository migration plan for turning `ai-workflow-skill` +from a single-root implementation repository with bundled skill wrappers into a +true multi-package monorepo whose primary deliverables are skills. + +In the target model: + +- runtime code lives in independently owned packages under `packages/` +- agent-facing skill bundles live under `skills/` +- support apps such as the web operator UI live under `apps/` +- root-level tooling exists to build, test, and package skill bundles from the + package graph + +This document is repository-architecture guidance. +It does not replace protocol and product docs such as `inbox`, `orch`, council, +or the web UI contract. + +## Decision Summary + +The migration direction is: + +- treat the repository as a skill workspace, not as one product root with a few + attached skills +- move `inbox` and `orch` runtime code into package-owned runtimes +- introduce a shared coordination kernel package for the coordination stack only +- keep independent skill runtimes, such as `repo-memory`, outside the + coordination kernel +- keep `skills/` as agent-facing packaging only +- use `go.work` plus expanded JS workspace config to manage the whole monorepo + +## Repository Model + +The repository should distinguish three kinds of things: + +### 1. Runtime Packages + +Runtime packages are real implementations with source code, tests, and their own +module boundaries. + +Examples: + +- coordination kernel +- inbox runtime +- orch runtime +- orch HTTP/web runtime +- repo-memory runtime + +### 2. Skill Bundles + +Skill bundles are the agent-facing deliverables. +They contain: + +- `SKILL.md` +- `agents/openai.yaml` +- bundled runtime artifacts under `assets/` +- optional references or assets needed by the skill + +Skill bundles should not be the long-term home of substantial runtime source +code. + +### 3. Support Apps + +Support apps are not themselves skills, but support skill-backed workflows. + +Examples: + +- `apps/web` operator UI + +## Target Layout + +```text +. +├─ go.work +├─ package.json +├─ pnpm-workspace.yaml +├─ apps/ +│ └─ web/ # operator web UI, not a skill bundle +├─ packages/ +│ ├─ coord-core/ # shared coordination kernel +│ ├─ inbox-runtime/ # inbox CLI runtime +│ ├─ orch-runtime/ # orch CLI runtime +│ ├─ orchd-runtime/ # orch HTTP + query/web backend runtime +│ ├─ repo-memory-runtime/ # briefdb / repo-memory runtime +│ └─ ... # future skill runtimes +├─ skills/ +│ ├─ inbox/ +│ ├─ orch/ +│ ├─ council-review/ +│ ├─ repo-memory/ +│ └─ ... # future agent-facing skill bundles +├─ docs/ +├─ scripts/ +│ ├─ package_skill_runtimes.sh +│ ├─ skill-bundles.json +│ └─ ... +└─ docs/tests/ + ├─ inbox-skill/ + ├─ orch-skill/ + ├─ council-review-skill/ + ├─ repo-memory-skill/ + └─ ... +``` + +## Package Boundaries + +### `packages/coord-core` + +This package exists only for the shared coordination stack. +It is not a generic dumping ground for every skill. + +It should contain: + +- shared SQLite open and pragma logic +- shared migrations and schema files for the coordination database +- shared coordination domain models: + - run + - task + - task attempt + - thread + - message + - artifact + - run event + - blocked task + - council models +- shared coordination store or repository logic +- shared protocol/error helpers used by multiple coordination runtimes + +It should not contain: + +- CLI command wiring +- HTTP transport +- frontend-oriented query models +- web handlers +- repo-memory knowledge-base code + +### `packages/inbox-runtime` + +This package owns the inbox worker-facing runtime. + +It should contain: + +- `cmd/inbox/main.go` +- CLI command wiring currently under `internal/cli/inbox` +- inbox-specific packaging tests + +It depends on `coord-core`. + +### `packages/orch-runtime` + +This package owns the orch leader-facing runtime. + +It should contain: + +- `cmd/orch/main.go` +- CLI command wiring currently under `internal/cli/orch` +- worktree-specific runtime helpers currently owned only by orch + +It depends on `coord-core`. + +`council-review` remains a skill bundle that currently reuses the `orch` binary +unless it later grows its own standalone runtime. + +### `packages/orchd-runtime` + +This package owns the HTTP and read-model runtime for the operator web surface. + +It should contain: + +- `cmd/orchd/main.go` +- current `internal/httpapi` +- current `internal/query` +- current `internal/app/web.go` + +It depends on `coord-core`. + +### `packages/repo-memory-runtime` + +This package owns the repo-memory implementation. + +It should contain: + +- `cmd/briefdb/main.go` +- markdown ingest/parser logic +- knowledge store and verification logic +- its own schema and runtime tests + +It must remain independent from `coord-core` unless it later proves it truly +shares the same coordination domain, which is not true today. + +### Future Runtime Packages + +Use a new `packages/*-runtime` package when all of the following are true: + +- the capability has real source code and tests +- it may evolve independently from existing runtimes +- it could plausibly become its own repo later +- the skill bundle should not be the long-term source-of-truth location + +## Skill Bundle Rules + +`skills/` becomes a packaging layer only. + +Each skill bundle should: + +- own `SKILL.md` +- own `agents/openai.yaml` +- own packaged runtime artifacts under `assets/` +- optionally own references or templates required by the skill + +Each skill bundle should not: + +- own the canonical runtime source code for substantial Go/TS systems +- duplicate shared schemas or business logic from runtime packages + +### Mapping Between Packages And Skills + +The mapping does not have to be one-to-one. + +Examples: + +- `packages/inbox-runtime` -> `skills/inbox` +- `packages/orch-runtime` -> `skills/orch` +- `packages/orch-runtime` -> `skills/council-review` as a reused runtime +- `packages/repo-memory-runtime` -> `skills/repo-memory` + +This keeps packaging flexible while preserving runtime ownership. + +## Build And Packaging Model + +### Go Workspace + +Add a root `go.work` that includes every Go runtime package: + +- `packages/coord-core` +- `packages/inbox-runtime` +- `packages/orch-runtime` +- `packages/orchd-runtime` +- `packages/repo-memory-runtime` + +The root repository should stop relying on one giant root `go.mod` as the long-term +source of truth. + +### JS Workspace + +Expand `pnpm-workspace.yaml` from only `apps/*` to: + +- `apps/*` +- `packages/*` + +Use `packages/` for any JS/TS runtime packages that emerge later. +`skills/` should not become a pnpm package tree unless a specific skill bundle +needs JS packaging metadata. + +### Skill Packaging Script + +Replace the current hardcoded [scripts/package_skill_clis.sh](/home/kurihada/project/ai-workflow-skill/scripts/package_skill_clis.sh) +with a declarative packaging flow. + +Recommended shape: + +- `scripts/skill-bundles.json`: declares which runtime package builds which skill asset +- `scripts/package_skill_runtimes.sh`: builds the declared binaries and installs them into skill assets + +Example mapping: + +```json +{ + "bundles": [ + { + "skill": "inbox", + "type": "go-binary", + "package": "./packages/inbox-runtime/cmd/inbox", + "output": "skills/inbox/assets/inbox" + }, + { + "skill": "orch", + "type": "go-binary", + "package": "./packages/orch-runtime/cmd/orch", + "output": "skills/orch/assets/orch" + }, + { + "skill": "council-review", + "type": "go-binary", + "package": "./packages/orch-runtime/cmd/orch", + "output": "skills/council-review/assets/orch" + }, + { + "skill": "repo-memory", + "type": "go-binary", + "package": "./packages/repo-memory-runtime/cmd/briefdb", + "output": "skills/repo-memory/assets/briefdb" + } + ] +} +``` + +This makes skill packaging a first-class workspace concern instead of a one-off +script tied to root paths. + +## Test Strategy + +### Runtime Tests + +Each runtime package owns: + +- unit tests +- integration tests +- package-local fixtures + +### Skill Forward Tests + +`docs/tests/*-skill/` remains skill-oriented. +These tests validate the bundled skill behavior, not only the runtime package. + +Examples: + +- `docs/tests/inbox-skill/` +- `docs/tests/orch-skill/` +- `docs/tests/council-review-skill/` +- future `docs/tests/repo-memory-skill/` + +### Cross-Package Validation + +Add workspace-level validation that checks: + +- every declared bundle can be built +- every skill asset exists after packaging +- skill package metadata still matches the bundled runtime behavior + +## Documentation Model + +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. + +## Migration Phases + +### Phase 0: Freeze The Target Shape + +Deliverables: + +- this migration plan +- execution roadmap +- implementation roadmap update + +Exit criteria: + +- target package split and packaging model are explicit + +### Phase 1: Workspace Bootstrap + +Changes: + +- add `go.work` +- expand `pnpm-workspace.yaml` to include `packages/*` +- add bundle manifest and new packaging script scaffold +- create empty package roots under `packages/` + +Exit criteria: + +- root workspace can resolve all package modules +- root scripts can target package paths + +### Phase 2: Extract `coord-core` + +Changes: + +- move shared coordination DB/schema/model/store/protocol logic into `packages/coord-core` +- replace old root imports with `coord-core` imports + +Exit criteria: + +- no coordination runtime depends on root `internal/db`, `internal/store`, or root `internal/protocol` + +### Phase 3: Extract `inbox-runtime` And `orch-runtime` + +Changes: + +- move `cmd/inbox` + `internal/cli/inbox` into `packages/inbox-runtime` +- move `cmd/orch` + `internal/cli/orch` into `packages/orch-runtime` +- rewire tests and packaging to package paths + +Exit criteria: + +- inbox and orch binaries build from package-owned runtimes +- `skills/inbox` and `skills/orch` package from package paths only + +### Phase 4: Extract `orchd-runtime` + +Changes: + +- move `cmd/orchd`, `internal/httpapi`, `internal/query`, and web app service layer into `packages/orchd-runtime` +- make `apps/web` depend only on HTTP contract and dev proxy, not root assumptions + +Exit criteria: + +- the web stack builds against `orchd-runtime` + +### Phase 5: Import `repo-memory-runtime` + +Changes: + +- move the exploratory `tmp/briefdb` runtime into `packages/repo-memory-runtime` +- normalize module pathing, tests, and packaging +- add `skills/repo-memory` +- add `docs/tests/repo-memory-skill/` + +Exit criteria: + +- `repo-memory` packages like any other skill runtime in the workspace + +### Phase 6: Remove Root Runtime Ownership + +Changes: + +- remove or archive the old root `cmd/` and `internal/` runtime ownership model +- keep root only for workspace orchestration, docs, scripts, skills, and support apps + +Exit criteria: + +- runtime source of truth lives only under `packages/` + +## Compatibility Rules During Migration + +- keep skill names stable: `inbox`, `orch`, `council-review`, `repo-memory` +- keep bundled asset paths stable where practical so downstream skill usage does not change unexpectedly +- prefer temporary thin shims over big-bang breakage while packages are being extracted +- migrate one runtime family at a time and keep packaging green after each phase +- do not mix unrelated runtime extraction with product-surface changes in the same step + +## Non-Goals + +This migration does not require: + +- splitting the repo into multiple Git repositories +- publishing Go modules externally before the workspace is stable +- moving every support app into `packages/` +- forcing every skill to own its own runtime package when runtime reuse is intentional + +## Success Criteria + +The migration is complete when: + +- root runtime ownership has been removed +- `packages/` is the source of truth for runtime code +- `skills/` is the source of truth for agent-facing skill bundles +- skill packaging is declarative and package-based +- `inbox`, `orch`, and `repo-memory` all follow the same workspace pattern +- the web app continues to function as a support surface without being mistaken for the primary deliverable