462 lines
12 KiB
Markdown
462 lines
12 KiB
Markdown
# 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
|
|
│ ├─ operator-api/ # operator 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`
|
|
- package-local CLI command wiring 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`
|
|
- package-local CLI command wiring 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/operator-api`
|
|
|
|
This package owns the HTTP and read-model runtime for the operator web surface.
|
|
|
|
It should contain:
|
|
|
|
- `cmd/operator-api/main.go`
|
|
- package-local `internal/httpapi`
|
|
- package-local `internal/query`
|
|
- package-local `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/operator-api`
|
|
- `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 `operator-api`
|
|
|
|
Changes:
|
|
|
|
- move the operator API runtime into `packages/operator-api`
|
|
- make `apps/web` depend only on HTTP contract and dev proxy, not root assumptions
|
|
|
|
Exit criteria:
|
|
|
|
- the web stack builds against `operator-api`
|
|
|
|
### 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
|
|
|
|
The migration does remove root runtime ownership once package-owned runtimes are in place.
|
|
Root `cmd/` and root `internal/` are not part of the long-term target shape.
|
|
|
|
## 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
|