# 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