skillpacks 0.1.1 → 0.1.2

package/packs/guided-walkthrough/codex/uat-guide/archive/v0.4/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: uat-guide
+description: Expand a UAT journey into click-by-click tester instructions, then update the result log on completion
+type: analysis
+version: v0.4
+argument-hint: "[optional: journey number, journey name, or 'next']"
+visual_tier: prototype
+---
+
+## Pack Availability Guard
+
+Before telling the user to run a skill from another project-local pack, check `.agents/project.json.enabled_packs`. If the target pack is not enabled, recommend `$pack install <pack>` inside Codex, or `npx skillpacks install <pack>` from the project shell, before the target skill. Global skills are always valid. Skills from this same pack are valid because the current skill is already running from that pack.
+
+# UAT Guide
+
+Invoke as `$uat-guide`.
+
+Expand a single UAT journey from `research/uat-plan.md` into detailed, step-by-step tester instructions. UAT planning (`$uat`) produces high-level task sequences ("sign up", "navigate to dashboard"); this skill turns each step into click-by-click, command-by-command, or request-by-request guidance that a tester unfamiliar with the product can follow without ambiguity.
+
+Do not generate UAT journeys. If no UAT plan exists, stop and recommend `$uat` from the product-testing pack.
+
+## Process
+
+1. **Locate UAT plan**
+   - Read `research/uat-plan.md`.
+   - If the file does not exist, stop and tell the user: "No UAT plan found. Run `$uat` first to generate acceptance journeys."
+
+2. **Select journey**
+   - Parse all `### Journey N:` headings and their `#### UAT result log` status fields.
+   - If `$ARGUMENTS` is non-empty, match by journey number or name (case-insensitive substring match).
+   - If `$ARGUMENTS` is `next` or empty, pick the first journey whose status is `Not run`.
+   - If all journeys have status `Pass`, `Fail`, or `Blocked`, tell the user all journeys are complete and offer to re-run a specific one.
+
+3. **Gather project context**
+   - Read `.agents/project.json`, `README.md`, `AGENTS.md`, `CLAUDE.md`, relevant `specs/`, `docs/`, and `tasks/` files when present.
+   - Search the codebase for routes, UI components, CLI entry points, API endpoints, environment variables, configuration files, and navigation structure relevant to the selected journey's task sequence.
+
+4. **Detect product interface type**
+   - Classify the product surface the journey touches:
+     - **Web app** -> click-by-click instructions (buttons, links, forms, pages).
+     - **CLI** -> command-by-command instructions (exact commands, flags, expected output).
+     - **API** -> request-by-request instructions (method, URL, headers, body, expected response).
+     - **Hybrid** -> mixed instructions matching each step's surface.
+   - Use the detected type to shape the instruction style for step 6.
+
+5. **Research current instructions**
+   - Use web search to find up-to-date documentation for any external services or platforms referenced in the journey (OAuth providers, third-party dashboards, payment processors, DNS registrars, etc.).
+   - Prioritize official documentation over blog posts.
+   - Service UIs change frequently -- never rely solely on prior knowledge; always search.
+   - If current web research is unavailable in the active environment, state that limitation clearly and keep external-service steps scoped to what local project evidence proves.
+
+6. **Expand task sequence**
+   - For each step in the journey's task sequence, produce:
+     - **Numbered sub-steps** with exact UI elements to click, commands to run, or requests to make. Use project-specific values (URLs, routes, field names, env vars) drawn from codebase context.
+     - **Checkpoint** tied to the journey's acceptance criteria -- what the tester should observe to confirm the step succeeded.
+     - **Evidence capture point** -- what to screenshot, copy, or record at this step.
+     - **Gotchas** -- common mistakes, timing issues, or easy-to-miss details.
+   - Begin the guide with a **Preparation** section drawn from the journey's Setup field (accounts, data, environment, permissions needed before starting).
+   - End the guide with a **Final verification** section drawn from the journey's acceptance criteria and expected success state.
+
+7. **Present guide**
+   - Output the guide directly in the conversation. Do not write it to a file.
+
+8. **Collect results**
+   - After presenting the guide, tell the user: "When you've completed this journey, let me know the result (Pass / Fail / Blocked) and any notes, and I'll update the result log."
+   - When the user reports completion:
+     - Update the `#### UAT result log` section for this journey inline in `research/uat-plan.md` with the reported status, evidence, tester notes, and any follow-up tasks promoted.
+     - Check off the corresponding item in `tasks/manual-todo.md`.
+     - If the result is `Fail` or `Blocked`, suggest follow-up routing: `$debug` for reproducible failures, `$guide` for external blockers, `$user-flow-map` from the product-design pack when acceptance criteria are unclear because journey flow, states, or recovery paths are underspecified, `$ux-variations --layout-mode` when the unresolved issue is layout alternatives, or `$uat-guide next` for the next journey. Apply the Pack Availability Guard before recommending a skill from another pack.
+
+## Output
+
+```markdown
+## UAT Guide: Journey N -- [Journey Name]
+
+**Target user**: [persona or role]
+**User goal**: [what the user is trying to accomplish]
+**Product surface**: [Web app | CLI | API | Hybrid]
+
+### Preparation
+
+- [Account, data, environment, or permission setup needed before starting]
+- [Pre-existing state or sample data to have ready]
+
+### Steps
+
+#### Step 1: [Task sequence step name]
+
+1. [Exact action -- click, type, run, send]
+2. [Next action with specific UI element / command / request detail]
+3. ...
+
+**Checkpoint**: [What the tester should see or verify]
+**Evidence**: [What to capture -- screenshot, output, response]
+**Gotchas**: [Common mistake or easy-to-miss detail, if any]
+
+#### Step 2: [Task sequence step name]
+
+1. ...
+
+...
+
+### Final Verification
+
+- [ ] [Acceptance criterion from the journey]
+- [ ] [Another acceptance criterion]
+- [ ] Expected success state: [observable user-visible result]
+
+### Non-Acceptance Signals
+
+- [Confusion, delay, missing affordance, incorrect result, trust issue, or blocker to watch for]
+
+### Tester Notes Prompt
+
+> [Question from the journey that captures whether the target user would accept this]
+
+---
+
+When you've completed this journey, let me know the result (Pass / Fail / Blocked) and any notes, and I'll update the result log.
+```
+
+## 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/uat-guide-{topic}.html`.
+
+## Constraints
+
+- **Always web search** for external services and platforms referenced in the journey when the active environment permits web access. Service UIs change; stale steps are worse than none.
+- **Project-specific values** -- never give generic placeholders when the codebase contains the actual values to use (URLs, routes, env vars, field names, commands).
+- **Read-only except result log** -- this skill does not modify code. The only files it may edit are `research/uat-plan.md` (result log section) and `tasks/manual-todo.md` (to check off a completed item), and only after the user reports completion.
+- **No shipping contract** -- updating a result log and checking off a manual-todo item is minor bookkeeping, not a code change. Do not auto-commit just for that. If other tracked changes are present, leave them for a proper shipping skill.
+- **One journey at a time** -- guide the user through one journey per invocation. They can run `$uat-guide next` for the next one.
+- **Don't execute the product** -- produce instructions for the user to follow. Do not start dev servers, launch browsers, call APIs, create accounts, or perform CLI workflows.
+- **Don't mark complete unprompted** -- only update the result log after the user explicitly reports the outcome.
+- **Don't invent acceptance criteria** -- use only the criteria defined in the UAT plan. If criteria are missing or unclear because flow, states, recovery, or handoff structure is underspecified, recommend `$user-flow-map` from the product-design pack; use `$ux-variations --layout-mode` only when the missing decision is layout alternatives.
+- **Handle all product surface types** -- web apps get click-by-click, CLIs get command-by-command, APIs get request-by-request, hybrids get mixed. Detect from codebase context; don't assume web.
+- **Prerequisite: UAT plan must exist** -- if `research/uat-plan.md` is missing, stop immediately and recommend `$uat` from the product-testing pack.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `$pack install <pack-name>` inside Codex, or `npx skillpacks install <pack-name>` from the project shell, to the recommendation.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/monorepo/PACK.md

@@ -34,14 +34,14 @@ scripts/pack.sh refresh
 
 ## Augmentation Injection Pattern
 
-This pack does not duplicate the global execution and shipping skills. It injects monorepo-aware pre/post steps around the existing contracts:
+This pack does not duplicate the base execution and shipping skills. It injects monorepo-aware pre/post steps around the existing contracts:
 
 - Pre-execution: run `mono-detect`, read the phase execution profile, generate lane specs when appropriate, and run `mono-guard` pre-flight.
 - Execution: keep root-only and cross-cutting steps serial in the main agent; dispatch only approved package-scoped lanes with disjoint `owns` paths and separate non-primary GitHub branches.
 - Post-integration: run consolidation/PR review, then `mono-guard` against the actual diff before package-scoped shipping.
 - Pre-ship: use `.agents/monorepo.json` and lane specs to run package and transitive-dependent validation before delegating to `/ship` or `$ship`.
 
-This differs from `*-kanban` packs, which intentionally provide workflow variants. The monorepo pack is an overlay that makes the normal skill pipeline workspace-aware while preserving the global skill contracts as the source of truth.
+This differs from `*-kanban` packs, which intentionally provide workflow variants. The monorepo pack is an overlay that makes the normal skill pipeline workspace-aware while preserving the base skill contracts as the source of truth.
 
 ## Package-Scope Tags
 

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

@@ -12,11 +12,11 @@ parent: mono-plan
 
 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.
+`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 base 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.
+`mono-detect` is the pack's detection foundation for the augmentation injection pattern. It does not replace `/exec`, `/ship`, or base 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
 
@@ -62,7 +62,7 @@ Use this skill to detect a pnpm workspace monorepo and generate the `.agents/mon
 - 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.
+- Treat `mono-detect` as an augmentation foundation for `mono-exec`, `mono-ship`, and `mono-guard`, not as a replacement for `/exec`, `/ship`, or base monorepo planning skills.
 
 ## Default Shipping Contract
 

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

@@ -19,7 +19,7 @@ Use this skill to execute planned work in a pnpm workspace monorepo with package
 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.
+The base `/exec` skill remains the source of truth for task selection, task docs, validation, history updates, commit/push, deploy handling, and next-step routing.
 
 ## Flags
 

package/packs/monorepo/claude/mono-guard/SKILL.md

@@ -10,7 +10,7 @@ argument-hint: "[--post-integration] [optional: lane-specs.json]"
 
 Use this skill to validate monorepo pack lane artifacts before parallel dispatch and to audit integrated lane changes after dispatch.
 
-This pack-local `mono-guard` consumes `.agents/lane-specs.json` and `.agents/monorepo.json`. It preserves behavioral compatibility with the global `/mono-guard` contract while using the monorepo pack's JSON artifacts and scripts as the project-local enforcement surface.
+This pack-local `mono-guard` consumes `.agents/lane-specs.json` and `.agents/monorepo.json`. It preserves behavioral compatibility with the base `/mono-guard` contract while using the monorepo pack's JSON artifacts and scripts as the project-local enforcement surface.
 
 ## Augmentation Injection Pattern
 
@@ -116,7 +116,7 @@ If `.agents/monorepo.json` is missing or stale, run `mono-detect` first. If `.ag
 - Do not run package manager install/add commands.
 - Do not modify `.agents/lane-specs.json` or `.agents/monorepo.json` except by invoking the designated generation/detection skills when appropriate.
 - Do not revert or repair post-integration changes; report violations only.
-- Keep behavior compatible with the global `/mono-guard` safety contract.
+- Keep behavior compatible with the base `/mono-guard` safety contract.
 
 ## Next-Step Routing
 

package/packs/monorepo/claude/mono-plan/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — mono-plan
 
-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.
+Alignment pages are optional for this operational skill. By default, report the outcome inline and write only the skill's normal durable artifacts (`tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Build `alignment/mono-plan-{topic}.html` only when the user explicitly requests an alignment page or when the agent explicitly identifies a concrete clarification/review need that cannot be resolved cleanly in conversation or the normal artifacts. When an alignment page is created, use the full contract below and a normalized topic slug derived from the app, feature, research subject, report subject, or output filename.
 
 **Visual rendering tier.** Each alignment page declares a rendering tier:
 - `document` (default) — text, tables, approval gates. No charts or interactive elements.
@@ -57,7 +57,9 @@ The tier is set per skill via `visual_tier` in SKILL.md frontmatter (or detected
 
 **Report-only research gates.** For report-only or pre-approval research skills, the first `review` alignment page must explicitly contain proposed research scope, source plan, assumptions/confidence, recommended output path, proposed file changes, and approval gates before synthesized research begins and before any working packet, canonical research, spec, or task file is created or updated.
 
-**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, and research-scope approval gates. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-mono-plan-research.md`; product-path mode uses `research/{slug}/_working/preliminary-mono-plan-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the full preliminary packet, evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+**Staged research workflow.** Heavy report-first research uses a scope-first three-stage approval workflow. Stage 1 is minimal scope discovery only: inspect enough repository, user, and source context to propose research scope, source plan, assumptions, output paths, and approval questions. Build the `review` alignment page before synthesized research. The page must render the proposed scope, available source categories, known context, assumptions/confidence, proposed working-packet and canonical output paths, research-scope approval gates, and a `Stage 2 Preview / Expected Review Format` section that shows the future Stage 2 review shape before research starts. Stop for final compiled response YAML approval of the research scope. Do not synthesize findings, rank candidates, recommend a path, or create working packets, canonical research, spec, or task files in Stage 1. Stage 2 starts only after final compiled response YAML approves the research scope with no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Perform the synthesized research, run required source/code checks, and write only a non-canonical working packet. Flat mode uses `research/_working/preliminary-mono-plan-research.md`; product-path mode uses `research/{slug}/_working/preliminary-mono-plan-research.md`. Existing raw evidence or search-log outputs may remain as supporting evidence when the skill contract already requires them, but synthesized deliverables stay in the working packet. Update the same `review` alignment page so it renders the complete working-packet substance as structured HTML review UI: purpose-built sections, tables, matrices, gates, cards, and tier-appropriate charts or diagrams that preserve every packet section, finding, caveat, and decision detail without summary loss. Raw Markdown packet text may appear only as a supplemental source view after the rendered review UI; do not make a `Full Preliminary Packet` or `Full Working Packet` raw Markdown dump, giant `<pre><code>` block, link-only view, or source-only view the primary review surface. Include the evidence matrix, assumptions/confidence register, source coverage gaps, proposed canonical file changes, and artifact approval gates. Partial compiled responses revise the working packet and review page, then remain in Stage 2. Stage 3 consumes final compiled response YAML for artifact approval only when it has `approval_status: ready-for-agent-review` and no unresolved `needs-clarification`, unresolved `down` feedback, or other unresolved negative feedback. Apply approved edits first, archive the working packet to `docs/history/archive/YYYY-MM-DD/HHMMSS/<original-working-path>`, remove the active working packet, write the approved canonical artifacts to the unchanged output paths, and convert the page to `confirmed` with the approval record preserved.
+
+**Stage 2 review-page template.** Stage 1 scope-review pages must include a `Stage 2 Preview / Expected Review Format` section that previews the exact section sequence, table shapes, evidence treatment, visual density, and approval gates the user will see after research; make it specific enough for the user to flag preferred content formats, grouping, labels, visuals, and evidence density before the agent does heavy research. After scope approval and research, the Stage 2 review page must include these sections as structured HTML, not as raw Markdown dumps: `Research Scope Approved` status block with approved scope, source plan, output paths, and unresolved caveats; `Executive Findings` or a skill-specific top-findings section with confidence labels; `Evidence Matrix` mapping claim, evidence/source/path, inference, confidence, assumptions, and decision impact; `Working Packet Review` with the complete working-packet substance rendered as purpose-built HTML sections, lists, tables, matrices, cards, and tier-appropriate charts or diagrams; `Alternatives / Rejected or Lower-Confidence Findings`; `Source Coverage & Gaps`; `Assumptions / Confidence Register`; `Proposed Canonical Artifacts & File Changes`; a required `User Format Preferences` gate asking whether the layout, tables, grouping, visuals, labels, and evidence density match expectations; and a required `Final Artifact Approval` gate for Stage 3 readiness. Raw Markdown packet text, search logs, or source notes may appear only as supplemental source views after the rendered review UI and never replace the Stage 2 review sections.
 
 **Required inline questions.** In `review` pages, 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. Confirmed pages must not keep these as required input controls; render the answered decisions as read-only records.
 

package/packs/monorepo/claude/mono-plan/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 2026-06-12
+
+- Made alignment pages optional by default: report inline and write the skill's normal durable artifacts unless the user requests an alignment page or the agent identifies a concrete clarification/review need.
+
 ## v0.0
 
 - Archived previous skill contract.

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

@@ -2,7 +2,7 @@
 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
+version: v0.2
 argument-hint: "<phase-number> [optional: path to roadmap if not tasks/roadmap.md]"
 ---
 
@@ -134,7 +134,7 @@ Run this **after** `/roadmap` sets `agent-team` or `implementation-safe` on a ph
 
 ## 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`.
+By default, this skill reports results inline and writes only its normal durable artifacts (for example `tasks/*.md`, reports, queues, benchmark notes, status docs, or other skill-specific files). Do not build an alignment page automatically. Create `alignment/mono-plan-{topic}.html` only when the user explicitly requests an alignment page or when you explicitly identify a concrete clarification/review need that cannot be handled cleanly inline; when you create one, follow `ALIGNMENT-PAGE.md` in this skill's directory.
 
 ## Constraints
 

package/packs/monorepo/claude/mono-plan/archive/v0.1/SKILL.md

@@ -0,0 +1,155 @@
+---
+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
+argument-hint: "<phase-number> [optional: path to roadmap if not tasks/roadmap.md]"
+---
+
+# Mono 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.md` must exist with at least one phase.
+- The project must be a monorepo (detected in step 1).
+
+## Process
+
+1. **Detect monorepo structure:**
+   - Check for `pnpm-workspace.yaml`, `turbo.json`, `lerna.json`, or `package.json` `workspaces` field.
+   - If none found, report "not a monorepo" and stop — this skill does not apply.
+   - Record the monorepo tool (pnpm workspaces, Turborepo, Lerna, npm workspaces).
+
+2. **Enumerate packages:**
+   - Parse the workspace config to list all packages and apps with their paths.
+   - Read each package's `package.json` to collect `name`, `dependencies`, and `devDependencies`.
+
+3. **Build internal dependency graph:**
+   - For each package, identify which other workspace packages it depends on.
+   - Compute a topological ordering. Flag cycles as errors.
+
+4. **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.
+
+5. **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.
+
+6. **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.
+
+7. **Recommend parallelization strategy:**
+   - If all packages are independent and GitHub branch/PR review is available → `agent-team` with one branch-backed lane per package.
+   - If linear dependency chain → `serial` or `implementation-safe` with ordered lanes.
+   - If mixed and GitHub branch/PR review is available → `agent-team` with 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`, or `serial`.
+
+8. **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 root `package.json`
+     - `Mode: write`
+     - `Depends on: none`
+     - `Scope:` "Install all dependencies needed by subsequent lanes. Do NOT implement features."
+   - **Package lanes (one per independent package or group):**
+     - `Owns: packages/<name>/` (or `apps/<name>/`)
+     - `Must not edit:` all lockfiles, all root configs, all paths owned by other lanes
+     - `Branch:` `agent-team/phase-N-<package-or-lane>`; never `main` or `master`
+     - `Mode: write`
+     - `Depends on:` Lane 0 (if it exists) + lanes for upstream internal dependencies
+     - `Scope:` 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 a `Mode: review` lane depending on all write lanes. Its scope must inspect every branch/PR, validate changed paths against `Owns` and `Must not edit`, record blocker/advisory findings, and approve only lanes safe to integrate.
+
+9. **Validate lane specs:**
+   - Every lockfile appears in `Must not edit` for ALL write lanes except the deps lane.
+   - `Owns` paths are disjoint across all lanes — no prefix overlaps.
+   - `Depends on` references are valid lane names with no cycles.
+   - No lane's `Scope` contains install/add commands (except the deps lane).
+
+## Output
+
+```markdown
+### 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
+
+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`.
+
+## 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-team` if the project cannot push lane branches to GitHub and review PRs; use `implementation-safe`, `research-only`, or `serial` instead.
+
+## 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.

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

@@ -21,7 +21,7 @@ Use this skill to ship completed work in a pnpm workspace monorepo only after pa
 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.
+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
 

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

@@ -1,5 +1,9 @@
 # scaffold changelog (claude)
 
+## v0.3 - 2026-06-12
+
+- Standardized active pack and skill install guidance on `npx skillpacks install <pack-or-skill>` instead of agent-native `/pack install` or `$pack install` recommendations.
+
 ## v0.2 - 2026-06-11
 
 - Added npm-aware pack install alternatives for new project root setup and early research shell routing.

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

@@ -2,7 +2,7 @@
 name: scaffold
 description: Generate a new package or app in the monorepo following established project conventions
 type: execution
-version: v0.2
+version: v0.3
 argument-hint: <type> <name> (e.g. "package utils" or "app admin-dashboard")
 ---
 
@@ -76,12 +76,12 @@ For product/app workflows, `/scaffold` is normally downstream of research, proto
 ## 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` inside Claude Code, or `npx skillpacks install business-discovery` from the project shell.
+- 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 `npx skillpacks install business-discovery` from the project shell.
 - 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.
+- Do not install domain packs as base skills; 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.

package/packs/monorepo/claude/scaffold/archive/v0.2/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.2
+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>` from this source checkout, or `npx skillpacks install <pack>` from the new project shell when using the published package, 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` inside Claude Code, or `npx skillpacks install business-discovery` from the project shell.
+- 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/mono-detect/SKILL.md

@@ -14,11 +14,11 @@ 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.
+`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 base 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.
+`mono-detect` is the pack's detection foundation for the augmentation injection pattern. It does not replace `$exec`, `$ship`, or base 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
 
@@ -64,7 +64,7 @@ Use this skill to detect a pnpm workspace monorepo and generate the `.agents/mon
 - 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.
+- Treat `mono-detect` as an augmentation foundation for `mono-exec`, `mono-ship`, and `mono-guard`, not as a replacement for `$exec`, `$ship`, or base monorepo planning skills.
 
 ## Default Shipping Contract
 

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

@@ -21,7 +21,7 @@ Use this skill to execute planned work in a pnpm workspace monorepo with package
 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.
+The base `$exec` skill remains the source of truth for task selection, task docs, validation, history updates, commit/push, deploy handling, and next-step routing.
 
 ## Flags
 

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

@@ -12,7 +12,7 @@ Invoke as `$mono-guard`.
 
 Use this skill to validate monorepo pack lane artifacts before parallel dispatch and to audit integrated lane changes after dispatch.
 
-This pack-local `mono-guard` consumes `.agents/lane-specs.json` and `.agents/monorepo.json`. It preserves behavioral compatibility with the global `$mono-guard` contract while using the monorepo pack's JSON artifacts and scripts as the project-local enforcement surface.
+This pack-local `mono-guard` consumes `.agents/lane-specs.json` and `.agents/monorepo.json`. It preserves behavioral compatibility with the base `$mono-guard` contract while using the monorepo pack's JSON artifacts and scripts as the project-local enforcement surface.
 
 ## Augmentation Injection Pattern
 
@@ -118,7 +118,7 @@ If `.agents/monorepo.json` is missing or stale, run `mono-detect` first. If `.ag
 - Do not run package manager install/add commands.
 - Do not modify `.agents/lane-specs.json` or `.agents/monorepo.json` except by invoking the designated generation/detection skills when appropriate.
 - Do not revert or repair post-integration changes; report violations only.
-- Keep behavior compatible with the global `$mono-guard` safety contract.
+- Keep behavior compatible with the base `$mono-guard` safety contract.
 
 ## Next-Step Routing