ai-workflow-skill/docs/skill-workspace-monorepo.md

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

.
├─ 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/           # 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
│  └─ ...

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/repo-memory/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/
• refresh every affected bundled asset and user-facing SKILL.md example when a shared runtime changes behavior or CLI defaults
• 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 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:

{
  "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/repo-memory",
      "output": "skills/repo-memory/assets/repo-memory"
    }
  ]
}

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

Test Intent Documentation

User-facing test intent should live with the executable tests, not in a separate Markdown plan tree.

Required shape:

• add a short comment above each top-level test describing the behavior it protects
• prefer package-local fixtures and helpers over cross-repo prose test plans
• keep bundled-skill verification as executable tests or scripts, not as standalone Markdown inventories

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/
• test intent stays in executable test source through short comments above top-level test cases

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 repo-memory runtime into packages/repo-memory-runtime
• normalize module pathing, tests, and packaging
• add skills/repo-memory

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