kurihada/ai-workflow-skill
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: add skill workspace monorepo migration plan

Browse Source
This commit is contained in:
kurihada
2026-03-20 12:23:43 +08:00
parent f58f48f0d5
commit b6b585b6a9
3 changed files with 569 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/implementation-roadmap.md
+48 -9
View File
@@ -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
docs/roadmaps/archive/skill-workspace-monorepo-migration-design.md
+63
View File
@@ -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
docs/skill-workspace-monorepo.md
+458
View File
@@ -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