mono-ship

Augment the standard ship lifecycle with monorepo package-scoped and transitive-dependent validation

SKILL.md

GitHub

Mono 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:

  1. Pre-ship: run mono-detect when needed, read .agents/lane-specs.json and .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.
  2. Ship: delegate to the standard /ship contract after validation passes.
  3. Post-ship: update tasks/lane-specs.md with 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 by mono-detect; contains workspace packages, package paths, build orchestrator, scripts, and dependency_graph.
  • .agents/lane-specs.json: generated by mono-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

  1. Run mono-detect.
    • If turbo.json is present, prefer turbo run for 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.
  2. Read .agents/monorepo.json.
    • Use packages to map changed paths to package names.
    • Use .agents/monorepo.json.dependency_graph to find internal package dependents.
  3. Read .agents/lane-specs.json when present.
    • Treat lanes with lifecycle integrated as 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-team lanes, confirm consolidation/PR review evidence exists before shipping; otherwise stop and rerun /mono-guard --post-integration.
  4. 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.
  5. Run package-scoped validation for each modified package:
    • Test: turbo run test --filter=<package> when Turborepo is available; otherwise pnpm --filter <package> run test.
    • Lint: turbo run lint --filter=<package> when Turborepo is available; otherwise pnpm --filter <package> run lint.
    • Build: turbo run build --filter=<package> when Turborepo is available; otherwise pnpm --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.
  6. 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.
  7. 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.

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:

  1. Update tasks/lane-specs.md if 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.
  2. If .agents/lane-specs.json is still part of the project workflow, update its lifecycle only through the same lane-spec artifact contract used by mono-exec.
  3. If --pipeline was used, plan the next phase or next step using the command reported by /ship.

Validation Command Preference

  • With turbo.json: prefer turbo run <task> --filter=<package> for test, lint, build, and dependent validation.
  • Without turbo.json: prefer pnpm --filter <package> run <task>.
  • Use .agents/monorepo.json.dependency_graph to 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 /ship status.
  • 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 /ship if 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 /ship task 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.