| name | monorepo-migration-guide |
| enabled | true |
| description | Use when performing monorepo migration guide — step-by-step guide for
migrating from multiple repositories to a monorepo structure. Covers
repository consolidation strategy, history preservation, build system
selection, CI/CD reconfiguration, code ownership setup, and dependency
management to enable a successful monorepo transition.
|
| required_connections | [{"prefix":"github","label":"GitHub"}] |
| config_fields | [{"key":"target_monorepo","label":"Target Monorepo Name","required":true,"placeholder":"e.g., org/platform"},{"key":"source_repos","label":"Source Repositories","required":true,"placeholder":"e.g., org/frontend, org/backend, org/shared-libs"},{"key":"build_tool","label":"Build Tool","required":false,"placeholder":"e.g., Turborepo, Nx, Bazel, Pants"}] |
| features | ["ENGINEERING","ARCHITECTURE"] |
Monorepo Migration Guide Skill
Migrate {{ source_repos }} into monorepo {{ target_monorepo }} using {{ build_tool }}.
Workflow
Phase 1 — Assessment
REPOSITORY INVENTORY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] Source repositories:
Repo | Language | Size | Commits | Contributors
___________________|__________|________|_________|_____________
| | | |
| | | |
| | | |
[ ] Shared dependencies identified: ___
[ ] Cross-repo dependencies mapped: ___
[ ] CI/CD pipelines to migrate: ___
[ ] Total git history size: ___ GB
Phase 2 — Structure Design
MONOREPO LAYOUT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
{{ target_monorepo }}/
packages/
[ ] ___ (from repo: ___)
[ ] ___ (from repo: ___)
[ ] ___ (from repo: ___)
libs/
[ ] shared utilities
[ ] common types/interfaces
tools/
[ ] build scripts
[ ] code generators
.github/
[ ] workflows (consolidated CI/CD)
[ ] CODEOWNERS
[ ] Package naming convention defined: ___
[ ] Import alias strategy defined: ___
[ ] Workspace configuration (package.json / go.work / etc.)
Phase 3 — History Migration
GIT HISTORY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Strategy (choose one):
[ ] Preserve full history (git filter-repo + subtree merge)
[ ] Preserve history with path rewrite
[ ] Fresh start (squash history, archive originals)
For each repo:
[ ] ___ — history migrated to packages/___ [ ] VERIFIED
[ ] ___ — history migrated to packages/___ [ ] VERIFIED
[ ] ___ — history migrated to packages/___ [ ] VERIFIED
[ ] Tags and releases preserved
[ ] Blame history intact
[ ] No merge conflicts in consolidated history
Phase 4 — Build System Setup
BUILD CONFIGURATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] {{ build_tool }} installed and configured
[ ] Task pipeline defined:
- build -> test -> lint (dependency order)
[ ] Incremental builds working (only changed packages)
[ ] Dependency graph validated
[ ] Remote caching configured (if applicable)
[ ] Build times:
- Full build: ___
- Incremental build: ___
- Affected-only build: ___
Phase 5 — CI/CD Migration
CI/CD RECONFIGURATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] CI pipeline runs only affected packages on PR
[ ] CD pipeline deploys only changed services
[ ] CODEOWNERS file configured per package
[ ] Branch protection rules applied
[ ] PR checks scoped to affected packages
[ ] Release workflow supports per-package versioning
[ ] Artifact publishing configured per package
Phase 6 — Validation and Cutover
VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[ ] All packages build successfully
[ ] All tests pass in monorepo
[ ] CI/CD pipeline produces correct artifacts
[ ] Developer workflow documented:
[ ] Setup instructions
[ ] Common commands
[ ] Troubleshooting guide
[ ] Original repos archived (read-only)
[ ] Redirect notices added to original repos
[ ] Team training completed
Counter-Rationalizations
| Shortcut | Counter | Why |
|---|
| "We can skip some steps for this case" | Adapt the workflow steps, don't skip them | Skipped steps are where incidents and oversights originate |
| "The user seems to already know what to do" | Complete all workflow phases with the user | The workflow catches blind spots that experience alone misses |
| "This is a minor case, full process is overkill" | Scale the process down, don't turn it off | Minor cases become major when unstructured; the process scales, not disappears |
| "I'll fill in the details later" | Complete each section before moving on | Deferred details are forgotten; real-time capture is more accurate |
| "The template output isn't necessary" | Always produce the structured output format | Structured output enables comparison, audit trails, and handoff to other teams |
Output Format
Produce a monorepo migration report with:
- Migration summary (repos consolidated, history preserved, timeline)
- Structure overview (monorepo layout, package map)
- Build performance (full vs incremental build times)
- CI/CD configuration (pipeline design, affected-only runs)
- Follow-up items (developer training, documentation, optimization)
