Skip to main content
All projects
Automation & AI
/projects/claude-superpack

Claude Superpack

project.claude-superpack.local
Claude Superpack project screenshot

  1. Problem:

    Skill packs for Claude Code fail in one of two directions—stay small and carry no real engineering judgment, or load so much always-on context that every turn pays for domain knowledge used once a month, with no mechanism to verify a claimed fix actually works.

  2. Solution:

    Rebuilt from a 33-skill always-loaded pack into a 9-skill risk-tiered engineering OS that sizes every task on two independent axes (scope and risk), pulls in 15 domain references only when a task needs them, and runs 4 deterministic Node scripts instead of asking the model to eyeball diffs, secrets, and build logs.

  3. Impact:

    Cut always-on context 73% (2,753 -> 742 tokens, cross-checked against Claude Code's own estimator) while adding capabilities v4 never had—a debugging skill, an evidence gate before any completion claim, and a high-precision credential scanner—then shipped it as a public npm package with GitHub Actions OIDC trusted publishing.

Overview

claude-superpack is an engineering operating system for Claude Code: nine always-on skills classify every request on two independent axes—scope (how much work) and risk (what happens if it's wrong)—then route into fifteen domain references and four deterministic scripts that load only when the task actually needs them. One rule overrides everything else: no completion claim without evidence produced after the change. Published to npm with GitHub Actions OIDC trusted publishing so every version is verifiably built from the repository.

Results & metrics

  • Cut always-on LLM context overhead by 73% (from 2,753 down to 742 tokens)
  • Modular architecture with 9 core skills and 15 on-demand engineering domain references
  • Enforced strict post-change evidence gates blocking speculative completion claims
  • Published to npm with GitHub Actions OIDC provenance and 100% test routing coverage

Before / after

  • Always-on context

    Before: ~2,753 tokens across 33 always-loaded skills (v4)

    After: ~742 tokens across 9 skills (v5), cross-checked against Claude Code's own estimator

  • Completion claims

    Before: Model asserted a fix worked based on its own read of the diff

    After: Evidence gate blocks any completion claim without tool output produced after the change

  • Codebase awareness

    Before: Persistent JSON knowledge graph under ~/.claude/graphs/, which went stale silently

    After: Blast radius computed fresh from the diff and grep every time—slower per call, never confidently wrong

  • Cross-session memory

    Before: Five skills wrote to ~/.claude/memory/, duplicating dedicated memory plugins

    After: Removed entirely; defers to claude-mem or Claude Code's native memory, keeps in-task state in durable plan files

What I built

Lean always-on context

Always-on context cut 73%, 2,753 to 742 tokens; 15 references load on demand.

Scope and risk

Every request is sized on two axes: scope sets planning depth, risk sets gate count.

Evidence gate

No completion claim without tool output produced after the change.

Stack

  • Two-axis task sizing, Scope (S0-S3) x Risk (R0-R3) sets planning depth and gate count independently
  • 9 skills, 4 content-activated (debugging, securing, shipping, requirements-grilling) + 5 phase-activated, reached from a core gate table
  • 15 domain references, (frontend, backend, data, ai-llm, cloud, devops, sre, security, performance, testing, architecture, quality, docs, parallel, routing), each structured Decide first / Build right / Failure modes / Evidence
  • 4 zero-dependency Node scripts, recon.mjs, gates.mjs, diffstat.mjs, secrets.mjs
  • Published as @sahilbnsll/claude-superpack, via GitHub Actions OIDC trusted publishing with signed provenance attestation
  • Three-tier benchmark suite, (structure, routing vocabulary, paired live evaluation) gates every release via npm run bench

Decisions

Key trade-offs and design calls that shaped the final delivery.

  • Two independent axes instead of one A/B/C/D tier

    Why
    Context
    v4's single complexity tier conflated "big" with "dangerous"—a 1,000-line refactor of a test helper and a one-line IAM policy change got identical treatment
    Decision
    Split into Scope (S0-S3, sets planning depth) and Risk (R0-R3, sets gate count), so a trivial edit gets one tool call and a production/IaC change doesn't execute until blast radius is stated out loud and confirmed

  • Delete the persistent memory system and codebase graph

    Why
    Context
    v4's ~/.claude/memory/ and ~/.claude/graphs/ cost context every session, duplicated dedicated memory plugins, and depended on the model reliably self-reporting its own state—a paired evaluation found that compliance happened once in eighty trials despite the instruction reaching the model every time
    Decision
    Removed both. Blast radius is now computed fresh from the diff and grep on every task; cross-session recall defers explicitly to claude-mem or Claude Code's native memory instead of reimplementing it

  • npm publishing via GitHub Actions OIDC, not a stored token

    Why
    Context
    A long-lived npm token sitting in CI is a standing credential that can leak or go stale
    Decision
    Trusted publishing authenticates through GitHub Actions' OIDC identity—no npm token exists to leak—and every version carries a signed provenance attestation tying it to the exact workflow run that built it

Architecture

The primary system boundaries, runtime pieces, and how the project was structured in production.

Diagram, 7 connections:
  1. User request → superpack: classify scope x risk
  2. superpack: classify scope x risk → debugging-systematically / securing-changes / shipping-safely / grilling-requirements (content-activated)
  3. superpack: classify scope x risk → codebase-recon -> planning-changes -> verifying-evidence -> reviewing-before-done (gate table)
  4. codebase-recon -> planning-changes -> verifying-evidence -> reviewing-before-done → 15 domain references, loaded on demand
  5. codebase-recon -> planning-changes -> verifying-evidence -> reviewing-before-done → recon.mjs / gates.mjs / diffstat.mjs / secrets.mjs
  6. recon.mjs / gates.mjs / diffstat.mjs / secrets.mjs → Evidence gate
  7. Evidence gate → Completion claim
  • superpack skill (SKILL.md + gate table)

    Core Routing & Sizing

    How

    Classifies every request on scope and risk, then routes to phase-activated skills via an explicit gate table—the only way those skills can be reached, since nobody types "I would like a blast-radius check now."

  • 15 on-demand markdown files

    Domain References

    How

    92KB of engineering depth that costs zero always-on tokens and loads only when the router selects it, versus being baked into an always-loaded skill description.

  • recon.mjs / gates.mjs / diffstat.mjs / secrets.mjs

    Deterministic Scripts

    How

    Replaces model guesswork with real tool output—secrets.mjs found 4 real credentials across 1,094 changed lines in 40ms with zero false positives; gates.mjs turned 15,247 bytes of build output into a 288-byte digest that preserved the evidence line.

Mermaid source

Paste into mermaid.live to edit the diagram.

flowchart TD
  U[User request] --> C[superpack: classify scope x risk]
  C -->|content-activated| CA[debugging-systematically / securing-changes / shipping-safely / grilling-requirements]
  C -->|gate table| PA[codebase-recon -> planning-changes -> verifying-evidence -> reviewing-before-done]
  PA --> DR[15 domain references, loaded on demand]
  PA --> SC[recon.mjs / gates.mjs / diffstat.mjs / secrets.mjs]
  SC --> EV[Evidence gate]
  EV --> DONE[Completion claim]

Pipeline

How changes moved from development through validation and deployment.

Select a step for its detail

Incidents

Operational failures, rehearsals, or recovery moments that changed how the system was run.

  • P1

    Global install silently skipped installing the skills

    Resolution

    Removed postinstall/preuninstall entirely as a breaking change (v5.0.2); install is now an explicit `npx ... install` step that exits non-zero on failure instead of a lifecycle script that swallowed errors

    Lesson: A package that writes into the user's home directory merely by being downloaded is a supply-chain smell regardless of whether it currently works—npm blocking install scripts by default was the signal this needed fixing, not the cause of the bug

  • P2

    Every skill description loaded twice

    Resolution

    v4 installed each skill both at ~/.claude/skills/<name>/ and again as a plugin-shaped copy underneath, roughly doubling always-on token cost to ~5,600 tokens/turn; the installer now installs one copy, deletes any leftover duplicate, and `claude-superpack doctor` detects the condition going forward

    Lesson: An installer needs an install manifest, not an assumption that its own previous version installed cleanly

  • P3

    Published tarballs weren't reproducible from their commit

    Resolution

    prepublishOnly ran the benchmark suite, which rewrote a results file with a fresh timestamp on every publish, so the packed tarball never matched the commit and left the working tree dirty; prepublishOnly now runs with --no-write

    Lesson: A pre-publish hook that mutates the working tree undermines the exact guarantee—build reproducibility—that provenance attestation exists to provide