# 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/`

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

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