skillpacks 0.1.0

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

@@ -0,0 +1,95 @@
+---
+name: scaffold
+description: Generate a new package or app in the monorepo following established project conventions
+type: execution
+version: v0.1
+argument-hint: <type> <name> (e.g. "package utils" or "app admin-dashboard")
+---
+
+# Scaffold
+
+Generate a new package or app in the monorepo that follows the project's established conventions and patterns.
+
+For product/app workflows, `/scaffold` is normally downstream of research, prototype consolidation, production specification, roadmap, and phase planning. Use it when `/roadmap` or `/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 input** from `$ARGUMENTS`:
+   - Extract the type (`package` or `app`) and the name.
+   - If not provided or unclear, ask the user.
+
+2. **Learn the project's conventions:**
+   - Read `.agents/project.json` when present. If it is missing, run or recommend `/pack recommend` and include the likely project type in the scaffold plan.
+   - If this 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.
+   - Read `CLAUDE.md` and `AGENTS.md` for project structure and conventions.
+   - Read the monorepo config (`turbo.json`, `pnpm-workspace.yaml`, or equivalent).
+   - Identify the directory pattern:
+     - Where do packages live? (`packages/`, `libs/`, etc.)
+     - Where do apps live? (`apps/`, `services/`, etc.)
+
+3. **Find a reference to copy from:**
+   - List existing packages/apps of the same type.
+   - Read the most recently created one (by git log) as the template.
+   - Identify the standard files:
+     - `package.json` (scripts, dependencies, exports)
+     - `tsconfig.json` (extends pattern)
+     - Source structure (`src/`, `index.ts`, etc.)
+     - Test setup (if present)
+     - Any other config files (`.eslintrc`, `tailwind.config.*`, etc.)
+
+4. **Enter plan mode:**
+   - Enter plan mode using EnterPlanMode.
+   - Present the scaffold plan:
+     - Directory: where it will be created
+     - Files to generate (with brief content description)
+     - Dependencies to include
+     - Reference package used as template
+   - Wait for user approval.
+
+5. **Generate the scaffold after approval:**
+   - If Claude Code already returned to normal mode after approval, do not call ExitPlanMode again; continue directly with generation. Only use the plan-mode exit tool when the session is still visibly in plan mode.
+   - Create the directory structure.
+   - Generate each file, adapting the template:
+     - Update `name` in `package.json` to match the new package name.
+     - Update paths and references.
+     - Create minimal placeholder source files (`src/index.ts` with a basic export).
+     - Include the standard test setup if the project uses tests.
+   - Run `pnpm install` (or equivalent) to link the new package.
+   - Run type-checking to verify the scaffold compiles.
+
+## Output
+
+### Scaffolded
+- **Type**: package/app
+- **Name**: `@scope/name`
+- **Location**: `packages/name/`
+
+### Files Created
+- `packages/name/package.json`
+- `packages/name/tsconfig.json`
+- `packages/name/src/index.ts`
+- ...
+
+### Next Steps
+- What the user should do next (add dependencies, implement features, wire up routes, etc.)
+
+## 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/app as the reference template — do not invent conventions.
+- Do not install domain packs globally; use project-local pack skill roots.
+- Always enter plan mode before creating files.
+- Do not call ExitPlanMode from normal mode. If Claude Code reports "You are not in plan mode" after approval, treat approval as complete and continue implementation.
+- Do not add unnecessary boilerplate — keep the scaffold minimal and consistent with existing packages.
+- If the project does not appear to be a monorepo, inform the user and ask how to proceed.
+- Do not install external dependencies beyond what the template uses.
+- 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/claude/scaffold/archive/v0.0/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: scaffold
+description: Generate a new package or app in the monorepo following established project conventions
+type: execution
+version: v0.0
+argument-hint: <type> <name> (e.g. "package utils" or "app admin-dashboard")
+---
+
+# Scaffold
+
+Generate a new package or app in the monorepo that follows the project's established conventions and patterns.
+
+For product/app workflows, `/scaffold` is normally downstream of research, prototype consolidation, production specification, roadmap, and phase planning. Use it when `/roadmap` or `/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 input** from `$ARGUMENTS`:
+   - Extract the type (`package` or `app`) and the name.
+   - If not provided or unclear, ask the user.
+
+2. **Learn the project's conventions:**
+   - Read `.agents/project.json` when present. If it is missing, run or recommend `/pack recommend` and include the likely project type in the scaffold plan.
+   - If this 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.
+   - Read `CLAUDE.md` and `AGENTS.md` for project structure and conventions.
+   - Read the monorepo config (`turbo.json`, `pnpm-workspace.yaml`, or equivalent).
+   - Identify the directory pattern:
+     - Where do packages live? (`packages/`, `libs/`, etc.)
+     - Where do apps live? (`apps/`, `services/`, etc.)
+
+3. **Find a reference to copy from:**
+   - List existing packages/apps of the same type.
+   - Read the most recently created one (by git log) as the template.
+   - Identify the standard files:
+     - `package.json` (scripts, dependencies, exports)
+     - `tsconfig.json` (extends pattern)
+     - Source structure (`src/`, `index.ts`, etc.)
+     - Test setup (if present)
+     - Any other config files (`.eslintrc`, `tailwind.config.*`, etc.)
+
+4. **Enter plan mode:**
+   - Enter plan mode using EnterPlanMode.
+   - Present the scaffold plan:
+     - Directory: where it will be created
+     - Files to generate (with brief content description)
+     - Dependencies to include
+     - Reference package used as template
+   - Wait for user approval.
+
+5. **Generate the scaffold after approval:**
+   - If Claude Code already returned to normal mode after approval, do not call ExitPlanMode again; continue directly with generation. Only use the plan-mode exit tool when the session is still visibly in plan mode.
+   - Create the directory structure.
+   - Generate each file, adapting the template:
+     - Update `name` in `package.json` to match the new package name.
+     - Update paths and references.
+     - Create minimal placeholder source files (`src/index.ts` with a basic export).
+     - Include the standard test setup if the project uses tests.
+   - Run `pnpm install` (or equivalent) to link the new package.
+   - Run type-checking to verify the scaffold compiles.
+
+## Output
+
+### Scaffolded
+- **Type**: package/app
+- **Name**: `@scope/name`
+- **Location**: `packages/name/`
+
+### Files Created
+- `packages/name/package.json`
+- `packages/name/tsconfig.json`
+- `packages/name/src/index.ts`
+- ...
+
+### Next Steps
+- What the user should do next (add dependencies, implement features, wire up routes, etc.)
+
+## 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/app as the reference template — do not invent conventions.
+- Do not install domain packs globally; use project-local pack skill roots.
+- Always enter plan mode before creating files.
+- Do not call ExitPlanMode from normal mode. If Claude Code reports "You are not in plan mode" after approval, treat approval as complete and continue implementation.
+- Do not add unnecessary boilerplate — keep the scaffold minimal and consistent with existing packages.
+- If the project does not appear to be a monorepo, inform the user and ask how to proceed.
+- Do not install external dependencies beyond what the template uses.
+- 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/affected/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.0
+
+- Archived previous skill contract.
+
+## v0.1 - 2026-05-25
+
+- Added research-quality alignment requirements covering claim/evidence/inference separation, no-context-loss HTML translation, evidence matrices, confidence/assumption registers, source coverage, and research completeness gates.

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

@@ -0,0 +1,38 @@
+---
+name: affected
+description: Analyze which monorepo packages and apps are affected by current changes
+type: analysis
+version: v0.1
+---
+
+# Affected
+
+Invoke as `$affected`.
+
+Use this skill when the user wants to understand the blast radius of their current changes in a monorepo.
+
+## Process
+
+1. Determine the change set from git diff or a specified commit range.
+2. Read the monorepo config to understand the package graph.
+3. Map changed files to their packages.
+4. Compute transitive dependents.
+5. Check for cross-cutting changes (root configs, shared packages).
+6. Recommend test commands for affected packages.
+
+## Output
+
+- **Directly Changed**: packages with file changes
+- **Transitively Affected**: downstream dependents
+- **Cross-Cutting**: root config changes affecting all packages
+- **Recommended Test Commands**: specific commands to run
+
+## Constraints
+
+- Do not run tests — only analyze and recommend.
+- Prefer Turbo-native filtering for Turborepo projects.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Affected Packages"
+  short_description: "Analyze monorepo blast radius of changes"
+  default_prompt: "Use $affected to analyze which packages are affected by current changes."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,66 @@
+---
+name: affected
+description: Analyze which monorepo packages and apps are affected by current changes
+type: analysis
+version: v0.0
+---
+
+# Affected
+
+Invoke as `$affected`.
+
+Use this skill when the user wants to understand the blast radius of their current changes in a monorepo.
+
+## Workflow
+
+1. Determine the change set from git diff or a specified commit range.
+2. Read the monorepo config to understand the package graph.
+3. Map changed files to their packages.
+4. Compute transitive dependents.
+5. Check for cross-cutting changes (root configs, shared packages).
+6. Recommend test commands for affected packages.
+
+## Output Format
+
+- **Directly Changed**: packages with file changes
+- **Transitively Affected**: downstream dependents
+- **Cross-Cutting**: root config changes affecting all packages
+- **Recommended Test Commands**: specific commands to run
+
+## Constraints
+
+- Do not run tests — only analyze and recommend.
+- Prefer Turbo-native filtering for Turborepo projects.
+
+
+## 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/affected-{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/affected-{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-detect/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.0
+
+- Archived previous skill contract.
+
+## v0.1 - 2026-05-25
+
+- Added research-quality alignment requirements covering claim/evidence/inference separation, no-context-loss HTML translation, evidence matrices, confidence/assumption registers, source coverage, and research completeness gates.

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

@@ -0,0 +1,71 @@
+---
+name: mono-detect
+description: Detect pnpm workspace structure, optional Turborepo overlay, package metadata, and internal dependency graph for monorepo-aware skills
+type: analysis
+version: v0.1
+argument-hint: "[optional: repository root]"
+invocation: sub-skill
+parent: mono-plan
+---
+
+# Mono Detect
+
+Invoke as `$mono-detect`.
+
+Use this skill to detect a pnpm workspace monorepo and generate the `.agents/monorepo.json` artifact consumed by the monorepo pack.
+
+`mono-detect` is the foundation skill for `mono-exec`, `mono-ship`, and `mono-guard`. Those skills use its output to inject monorepo-aware pre/post steps into the standard `$exec` and `$ship` contracts without duplicating the global workflow.
+
+## Augmentation Injection Pattern
+
+`mono-detect` is the pack's detection foundation for the augmentation injection pattern. It does not replace `$exec`, `$ship`, or global monorepo planning skills; it supplies `.agents/monorepo.json` so `mono-exec`, `mono-ship`, and `mono-guard` can inject monorepo-aware pre-flight and post-integration checks around those existing workflows.
+
+## Process
+
+1. Resolve the target repository root.
+   - Use `$ARGUMENTS` as the root when provided.
+   - Otherwise use the current working directory.
+2. Locate the pack script relative to this skill: `../../scripts/mono-detect.sh` from the monorepo pack root.
+3. Check whether `.agents/monorepo.json` is fresh:
+   - Run `packs/monorepo/scripts/mono-detect.sh <root> --check-stale`.
+   - If it prints `fresh: .agents/monorepo.json`, keep the existing artifact.
+   - If the file is missing, stale, or the check does not report fresh, run `packs/monorepo/scripts/mono-detect.sh <root>` to regenerate it.
+4. If detection fails because `pnpm-workspace.yaml` is missing:
+   - Report that the project is not a detected pnpm monorepo.
+   - Suggest `$mono-migrate` as a future V2 migration route when the user wants to convert a single-app project.
+   - Do not create `.agents/monorepo.json` by hand.
+5. Read `.agents/monorepo.json` and summarize:
+   - Workspace manager.
+   - Build orchestrator (`turborepo` when `turbo.json` is present, otherwise none).
+   - Package count and package paths.
+   - Internal dependency graph edges.
+   - Turborepo pipeline names.
+6. Report staleness behavior:
+   - Mention that the artifact is regenerated when `pnpm-workspace.yaml`, `turbo.json`, or workspace `package.json` files are newer than `.agents/monorepo.json`.
+7. Route the next step:
+   - If detection passed and the user is preparing execution, recommend `$mono-exec`.
+   - If detection passed and the user is checking lane safety, recommend `$mono-guard`.
+   - If detection failed because this is not a pnpm monorepo, recommend `$mono-migrate` as the V2 advisory route.
+
+## Output
+
+- **Detection:** detected, fresh, regenerated, or not detected.
+- **Workspace:** manager, build orchestrator, root path.
+- **Packages:** count plus package name/path list.
+- **Dependency graph:** internal dependency edges; say `none` when no internal edges exist.
+- **Turbo pipelines:** pipeline names when present; say `none` when Turborepo is absent.
+- **Artifact:** `.agents/monorepo.json` path and whether it was reused or regenerated.
+- **Next work:** concrete follow-up.
+- **Recommended next command:** one command.
+
+## Constraints
+
+- Do not edit task files.
+- Do not run package manager install/add commands.
+- Do not infer non-pnpm workspace managers in V1.
+- Do not modify `.agents/monorepo.json` manually; use `mono-detect.sh`.
+- Treat `mono-detect` as an augmentation foundation for `mono-exec`, `mono-ship`, and `mono-guard`, not as a replacement for `$exec`, `$ship`, or global monorepo planning skills.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

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

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Mono Detect"
+  short_description: "Detect pnpm workspace packages, dependency graph, and Turbo pipelines"
+  default_prompt: "Use $mono-detect to detect the monorepo workspace structure and write .agents/monorepo.json."
+
+policy:
+  allow_implicit_invocation: true

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

@@ -0,0 +1,97 @@
+---
+name: mono-detect
+description: Detect pnpm workspace structure, optional Turborepo overlay, package metadata, and internal dependency graph for monorepo-aware skills
+type: analysis
+version: v0.0
+argument-hint: "[optional: repository root]"
+---
+
+# Mono Detect
+
+Invoke as `$mono-detect`.
+
+Use this skill to detect a pnpm workspace monorepo and generate the `.agents/monorepo.json` artifact consumed by the monorepo pack.
+
+`mono-detect` is the foundation skill for `mono-run`, `mono-ship`, and `mono-guard`. Those skills use its output to inject monorepo-aware pre/post steps into the standard `$run` and `$ship` contracts without duplicating the global workflow.
+
+## Augmentation Injection Pattern
+
+`mono-detect` is the pack's detection foundation for the augmentation injection pattern. It does not replace `$run`, `$ship`, or global monorepo planning skills; it supplies `.agents/monorepo.json` so `mono-run`, `mono-ship`, and `mono-guard` can inject monorepo-aware pre-flight and post-integration checks around those existing workflows.
+
+## Workflow
+
+1. Resolve the target repository root.
+   - Use `$ARGUMENTS` as the root when provided.
+   - Otherwise use the current working directory.
+2. Locate the pack script relative to this skill: `../../scripts/mono-detect.sh` from the monorepo pack root.
+3. Check whether `.agents/monorepo.json` is fresh:
+   - Run `packs/monorepo/scripts/mono-detect.sh <root> --check-stale`.
+   - If it prints `fresh: .agents/monorepo.json`, keep the existing artifact.
+   - If the file is missing, stale, or the check does not report fresh, run `packs/monorepo/scripts/mono-detect.sh <root>` to regenerate it.
+4. If detection fails because `pnpm-workspace.yaml` is missing:
+   - Report that the project is not a detected pnpm monorepo.
+   - Suggest `$mono-migrate` as a future V2 migration route when the user wants to convert a single-app project.
+   - Do not create `.agents/monorepo.json` by hand.
+5. Read `.agents/monorepo.json` and summarize:
+   - Workspace manager.
+   - Build orchestrator (`turborepo` when `turbo.json` is present, otherwise none).
+   - Package count and package paths.
+   - Internal dependency graph edges.
+   - Turborepo pipeline names.
+6. Report staleness behavior:
+   - Mention that the artifact is regenerated when `pnpm-workspace.yaml`, `turbo.json`, or workspace `package.json` files are newer than `.agents/monorepo.json`.
+7. Route the next step:
+   - If detection passed and the user is preparing execution, recommend `$mono-run`.
+   - If detection passed and the user is checking lane safety, recommend `$mono-guard`.
+   - If detection failed because this is not a pnpm monorepo, recommend `$mono-migrate` as the V2 advisory route.
+
+## Output Format
+
+- **Detection:** detected, fresh, regenerated, or not detected.
+- **Workspace:** manager, build orchestrator, root path.
+- **Packages:** count plus package name/path list.
+- **Dependency graph:** internal dependency edges; say `none` when no internal edges exist.
+- **Turbo pipelines:** pipeline names when present; say `none` when Turborepo is absent.
+- **Artifact:** `.agents/monorepo.json` path and whether it was reused or regenerated.
+- **Next work:** concrete follow-up.
+- **Recommended next command:** one command.
+
+## Constraints
+
+- Do not edit task files.
+- Do not run package manager install/add commands.
+- Do not infer non-pnpm workspace managers in V1.
+- Do not modify `.agents/monorepo.json` manually; use `mono-detect.sh`.
+- Treat `mono-detect` as an augmentation foundation for `mono-run`, `mono-ship`, and `mono-guard`, not as a replacement for `$run`, `$ship`, or global monorepo planning skills.
+
+## 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-detect-{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-detect-{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 the two-line pair `**Next work:** <specific task, blocker, or follow-up>` 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-exec/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## v0.1 - 2026-05-26
+
+- Renamed the execution wrapper command from `mono-run` to `mono-exec` to follow the exec command surface.
+
+## v0.0
+
+- Initial skill contract.

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

@@ -0,0 +1,117 @@
+---
+name: mono-exec
+description: Augment the standard exec lifecycle with monorepo detection, lane-spec generation, guard validation, and package-scoped dispatch
+type: execution
+version: v0.1
+argument-hint: "[--phase] [--pipeline]"
+invocation: orchestrator
+---
+
+# Mono Exec
+
+Invoke as `$mono-exec`.
+
+Use this skill to execute planned work in a pnpm workspace monorepo with package-aware guardrails. `mono-exec` does not replace `$exec`; it injects monorepo-aware pre/post steps around the standard `$exec` contract.
+
+## Augmentation Injection Pattern
+
+`mono-exec` adds these stages around normal exec execution:
+
+1. **Pre-execution:** run `mono-detect`, generate lane specs when the phase is eligible for parallel monorepo dispatch, run `mono-guard` pre-flight, and present lane specs for plan-mode approval.
+2. **Dispatch:** run cross-cutting steps serially first in the main agent, then dispatch package-scoped worktree waves on separate GitHub branches only after lane specs are approved and guard validation passes.
+3. **Post-dispatch:** perform consolidation/PR review, run `mono-guard --post-integration`, update lane-spec lifecycle, then continue to `mono-ship` when shipping is requested.
+
+The global `$exec` skill remains the source of truth for task selection, task docs, validation, history updates, commit/push, deploy handling, and next-step routing.
+
+## Flags
+
+- Default: execute the next incomplete step.
+- `--phase`: execute all steps in the current phase, using cross-cutting serial work first and package-scoped waves where eligible.
+- `--pipeline`: execute the monorepo run flow and continue into `mono-ship` after successful post-integration guard validation.
+
+## Process
+
+1. Run `mono-detect`.
+   - If the project is not a detected pnpm workspace monorepo, delegate directly to `$exec`.
+   - If `turbo.json` is present, record that build/test/lint should defer to `turbo run`.
+   - If Turborepo is absent, record that build/test/lint should fall back to `pnpm --filter`.
+2. Read the current phase execution profile from `tasks/todo.md` and, when needed for phase context, `tasks/roadmap.md`.
+3. Decide execution mode:
+   - If the phase mode is `serial`, delegate directly to `$exec`.
+   - If the phase mode is not monorepo-parallel eligible, delegate directly to `$exec`.
+   - If the phase mode is `agent-team` or explicitly package-scoped parallel work, continue with lane-spec generation.
+4. Generate `.agents/lane-specs.json`.
+   - Include `phase`, `source_roadmap_hash`, `lifecycle`, `cross_cutting_steps`, and `lanes`.
+   - Each lane must include `id`, `step`, `packages`, `owns`, `must_not_edit`, `depends_on`, `mode`, and `branch`.
+   - Put root-only, shared-package, lockfile, and root-config work into `cross_cutting_steps` with serial mode.
+   - Put package-contained work into lanes with package-owned `owns` paths.
+   - Ensure every package lane's `must_not_edit` includes lockfiles, root config files, and other lanes' package paths.
+   - Ensure every package lane's `branch` is a deterministic non-primary GitHub branch such as `agent-team/phase-N-<lane-id>`.
+5. Generate `tasks/lane-specs.md` as the committed human-readable mirror of `.agents/lane-specs.json`.
+6. Run `mono-guard` pre-flight.
+   - Use `packs/monorepo/scripts/lane-spec-validate.sh` through `mono-guard`.
+   - Stop on `FAIL`.
+   - Present `WARN` findings for review before dispatch.
+7. Enter plan mode with lane specs for approval before launching package-scoped lanes.
+8. Dispatch work:
+   - Execute cross-cutting steps serially in the main agent first.
+   - Create worktree-isolated package lanes on their declared GitHub branches for parallel work after cross-cutting work is integrated.
+   - Give every lane its `branch`, `owns`, `must_not_edit`, `depends_on`, package scope, validation commands, and deliverable.
+   - Require every lane to commit to its branch, push it, open or update a draft PR, and return branch name, commit SHA, validation evidence, PR URL, and changed paths.
+   - Do not dispatch a lane until its `depends_on` steps are satisfied.
+   - If the repo has no GitHub remote, branch push is unavailable, or PR creation/review cannot happen, stop before dispatch.
+9. Apply stop-all-lanes failure semantics:
+   - If any lane fails, halt remaining lanes.
+   - Preserve worktree state for inspection.
+   - Update `.agents/lane-specs.json` lifecycle to `failed`.
+   - Update `tasks/lane-specs.md` with the failed lane and reason.
+   - Report the blocker and stop before shipping.
+10. After all lanes complete:
+   - Run the consolidation/PR review step: inspect every lane PR, validate changed paths against `owns` and `must_not_edit`, classify findings as blocker or advisory, and approve only safe lanes.
+   - Stop before integration if any lane has blocker findings, missing PR evidence, or changed files outside its boundary.
+   - Integrate approved lane work in dependency order from the reviewed remote branches.
+   - Run `mono-guard --post-integration`.
+   - If post-integration guard fails, stop and report boundary violations.
+   - If it passes, set lane-spec lifecycle to `integrated` and update `tasks/lane-specs.md`.
+11. If `--pipeline` was used, continue to `mono-ship`; otherwise report next work and recommended command.
+
+## Validation Command Preference
+
+- With `turbo.json`: prefer `turbo run <task> --filter=<package>` for build, test, lint, and package validation.
+- Without `turbo.json`: prefer `pnpm --filter <package> run <task>`.
+- Use `.agents/monorepo.json.dependency_graph` to order package work when Turborepo is absent.
+
+## Output
+
+- **Detection:** monorepo detected or delegated to `$exec`.
+- **Execution mode:** serial delegation, guarded package lanes, or pipeline.
+- **Lane specs:** `.agents/lane-specs.json` and `tasks/lane-specs.md` status.
+- **Guard result:** pre-flight and post-integration verdicts.
+- **Dispatch result:** cross-cutting steps, package lanes, branch/commit/PR evidence, failures, and preserved worktrees when applicable.
+- **Consolidation/PR review:** reviewed PRs, blocker/advisory findings, approved branches, and integration order.
+- **Lifecycle:** draft, approved, dispatched, integrated, or failed.
+- **Next work:** concrete follow-up.
+- **Recommended next command:** one command.
+
+## Constraints
+
+- Do not run package manager install/add commands in package lanes.
+- Do not modify lockfiles from parallel lanes.
+- Do not dispatch package lanes unless `mono-guard` pre-flight passes and lane specs are approved.
+- Do not dispatch package lanes unless every write lane has a non-primary GitHub branch and PR review can be performed.
+- Do not continue after a lane failure; preserve worktree state and mark lifecycle `failed`.
+- Do not bypass standard `$exec` task selection, validation, history, commit/push, deploy, or next-step routing responsibilities.
+- Do not use GitHub Actions.
+
+## Next-Step Routing
+
+- Non-monorepo or serial phase: `$exec`.
+- Pre-flight guard failure: `$mono-guard` after fixing or regenerating lane specs.
+- Successful guarded run without pipeline: `$mono-ship`.
+- Failed lane dispatch: inspect preserved worktree state, then rerun `$mono-exec` after the blocker is fixed.
+- Completed pipeline: follow the next command reported by `mono-ship`.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.