docs: add skill workspace monorepo migration plan

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
+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. keep the authored inbox test-plan set in `docs/tests/inbox/` synchronized if future `orch` or web work changes shared CLI-visible behavior
+2. start `Milestone 10: Skill Workspace Monorepo Migration` by bootstrapping `go.work`, expanding workspace metadata, and creating the first empty `packages/` roots
-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
+3. extract the shared coordination kernel into `packages/coord-core` before moving `inbox`, `orch`, or `orchd` into package-owned runtimes
-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
+4. keep the authored skill forward-test plans under `docs/tests/*-skill/` synchronized as runtime ownership moves from root paths to package paths
-5. add council result/report screens and realtime event handling after the operator write path is clear
+5. replace the hardcoded skill packaging flow with declarative bundle metadata before adding `repo-memory`
-6. install additional `cadence-ui` components on demand when those screens need them, instead of reintroducing bespoke primitives into `apps/web`
+6. import `repo-memory` only after the package-based runtime and skill packaging pattern exists
-7. keep `api/openapi.yaml`, `api/events.md`, and `docs/web-product-monorepo.md` synchronized as the web surface expands
 
-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

@@ -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

@@ -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