skillpacks 0.1.1 → 0.1.2

package/packs/gitops/codex/sync/archive/v0.4/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: sync
+description: Pull latest changes from remote and report status
+type: shipping
+version: v0.4
+---
+
+# Sync
+
+Invoke as `$sync`.
+
+Pull the latest changes from the remote repository and report status.
+
+## Process
+
+1. Check current state:
+   - Run `git status` to check for uncommitted changes.
+   - If there are uncommitted changes, stash them first, pull, then pop the stash. Warn the user about the stash.
+2. Pull from remote:
+   - Run `git pull --rebase origin <current-branch>`.
+   - If rebase conflicts occur, abort the rebase, try `git pull --no-rebase` instead, and report any merge conflicts for the user to resolve.
+3. Check for outstanding work:
+   - Check if `tasks/roadmap.md` exists for the full plan, and `tasks/todo.md` for the current phase.
+   - If `tasks/todo.md` exists, read it and look for unchecked items (`- [ ]`).
+   - If there are incomplete items, summarise: which phase is current, what the next step is, and how many steps/phases remain.
+   - If `tasks/manual-todo.md` exists, count unchecked manual tasks and include in the summary.
+   - If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items and include those counts separately. Do not treat them as active plan steps.
+   - If all items are checked, report that the plan is complete.
+   - If neither file exists, note that there is no active plan.
+4. Check provisioned agent config:
+   - If `CLAUDE.md` or `AGENTS.md` contains `<!-- provision-agentic-config vX.Y -->`, extract the version.
+   - Read the canonical `provision-agentic-config` skill from the first existing path in this order:
+     1. `~/.codex/skills/provision-agentic-config/SKILL.md`
+     2. `~/.claude/skills/provision-agentic-config/SKILL.md`
+     3. `base/codex/provision-agentic-config/SKILL.md` in the current repo, when present
+     4. `base/claude/provision-agentic-config/SKILL.md` in the current repo, when present
+   - Extract the `version:` field from the canonical skill's YAML frontmatter.
+   - Extract the canonical provisioned blocks from the same skill:
+     - `CLAUDE.md`: the fenced block under `Required Claude Block` or the section that says "The Claude block to insert into `./CLAUDE.md`".
+     - `AGENTS.md`: the fenced block under `Required AGENTS Block` or the section that says "The AGENTS block to insert into `./AGENTS.md`".
+   - Compare each existing project file against its corresponding canonical block after normalizing line endings and trimming only leading/trailing whitespace around the block. Do not ignore changed bullets, headings, command examples, or policy text.
+   - If the installed skill version is newer than the provisioned version in either file, warn: `⚠ CLAUDE.md provisioned with vX.Y but provision-agentic-config is at vX.Y — consider re-running $provision-agentic-config`
+   - If the version comment is missing from `CLAUDE.md` or `AGENTS.md`, note: `ℹ No provision version found in CLAUDE.md/AGENTS.md — run $provision-agentic-config to add version tracking`
+   - If a project file has the current version comment but the provisioned block content differs from the canonical block, warn: `⚠ CLAUDE.md provisioned block differs from the canonical provision-agentic-config vX.Y block — re-run $provision-agentic-config`
+   - If a canonical block cannot be extracted, fall back to the version-only check and note: `ℹ Could not extract canonical provision-agentic-config block; checked version comment only`
+   - If none of the canonical skill files exists, skip this check silently.
+   - Always report the local canonical source path used and its `version:` field when this check runs.
+5. Check skill-install drift (track-latest):
+   - Project-local pack/skill installs under `.claude/skills` and `.codex/skills` are managed copies stamped with `.agentic-skills-managed`, which now records `source_version` and `source_sha`. When canonical sources in the `agentic-skills` checkout move ahead, the installed copies fall behind.
+   - Resolve the `agentic-skills` checkout from any install marker's `source=` path (the parent above `.../packs/..` or `.../base/..` is the repo root). If no managed install exists or the checkout cannot be resolved, skip this check silently.
+   - Run `scripts/pack.sh doctor` from the project root using that checkout (read-only; it never mutates installs).
+   - Fold any `stale` skills into the Report status block with the fix command `scripts/pack.sh refresh`. Report `unknown` skills as "run `scripts/pack.sh refresh` to enable drift tracking" and leave `pinned` skills noted as frozen.
+   - Must not mutate. Plain `$sync` only warns; it never runs `refresh`, re-copies, or otherwise changes installs. Direct the user to `scripts/pack.sh refresh` (or enable auto-refresh) for the actual update.
+6. Resolve GitHub freshness preference:
+   - Use the user-local machine-wide preference file at `~/.agentic-skills/preferences.json`.
+   - Read `sync.github_freshness_check`, whose only allowed values are `"ask"`, `"always"`, and `"never"`.
+   - If the file or key is missing, ask the user once which default to remember:
+     - Always check GitHub during sync
+     - Never check GitHub during sync
+     - Ask each time
+   - Create `~/.agentic-skills/preferences.json` if needed and save the selected value as:
+     ```json
+     {
+       "sync": {
+         "github_freshness_check": "ask"
+       }
+     }
+     ```
+   - If the value is `"always"`, check GitHub remote freshness automatically.
+   - If the value is `"never"`, skip GitHub freshness checks and report that local canonical `provision-agentic-config` was used without a GitHub check.
+   - If the value is `"ask"`, ask before checking GitHub for this sync.
+   - Treat malformed JSON or an unsupported value as missing preference and ask again before writing one of the allowed values.
+7. Optional GitHub freshness check:
+   - Only run this check when the resolved preference or explicit user approval says to check GitHub.
+   - Compare the local `agentic-skills` checkout against `origin/HEAD` using non-mutating commands such as `git remote get-url origin`, `git rev-parse HEAD`, `git rev-parse origin/HEAD`, and, when remote freshness is explicitly enabled, `git fetch --dry-run` or an equivalent non-mutating freshness probe.
+   - Report the local checkout commit, remote URL, local `origin/HEAD` commit if available, and whether the local checkout appears behind the remote.
+   - Do not pull, fast-forward, rebase, install, or mutate the checkout from plain `$sync`.
+   - If a GitHub check shows the local checkout is stale, recommend `$init-agentic-skills update` for an explicit update.
+8. Report status:
+   - Branch name
+   - Commits pulled (if any) — show short log of new commits
+   - Whether stashed changes were re-applied
+   - Any conflicts that need manual resolution
+   - Current `git status`
+   - **Agent config drift** — provisioning version, local canonical source path/version, and canonical block match/drift status for `CLAUDE.md` and `AGENTS.md`, if checked
+   - **Skill-install drift** — any `stale` project skill installs (with `vOld → vNew`), `unknown` installs needing a refresh to enable tracking, and the `scripts/pack.sh refresh` fix command; report "all installs current" when none are stale, or skip the line when no managed installs exist
+   - **GitHub freshness** — preference value, whether GitHub was checked, and the local checkout/remote status; when skipped, say local canonical was used
+   - **Outstanding work** — summary from step 3 (next step, current phase, remaining work, pending manual tasks) or "No active plan"
+   - **Advisory tasks** — pending record/recurring counts, if those files exist
+9. Post-sync actions:
+   a) Check if `sync.md` exists at the project root.
+   b) **If `sync.md` exists** — parse and execute it:
+      - Read `sync.md` and identify sections by H2 headings.
+      - **Dependencies** (aliases: "Deps", "Dependency Management"): Execute shell commands in fenced code blocks. Report output briefly.
+      - **Conflict Resolution** (aliases: "Conflicts"): If the pull introduced merge conflicts (from step 2), apply the guidance in this section. If no conflicts, skip silently.
+      - **Custom** (aliases: "Project-Specific", "Scripts", "Setup"): Execute shell commands in fenced code blocks in order. Report output briefly.
+      - **Notifications** (aliases: "Awareness", "Alerts", "Watch"): For each bullet, check if the mentioned file/directory was modified in pulled commits (`git diff --name-only` against pre-pull HEAD). If any match, print a prominent alert.
+      - Unrecognised headings: skip with a note.
+      - Report a summary of all post-sync actions taken.
+   c) **If `sync.md` does not exist** — suggest creating one:
+      - Analyse the project to detect: package manager (look for lockfiles), common scripts (package.json, Makefile, Justfile), config templates (.env.example, docker-compose.yml).
+      - Present a suggested `sync.md` following the format below.
+      - Ask: "Would you like me to create this `sync.md`?"
+      - **Only create the file if the user approves.**
+
+## sync.md format
+
+The `sync.md` file lives at the project root. H2 sections are categories. Shell commands go in fenced code blocks; prose guidance goes in bullet points.
+
+```markdown
+# Post-Sync Actions
+
+## Dependencies
+
+```sh
+npm install
+```
+
+## Conflict Resolution
+
+- Always accept theirs for `package-lock.json`
+
+## Custom
+
+```sh
+npm run codegen
+```
+
+## Notifications
+
+- `.env.example` — check for new environment variables
+- `CLAUDE.md` — review if project conventions were updated
+```
+
+## Constraints
+
+- Do not force-push or rewrite history.
+- Do not auto-resolve merge conflicts — report them and let the user decide. However, if `sync.md` has a Conflict Resolution section, follow its guidance for the specific files/patterns it covers.
+- If stash pop fails due to conflicts, leave the stash intact and report it.
+- Post-sync commands from `sync.md` run in the project root directory.
+- If any post-sync command fails, report the error and continue with remaining actions.
+- Never auto-create `sync.md` without explicit user approval.
+- Do not execute commented-out sections (`<!-- ... -->`).
+- Plain `$sync` must not update the `agentic-skills` checkout, pull from GitHub for the local canonical source, or reinstall skills. Only `$init-agentic-skills update` / `$init-agentic-skills latest` may perform that explicit update flow after confirmation.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/gitops/codex/sync/archive/v0.5/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: sync
+description: Pull latest changes from remote and report status
+type: shipping
+version: v0.5
+---
+
+# Sync
+
+Invoke as `$sync`.
+
+Pull the latest changes from the remote repository and report status.
+
+## Process
+
+1. Check current state:
+   - Run `git status` to check for uncommitted changes.
+   - If there are uncommitted changes, stash them first, pull, then pop the stash. Warn the user about the stash.
+2. Pull from remote:
+   - Run `git pull --rebase origin <current-branch>`.
+   - If rebase conflicts occur, abort the rebase, try `git pull --no-rebase` instead, and report any merge conflicts for the user to resolve.
+3. Check for outstanding work:
+   - Check if `tasks/roadmap.md` exists for the full plan, and `tasks/todo.md` for the current phase.
+   - If `tasks/todo.md` exists, read it and look for unchecked items (`- [ ]`).
+   - If there are incomplete items, summarise: which phase is current, what the next step is, and how many steps/phases remain.
+   - If `tasks/manual-todo.md` exists, count unchecked manual tasks and include in the summary.
+   - If `tasks/record-todo.md` or `tasks/recurring-todo.md` exists, count unchecked advisory items and include those counts separately. Do not treat them as active plan steps.
+   - If all items are checked, report that the plan is complete.
+   - If neither file exists, note that there is no active plan.
+4. Check provisioned agent config:
+   - If `CLAUDE.md` or `AGENTS.md` contains `<!-- provision-agentic-config vX.Y -->`, extract the version.
+   - Read the canonical `provision-agentic-config` skill from the first existing path in this order:
+     1. `~/.codex/skills/provision-agentic-config/SKILL.md`
+     2. `~/.claude/skills/provision-agentic-config/SKILL.md`
+     3. `base/codex/provision-agentic-config/SKILL.md` in the current repo, when present
+     4. `base/claude/provision-agentic-config/SKILL.md` in the current repo, when present
+   - Extract the `version:` field from the canonical skill's YAML frontmatter.
+   - Extract the canonical provisioned blocks from the same skill:
+     - `CLAUDE.md`: the fenced block under `Required Claude Block` or the section that says "The Claude block to insert into `./CLAUDE.md`".
+     - `AGENTS.md`: the fenced block under `Required AGENTS Block` or the section that says "The AGENTS block to insert into `./AGENTS.md`".
+   - Compare each existing project file against its corresponding canonical block after normalizing line endings and trimming only leading/trailing whitespace around the block. Do not ignore changed bullets, headings, command examples, or policy text.
+   - If the installed skill version is newer than the provisioned version in either file, warn: `⚠ CLAUDE.md provisioned with vX.Y but provision-agentic-config is at vX.Y — consider re-running $provision-agentic-config`
+   - If the version comment is missing from `CLAUDE.md` or `AGENTS.md`, note: `ℹ No provision version found in CLAUDE.md/AGENTS.md — run $provision-agentic-config to add version tracking`
+   - If a project file has the current version comment but the provisioned block content differs from the canonical block, warn: `⚠ CLAUDE.md provisioned block differs from the canonical provision-agentic-config vX.Y block — re-run $provision-agentic-config`
+   - If a canonical block cannot be extracted, fall back to the version-only check and note: `ℹ Could not extract canonical provision-agentic-config block; checked version comment only`
+   - If none of the canonical skill files exists, skip this check silently.
+   - Always report the local canonical source path used and its `version:` field when this check runs.
+5. Check skill-install drift (track-latest):
+   - Project-local pack/skill installs under `.claude/skills` and `.codex/skills` are managed copies stamped with `.agentic-skills-managed`, which now records `source_version` and `source_sha`. When canonical sources in the `agentic-skills` checkout move ahead, the installed copies fall behind.
+   - Resolve the `agentic-skills` checkout from any install marker's `source=` path (the parent above `.../packs/..` or `.../base/..` is the repo root). If no managed install exists or the checkout cannot be resolved, skip this check silently.
+   - Run `scripts/pack.sh doctor` from the project root using that checkout (read-only; it never mutates installs).
+   - Fold any `stale` skills into the Report status block and surface the exact refresh command the doctor itself reported (the context-aware dual hint). Prefer `npx skillpacks refresh` when the resolved managing source is the published npx `skillpacks` package (the marker `source=` path has no `.git`); use `scripts/pack.sh refresh` run from the resolved source-checkout root otherwise. Report `unknown` skills as "run the doctor-reported refresh command to enable drift tracking" with the same npx-vs-checkout choice, and leave `pinned` skills noted as frozen. Do not print a bare `scripts/pack.sh refresh`, which will not resolve from a non-checkout project directory.
+   - Must not mutate. Plain `$sync` only warns; it never runs `refresh`, re-copies, or otherwise changes installs. Direct the user to the doctor-reported refresh command — `npx skillpacks refresh` for installs managed by the published npx package, or `scripts/pack.sh refresh` run from the source checkout (or enable auto-refresh) — for the actual update.
+6. Resolve GitHub freshness preference:
+   - Use the user-local machine-wide preference file at `~/.agentic-skills/preferences.json`.
+   - Read `sync.github_freshness_check`, whose only allowed values are `"ask"`, `"always"`, and `"never"`.
+   - If the file or key is missing, ask the user once which default to remember:
+     - Always check GitHub during sync
+     - Never check GitHub during sync
+     - Ask each time
+   - Create `~/.agentic-skills/preferences.json` if needed and save the selected value as:
+     ```json
+     {
+       "sync": {
+         "github_freshness_check": "ask"
+       }
+     }
+     ```
+   - If the value is `"always"`, check GitHub remote freshness automatically.
+   - If the value is `"never"`, skip GitHub freshness checks and report that local canonical `provision-agentic-config` was used without a GitHub check.
+   - If the value is `"ask"`, ask before checking GitHub for this sync.
+   - Treat malformed JSON or an unsupported value as missing preference and ask again before writing one of the allowed values.
+7. Optional GitHub freshness check:
+   - Only run this check when the resolved preference or explicit user approval says to check GitHub.
+   - Compare the local `agentic-skills` checkout against `origin/HEAD` using non-mutating commands such as `git remote get-url origin`, `git rev-parse HEAD`, `git rev-parse origin/HEAD`, and, when remote freshness is explicitly enabled, `git fetch --dry-run` or an equivalent non-mutating freshness probe.
+   - Report the local checkout commit, remote URL, local `origin/HEAD` commit if available, and whether the local checkout appears behind the remote.
+   - Do not pull, fast-forward, rebase, install, or mutate the checkout from plain `$sync`.
+   - If a GitHub check shows the local checkout is stale, recommend `$init-agentic-skills update` for an explicit update.
+8. Report status:
+   - Branch name
+   - Commits pulled (if any) — show short log of new commits
+   - Whether stashed changes were re-applied
+   - Any conflicts that need manual resolution
+   - Current `git status`
+   - **Agent config drift** — provisioning version, local canonical source path/version, and canonical block match/drift status for `CLAUDE.md` and `AGENTS.md`, if checked
+   - **Skill-install drift** — any `stale` project skill installs (with `vOld → vNew`), `unknown` installs needing a refresh to enable tracking, and the doctor-reported refresh command (`npx skillpacks refresh`, or `scripts/pack.sh refresh` from a source checkout); report "all installs current" when none are stale, or skip the line when no managed installs exist
+   - **GitHub freshness** — preference value, whether GitHub was checked, and the local checkout/remote status; when skipped, say local canonical was used
+   - **Outstanding work** — summary from step 3 (next step, current phase, remaining work, pending manual tasks) or "No active plan"
+   - **Advisory tasks** — pending record/recurring counts, if those files exist
+9. Post-sync actions:
+   a) Check if `sync.md` exists at the project root.
+   b) **If `sync.md` exists** — parse and execute it:
+      - Read `sync.md` and identify sections by H2 headings.
+      - **Dependencies** (aliases: "Deps", "Dependency Management"): Execute shell commands in fenced code blocks. Report output briefly.
+      - **Conflict Resolution** (aliases: "Conflicts"): If the pull introduced merge conflicts (from step 2), apply the guidance in this section. If no conflicts, skip silently.
+      - **Custom** (aliases: "Project-Specific", "Scripts", "Setup"): Execute shell commands in fenced code blocks in order. Report output briefly.
+      - **Notifications** (aliases: "Awareness", "Alerts", "Watch"): For each bullet, check if the mentioned file/directory was modified in pulled commits (`git diff --name-only` against pre-pull HEAD). If any match, print a prominent alert.
+      - Unrecognised headings: skip with a note.
+      - Report a summary of all post-sync actions taken.
+   c) **If `sync.md` does not exist** — suggest creating one:
+      - Analyse the project to detect: package manager (look for lockfiles), common scripts (package.json, Makefile, Justfile), config templates (.env.example, docker-compose.yml).
+      - Present a suggested `sync.md` following the format below.
+      - Ask: "Would you like me to create this `sync.md`?"
+      - **Only create the file if the user approves.**
+
+## sync.md format
+
+The `sync.md` file lives at the project root. H2 sections are categories. Shell commands go in fenced code blocks; prose guidance goes in bullet points.
+
+```markdown
+# Post-Sync Actions
+
+## Dependencies
+
+```sh
+npm install
+```
+
+## Conflict Resolution
+
+- Always accept theirs for `package-lock.json`
+
+## Custom
+
+```sh
+npm run codegen
+```
+
+## Notifications
+
+- `.env.example` — check for new environment variables
+- `CLAUDE.md` — review if project conventions were updated
+```
+
+## Constraints
+
+- Do not force-push or rewrite history.
+- Do not auto-resolve merge conflicts — report them and let the user decide. However, if `sync.md` has a Conflict Resolution section, follow its guidance for the specific files/patterns it covers.
+- If stash pop fails due to conflicts, leave the stash intact and report it.
+- Post-sync commands from `sync.md` run in the project root directory.
+- If any post-sync command fails, report the error and continue with remaining actions.
+- Never auto-create `sync.md` without explicit user approval.
+- Do not execute commented-out sections (`<!-- ... -->`).
+- Plain `$sync` must not update the `agentic-skills` checkout, pull from GitHub for the local canonical source, or reinstall skills. Only `$init-agentic-skills update` / `$init-agentic-skills latest` may perform that explicit update flow after confirmation.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/guided-walkthrough/claude/uat-guide/ALIGNMENT-PAGE.md

@@ -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-uat-guide-research.md`; product-path mode uses `research/{slug}/_working/preliminary-uat-guide-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-uat-guide-research.md`; product-path mode uses `research/{slug}/_working/preliminary-uat-guide-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.
 
 **Prototype tier rendering.** This skill's alignment page uses the `prototype` tier. In addition to charts and diagrams, functional interactive components (clickable flows, live CSS previews, drag interactions) are permitted. Prototypes are ephemeral previews, not production code. Each interactive component must include a reset button that restores initial state. Interactive components must be self-contained within the HTML file with no external dependencies. Include all visual tier requirements (chart snippets, table fallbacks, aria-labels, toggles) plus: state isolation (no localStorage/sessionStorage persistence), clear "this is a preview" labeling, and graceful degradation when JavaScript is disabled.
 

package/packs/guided-walkthrough/claude/uat-guide/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.5 - 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.4 - 2026-06-11
 
 - Added npm-aware Pack Availability Guard wording while preserving Claude `/pack install` routing.

package/packs/guided-walkthrough/claude/uat-guide/SKILL.md

@@ -2,14 +2,14 @@
 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
+version: v0.5
 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 Claude Code, 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.
+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 `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
 
@@ -134,7 +134,7 @@ When this skill produces durable deliverables (research, specs, plans, reports,
 - **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` (product-design pack); use `/ux-variations --layout-mode` (product-design pack) 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` (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 Claude Code, or `npx skillpacks install <pack-name>` from the project shell, to the recommendation.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `npx skillpacks install <pack-name>` from the project shell, to the recommendation.
 
 ## Default Shipping Contract
 

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

@@ -0,0 +1,141 @@
+---
+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 Claude Code, 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` (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`, `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.
+
+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` (product-design pack) when acceptance criteria are unclear because journey flow, states, or recovery paths are underspecified, `/ux-variations --layout-mode` (product-design pack) when the unresolved issue is layout alternatives, or `/uat-guide [next]` for the next journey.
+
+## Output
+
+```
+## 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. 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` (product-design pack); use `/ux-variations --layout-mode` (product-design pack) 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` (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 Claude Code, 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/guided-walkthrough/codex/uat-guide/ALIGNMENT-PAGE.md

@@ -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-uat-guide-research.md`; product-path mode uses `research/{slug}/_working/preliminary-uat-guide-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-uat-guide-research.md`; product-path mode uses `research/{slug}/_working/preliminary-uat-guide-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.
 
 **Prototype tier rendering.** This skill's alignment page uses the `prototype` tier. In addition to charts and diagrams, functional interactive components (clickable flows, live CSS previews, drag interactions) are permitted. Prototypes are ephemeral previews, not production code. Each interactive component must include a reset button that restores initial state. Interactive components must be self-contained within the HTML file with no external dependencies. Include all visual tier requirements (chart snippets, table fallbacks, aria-labels, toggles) plus: state isolation (no localStorage/sessionStorage persistence), clear "this is a preview" labeling, and graceful degradation when JavaScript is disabled.
 

package/packs/guided-walkthrough/codex/uat-guide/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.5 - 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.4 - 2026-06-11
 
 - Added npm-aware Pack Availability Guard wording while preserving Codex `$pack install` routing.

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

@@ -2,14 +2,14 @@
 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
+version: v0.5
 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.
+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 `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
 
@@ -135,7 +135,7 @@ When this skill produces durable deliverables (research, specs, plans, reports,
 - **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.
+- When recommending a skill from another pack, verify the pack is installed via `.agents/project.json` `enabled_packs`. If not installed, prepend `npx skillpacks install <pack-name>` from the project shell, to the recommendation.
 
 ## Default Shipping Contract