alignment_status: review
Pack Skill Sunset Plan
This page records the decision to fully remove the agent-facing /pack (Claude) and $pack (Codex) skills. Scope is skill-only: scripts/pack.sh stays as the backend (this checkout uses the shell script, not npx skillpacks), and the packages/skillpacks CLI is unaffected. It records the verified reference surface that must be repointed, the real removal blockers and phases, a guided-setup decision gate for the one capability genuinely lost by deletion, and the gates that must be approved before any removal begins.
approval_status: ready-for-agent-review.
Table of Contents
Recommendation Summary
Remove both pack skill mirrors (base/claude/pack/ and base/codex/pack/). Keep scripts/pack.sh as the backend — this checkout already invokes the shell script directly, so the skills are a redundant agent-facing entry point.
Skill-only. scripts/pack.sh and the packages/skillpacks CLI stay. The CLAUDE.md/AGENTS.md missing-skill fallback uses scripts/pack.sh which and never invokes /pack or $pack, so it is unaffected.
The skill's guided setup (repo inspection → pack classification → confirmation gate) and Pack Selection routing knowledge. None of this exists in scripts/pack.sh. Its destination is an explicit gate on this page.
Do not remove until active routing references (init-agentic-skills and the other callers below) are repointed off /pack/$pack and the guided-setup gate is resolved.
Current Dependency Evidence
All paths below are verified against this checkout. What is removed is the two skill roots; everything that references /pack or $pack must be repointed (to scripts/pack.sh or to init-agentic-skills) before the roots can be deleted. The shell script and npm CLI are explicitly out of scope and stay in place.
| Surface | Repo path | Reference type | Removal impact |
|---|---|---|---|
| Skill roots removed | base/claude/pack/, base/codex/pack/ |
Each holds SKILL.md v0.10, CHANGELOG.md, a bundled scripts/pack.sh, and archive/v0.0–v0.9. No scripted base-skill retirement helper exists. |
Removal is git rm of both directories plus reference cleanup plus generated-artifact regen. |
| Primary routing dependency | base/{claude,codex}/init-agentic-skills/SKILL.md |
Routes to /pack / $pack for guided setup and refresh (claude lines 11, 24, 25, 35; codex 13, 26, 27, 37). |
Must be repointed before removal; this is the main caller and the natural home for the guided flow. |
Routing references (recommend) |
base/{claude,codex}/idea-scope-brief/SKILL.md; packs/product-design/{claude,codex}/spec-interview/SKILL.md; packs/monorepo/{claude,codex}/scaffold/SKILL.md |
Name /pack recommend / $pack recommend (idea-scope-brief 174/177; spec-interview 68/70; scaffold 22/19). |
Repoint to scripts/pack.sh recommend. |
| Routing references (bare invocation) | packs/skill-dev/{claude,codex}/skill-interview/SKILL.md; packs/project-fleet/codex/spin-off/SKILL.md:92 |
skill-interview names /pack (96) / $pack (98); spin-off has Recommended next skill: $pack. |
Repoint to scripts/pack.sh or to init-agentic-skills per the guided-setup gate. |
| Routing references (exec-loop boundary) | packs/exec-loop/{claude,codex}/{ship,ship-end}/SKILL.md |
"Pack install artifact boundary" passages name /pack/$pack alongside scripts/pack.sh refresh. |
Repoint to the shell route only. |
| Public docs | README.md:140, docs/QUICKSTART.md:91, docs/packs.md:101-102, docs/codex-workflow.md:65,67, docs/skills-reference.md:93, docs/operating-modes.md:197 |
Document the skill (skills-reference is the base-skill table row). docs/skillpacks-install-routing-contract.md already describes /pack install as the legacy route. |
Remove or repoint skill mentions; keep shell/CLI guidance. |
| Hard-coded required-file lists | scripts/skill-install-routing-audit.sh:24,31; packages/skillpacks/scripts/build-package.mjs:77 |
P1_REQUIRED_FILES includes both pack SKILL paths (exits 1 if missing); requiredBuildFiles includes base/codex/pack/SKILL.md (throws on missing). |
Both must be edited or the audit/build will fail after removal. |
| Tests that will fail | packages/skillpacks/test/{package-boundary,manifest,lifecycle}.test.mjs |
package-boundary:84 asserts pack path is published; manifest:66-70 asserts skillByPath('base/codex/pack/SKILL.md'); lifecycle:295,543,602,628,654,753 assert pack-root existence after init/install/refresh. |
Must be updated to assert absence/removal before tests go green. |
| Generated artifacts | packages/skillpacks/dist/skillpacks-manifest.json (+ build/dist/ copy); apps/skills-showcase/public/assets/skills-data.js and docs/skills-showcase/assets/skills-data.js |
Manifest carries base-claude-pack/base-codex-pack entries; showcase data carries /pack/$pack entries. Index-based — stage source removal first per CLAUDE.md. |
Regenerate after source removal is staged. |
| Out of scope (staying) | scripts/pack.sh, packages/skillpacks CLI |
The shell pack manager and npm CLI are independent of the skill directories. | Not removed, not modified by this work. Not affected: mirror-parity audit, base-skill version-parity audit, alignment audit, .agents/project.json. |
Sunset Definition
"Sunset" can mean three different outcomes. The decision recorded here is full removal; the other two are documented as non-recommended alternatives.
| Option | Meaning | Advantages | Risks | Recommendation |
|---|---|---|---|---|
Remove pack skill |
git rm both base/claude/pack/ and base/codex/pack/ roots after routing references and docs are repointed and the guided-setup gate is resolved. |
Eliminates a redundant agent-facing entry point; scripts/pack.sh already does the work directly. No CLI parity needed because the backend stays. |
Loses the skill's guided setup unless its destination is decided (the guided-setup gate). Agents trained on /pack/$pack must learn the shell route. |
Recommended. |
| Deprecate and retain compatibility shim | Mark the skill deprecated, route work to scripts/pack.sh, and keep a thin shim skill for one release cycle. |
Preserves the existing entry point while nudging callers off it. | Keeps the redundant skill registry surface and the maintenance of a shim with no backend of its own. | Not recommended — adds surface without value when the backend already exists. |
| Keep as active facade | Keep pack as the agent-facing UX and let it call scripts/pack.sh internally. |
Lowest disruption for agents. | Does not accomplish removal; keeps two parallel entry points indefinitely. | Not recommended — this is the status quo the decision rejects. |
Target Replacement Model
After removal there is no /pack/$pack skill. The canonical route in this checkout becomes the shell script directly; the npm CLI remains the route for package consumers. The skill's guided UX is either migrated into init-agentic-skills or dropped, per the guided-setup gate.
scripts/pack.sh <command> — recommend, which, install, install-deck, refresh, pin, prune, lock handling. Unchanged by this work.
npx skillpacks <command> / gskp remain the route for installed-package users. Out of scope here.
Already uses scripts/pack.sh which <skill> in CLAUDE.md/AGENTS.md and never invoked the skill. No change needed.
Either migrate the repo inspection → pack classification → confirmation flow and Pack Selection routing into init-agentic-skills, or drop it and route to raw scripts/pack.sh recommend + install.
Readiness Blockers
| Blocker | Why it blocks removal | Required proof | Owner surface |
|---|---|---|---|
| Repoint active routing references | Skills route to /pack/$pack for guided setup, refresh, and recommend. Deleting the roots leaves dangling skill routes. |
No active SKILL.md names /pack or $pack; each is repointed to scripts/pack.sh or init-agentic-skills per the guided-setup gate. |
init-agentic-skills, idea-scope-brief, spec-interview, scaffold, skill-interview, spin-off, exec-loop ship/ship-end. |
| Docs cleanup | Public docs document the skill as a live route. | Skill mentions removed or repointed to the shell/CLI route; base-skill table row dropped. | README.md, docs/QUICKSTART.md, docs/packs.md, docs/codex-workflow.md, docs/skills-reference.md, docs/operating-modes.md. |
| Edit hard-coded required-file lists | P1_REQUIRED_FILES and requiredBuildFiles include pack SKILL paths; both fail hard once the files are gone. |
Pack paths removed from both lists; audit exits 0 and build does not throw. | scripts/skill-install-routing-audit.sh:24,31, packages/skillpacks/scripts/build-package.mjs:77. |
| Update failing tests | Tests assert the pack path is published and pack roots exist after lifecycle operations. | Assertions updated to expect absence; test:node passes. |
package-boundary.test.mjs:84, manifest.test.mjs:66-70, lifecycle.test.mjs:295,543,602,628,654,753. |
| Regenerate generated artifacts | Manifest and showcase data carry pack entries; they are index-based, so removal must be staged before regen (per CLAUDE.md). |
Manifest (+ build copy) and both skills-data.js files no longer carry pack entries; build:check passes. |
dist/skillpacks-manifest.json (+ build/dist/), apps/skills-showcase/public/assets/skills-data.js, docs/skills-showcase/assets/skills-data.js. |
| Resolve guided-setup destination | The skill's repo inspection → classification → confirmation flow and Pack Selection routing exist nowhere else. Removal silently loses them unless a destination is chosen. | Gate answered: either the flow is migrated into init-agentic-skills or explicitly dropped in favor of raw scripts/pack.sh recommend + install. |
Guided-setup gate on this page; init-agentic-skills/SKILL.md if migration is chosen. |
Implementation Phases
| Phase | Work | Exit criteria | Proceed gate |
|---|---|---|---|
| 1. Confirm reference map | Re-verify the reference surface in the evidence table against the live checkout (routing refs, docs, required-file lists, tests, generated artifacts). | Evidence table matches the checkout; no unlisted /pack/$pack reference remains. |
Approve current reference map. |
| 2. Resolve guided-setup gate | Decide whether the guided flow + Pack Selection routing migrates into init-agentic-skills or is dropped in favor of raw scripts/pack.sh. |
Guided-setup gate answered; destination chosen. | Approve guided-setup destination. |
| 3. Repoint routing refs + docs | Repoint every active SKILL.md reference and every doc mention to scripts/pack.sh or init-agentic-skills per phase 2. |
No active skill or doc names /pack/$pack; base-skill table row dropped. |
Approve repointed routes. |
| 4. Edit required-file lists + tests | Remove pack paths from P1_REQUIRED_FILES and requiredBuildFiles; update the failing package tests to expect absence. |
skill-install-routing-audit.sh exits 0; test:node passes against the edited lists. |
Approve audit/test contract. |
| 5. Remove dirs + regenerate artifacts | git rm both pack roots, git add the removal, then regenerate manifest (+ build copy) and both skills-data.js files (staged-before-build per CLAUDE.md). |
Pack roots gone; generated artifacts carry no pack entries; source + regenerated artifacts staged together. | Approve removal + regen. |
| 6. Verification + ship | Run the release verification set; update ship manifest; commit and push. | All required checks pass or any pre-existing failure is proven against an unmodified baseline. | Approve release readiness. |
Release Verification
This planning page is verified only by the alignment audit. The downstream removal implementation runs the wider set below because it touches the base-skill registry, generated package outputs, and public docs.
node scripts/audit-alignment-pages.mjs (run node scripts/inject-tts.mjs first if TTS-include diagnostics fire), plus git diff --check.
bash scripts/skill-install-routing-audit.sh — must exit 0 after pack paths are removed from P1_REQUIRED_FILES.
npm --workspace packages/skillpacks run test:node — confirms the updated boundary/manifest/lifecycle assertions pass.
npm --workspace packages/skillpacks run build:check — validates the regenerated manifest against the git index.
Decision Gates
Answer these gates with the bottom compile control before any implementation starts. Partial responses are allowed and should be treated as review feedback, not implementation approval.
Gate 1: Sunset Target
What is the intended end state for the pack skill?
Gate 2: Backend Scope
What is the scope of the removal relative to the pack backend?
Gate 3: Guided-Setup Destination
The skill's guided setup (repo inspection → pack classification → confirmation gate) and Pack Selection routing exist nowhere else. Where should that capability go when the skill is removed?
Gate 4: Approval To Proceed
May an agent proceed with implementation after this page is reviewed?
Compile Responses
Use this section to compile gate answers and selected section feedback into YAML. Complete approval requires all four required gates answered and no unresolved negative or clarification feedback.