skillpacks 0.1.1 → 0.1.2

package/packs/repo-maintenance/codex/bootstrap-repo/archive/v0.4/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: bootstrap-repo
+description: Initialize or reset a repository README and agent workflow docs from a short project brief
+type: execution
+version: v0.4
+argument-hint: "<project brief>"
+---
+
+# Bootstrap Repo
+
+Invoke as `$bootstrap-repo`.
+
+Initialize a repository with a useful `README.md` and the standard agent workflow docs. When invoked with `--reset-existing`, first archive stale implementation and documentation files from a non-empty stuck repo so the fresh start is not built on old code or old assumptions by accident.
+
+## Process
+
+1. **Parse the project brief and mode** from `$ARGUMENTS`:
+   - Detect `--reset-existing`, `--in-place-reset`, or an explicit request to archive/reset the current codebase before bootstrap.
+   - Extract the project name, purpose, setup instructions, run/test commands, and any constraints.
+   - If the brief is missing or too thin to write a useful README, ask for the project name and one-sentence purpose. Ask for setup or run instructions only when the repository does not make them discoverable.
+
+2. **Inspect the target repository:**
+   - Read existing `README.md`, `CLAUDE.md`, `AGENTS.md`, package manifests, obvious build files, and directory names.
+   - Preserve discovered commands and facts. Do not invent dependency managers, deployment targets, or product claims.
+
+3. **Reset existing stale repo when explicitly requested:**
+   - Only perform this step when reset mode is explicit. Never archive or move files during ordinary bootstrap.
+   - Confirm the repo is non-empty and contains stale implementation, docs, research, specs, task files, design notes, or generated app structure. If it is already empty or freshly initialized, skip archival and note why.
+   - Create `archive/YYYY-MM-DD-HHMMSS/` and move stale implementation and documentation files/directories there before writing fresh bootstrap docs.
+   - Archive old docs by default, including `docs/`, `alignment/`, `research/`, `specs/`, `tasks/`, planning reports, implementation notes, design docs, old README content, and prior roadmap/todo/history files. These may remain useful as historical evidence in the archive, but they must not stay active as source-of-truth inputs.
+   - Do not archive `.git/`, `.agents/`, `archive/`, `desk-flip-report.md`, root agent config files needed for the current session, or the newly written high-level concept artifact.
+   - Preserve exactly one active concept seed, such as `concept.md` or `README.md` `## Concept`, derived from the bootstrap brief or `desk-flip-report.md`. Keep it high level: product name, target user, core problem, value proposition, non-goals, and open questions. Do not preserve old research/spec detail as active files.
+   - Preserve a manifest at `archive/YYYY-MM-DD-HHMMSS/MANIFEST.md` listing every moved path, every intentionally preserved path, and the high-level concept source that justified the reset.
+   - Prefer `git mv` for tracked paths so history remains understandable. Use ordinary moves only for untracked paths.
+   - Do not delete old files outright. If a path cannot be moved safely, stop and report the blocker instead of partially resetting further.
+   - After archival, the root should contain only the fresh-start sources of truth: git metadata, agent config, the archive directory, `desk-flip-report.md`, the high-level concept artifact, and any newly written bootstrap docs. Old docs/research/specs belong in the archive.
+
+4. **Create or update `README.md`:**
+   - If `README.md` is absent, empty, or placeholder-like, write a concise README with:
+     - `# <Project Name>`
+     - A short purpose summary.
+     - `## Getting Started`
+     - `## Development`
+     - `## Notes`
+   - If `README.md` already has substantial content, preserve it. Ask before replacing it; otherwise add a small bootstrap section only when it improves the file.
+   - Use the project brief as the primary source and repository inspection as supporting evidence.
+
+5. **Provision agent workflow docs:**
+   - Run `$provision-agentic-config` for the same repository.
+   - Confirm `CLAUDE.md` and `AGENTS.md` exist after provisioning.
+   - Preserve unrelated existing content in both files.
+
+6. **Verify the result:**
+   - Check that `README.md`, `CLAUDE.md`, and `AGENTS.md` exist.
+   - Confirm the corresponding workflow orchestration block appears exactly once in each of `CLAUDE.md` and `AGENTS.md`.
+   - Report whether the monorepo safety block was included or skipped by `$provision-agentic-config`.
+   - In reset mode, check that `archive/YYYY-MM-DD-HHMMSS/MANIFEST.md` exists and lists moved and preserved paths, and verify old docs/research/specs/tasks were archived rather than left active.
+
+7. **Route research-first after product bootstrap:**
+   - If this is a product, app, SaaS, dashboard, internal tool, marketplace, website, or other user-facing restart, rebuild market and lifecycle alignment from the high-level concept before UI requirements or prototypes.
+   - Check `.agents/project.json.enabled_packs` when present. If `business-research` is not enabled, recommend `npx skillpacks install business-research` from the project shell, before `$customer-discovery`. If `customer-lifecycle` is not enabled, include `npx skillpacks install customer-lifecycle` before `$journey-map`.
+   - When required packs are available, recommend `$customer-discovery <concept>` as the next command. After `$customer-discovery`, the intended sequence is `$competitive-analysis` -> `$journey-map` -> `$positioning` -> `$user-flow-map` -> `$ui-interview --requirements-only` -> `$ux-variations --layout-mode` -> prototype work.
+   - If current, accepted `research/icp.md`, `research/competitive-analysis.md`, and `research/journey-map.md` already exist from the fresh reset but positioning is missing, then recommend `$positioning <topic>`.
+   - If positioning exists but a flow map is missing, recommend `$user-flow-map <topic>`.
+   - If a flow map exists but UI requirements are missing, recommend `$ui-interview --requirements-only <topic>`.
+   - If UI requirements exist but layout variations are missing, recommend `$ux-variations --layout-mode <topic>`.
+   - Only route directly to `$roadmap` or `$exec` when the project is non-UI/non-product work or already has accepted alignment artifacts and a consolidated prototype.
+   - The intended product sequence after reset is: `$customer-discovery` -> `$competitive-analysis` -> `$journey-map` -> `$positioning` -> `$user-flow-map` -> `$ui-interview --requirements-only` -> `$ux-variations --layout-mode` -> build variants/prototypes via `$exec` or the applicable prototype-building route -> `$uat --variant-evaluation` -> `$consolidate-variations` -> `$research-roadmap --post-prototype` -> `$spec-interview` or `$roadmap`.
+
+## Output
+
+```markdown
+Bootstrapped repository
+- README.md: [created | updated | preserved], source: [arguments | prompts | existing content]
+- Reset archive: [created archive/YYYY-MM-DD-HHMMSS | skipped (<reason>)]
+- Active concept seed: [concept.md | README.md ## Concept | other]
+- CLAUDE.md: [created | updated | unchanged], corresponding workflow block appears once
+- AGENTS.md: [created | updated | unchanged], corresponding workflow block appears once
+- Monorepo safety block: [included (<heuristic>) | skipped]
+- Verification: [commands/checks run]
+- Recommended next command: [npx skillpacks install business-research | npx skillpacks install customer-lifecycle | npx skillpacks install product-design | $customer-discovery <concept> | $positioning <topic> | $user-flow-map <topic> | $ui-interview --requirements-only <topic> | $ux-variations --layout-mode <topic> | $roadmap | $exec]
+```
+
+## Constraints
+
+- Do not overwrite substantial existing `README.md` content without explicit user confirmation.
+- Do not invent setup, test, deploy, or architecture details that are not in the brief or repository.
+- Keep the README concise and useful for a new contributor.
+- Do not modify files other than `README.md`, `CLAUDE.md`, and `AGENTS.md` unless the user explicitly asks or invokes reset mode.
+- Reset mode may move stale files, including old docs/research/specs/tasks, into `archive/YYYY-MM-DD-HHMMSS/` and write that archive's `MANIFEST.md`; it may not delete files outright.
+- In reset mode, do not preserve old docs as active files just because they were marked salvageable. Use them only as archived historical evidence; active research and requirements restart from the high-level concept.
+- Do not create, modify, or suggest GitHub Actions workflows.
+
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/report-gen/claude/report-website/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-report-website-research.md`; product-path mode uses `research/{slug}/_working/preliminary-report-website-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-report-website-research.md`; product-path mode uses `research/{slug}/_working/preliminary-report-website-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/report-gen/codex/report-website/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-report-website-research.md`; product-path mode uses `research/{slug}/_working/preliminary-report-website-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-report-website-research.md`; product-path mode uses `research/{slug}/_working/preliminary-report-website-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/research-admin/claude/research-roadmap/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — research-roadmap
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/research-roadmap-{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/research-roadmap-{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-research-roadmap-research.md`; product-path mode uses `research/{slug}/_working/preliminary-research-roadmap-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-research-roadmap-research.md`; product-path mode uses `research/{slug}/_working/preliminary-research-roadmap-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.
 
 **Research-roadmap translation.** Render repository/documentation evidence by file path, observed documentation facts, inferred research gaps, priority rationale, rejected lower-priority items, source coverage gaps, and downstream implications for the next skill route.
 

package/packs/research-admin/claude/research-roadmap/CHANGELOG.md

@@ -1,5 +1,13 @@
 # research-roadmap changelog (claude)
 
+## v0.18 - 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.17 - 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.16 - 2026-06-10
 
 - Converted the hand-authored alignment-page section to the generator-owned stub plus a bundled `ALIGNMENT-PAGE.md`; the page contract now follows the full shared convention (lifecycle states, central alignment index, section feedback, gate/feedback YAML, TTS, browser open) with the research-roadmap-specific gates from the generator gate map.

package/packs/research-admin/claude/research-roadmap/SKILL.md

@@ -2,13 +2,13 @@
 name: research-roadmap
 description: Scan research and documentation health, then maintain a priority documentation queue
 type: planning
-version: v0.16
+version: v0.18
 invocation: orchestrator
 ---
 
 ## 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>` instead of 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>` instead of 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.
 
 # Research Roadmap - Documentation Queue Manager
 
@@ -55,7 +55,7 @@ Otherwise, continue with the standard process starting at step 1.
    - devtool: SDK, CLI, API, library, infra, docs, examples, or package-first developer workflow
    - business-app: SaaS, marketplace, productivity, workflow, enterprise, or user-facing app
 4. If the project type cannot be inferred, default to `business-app`.
-5. If an expected pack is not installed, add a priority todo for `/pack install <pack>` before pack-specific research todos.
+5. If an expected pack is not installed, add a priority todo for `npx skillpacks install <pack>` before pack-specific research todos.
 
 ### 2. Resolve Documentation Roots
 
@@ -219,7 +219,7 @@ Order immediately actionable todo items so the user can complete documentation w
 8. Missing or stale roadmap/task docs.
 9. Reconciliation items when conflicting docs are detected.
 
-Within research items, use this dependency order when relevant. When emitting queued commands for pack-based skills, apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, queue `/pack install <pack>` before the skill:
+Within research items, use this dependency order when relevant. When emitting queued commands for pack-based skills, apply the Pack Availability Guard — if the target skill's pack is not in `.agents/project.json` `enabled_packs`, queue `npx skillpacks install <pack>` before the skill:
 
 When `research/.progress.yaml` exists, show per-path pipeline progress alongside the priority queue. For each path in `active_paths`, show its `pipeline_stage` and queue the next missing research step. For `deferred` or `revisit_candidate` paths, add a concise record or queue note with the `revisit_trigger` and `next_skill` rather than scheduling full downstream research. When 3+ deferred paths accumulate with no recent activation, add `/product-line review` as a priority queue item to prompt portfolio review.
 
@@ -438,7 +438,7 @@ Populate `tasks/todo.md` `## Priority Documentation Todo` with research skills t
 
 ## 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/research-roadmap-{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/research-roadmap-{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.
 
 ## Default Shipping Contract