mono-plan
Detect monorepo structure, identify shared chokepoints, and generate safe parallel lane specs aligned to package boundaries
SKILL.mdpacks/monorepo/claude/mono-plan/SKILL.md
GitHubMono Plan
Generate monorepo-safe parallelization lane specs for a roadmap phase. Detects package boundaries, shared chokepoints (lockfiles, root configs), and internal dependency ordering to produce lane specifications in the exact format that /plan-phase expects for execution profiles.
Run this after /roadmap sets agent-team or implementation-safe on a phase and before /plan-phase decomposes it.
Prerequisites
tasks/roadmap.mdmust exist with at least one phase.- The project must be a monorepo (detected in step 1).
Process
Detect monorepo structure:
- Check for
pnpm-workspace.yaml,turbo.json,lerna.json, orpackage.jsonworkspacesfield. - If none found, report "not a monorepo" and stop — this skill does not apply.
- Record the monorepo tool (pnpm workspaces, Turborepo, Lerna, npm workspaces).
- Check for
Enumerate packages:
- Parse the workspace config to list all packages and apps with their paths.
- Read each package's
package.jsonto collectname,dependencies, anddevDependencies.
Build internal dependency graph:
- For each package, identify which other workspace packages it depends on.
- Compute a topological ordering. Flag cycles as errors.
Identify shared chokepoints:
- Lockfiles:
pnpm-lock.yaml,package-lock.json,yarn.lock,bun.lockb— any that exist in the repo root. - Root configs:
tsconfig.base.json,tsconfig.json(root),turbo.json,tailwind.config.*,.env*,jest.config.*,vitest.config.*,eslint.config.*,.eslintrc.*— any root-level config that packages inherit. - High-fan-out shared packages: workspace packages depended on by 3+ other packages.
- Lockfiles:
Read the target phase:
- Parse
tasks/roadmap.md(or the path from$ARGUMENTS) for phase$ARGUMENTS[0]. - Extract the phase's Scope, Acceptance Criteria, and any existing parallelization hints.
- Parse
Map phase scope to packages:
- Match the phase's scope description to specific packages.
- Classify each relevant package as:
- Independent: no internal dependencies on other in-scope packages.
- Dependent: depends on another in-scope package (must wait for it).
- Shared: a high-fan-out package that multiple lanes would need — requires careful ownership.
Recommend parallelization strategy:
- If all packages are independent and GitHub branch/PR review is available →
agent-teamwith one branch-backed lane per package. - If linear dependency chain →
serialorimplementation-safewith ordered lanes. - If mixed and GitHub branch/PR review is available →
agent-teamwith dependency edges between branch-backed lanes. - If scope touches only root configs or shared packages → downgrade to
serial. - If branch push or PR review is unavailable → downgrade to
implementation-safe,research-only, orserial.
- If all packages are independent and GitHub branch/PR review is available →
Generate lane specs:
- Lane 0 — deps (serial, conditional): If ANY lane's scope requires adding dependencies (
pnpm add,npm install, etc.), generate a serial deps lane that:Owns:all lockfiles and rootpackage.jsonMode: writeDepends on: noneScope:"Install all dependencies needed by subsequent lanes. Do NOT implement features."
- Package lanes (one per independent package or group):
Owns: packages/<name>/(orapps/<name>/)Must not edit:all lockfiles, all root configs, all paths owned by other lanesBranch:agent-team/phase-N-<package-or-lane>; nevermainormasterMode: writeDepends on:Lane 0 (if it exists) + lanes for upstream internal dependenciesScope:the phase work scoped to this package. Append: "Do NOT run pnpm install, npm install, yarn add, or any command that modifies the lockfile. Commit to your assigned branch, push it, and open or update a draft PR before returning."
- Consolidation/PR review lane (required for
agent-team): Add aMode: reviewlane depending on all write lanes. Its scope must inspect every branch/PR, validate changed paths againstOwnsandMust not edit, record blocker/advisory findings, and approve only lanes safe to integrate.
- Lane 0 — deps (serial, conditional): If ANY lane's scope requires adding dependencies (
Validate lane specs:
- Every lockfile appears in
Must not editfor ALL write lanes except the deps lane. Ownspaths are disjoint across all lanes — no prefix overlaps.Depends onreferences are valid lane names with no cycles.- No lane's
Scopecontains install/add commands (except the deps lane).
- Every lockfile appears in
Output
### Mono Plan: Phase N
**Monorepo tool:** pnpm workspaces / Turborepo / etc.
**Packages in scope:** N of M total
#### Shared Chokepoints
- `pnpm-lock.yaml` — lockfile (root)
- `tsconfig.base.json` — shared TypeScript config
- `packages/ui` — depended on by 5 packages
#### Package Dependency Graph (in-scope)
- `packages/foo` → independent
- `packages/bar` → depends on `packages/foo`
- `apps/web` → depends on `packages/foo`, `packages/bar`
#### Recommended Strategy
**Parallel mode:** agent-team
**Rationale:** [why this mode fits]
#### Lane Specifications
- Lane: deps
- Agent: general-purpose
- Role: implementer
- Mode: write
- Scope: Install all dependencies needed by subsequent lanes. Do NOT implement features.
- Owns: `pnpm-lock.yaml`, `package.json` (root)
- Must not edit: `packages/*/`, `apps/*/`
- Depends on: none
- Deliverable: lockfile and root package.json updated
- Lane: foo
- Agent: general-purpose
- Role: implementer
- Mode: write
- Scope: [phase work for foo]. Do NOT run pnpm install or any lockfile-modifying command.
- Owns: `packages/foo/`
- Must not edit: `pnpm-lock.yaml`, `tsconfig.base.json`, `packages/bar/`, `apps/web/`
- Branch: `agent-team/phase-N-foo`
- Depends on: deps
- Deliverable: branch name, commit SHA, validation evidence, PR URL, and changed paths
- Lane: consolidation-pr-review
- Agent: general-purpose
- Role: reviewer
- Mode: review
- Scope: Review every lane branch/PR, verify path boundaries, classify findings as blocker/advisory, and approve only safe lanes for integration.
- Depends on: foo, [all other write lanes]
- Deliverable: PR review summary, blocker/advisory findings, approved branches, and integration order
[...more lanes...]
Alignment Page
Follow the shared alignment-page convention via the packaged convention resolver; output path is alignment/mono-plan-{topic}.html. By default, report results inline and write only this skill's normal durable artifacts; create an alignment page only when explicitly requested or when a concrete clarification/review need cannot be handled cleanly inline.
Constraints
- Do not modify
tasks/roadmap.md,tasks/todo.md, or any task file — output is advisory only. - Do not run
pnpm install,npm install,yarn add, or any package manager command. - Do not create lanes for packages outside the phase's scope.
- If the phase scope is ambiguous (can't map to specific packages), enter plan mode and ask the user via
AskUserQuestion. - Maximum 12 parallel write lanes — if more packages are in scope, group related packages into combined lanes.
- Do not recommend
agent-teamif the project cannot push lane branches to GitHub and review PRs; useimplementation-safe,research-only, orserialinstead.
Next-Step Routing
- Next command:
/plan-phase N— incorporate the lane specs into the execution profile. - Before dispatch:
/mono-guard— validate the final execution profile.
Default Shipping Contract
Follow the shared shipping contract convention in CLAUDE.md.