skillpacks 0.1.1 → 0.1.2

package/packs/release-ops/claude/release/archive/v0.1/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: release
+description: Version bump, generate changelog, tag, and prepare a release
+type: shipping
+version: v0.1
+argument-hint: "[patch|minor|major] or [specific version like 1.2.3]"
+---
+
+# Release
+
+Manage the release ceremony: version bump, changelog generation, git tag, and optional deploy trigger.
+
+## Process
+
+1. **Determine the version bump** from `$ARGUMENTS`:
+   - `patch`, `minor`, or `major` → compute the next version from the current one.
+   - Specific version (e.g., `1.2.3`) → use it directly.
+   - If no argument, analyze commits since the last tag to suggest a version:
+     - Any `feat:` commits → suggest `minor`
+     - Only `fix:` / `chore:` / `docs:` → suggest `patch`
+     - Any `BREAKING CHANGE` or `!:` → suggest `major`
+   - Confirm the version with the user before proceeding.
+
+2. **Pre-release checks:**
+   - Ensure the working tree is clean.
+   - Resolve the primary branch: prefer `main`; if it does not exist, use `master`. If neither exists, stop and explain the blocker.
+   - Ensure the current branch is the primary branch. If not, stop and tell the user to cut releases only from `main`/`master`.
+   - Ensure the primary branch is up to date with remote.
+   - Run tests to verify everything passes.
+   - Check for any TODO or FIXME items in `tasks/roadmap.md`, `tasks/todo.md`, and `tasks/manual-todo.md` (if it exists) that should block the release. Count `tasks/record-todo.md` and `tasks/recurring-todo.md` as advisory only unless an item explicitly says it blocks release.
+
+3. **Generate the changelog:**
+   - Find the last git tag (or first commit if no tags exist).
+   - Collect all commits since the last tag.
+   - Group by conventional commit type:
+     - **Features** (`feat:`)
+     - **Bug Fixes** (`fix:`)
+     - **Breaking Changes** (`BREAKING CHANGE` or `!:`)
+     - **Other** (`refactor:`, `chore:`, `docs:`, `test:`, `perf:`)
+   - Format as a markdown changelog entry with the version and date.
+
+4. **Apply the version bump:**
+   - Update `package.json` version (root and/or workspace packages as appropriate).
+   - If a `CHANGELOG.md` exists, prepend the new entry. If not, create one.
+   - If the project uses other version files (e.g., `version.ts`, `__version__.py`), update those too.
+
+5. **Commit and tag:**
+   - Stage the changed files.
+   - Commit with message: `release: vX.Y.Z`
+   - Create an annotated git tag: `vX.Y.Z` with the changelog entry as the tag message.
+
+6. **Ask about next steps:**
+   - Push the commit and tag? (ask for confirmation)
+   - Create a GitHub release? (ask for confirmation)
+   - Trigger a deploy? (ask for confirmation)
+
+## Output
+
+### Release vX.Y.Z
+
+**Changelog:**
+
+#### Features
+- commit summary (hash)
+
+#### Bug Fixes
+- commit summary (hash)
+
+#### Breaking Changes
+- commit summary (hash)
+
+**Files Updated:**
+- `package.json` — version bumped
+- `CHANGELOG.md` — entry added
+
+**Tag:** `vX.Y.Z`
+
+**Next steps:** push / GitHub release / deploy (awaiting confirmation)
+
+## Constraints
+- Always confirm the version with the user before making changes.
+- Never push or create a GitHub release without explicit user confirmation.
+- **Do not push to an existing feature branch.** Releases should only be cut from `main`/`master`. If on a feature branch, stop and ask the user.
+- If tests fail during pre-release checks, stop and report — do not release broken code.
+- For monorepos, ask the user whether this is a root release or a package-specific release.
+- Do not modify code as part of the release — only version files, changelogs, and tags.
+
+
+## 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/release-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/release-ops/codex/branch-lifecycle/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — branch-lifecycle
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/branch-lifecycle-{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/branch-lifecycle-{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-branch-lifecycle-research.md`; product-path mode uses `research/{slug}/_working/preliminary-branch-lifecycle-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-branch-lifecycle-research.md`; product-path mode uses `research/{slug}/_working/preliminary-branch-lifecycle-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/release-ops/codex/branch-lifecycle/CHANGELOG.md

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

package/packs/release-ops/codex/branch-lifecycle/SKILL.md

@@ -2,7 +2,7 @@
 name: branch-lifecycle
 description: "Evaluate feature branches and decide whether to merge, salvage, keep open, or delete based on branch health, PR status, and stale-branch heuristics"
 type: ops
-version: v0.1
+version: v0.2
 argument-hint: "[--force] [list | pr [branch...] | review <branch-or-pr> | merge <branch-or-pr> | salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>] | cleanup]"
 ---
 
@@ -153,7 +153,7 @@ This is an exception workflow. The default repository policy is direct-to-primar
 
 ## 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/branch-lifecycle-{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/branch-lifecycle-{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
 

package/packs/release-ops/codex/branch-lifecycle/archive/v0.1/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: branch-lifecycle
+description: "Evaluate feature branches and decide whether to merge, salvage, keep open, or delete based on branch health, PR status, and stale-branch heuristics"
+type: ops
+version: v0.1
+argument-hint: "[--force] [list | pr [branch...] | review <branch-or-pr> | merge <branch-or-pr> | salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>] | cleanup]"
+---
+
+# Branch Lifecycle
+
+Invoke as `$branch-lifecycle`.
+
+Evaluate feature branches after review and drive one of four outcomes: `merge`, `salvage`, `keep-open`, or `delete`.
+
+This is an exception workflow. The default repository policy is direct-to-primary development on `main`/`master`; use this skill for legacy branches, externally introduced branches, explicit user requests for branch/PR work, or `agent-team` lane branches created by an approved parallel plan.
+
+## Arguments
+
+- **No args** or **`list`**: inventory candidate branches and recommend an action for each.
+- **`pr [branch...]`**: create PRs for branches that do not already have one and pass basic readiness checks.
+- **`review <branch-or-pr>`**: classify a branch or PR as `merge`, `salvage`, `keep-open`, or `delete`.
+- **`merge <branch-or-pr>`**: merge only if the strict merge gate passes.
+- **`salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>]`**: cherry-pick selected commits onto a fresh target branch.
+- **`cleanup`**: delete merged branches and prompt for stale unmerged branches.
+- **`--force`**: skip confirmations for safe-destructive actions (PR creation, approved merge, merged-branch deletion). Never skips confirmation for deleting an unmerged branch.
+
+## Process
+
+1. **Resolve repository context:**
+   - Detect the base branch in this order: repository default branch, `main`, then `master`.
+   - Run `git status` and report uncommitted changes before any mutating action.
+   - Use `gh` for PR metadata and merge operations when available. If `gh` is unavailable or unauthenticated, report that limitation and continue with local-only facts where possible.
+   - State clearly that normal solo-dev work should land directly on the base branch, not stay on a feature branch.
+
+2. **Build branch inventory:**
+   - Enumerate local branches except the current branch and base branch.
+   - For each branch, gather:
+     - Ahead/behind counts vs base: `git rev-list --left-right --count <base>...<branch>`
+     - Last commit date/author: `git log -1 --format="%cr|%an" <branch>`
+     - Unique commits vs base: `git log --reverse --oneline <base>..<branch>`
+     - PR status and checks, when a PR exists
+   - Flag a branch as **stale** when it has no open PR and its last commit is older than 30 days.
+
+3. **Apply the decision policy:**
+   - **Merge** only when all strict-gate checks pass:
+     - focused scope
+     - passing CI/tests or no required checks
+     - no merge conflicts
+     - approval requirements satisfied, or no required review
+     - no unresolved high-severity review findings
+   - **Salvage** when the branch is outdated, mixed in scope, or not merge-ready but contains specific commits worth keeping.
+   - **Keep-open** when the branch is active and still worth finishing on its current line of development.
+   - **Delete** when the branch is stale or below standards and no clearly valuable commits remain.
+   - Increase confidence in a `delete` recommendation when stale is combined with any of:
+     - behind base by 10 or more commits
+     - failing or missing checks on an abandoned PR
+     - obviously mixed or abandoned scope
+
+4. **Execute the requested subcommand** using the rules below.
+
+## Subcommand Actions
+
+### `list`
+
+1. Print a table with:
+   - branch
+   - age
+   - ahead/behind
+   - PR status
+   - checks
+   - recommendation
+2. Use `merge`, `salvage`, `keep-open`, or `delete` in the recommendation column.
+3. Include a brief reason for non-merge recommendations, such as `stale`, `mixed scope`, `behind base`, or `failing checks`.
+
+### `pr [branch...]`
+
+1. Use the supplied branches, or find local branches without an open PR.
+2. Refuse to create a PR for:
+   - the current branch
+   - the base branch
+   - branches already marked `delete`
+3. For each eligible branch:
+   - summarize commits unique to the branch
+   - confirm with the user unless `--force`
+   - create the PR with `gh pr create`
+4. If a branch is a better `salvage` candidate than a PR candidate, say so and do not open the PR automatically.
+
+### `review <branch-or-pr>`
+
+1. Resolve the target to a branch and, if present, its PR.
+2. Evaluate:
+   - scope focus
+   - CI/tests
+   - conflicts
+   - approval state
+   - stale status
+   - whether the branch contains a small set of clearly reusable commits
+3. Output:
+   - target summary
+   - branch facts
+   - findings
+   - recommended action: `merge`, `salvage`, `keep-open`, or `delete`
+   - the reason tied to the decision policy
+
+### `merge <branch-or-pr>`
+
+1. Resolve the target to an open PR. If the branch has no PR, stop and recommend `pr` or `salvage`.
+2. Re-check the strict merge gate.
+3. If any merge gate fails, stop and explain which requirement failed.
+4. Confirm with the user unless `--force`.
+5. Merge with squash by default: `gh pr merge <number> --squash`
+   - Respect `CLAUDE.md` if it specifies a different merge strategy.
+6. Report the merged PR and resulting commit hash.
+
+### `salvage <branch-or-pr> [--onto <base>] [--commits <sha,...>]`
+
+1. Resolve the source branch and target base branch.
+   - Default target base is the detected repository base branch.
+   - If `--onto` is provided, use that branch as the target base.
+2. Show the commit list unique to the source branch in chronological order.
+3. Determine which commits to keep:
+   - if `--commits` is provided, use those SHAs in the given order
+   - otherwise, ask the user to choose commits explicitly
+4. Create a fresh target branch from the chosen base, using a name derived from the source branch such as `salvage/<source>-<date>`.
+5. Cherry-pick the selected commits in order.
+6. If a conflict occurs:
+   - stop immediately
+   - report the conflicted files and the standard `git cherry-pick --continue` / `--abort` next steps
+   - do not auto-resolve or continue
+7. Report the new branch name and the preserved commits.
+8. Never delete the source branch automatically after salvage.
+
+### `cleanup`
+
+1. Find merged branches and confirm deletion unless `--force`.
+2. Delete local merged branches with `git branch -d`.
+3. If the matching remote branch exists, delete it too after the same confirmation scope.
+4. Identify stale unmerged branches and print their recommendation reasons.
+5. Ask for confirmation before deleting each unmerged branch individually.
+   - Even with `--force`, never auto-delete an unmerged branch.
+6. If a stale branch looks salvageable, recommend `salvage` instead of deleting it immediately.
+
+## Constraints
+
+- Never force-push or rewrite history.
+- Never merge a PR that fails the strict gate.
+- Never auto-delete an unmerged branch.
+- Never auto-delete a source branch after salvage.
+- Never cherry-pick the full branch implicitly; salvage is commit-selective by default.
+- If the working tree is dirty and the requested action is mutating, warn first and stop unless the user explicitly wants to continue.
+- Prefer reporting and stopping over making branch-history decisions silently.
+
+
+## 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/branch-lifecycle-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/release-ops/codex/release/ALIGNMENT-PAGE.md

@@ -1,6 +1,6 @@
 # Alignment Page — release
 
-When this skill produces durable deliverables (research, specs, plans, reports, prototypes, or any document output), build a full-depth HTML alignment page at `alignment/release-{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/release-{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-release-research.md`; product-path mode uses `research/{slug}/_working/preliminary-release-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-release-research.md`; product-path mode uses `research/{slug}/_working/preliminary-release-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/release-ops/codex/release/CHANGELOG.md

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

package/packs/release-ops/codex/release/SKILL.md

@@ -2,7 +2,7 @@
 name: release
 description: Version bump, generate changelog, tag, and prepare a release
 type: shipping
-version: v0.1
+version: v0.2
 ---
 
 # Release
@@ -42,7 +42,7 @@ Use this skill when the user wants to cut a release for the project.
 
 ## 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/release-{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/release-{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
 

package/packs/release-ops/codex/release/archive/v0.1/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: release
+description: Version bump, generate changelog, tag, and prepare a release
+type: shipping
+version: v0.1
+---
+
+# Release
+
+Invoke as `$release`.
+
+Use this skill when the user wants to cut a release for the project.
+
+## Process
+
+1. Determine version bump from arguments or analyze commits to suggest one.
+2. Run pre-release checks:
+   - Ensure the working tree is clean.
+   - Resolve the primary branch: prefer `main`; if it does not exist, use `master`. If neither exists, stop and explain the blocker.
+   - Ensure the current branch is the primary branch. If not, stop and tell the user to cut releases only from `main`/`master`.
+   - Ensure the primary branch is up to date with remote.
+   - Run tests to verify everything passes.
+3. Generate changelog from conventional commits since last tag.
+4. Bump version in package.json and other version files.
+5. Commit and create annotated git tag.
+6. Ask about push, GitHub release, and deploy.
+
+## Output
+
+- **Changelog**: features, fixes, breaking changes
+- **Files Updated**: version files and changelog
+- **Tag**: version tag created
+- **Next Steps**: awaiting confirmation for push/release/deploy
+
+## Constraints
+
+- Always confirm version with user before changes.
+- Never push or create GitHub releases without explicit confirmation.
+- **Do not push to an existing feature branch.** Releases should only be cut from `main`/`master`. If on a feature branch, stop and ask the user.
+- Stop if tests fail — do not release broken code.
+
+
+## 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/release-{topic}.html`.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.

package/packs/remotion/claude/video-build/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-video-build-research.md`; product-path mode uses `research/{slug}/_working/preliminary-video-build-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-video-build-research.md`; product-path mode uses `research/{slug}/_working/preliminary-video-build-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/remotion/claude/video-build/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.2 - 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.0
 
 - Archived previous skill contract.

package/packs/remotion/claude/video-build/SKILL.md

@@ -2,13 +2,13 @@
 name: video-build
 description: Transform an approved video script into a Remotion build specification with scaffolded project directory, compositions, scene components, and render config
 type: planning
-version: v0.1
+version: v0.2
 argument-hint: "<script-path-or-slug> [--style minimal|motion-heavy|kinetic-text] [--fps 30|60] [--resolution 1080p|4k]"
 ---
 
 ## 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.
 
 # Video Build
 

package/packs/remotion/claude/video-build/archive/v0.1/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: video-build
+description: Transform an approved video script into a Remotion build specification with scaffolded project directory, compositions, scene components, and render config
+type: planning
+version: v0.1
+argument-hint: "<script-path-or-slug> [--style minimal|motion-heavy|kinetic-text] [--fps 30|60] [--resolution 1080p|4k]"
+---
+
+## 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.
+
+# Video Build
+
+Invoke as `/video-build`.
+
+Take an approved video script and produce a build specification document and a scaffolded Remotion project directory with compositions, scene components, asset manifest, and render config.
+
+## Prerequisites
+
+- `specs/youtube/video-script-<slug>.md` must exist.
+- Remotion availability is checked (`npx remotion --help`). If not installed, produce the spec and scaffold but defer render commands to `tasks/manual-todo.md`.
+
+## Inputs
+
+- `specs/youtube/video-script-<slug>.md`
+- `specs/youtube/series-<slug>.md` (visual identity)
+- `research/youtube/product-led-media-map-<slug>.md` (proof assets)
+- Codebase scan for design tokens, logos, and fonts.
+
+## Process
+
+0. Resolve arguments: script path or slug, style (`minimal`, `motion-heavy`, `kinetic-text`), fps (`30`, `60`), resolution (`1080p`, `4k`).
+1. Load script, series spec (visual identity), product-led-media-map (proof assets), and scan codebase for design tokens, logos, and fonts.
+2. Interview (AskUserQuestion): visual identity (colors, fonts, logo), asset sourcing per asset requirement, technical config (platform, fps, resolution, existing Remotion project?).
+3. Design component tree: map script scenes to Remotion components with durations in frames, visual elements, animation timing, and audio references.
+4. Present build specification: component tree diagram, per-scene build plan, asset manifest, render config. Validate with user.
+5. Write output only after user confirmation.
+
+## Output
+
+Create the `specs/youtube/` and `src/videos/<slug>/` directories if they do not exist.
+
+Write `specs/youtube/video-build-<slug>.md` with:
+
+- **Build Brief:** script reference, style, fps, resolution, target platform.
+- **Component Tree:** diagram and component descriptions.
+- **Scene-by-Scene Build Plan:** table — component, duration (frames/seconds), visual elements, animation type, assets.
+- **Asset Manifest:** table — name, type, status (`available`/`placeholder`/`needs-creation`), path, notes.
+- **Audio Plan:** narration, music, SFX, sync points.
+- **Render Configuration:** composition ID, fps, width, height, codec, output format.
+- **Typography & Color Tokens:** fonts, sizes, colors from brand/series.
+- **Transition Library:** which transitions between which scenes.
+- **Next Steps.**
+
+Write `specs/youtube/video-build-<slug>-interview.md` with the interview log.
+
+Scaffold `src/videos/<slug>/`:
+
+```
+composition.tsx        // Root composition with Sequence timing
+scenes/               // One component per script scene
+transitions/          // Reusable transition components
+components/           // Shared UI (LowerThird, BrowserFrame, etc.)
+assets/
+  manifest.json       // Asset paths and statuses
+config/
+  render.ts           // Render configuration
+  theme.ts            // Colors, fonts, spacing tokens
+```
+
+### Task Classification
+
+After writing output:
+
+- `tasks/todo.md`: render commands, asset sourcing automation, subtitle generation.
+- `tasks/manual-todo.md`: record footage, source music, record voiceover, YouTube upload, metadata, thumbnail, scheduling.
+- `tasks/recurring-todo.md`: review performance at 7-day and 30-day marks.
+
+## Approved Artifact Handoff
+
+After an approved synthesized write, explicit write/update mode, or any direct artifact mutation:
+
+- List every created or updated synthesized artifact path in the final response.
+- State the verification performed, such as readback, schema/check command, or why no executable verification applies for a Markdown-only strategy artifact.
+- Check and report the relevant git status for intended artifacts when the project is a git repository. If intended artifacts are modified or untracked, make the next action shipping, committing, or an explicit dirty-artifact handoff before recommending downstream strategy work.
+- Do not imply the research workflow is complete while approved artifacts remain untracked or uncommitted unless the user explicitly asked not to ship.
+- If stopping for approval before writing, the approval request remains the next action; do not include downstream routing.
+
+## Intent-Aware Routing
+
+Before applying the default `## Next-Skill Routing` sequence, classify the user's immediate intent and route to the missing action that best serves that intent:
+
+- Strategy refresh: recommend the missing or stale positioning, programming, portfolio, metrics, or product-media artifact.
+- Recording prep: recommend the missing series spec, script, build proof, walkthrough guide, or validation artifact needed before recording.
+- Upload prep: recommend packaging, title/thumbnail, description, chapters, or final metadata work before broader strategy work.
+- Performance review: recommend metrics, cadence, portfolio, peer benchmark, or owner-analytics export work before new content planning.
+- Owner analytics or private/manual platform evidence: route to an explicit manual/guide handoff instead of inventing unavailable metrics.
+- Dirty intended artifacts: route to shipping/commit/handoff first, not another creator strategy skill.
+
+Use the default next-skill sequence only when no stronger user intent, missing artifact, manual blocker, or dirty-artifact handoff applies.
+
+## 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/video-build-{topic}.html`.
+
+## Constraints
+
+- Every scene component must match the approved script timing — do not add or remove scenes.
+- Do not generate AI voiceover without explicit user approval.
+- Do not embed copyrighted assets without the user confirming licensing.
+- Asset manifest must clearly distinguish `available` vs `placeholder` vs `needs-creation`.
+- Respect series visual identity when a series spec exists.
+- Present the build specification before writing — never write until the user confirms.
+- Keep components composable — series should reuse intro/outro/transition/lower-third across episodes.
+- Do not expose secrets, private customer data, or unreleased commitments.
+
+## Default Shipping Contract
+
+Follow the shared shipping contract convention in CLAUDE.md.