skillpacks 0.1.0

package/packs/monorepo/codex/mono-plan/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: mono-plan
+description: Detect monorepo structure, identify shared chokepoints, and generate safe parallel lane specs aligned to package boundaries
+type: planning
+version: v0.1
+---
+
+# Mono Plan
+
+Invoke as `$mono-plan`.
+
+Use this skill when the user needs to plan safe parallel work across a monorepo. Generates lane specs aligned to package boundaries with lockfile and root config safety built in.
+
+Run after `/roadmap` sets `agent-team` or `implementation-safe` on a phase, before `/plan-phase` decomposes it.
+
+## Process
+
+1. Detect monorepo structure (`pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, `package.json` workspaces). Stop if not a monorepo.
+2. Enumerate packages, read each `package.json`, build internal dependency graph.
+3. Identify shared chokepoints: lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`), root configs (`tsconfig.base.json`, `turbo.json`, etc.), high-fan-out shared packages (3+ dependents).
+4. Read the target phase from `tasks/roadmap.md`, map scope to specific packages.
+5. Classify packages: independent, dependent, or shared.
+6. Recommend strategy: `agent-team` (independent packages with branch-backed lanes), `serial` (linear chain), or mixed with dependency edges.
+7. Generate lane specs in execution profile format:
+   - **Lane 0 (deps):** serial lane owning lockfiles if any lane needs dependency installs. All write lanes depend on it.
+   - **Package lanes:** one per package, `Owns` scoped to package dir, `Must not edit` includes all lockfiles + root configs + other lanes' paths, and `Branch` uses `agent-team/phase-N-<package-or-lane>`. Scope text includes "Do NOT run pnpm install or any lockfile-modifying command."
+   - **Consolidation/PR review:** add a final review lane or implementation step that reviews every package lane branch/PR before integration.
+8. Validate: disjoint Owns, all lockfiles excluded from write lanes, valid DAG, unique non-primary branches, and a consolidation/PR review gate.
+
+## Output
+
+- **Monorepo tool and package count**
+- **Shared Chokepoints**: lockfiles, root configs, high-fan-out packages
+- **Package Dependency Graph**: in-scope packages with dependency edges
+- **Recommended Strategy**: parallel mode and rationale
+- **Lane Specifications**: in execution profile format (Agent, Role, Mode, Scope, Owns, Must not edit, Branch, Depends on, Deliverable)
+- **Consolidation/PR Review**: required final gate for `agent-team` package lanes, including branch/PR review and boundary checks before integration
+
+## Constraints
+
+- Do not modify task files — output is advisory only.
+- Do not run package manager install/add commands.
+- Maximum 12 parallel write lanes — group if more packages are in scope.
+- Do not recommend `agent-team` if the project cannot push lane branches to GitHub and review PRs; use `implementation-safe`, `research-only`, or `serial` instead.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page following `ALIGNMENT-PAGE.md` in this skill's directory. Output: `alignment/mono-plan-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/monorepo/codex/mono-plan/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Mono Plan"
+  short_description: "Generate branch-backed monorepo parallel lane specs"
+  default_prompt: "Use $mono-plan to generate safe branch-backed parallel lane specs for this monorepo phase."
+
+policy:
+  allow_implicit_invocation: true

package/packs/monorepo/codex/mono-plan/archive/v0.0/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: mono-plan
+description: Detect monorepo structure, identify shared chokepoints, and generate safe parallel lane specs aligned to package boundaries
+type: planning
+version: v0.0
+---
+
+# Mono Plan
+
+Invoke as `$mono-plan`.
+
+Use this skill when the user needs to plan safe parallel work across a monorepo. Generates lane specs aligned to package boundaries with lockfile and root config safety built in.
+
+Run after `/roadmap` sets `agent-team` or `implementation-safe` on a phase, before `/plan-phase` decomposes it.
+
+## Workflow
+
+1. Detect monorepo structure (`pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, `package.json` workspaces). Stop if not a monorepo.
+2. Enumerate packages, read each `package.json`, build internal dependency graph.
+3. Identify shared chokepoints: lockfiles (`pnpm-lock.yaml`, `package-lock.json`, `yarn.lock`, `bun.lockb`), root configs (`tsconfig.base.json`, `turbo.json`, etc.), high-fan-out shared packages (3+ dependents).
+4. Read the target phase from `tasks/roadmap.md`, map scope to specific packages.
+5. Classify packages: independent, dependent, or shared.
+6. Recommend strategy: `agent-team` (independent packages with branch-backed lanes), `serial` (linear chain), or mixed with dependency edges.
+7. Generate lane specs in execution profile format:
+   - **Lane 0 (deps):** serial lane owning lockfiles if any lane needs dependency installs. All write lanes depend on it.
+   - **Package lanes:** one per package, `Owns` scoped to package dir, `Must not edit` includes all lockfiles + root configs + other lanes' paths, and `Branch` uses `agent-team/phase-N-<package-or-lane>`. Scope text includes "Do NOT run pnpm install or any lockfile-modifying command."
+   - **Consolidation/PR review:** add a final review lane or implementation step that reviews every package lane branch/PR before integration.
+8. Validate: disjoint Owns, all lockfiles excluded from write lanes, valid DAG, unique non-primary branches, and a consolidation/PR review gate.
+
+## Output Format
+
+- **Monorepo tool and package count**
+- **Shared Chokepoints**: lockfiles, root configs, high-fan-out packages
+- **Package Dependency Graph**: in-scope packages with dependency edges
+- **Recommended Strategy**: parallel mode and rationale
+- **Lane Specifications**: in execution profile format (Agent, Role, Mode, Scope, Owns, Must not edit, Branch, Depends on, Deliverable)
+- **Consolidation/PR Review**: required final gate for `agent-team` package lanes, including branch/PR review and boundary checks before integration
+
+## Constraints
+
+- Do not modify task files — output is advisory only.
+- Do not run package manager install/add commands.
+- Maximum 12 parallel write lanes — group if more packages are in scope.
+- Do not recommend `agent-team` if the project cannot push lane branches to GitHub and review PRs; use `implementation-safe`, `research-only`, or `serial` instead.
+
+## Alignment Page
+
+When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/mono-plan-{topic}.html`. Use a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
+
+**Full content requirement.** The alignment page must contain the complete content of every proposed markdown deliverable -- every section, every finding, every detail, every list item. It is a thorough interactive review document, not a summary. Render the full deliverable content in clean, readable HTML with appropriate hierarchy, styling, and navigation. If the skill writes multiple scoped deliverables in one run, build one alignment page that contains all deliverables with anchor-linked navigation. Durable tracker artifacts, such as `research/assumption-tracker.md`, remain canonical markdown outputs but must also be fully rendered into the alignment page before approval.
+
+**Dark-mode styling.** Use a dark color scheme by default. Base CSS variables: `--bg: #0d1117; --surface: #161b22; --border: #30363d; --text: #c9d1d9; --text-muted: #8b949e; --accent: #58a6ff; --green: #3fb950; --red: #f85149; --orange: #d29922; --purple: #bc8cff;`. Apply `background: var(--bg); color: var(--text);` on body. Use `--surface` for cards, nav, and table headers. Use `--border` for all borders. Use `--purple` for question blocks and gate headings. Use `--accent` for links and section headings. Keep headings `color: #fff` or `var(--accent)` for hierarchy. Question block backgrounds should use `#1c2333`.
+
+**Alignment gates.** Treat gates as explicit review sections inside the HTML page. A gate blocks finalization until its required inline questions are answered and compiled into YAML. Include every gate that applies to the skill output, and include these gate types whenever relevant: evidence coverage, assumptions/confidence, scope/non-goals, candidate/verdict decisions, artifact destination, proposed file changes, coverage checkpoint, and post-approval route.
+
+**Report-only research gates.** For report-only or pre-approval research skills, the alignment page must explicitly contain evidence coverage, assumptions/confidence, recommended path, proposed file changes, and approval gates before any canonical research, spec, or task file is created or updated.
+
+
+**Required inline questions.** Each gate must contain at least one required inline question placed directly under the content it governs, inside a visually distinct question block. Each question must use radio-button inputs and include two standing options after the skill-generated choices: "Other / None of the above" backed by a multi-line text box for free-form input, and "Need clarification" backed by an optional notes box where the user can explain what is unclear. When any radio option other than "Other" or "Need clarification" is selected, show an optional "Additional notes" text box beneath it so the user can qualify their choice. Generate questions based on what genuinely needs user input -- do not add filler questions. Do not create a separate bottom "Decisions & Clarifications" section.
+
+**Gate YAML contract.** At the bottom of the page, include a "Compile Answers" button that aggregates answers from all inline gate questions throughout the page, including free-text notes. The button remains disabled until every required question has a selection, shows a count of remaining unanswered questions, and scrolls to the first unanswered question if clicked early. When every question is answered, generate a structured YAML block with one item per gate answer using this stable shape: `section`, `gate_type`, `status` (`answered`, `other`, or `needs-clarification`), `answer`, optional `notes`, and optional `target_artifact` or `target_path` when the gate controls file output. After successful compilation, automatically attempt to copy the YAML to the clipboard with the Clipboard API, display copy status, and display the YAML in a read-only textarea with an explicit "Copy YAML" button. The copy button must retry clipboard copy when supported and fall back to selecting the textarea contents when clipboard access is unavailable or blocked.
+
+**Pre-approval stop.** Before user approval, the next action is review of the HTML alignment page, not downstream routing. Ask the user to review the page and provide the compiled YAML answers. Do not include `Recommended next skill`, `Recommended next command`, or downstream routing language until after compiled YAML has been provided and the approved artifacts have been written or updated.
+
+**Diff highlighting on updates.** When the agent updates an existing alignment page after receiving compiled answers, highlight what changed since the previous version. The agent chooses inline annotation or side-by-side layout per situation.
+
+**Archiving.** Before replacing an existing alignment page, archive it to `docs/history/archive/YYYY-MM-DD/HHMMSS/alignment/mono-plan-{topic}.html`.
+
+**Browser open.** Attempt to open the resulting HTML page in the browser and report whether the open succeeded or was blocked. A blocked browser-open attempt does not make the skill fail when the files were written correctly.
+
+## Default Shipping Contract
+
+- **Default next-step routing:** when reporting completion, include either `Recommended next skill: <command>` or the two-line pair `**Next work:** <specific task or "none">` and `**Recommended next command:** <one command or route>` so the next operator has a concrete handoff.
+- If this skill creates or modifies tracked repository files, finish by committing and pushing all intended changes to the repository primary branch (`main` when present, otherwise `master`) before stopping, even if the user did not explicitly ask for commit/push.
+- Do not leave tracked changes or unpushed commits behind. If unrelated tracked work is already present, either include it in sensible commits too or stop and explain the blocker.
+- This contract does not override stricter safety rules about secrets, destructive history changes, release publication/tag confirmation, or production deploy confirmation.

package/packs/monorepo/codex/mono-ship/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: mono-ship
+description: Augment the standard ship lifecycle with monorepo package-scoped and transitive-dependent validation
+type: shipping
+version: v0.0
+argument-hint: "[--pipeline]"
+invocation: orchestrator
+---
+
+# 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 global `$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.

package/packs/monorepo/codex/mono-ship/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Mono Ship"
+  short_description: "Run PR-reviewed package validation before shipping"
+  default_prompt: "Use $mono-ship to confirm branch-backed lane review and run monorepo-aware package validation before delegating to $ship."
+
+policy:
+  allow_implicit_invocation: true

package/packs/monorepo/codex/scaffold/CHANGELOG.md

@@ -0,0 +1,9 @@
+# scaffold changelog (codex)
+
+## v0.1 - 2026-06-07
+
+- Routed early product scaffold follow-up guidance from retired `$icp` to `$customer-discovery`.
+
+## v0.0
+
+- Initial version.

package/packs/monorepo/codex/scaffold/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: scaffold
+description: Generate a new package or app in the monorepo following established project conventions
+type: execution
+version: v0.1
+---
+
+# Scaffold
+
+Invoke as `$scaffold`.
+
+Use this skill when the user wants to create a new package or app in their monorepo.
+
+For product/app workflows, `$scaffold` is normally downstream of research, prototype consolidation, production specification, roadmap, and phase planning. Use it when `$roadmap`/`$plan-phase` identifies that the next implementation step needs a new app/package root. Do not route from `$idea-scope-brief`, `$bootstrap-repo`, `$customer-discovery`, `$competitive-analysis`, `$journey-map`, `$ux-variations`, or `$ui-interview` directly to `$scaffold` unless the user explicitly asks to create a minimal shell first.
+
+## Process
+
+1. Parse the type (package/app) and name from arguments.
+2. Check `.agents/project.json`. If it is missing, run or recommend `$pack recommend` and include the likely project type in the scaffold plan.
+3. If the scaffold creates a new project root, include `.agents/project.json` and install the matching local pack with `scripts/pack.sh install <pack>` after the root exists.
+4. Learn conventions from CLAUDE.md, AGENTS.md, `.agents/project.json`, and monorepo config.
+5. Find the most recently created package/app as a template.
+6. Present the scaffold plan and wait for approval. Use `update_plan` to track the work; use `request_user_input` only if the session is already in Plan mode and a structured choice would help.
+7. Generate files, adapting the template with the new name.
+8. Run install and type-check to verify.
+
+## Output
+
+- **Scaffolded**: type, name, location
+- **Files Created**: list of generated files
+- **Next Steps**: what to do after scaffolding
+
+## Next-Step Routing
+
+- If the scaffold was created as part of an active roadmap/phase, recommend `$exec` to continue the current implementation step.
+- If the user explicitly requested an early shell before research, keep the next route on the research-first product workflow: `$customer-discovery` when the concept is ready and business-discovery is enabled, otherwise `$pack install business-discovery`.
+- If the scaffold is for a non-product package with no pending roadmap item, recommend `$roadmap` or `$plan-phase` only when implementation sequencing is missing.
+
+## Constraints
+
+- Always use an existing package as the reference template.
+- Do not install domain packs globally; use project-local pack skill roots.
+- Present the plan and get approval before creating files. Do not assume a Claude-style `EnterPlanMode` or clear-context accept flow exists.
+- Keep the scaffold minimal — no unnecessary boilerplate.
+- Do not treat scaffolding as product validation. It creates structure only; ICP, market, journey, UX, UI, and prototype decisions belong to their upstream skills.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/monorepo/codex/scaffold/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Scaffold"
+  short_description: "Generate new monorepo package or app"
+  default_prompt: "Use $scaffold to scaffold a new package or app following project conventions."
+
+policy:
+  allow_implicit_invocation: true

package/packs/monorepo/codex/scaffold/archive/v0.0/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: scaffold
+description: Generate a new package or app in the monorepo following established project conventions
+type: execution
+version: v0.0
+---
+
+# Scaffold
+
+Invoke as `$scaffold`.
+
+Use this skill when the user wants to create a new package or app in their monorepo.
+
+For product/app workflows, `$scaffold` is normally downstream of research, prototype consolidation, production specification, roadmap, and phase planning. Use it when `$roadmap`/`$plan-phase` identifies that the next implementation step needs a new app/package root. Do not route from `$idea-scope-brief`, `$bootstrap-repo`, `$icp`, `$competitive-analysis`, `$journey-map`, `$ux-variations`, or `$ui-interview` directly to `$scaffold` unless the user explicitly asks to create a minimal shell first.
+
+## Process
+
+1. Parse the type (package/app) and name from arguments.
+2. Check `.agents/project.json`. If it is missing, run or recommend `$pack recommend` and include the likely project type in the scaffold plan.
+3. If the scaffold creates a new project root, include `.agents/project.json` and install the matching local pack with `scripts/pack.sh install <pack>` after the root exists.
+4. Learn conventions from CLAUDE.md, AGENTS.md, `.agents/project.json`, and monorepo config.
+5. Find the most recently created package/app as a template.
+6. Present the scaffold plan and wait for approval. Use `update_plan` to track the work; use `request_user_input` only if the session is already in Plan mode and a structured choice would help.
+7. Generate files, adapting the template with the new name.
+8. Run install and type-check to verify.
+
+## Output
+
+- **Scaffolded**: type, name, location
+- **Files Created**: list of generated files
+- **Next Steps**: what to do after scaffolding
+
+## Next-Step Routing
+
+- If the scaffold was created as part of an active roadmap/phase, recommend `$exec` to continue the current implementation step.
+- If the user explicitly requested an early shell before research, keep the next route on the research-first product workflow: `$icp` when the concept is ready and business-discovery is enabled, otherwise `$pack install business-discovery`.
+- If the scaffold is for a non-product package with no pending roadmap item, recommend `$roadmap` or `$plan-phase` only when implementation sequencing is missing.
+
+## Constraints
+
+- Always use an existing package as the reference template.
+- Do not install domain packs globally; use project-local pack skill roots.
+- Present the plan and get approval before creating files. Do not assume a Claude-style `EnterPlanMode` or clear-context accept flow exists.
+- Keep the scaffold minimal — no unnecessary boilerplate.
+- Do not treat scaffolding as product validation. It creates structure only; ICP, market, journey, UX, UI, and prototype decisions belong to their upstream skills.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/monorepo/scripts/lane-spec-validate.sh

@@ -0,0 +1,253 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+usage() {
+  cat <<'EOF'
+Usage: lane-spec-validate.sh [lane-specs.json]
+
+Validate a monorepo lane-spec artifact.
+
+Arguments:
+  lane-specs.json  Lane-spec file to validate. Defaults to .agents/lane-specs.json.
+
+Checks:
+  - Required top-level fields and lane fields are present.
+  - Lifecycle is one of draft, approved, dispatched, integrated, failed.
+  - Lane owns paths are disjoint.
+  - Every lane must_not_edit includes lockfile and root config paths.
+  - Lane depends_on references resolve to known step IDs.
+  - Every lane has a unique non-primary branch name for PR review.
+EOF
+}
+
+SPEC_FILE=".agents/lane-specs.json"
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    *)
+      if [[ "$SPEC_FILE" != ".agents/lane-specs.json" ]]; then
+        echo "ERROR: unexpected argument: $1" >&2
+        usage >&2
+        exit 2
+      fi
+      SPEC_FILE="$1"
+      shift
+      ;;
+  esac
+done
+
+node - "$SPEC_FILE" <<'NODE'
+const fs = require("fs");
+const path = require("path");
+
+const specFile = process.argv[2];
+const validLifecycles = new Set(["draft", "approved", "dispatched", "integrated", "failed"]);
+const requiredRootMustNotEdit = ["pnpm-lock.yaml", "package.json", "pnpm-workspace.yaml", "turbo.json"];
+const topLevelFields = ["phase", "source_roadmap_hash", "lifecycle", "cross_cutting_steps", "lanes"];
+const laneFields = ["id", "step", "packages", "owns", "must_not_edit", "depends_on", "mode", "branch"];
+
+function fail(message, code = 1) {
+  console.error(`ERROR: ${message}`);
+  process.exit(code);
+}
+
+function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    fail(`failed to parse JSON at ${file}: ${error.message}`);
+  }
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function describeLane(lane, index) {
+  return isPlainObject(lane) && typeof lane.id === "string" && lane.id.trim()
+    ? `lane ${lane.id}`
+    : `lane at index ${index}`;
+}
+
+function normalizePath(value) {
+  if (typeof value !== "string") return null;
+  let normalized = value.trim().replace(/\\/g, "/").replace(/^\.\//, "");
+  normalized = path.posix.normalize(normalized);
+  if (normalized === ".") normalized = "";
+  normalized = normalized.replace(/^\/+/, "");
+  return normalized;
+}
+
+function normalizeBoundary(value) {
+  const normalized = normalizePath(value);
+  if (normalized === null || normalized === "") return normalized;
+  return value.endsWith("/") && !normalized.endsWith("/") ? `${normalized}/` : normalized;
+}
+
+function pathContains(parent, child) {
+  const parentDir = parent.endsWith("/") ? parent : `${parent}/`;
+  return child === parent || child.startsWith(parentDir);
+}
+
+function hasBoundary(list, required) {
+  const normalizedRequired = normalizePath(required);
+  return list.some((entry) => {
+    const normalizedEntry = normalizePath(entry);
+    return normalizedEntry === normalizedRequired;
+  });
+}
+
+function assertString(value, field) {
+  if (typeof value !== "string" || !value.trim()) {
+    fail(`${field} must be a non-empty string`);
+  }
+}
+
+function assertStringArray(value, field, { allowEmpty = true } = {}) {
+  if (!Array.isArray(value)) {
+    fail(`${field} must be an array`);
+  }
+  if (!allowEmpty && value.length === 0) {
+    fail(`${field} must not be empty`);
+  }
+  for (const [index, item] of value.entries()) {
+    if (typeof item !== "string" || !item.trim()) {
+      fail(`${field}[${index}] must be a non-empty string`);
+    }
+  }
+}
+
+if (!fs.existsSync(specFile)) {
+  fail(`lane-spec file not found: ${specFile}`);
+}
+
+const spec = readJson(specFile);
+if (!isPlainObject(spec)) {
+  fail("lane-spec root must be a JSON object");
+}
+
+for (const field of topLevelFields) {
+  if (!(field in spec)) {
+    fail(`missing required top-level field: ${field}`);
+  }
+}
+
+assertString(spec.phase, "phase");
+assertString(spec.source_roadmap_hash, "source_roadmap_hash");
+assertString(spec.lifecycle, "lifecycle");
+
+if (!validLifecycles.has(spec.lifecycle)) {
+  fail(`invalid lifecycle: ${spec.lifecycle}`);
+}
+
+if (!Array.isArray(spec.cross_cutting_steps)) {
+  fail("cross_cutting_steps must be an array");
+}
+
+if (!Array.isArray(spec.lanes) || spec.lanes.length === 0) {
+  fail("lanes must be a non-empty array");
+}
+
+const knownSteps = new Set();
+for (const [index, step] of spec.cross_cutting_steps.entries()) {
+  if (!isPlainObject(step)) {
+    fail(`cross_cutting_steps[${index}] must be an object`);
+  }
+  assertString(step.step, `cross_cutting_steps[${index}].step`);
+  if (knownSteps.has(step.step)) {
+    fail(`duplicate step id: ${step.step}`);
+  }
+  knownSteps.add(step.step);
+}
+
+const laneIds = new Set();
+const branchNames = new Set();
+const owns = [];
+
+for (const [index, lane] of spec.lanes.entries()) {
+  const label = describeLane(lane, index);
+  if (!isPlainObject(lane)) {
+    fail(`${label} must be an object`);
+  }
+
+  for (const field of laneFields) {
+    if (!(field in lane)) {
+      fail(`${label} missing required field: ${field}`);
+    }
+  }
+
+  assertString(lane.id, `${label}.id`);
+  assertString(lane.step, `${label}.step`);
+  assertString(lane.mode, `${label}.mode`);
+  assertString(lane.branch, `${label}.branch`);
+  assertStringArray(lane.packages, `${label}.packages`, { allowEmpty: false });
+  assertStringArray(lane.owns, `${label}.owns`, { allowEmpty: false });
+  assertStringArray(lane.must_not_edit, `${label}.must_not_edit`, { allowEmpty: false });
+  assertStringArray(lane.depends_on, `${label}.depends_on`);
+
+  if (laneIds.has(lane.id)) {
+    fail(`duplicate lane id: ${lane.id}`);
+  }
+  laneIds.add(lane.id);
+
+  const branch = lane.branch.trim();
+  if (branch === "main" || branch === "master") {
+    fail(`${label}.branch must not be the primary branch: ${branch}`);
+  }
+  if (!/^[A-Za-z0-9._/-]+$/.test(branch)) {
+    fail(`${label}.branch contains unsupported characters: ${branch}`);
+  }
+  if (branchNames.has(branch)) {
+    fail(`duplicate branch name: ${branch}`);
+  }
+  branchNames.add(branch);
+
+  if (knownSteps.has(lane.step)) {
+    fail(`duplicate step id: ${lane.step}`);
+  }
+  knownSteps.add(lane.step);
+
+  for (const required of requiredRootMustNotEdit) {
+    if (!hasBoundary(lane.must_not_edit, required)) {
+      fail(`${label}.must_not_edit missing required root boundary: ${required}`);
+    }
+  }
+
+  for (const ownerPath of lane.owns) {
+    const normalized = normalizeBoundary(ownerPath);
+    if (!normalized) {
+      fail(`${label}.owns contains an empty path`);
+    }
+    owns.push({ lane: lane.id, path: normalized });
+  }
+}
+
+for (const [index, lane] of spec.lanes.entries()) {
+  const label = describeLane(lane, index);
+  for (const dependency of lane.depends_on) {
+    if (!knownSteps.has(dependency)) {
+      fail(`${label}.depends_on references unknown step: ${dependency}`);
+    }
+    if (dependency === lane.step) {
+      fail(`${label}.depends_on references its own step: ${dependency}`);
+    }
+  }
+}
+
+for (let leftIndex = 0; leftIndex < owns.length; leftIndex += 1) {
+  for (let rightIndex = leftIndex + 1; rightIndex < owns.length; rightIndex += 1) {
+    const left = owns[leftIndex];
+    const right = owns[rightIndex];
+    if (left.lane === right.lane) continue;
+    if (pathContains(left.path, right.path) || pathContains(right.path, left.path)) {
+      fail(`owns paths overlap between lanes ${left.lane} and ${right.lane}: ${left.path} <-> ${right.path}`);
+    }
+  }
+}
+
+console.log(`valid: ${specFile}`);
+NODE