docs: add skill workspace monorepo migration plan

2026-03-20 12:23:43 +08:00
parent f58f48f0d5
commit b6b585b6a9
3 changed files with 569 additions and 9 deletions
@@ -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