mono-ship
Augment the standard ship lifecycle with monorepo package-scoped and transitive-dependent validation
SKILL.mdpacks/monorepo/claude/mono-ship/SKILL.md
GitHubMono Ship
Invoke as /mono-ship.
Use this skill to ship completed work in a pnpm workspace monorepo only after package-scoped and transitive-dependent validation has passed. mono-ship does not replace /ship; it injects monorepo-aware validation before standard shipping and lane-spec status updates after standard shipping.
Augmentation Injection Pattern
mono-ship adds these stages around normal ship execution:
- Pre-ship: run
mono-detectwhen needed, read.agents/lane-specs.jsonand.agents/monorepo.json, confirm branch-backed lane work has passed consolidation/PR review, identify modified packages, run package-scoped test/lint/build, and run transitive-dependent validation from the dependency graph. - Ship: delegate to the standard
/shipcontract after validation passes. - Post-ship: update
tasks/lane-specs.mdwith shipping status, lifecycle notes, and the next routed command.
The base /ship skill remains the source of truth for final validation policy, task docs, history updates, commit/push, deploy handling, and next-step routing.
Inputs
.agents/monorepo.json: generated bymono-detect; contains workspace packages, package paths, build orchestrator, scripts, anddependency_graph..agents/lane-specs.json: generated bymono-exec; contains lane lifecycle and package ownership for modified work.tasks/lane-specs.md: committed human-readable mirror of lane status and shipping status.- Git diff: used to identify changed package paths when lane specs are absent, stale, or incomplete.
If .agents/monorepo.json is missing or stale, run mono-detect first. If the project is not a detected pnpm workspace monorepo, delegate directly to /ship.
Pre-Ship Workflow
- Run
mono-detect.- If
turbo.jsonis present, preferturbo runfor package validation. - If Turborepo is absent, fall back to
pnpm --filter. - If detection fails because this is not a pnpm workspace monorepo, delegate directly to
/ship.
- If
- Read
.agents/monorepo.json.- Use
packagesto map changed paths to package names. - Use
.agents/monorepo.json.dependency_graphto find internal package dependents.
- Use
- Read
.agents/lane-specs.jsonwhen present.- Treat lanes with lifecycle
integratedas the preferred source for modified packages. - If lane specs are missing or do not identify all changed package paths, supplement with
git diff --name-only. - If lane specs contain branch-backed
agent-teamlanes, confirm consolidation/PR review evidence exists before shipping; otherwise stop and rerun/mono-guard --post-integration.
- Treat lanes with lifecycle
- Determine the package validation set.
- Include every package modified by the current shipping boundary.
- Include every transitive dependent of each modified package by walking reverse edges from
dependency_graph. - Include directly changed shared packages even if no lane owns them.
- Run package-scoped validation for each modified package:
- Test:
turbo run test --filter=<package>when Turborepo is available; otherwisepnpm --filter <package> run test. - Lint:
turbo run lint --filter=<package>when Turborepo is available; otherwisepnpm --filter <package> run lint. - Build:
turbo run build --filter=<package>when Turborepo is available; otherwisepnpm --filter <package> run build. - Skip a task only when the package lacks that script or the repo's validation contract explicitly says it is not applicable; record the skip with rationale.
- Test:
- Run transitive-dependent validation.
- For packages that depend on modified packages, run their available test, lint, and build scripts using the same Turbo-first preference.
- With Turborepo, prefer
turbo run <task> --filter=<dependent>to let Turbo include relevant dependency ordering and cache behavior. - Without Turborepo, order dependent validation from nearest dependent outward using the dependency graph.
- Stop and report on any validation failure before shipping.
- Do not delegate to
/ship. - Do not update lifecycle to shipped.
- Report failed command, package, task, and the smallest recommended fix path.
- Do not delegate to
Ship Workflow
After pre-ship validation passes, delegate to /ship.
mono-ship must not bypass or duplicate standard /ship responsibilities. /ship owns commit grouping, push target, deploy contract handling, final task/history updates, quality manifest requirements, and final next-step routing.
Post-Ship Workflow
After /ship completes successfully:
- Update
tasks/lane-specs.mdif it exists.- Record shipping status as shipped.
- Record validation packages and transitive dependents that were checked.
- Record the final commit or push summary when available.
- Preserve lane history instead of rewriting prior failure or integration notes.
- If
.agents/lane-specs.jsonis still part of the project workflow, update its lifecycle only through the same lane-spec artifact contract used bymono-exec. - If
--pipelinewas used, plan the next phase or next step using the command reported by/ship.
Validation Command Preference
- With
turbo.json: preferturbo run <task> --filter=<package>for test, lint, build, and dependent validation. - Without
turbo.json: preferpnpm --filter <package> run <task>. - Use
.agents/monorepo.json.dependency_graphto compute transitive dependents and validation order when Turborepo is absent.
Output
- Detection: monorepo detected or delegated to
/ship. - Modified packages: package names and source used to identify them.
- Transitive dependents: dependent packages selected from
dependency_graph. - Validation: commands run, skipped scripts with rationale, failures or warnings.
- Ship result: delegated
/shipstatus. - Lane specs: lane-spec mirror status update, when applicable.
- Next work: concrete follow-up.
- Recommended next command: one command.
Constraints
- Do not run package manager install/add commands.
- Do not modify lockfiles as part of shipping validation.
- Do not proceed to
/shipif package-scoped or transitive-dependent validation fails. - Do not hide package warnings; fix them, accept them with rationale, or report them as unresolved blockers.
- Do not bypass standard
/shiptask docs, history, commit/push, deploy, quality gate, or next-step routing responsibilities. - Do not use GitHub Actions.
Next-Step Routing
- Non-monorepo project:
/ship. - Missing or stale
.agents/monorepo.json:/mono-detect. - Validation failure before shipping: fix the package failure, then rerun
/mono-ship. - Successful pre-ship validation: delegate to
/ship. - Successful pipeline ship: follow the next command reported by
/ship, usually/exec.
Default Shipping Contract
Follow the shared shipping contract convention in CLAUDE.md.