@thebassclef/lite 1.1.1 → 1.2.0

package/dist/lite/.claude/skills/secrets-bootstrap/SKILL.md

@@ -0,0 +1,209 @@
+---
+tier: lite
+name: secrets-bootstrap
+description: "Verify the operator's shell env against the secrets manifest. Calls the per-storage-type adapter; env and github_actions_secret implemented, others stub for V2. --write bootstraps ~/.config/bassclef/secrets.env. Read-only by default."
+problem: "Operator shell env drifts from the secrets manifest. Missing secrets surface mid-session."
+value: "Verifies the operator's shell env against the secrets manifest. Calls adapters per storage type."
+inputs: [Optional --verbose flag]
+outputs: [Secret check status per key, Missing secrets list, Adapter output]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /secrets-bootstrap — Verify + Bootstrap Shell Secrets
+
+Reads substrate.secrets.md, dispatches each entry to the adapter for
+its `storage.type`, and reports green/red per secret. With `--write`,
+writes placeholder shell-env entries for missing `storage.type: env`
+secrets so the operator can fill in values once.
+
+## When to invoke
+
+- **First-time setup** of a fresh bassclef clone — run with `--write`
+  to bootstrap `~/.config/bassclef/secrets.env`
+- **Pre-flight before `/provision-deploy-host`** (called automatically
+  as Phase 0 by that skill) — verifies all required env vars exist
+  before any external API call
+- **Periodic health-check** — run with `--health-check` to invoke
+  each entry's `health_check_command` and surface stale or revoked
+  secrets
+
+## When NOT to invoke
+
+- Routine session-start orientation — the `90-secrets-expiry.sh`
+  reflection hook already surfaces expired/expiring secrets
+- Setting GitHub Actions secrets — those live in GitHub; bootstrap
+  reads them via API but does NOT write them. Use `gh secret set`
+  for GHA-side writes.
+
+## Sources read
+
+- `substrate.secrets.md` — declarative secrets manifest (Shape B,
+  YAML frontmatter)
+- `bassclef-platform.yml` — `secrets.storage_default` (used as
+  fallback when an entry's `storage.type` is unset)
+- `scripts/adapters/secrets/<type>.sh` — per-type adapter implementations
+- `standards/secrets-lifecycle.md` — semantics for storage_default
+  + per-secret override
+- `standards/bassclef-platform.md` — XDG `~/.config/bassclef/secrets.env`
+  convention
+
+## Storage.type adapters
+
+| `storage.type` | Adapter | V1 status | What it does |
+|----------------|---------|-----------|--------------|
+| `env` | `scripts/adapters/secrets/env.sh` | **implemented** | Checks `${reference}` shell env var; `--write` appends placeholder to `~/.config/bassclef/secrets.env` |
+| `github_actions_secret` | `scripts/adapters/secrets/github_actions_secret.sh` | **implemented** | Checks via `gh secret list` (read-only); never writes |
+| `1password` | `scripts/adapters/secrets/1password.sh` | stub | Stubs `op read op://<vault>/<item>/<field>`; reports "V2 adapter deferred" |
+| `aws_secrets_manager` | `scripts/adapters/secrets/aws_secrets_manager.sh` | stub | Stubs `aws secretsmanager get-secret-value`; "V2 adapter deferred" |
+| `file` | `scripts/adapters/secrets/file.sh` | stub | Stubs file-existence check at `reference` path; "V2 adapter deferred" |
+| `custom` | `scripts/adapters/secrets/custom.sh` | stub | Stubs custom-reference resolution; "V2 adapter deferred" |
+
+V2 adapters land when a real consumer needs them. The pattern is
+schema-stable — adapters drop in without schema changes.
+
+## Usage
+
+```bash
+# Read-only check — surfaces green per secret with all-good or red with gap
+bash scripts/secrets-bootstrap.sh
+
+# Bootstrap missing env-typed secrets to ~/.config/bassclef/secrets.env
+bash scripts/secrets-bootstrap.sh --write
+
+# Run health_check_command per entry
+bash scripts/secrets-bootstrap.sh --health-check
+
+# Repair legacy secrets.env that lacks `export ` prefixes (bassclef#976).
+# Without `export`, bash subprocesses don't inherit the variable — adapter
+# checks pass in zsh but fail in `bash lib/luminary-pick.sh` etc.
+# Creates dated backup before rewriting.
+bash scripts/secrets-bootstrap.sh --repair
+
+# Combinations
+bash scripts/secrets-bootstrap.sh --write --health-check
+```
+
+## --repair (bassclef#976)
+
+`/secrets-bootstrap --repair` walks `~/.config/bassclef/secrets.env`
+line by line and adds the `export ` prefix to every assignment line
+that lacks it. Comments, blank lines, and already-exported lines pass
+through untouched. A dated backup (`secrets.env.bak.YYYYMMDDTHHMMSSZ`)
+is created before the rewrite.
+
+Why this matters: sourcing a file with bare `VAR=value` lines sets
+the shell variable in zsh — `echo $VAR` works — but the variable does
+NOT enter the environment. Every bash subprocess the shell launches
+(every bassclef hook, every helper script) reads only the environment.
+Result: `[OK] ANTHROPIC_API_KEY (env) — set via secrets.env` in the
+bootstrap output, then `bash lib/luminary-pick.sh` reports "not set"
+seconds later. `--repair` closes that surface.
+
+The env adapter's own writes already use the `export ` prefix
+(`scripts/adapters/secrets/env.sh`). `--repair` is for the case where
+an operator hand-edited the file and dropped the prefix, or where the
+file pre-dates the bassclef#976 fix.
+
+## Output format
+
+One line per secret:
+
+```
+[OK]   SLACK_WEBHOOK_ACTIVITY    (github_actions_secret) — verified via gh
+[OK]   CLOUDFLARE_API_TOKEN      (env)                   — set in shell env
+[GAP]  ANTHROPIC_API_KEY         (env)                   — env var unset
+       → fix: export ANTHROPIC_API_KEY=<value> ; or rerun with --write
+[STUB] OP_VAULT_DEMO              (1password)            — adapter deferred to V2
+```
+
+Summary line at end:
+
+```
+Result: 12/14 OK / 1 gap / 1 stub  (14 secrets tracked)
+Exit code: 0 (no gaps in implemented adapters) / 1 (gaps surface)
+```
+
+`--write` mode:
+
+```
+[GAP]  ANTHROPIC_API_KEY         (env)                   — env var unset
+       → wrote placeholder to ~/.config/bassclef/secrets.env
+       → edit the file + add real value, then run `source ~/.zshrc`
+```
+
+## Procedure
+
+1. **Read substrate.secrets.md** YAML frontmatter
+2. **For each secret entry**:
+   1. Resolve `storage.type` (use `secrets.storage_default` from
+      bassclef-platform.yml as fallback)
+   2. Source `scripts/adapters/secrets/${storage.type}.sh`
+   3. Call adapter's `secret_check <name> <reference>` → returns OK/GAP/STUB
+   4. If `--write` AND result is GAP AND adapter supports `secret_write`,
+      call `secret_write <name> <reference>` (env adapter only V1)
+   5. If `--health-check` AND `health_check_command` present, run it;
+      surface result
+3. **Aggregate** results, print summary line, exit 0 (all OK or only
+   stubs) / 1 (one or more GAPs in implemented adapters)
+
+## Idempotency
+
+- Read-only by default; running twice in a row produces identical output
+- `--write` is idempotent: if `~/.config/bassclef/secrets.env` already
+  has a line for the secret, the existing line is left in place
+  (writes never overwrite). If the file doesn't exist, it's created
+  with `chmod 600`.
+- `--write` prompts the operator once at first invocation to add a
+  source-line to `~/.zshrc` if not already present:
+  ```
+  Add `source ~/.config/bassclef/secrets.env` to ~/.zshrc? [y/N]
+  ```
+
+## Test plan
+
+- [x] All-present: every secret has its env var set / its GHA secret
+  exists → exit 0, 0 gaps
+- [x] One missing: a single env var unset → exit 1, 1 GAP, remediation
+  hint shown
+- [x] Stub-only adapter: secret with `storage.type: 1password` →
+  STUB report, doesn't count toward exit-code-1
+- [x] `--write` mode: missing env-typed secret → placeholder written
+  to ~/.config/bassclef/secrets.env (created if missing, chmod 600)
+- [x] `--write` idempotent: re-run leaves file unchanged
+- [x] `--health-check` mode: runs `health_check_command` per entry,
+  surfaces output
+
+## Composes with
+
+| Skill | How it composes |
+|---|---|
+| `/provision-deploy-host` | Calls `/secrets-bootstrap` as Phase 0 (fail-fast on missing creds) |
+| `/launch-preview` | Optional pre-flight verification |
+| `90-secrets-expiry.sh` (hook) | Sibling concern — expiry vs. presence |
+
+## Distinct from
+
+- `90-secrets-expiry.sh` — checks `expires_at` field; complementary
+- `gh secret set` — actual write-side for GHA secrets; bootstrap is read-only for that storage type
+- `op signin` / `op item create` — actual write-side for 1Password; V2 adapter would call these
+
+## Override paths
+
+- `SKIP_SECRETS_BOOTSTRAP=1` env var (logged) — bypass the skill
+  entirely; rare, not for normal work
+- `--storage-types env,github_actions_secret` — limit dispatch to a
+  subset of types (useful for testing)
+- `--secret SLACK_WEBHOOK_ACTIVITY` — check just one secret by name
+
+## Refs
+
+- bassclef#461 — issue this skill closes (WU-2 of 2026-05-04 bet)
+- bassclef#462 — sibling: bassclef-platform.yml provides storage_default
+- standards/secrets-lifecycle.md — secret lifecycle semantics
+- standards/bassclef-platform.md — XDG path convention
+- substrate.secrets.md — manifest read
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/skill/SKILL.md

@@ -0,0 +1,304 @@
+---
+tier: lite
+name: skill
+description: "Compose a new bassclef skill from idea to conforming SKILL.md. Runs the taxonomy gate (skill / rule / hook / luminary?). Generates a verb-first plain-language description. Scaffolds the frame. Pre-validates against the live clarity gate."
+problem: "Adding a new bassclef skill takes manual scaffolding. Frontmatter and body shape drift."
+value: "Composes a new bassclef skill from idea to conforming SKILL.md. Runs the taxonomy gate."
+inputs: [Skill idea and rough description]
+outputs: [SKILL.md file conforming to shape, Frontmatter with all required fields, Body sections]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /skill — Meta-Workflow for Skill Creation
+
+Closes the methodology+mechanism+workflow triad with `bassclef#371`
+(context-engineering rule), `bassclef#377` (skill-description-clarity
+rule), and `bassclef#382` (substrate-clarity-gate hook). Rules
+prescribe; the hook BLOCKs violations; this workflow PRODUCES
+conforming output from the start.
+
+Pre-emptive shaping beats post-hoc blocking.
+
+## When to use
+
+- Operator dispatches `/skill <name-or-purpose>` to compose a new substrate skill
+- Agent considers proposing a new skill but is unsure if a rule, hook, or luminary would be the right primitive (taxonomy-only mode answers this)
+- Existing skill description fails substrate-clarity-gate; description-only mode regenerates
+
+## When NOT to use
+
+- Modifying existing skills — that's audit territory (bassclef#373/#374/#375)
+- Creating a new rule, hook, or luminary — different surfaces, different scaffolds (taxonomy gate refuses and routes the operator)
+- Auto-generating skill body content — workflow scaffolds the frame; operator writes substance
+
+## Usage
+
+```
+/skill <name-or-purpose>            → interactive: taxonomy gate → full SKILL.md draft
+/skill <name> --taxonomy-only       → just answers "skill / rule / hook / luminary?"
+/skill <name> --description-only    → just generates the description per bassclef#377
+/skill <name> --full                → full SKILL.md scaffold (default for new skills)
+```
+
+## The taxonomy gate (the hardest check)
+
+Before generating, workflow asks itself the four-quadrant question
+and surfaces the answer to the operator:
+
+| If the thing... | Use |
+|----------------|-----|
+| Loads into every conversation as persistent context (do/don't) | **rule** in `.claude/rules/` |
+| Mechanically enforces at write/edit time (BLOCK on violation) | **hook** in `.claude/hooks/` |
+| Provides bounded perspective for design/architecture decisions | **luminary** in `.claude/luminaries/` |
+| Is a composable procedure with clear input + output, dispatchable by operator | **skill** in `.claude/skills/` |
+
+If multiple match: surface the choice to operator. Default to **skill**
+only when ALL of:
+
+- Input/output is clearly procedural (verb-noun shape: "compose X", "audit Y", "dispatch Z")
+- Operator would dispatch it more than once
+- The work has a clear endpoint, not "always-on" enforcement
+
+If the thing is "always-on enforcement" → it's a **rule** (loaded as
+context) or **hook** (mechanical). If the thing is "perspective for
+decisions" → it's a **luminary**. INSTEAD of writing a skill, route
+to the right primitive.
+
+## Procedure
+
+### Step 1 — Taxonomy gate
+
+Ask the four-quadrant question. Default to skill ONLY when the test
+above passes. If routing to rule/hook/luminary, output:
+
+```
+TAXONOMY ROUTING:
+  Input:    <name-or-purpose>
+  Decision: <rule | hook | luminary>
+  Why:      <one-sentence reason>
+  Next:     <where to go — pointer to rule/hook/luminary creation pattern>
+```
+
+Operator decides whether to proceed with the routed primitive or
+override taxonomy and force a skill.
+
+### Step 2 — Generate description
+
+If taxonomy = skill, run:
+
+1. **Compose with `/value-prop` tweet mode** for the verb-first claim + sharpener (≤280 chars target)
+2. **Compose with `/kiss words` mode** to substitute jargon for plain-language alternatives
+3. **Verify against bassclef#377 rule format**: `<verb> <outcome>. <one-line how>. <one-line why-distinct>.`
+
+INSTEAD of reimplementing description generation, this skill DISPATCHES
+to the existing skills. Output is "/value-prop tweet" + "/kiss words"
+applied in sequence.
+
+### Step 3 — Scaffold the frame (per ADR-044 unified template)
+
+Default frame per ADR-044. This supersedes ADR-040 D4 and the prior /skill scaffold.
+
+<!-- FKGL-EXEMPT: ADR-044 spec content — required substrate contract -->
+
+**Frontmatter fields:**
+- `name` — use lowercase, numbers, and dashes. Gerund form preferred per Anthropic.
+- `description` — from Step 2. Up to 280 chars. Third person. Both what and when. Pushy trigger.
+- `tier` — one of upstream, lite, standard, or ultra per ADR-043.
+- `maturity` — one of alpha, beta, stable, or hardened per ADR-043. Optional. Defaults to stable.
+- `user_invocable`, `disable_model_invocation` — Anthropic Claude Code convention.
+- `modes` / `tiers` / `sizes` — YAML list when applicable. Mirror inline in description per bassclef#535.
+- `composes_with` — YAML list. Resolves to real skills per substrate-clarity-gate.
+- `depends_on` — YAML list. Advisory in V1.
+
+**Body sections in order:**
+
+1. `# /skill-name` — H1 with the slash command form.
+2. `## What you get` — outcome opener written in past tense as if shipped.
+3. `## When to use it` — discriminator that names the primary persona per Cooper.
+4. `## When NOT to use` — anti scope. Names sibling skills per Krug.
+5. `## FAQ` — 4 to 6 questions with 2-3 sentence answers.
+6. `## Details below the fold` — runnable protocol. Numbered steps with feedback loops.
+7. `## Examples` — input and output pairs. Required when the skill produces prose or code the reader will ship.
+8. `## Anti-patterns and INSTEAD` — required table. At least 3 rows.
+9. `## Composes with` — bullet list of skills this one runs or extends.
+10. `## Distinct from` — bullet list of adjacent skills. Each entry names the discriminator.
+11. `## Rules` — self check bullets.
+12. `## Test cases` — evaluation prompts. Required when body is over 100 lines OR skill ships to bassclef-lite.
+13. `## Sources read` — evidence trail per bassclef#559.
+14. `## Why this skill exists` — rationale.
+
+**Progressive disclosure per Anthropic:**
+- When SKILL.md approaches 500 lines, split detail into `.claude/skills/<slug>/references/<domain>.md`.
+- Reference files must be one level deep from SKILL.md.
+- Reference files longer than 100 lines carry a table of contents at top.
+- Executable scripts live at `.claude/skills/<slug>/scripts/`.
+
+**Prose disciplines the scaffold owes (enforced at Step 4):**
+- FKGL grade 8-9 for 80% of prose. Ceiling grade 10 per ADR-040 D4 kept alive by ADR-044.
+- Avoid compound nouns not in the substrate allowlist per `standards/bassclef-internal-jargon.md`.
+- Plain English at grade 8-9 per bassclef#790.
+
+<!-- /FKGL-EXEMPT -->
+
+The frame is structural. You write the content.
+
+### Step 4 — Pre-validate the full clarity chain (ADR-044)
+
+Before writing the file, `/skill` runs the draft through the full clarity chain. Three hooks fire in order. Any BLOCK returns the draft to Step 2 for description work or Step 3 for body work.
+
+```bash
+INPUT_JSON=$(jq -n --arg fp "$FILE_PATH" --arg c "$DRAFT_CONTENT" \
+  '{tool_name: "Write", tool_input: {file_path: $fp, content: $c}}')
+
+# Layer 1 — substrate-clarity-gate (frontmatter + description + INSTEAD blocks)
+printf '%s' "$INPUT_JSON" | bash .claude/hooks/substrate-clarity-gate.sh || exit 2
+
+# Layer 2 — skill-body-grade-gate (FKGL grade 8-9 for 80% of prose; ceiling 10)
+printf '%s' "$INPUT_JSON" | bash .claude/hooks/skill-body-grade-gate.sh || exit 2
+
+# Layer 3 — compound-noun-scrub (allowlist per standards/bassclef-internal-jargon.md)
+printf '%s' "$INPUT_JSON" | bash .claude/hooks/compound-noun-scrub.sh || exit 2
+```
+
+Prior /skill Step 4 ran only Layer 1. Layers 2 and 3 fired post-facto at Write time, so drafts often produced a BLOCK the operator saw after the file was ready. ADR-044 wires all three into the workflow so the draft is clean before the Write call.
+
+What the chain checks on a SKILL.md.
+
+Layer 1 runs `substrate-clarity-gate`:
+
+| Check | Tier | Source |
+|---|---|---|
+| Frontmatter required fields (name + description) | BLOCK | bassclef#862 Gap 1 |
+| Frontmatter recognized fields | WARN | bassclef#862 Gap 1 |
+| `composes_with:` names resolve to real skills | BLOCK | bassclef#862 Gap 3 |
+| `depends_on:` names resolve | ADVISORY | bassclef#862 Gap 3 |
+| Description ≤280 chars | BLOCK | bassclef#377 |
+| Description verb-first opener | BLOCK | bassclef#377 |
+| Description in plain English (no bassclef jargon) | BLOCK | bassclef#496 |
+| Body INSTEAD block discipline — every DON'T or NEVER or AVOID paired with INSTEAD within 5 lines | BLOCK | bassclef#371 / bassclef#1249 |
+| ADR-044 required sections present (V1 advisory) | ADVISORY | ADR-044 |
+
+Layer 2 runs `skill-body-grade-gate`:
+
+| Check | Tier | Source |
+|---|---|---|
+| FKGL grade 8-9 for 80% of prose; ceiling 10 per sentence | BLOCK | ADR-040 D4 kept alive by ADR-044 + bassclef#790 |
+| FKGL-EXEMPT blocks honored for structured spec content | pass-through | ADR-040 D4 |
+
+Layer 3 runs `compound-noun-scrub`:
+
+| Check | Tier | Source |
+|---|---|---|
+| Hyphenated compounds outside allowlist BLOCK | BLOCK | standards/bassclef-internal-jargon.md + bassclef#382 |
+| Standard tech vocab in allowlist passes | pass-through | allowlist |
+
+Three outcomes:
+
+- **Hook PASSES (exit 0, no ADVISORY)**: write file (or surface for operator review + commit)
+- **Hook ADVISORY (exit 0, ADVISORY message)**: surface message + ship anyway (operator decides)
+- **Hook BLOCKs (exit 2)**: surface the BLOCK message + iterate (return to Step 2 for description; return to Step 3 + revise body content for INSTEAD-pairing)
+
+INSTEAD of operator discovering the violation post-write, the workflow
+catches it before write. The hook is bassclef-internal; bypassing it
+defeats the whole point of the workflow.
+
+The body INSTEAD-block check uses the same shape as the rule + luminary
+surfaces (substrate-clarity-gate.sh lines 491-540): every negation
+trigger word requires a literal `INSTEAD:` substitute within 5 lines.
+Allowlist grandfathers 42 existing skills with 60-day grace through
+2026-08-18 per bassclef#1249.
+
+### Step 5 — Output for operator review
+
+```
+DRAFT skill: <path>
+
+<full SKILL.md content>
+
+Pre-validation: PASS / ADVISORY / BLOCK
+Action:         operator commits OR rejects
+```
+
+Workflow does NOT auto-commit. Operator reviews, edits if needed,
+then `git add` + `git commit`.
+
+## Args reference
+
+| Arg | Mode | Use |
+|-----|------|-----|
+| `<name-or-purpose>` | full (default) | Interactive: taxonomy gate → description → frame → pre-validate |
+| `--taxonomy-only` | taxonomy | Just answers "skill / rule / hook / luminary?" without scaffolding |
+| `--description-only` | description | Just generates the description per bassclef#377; useful for fixing existing skills (operator-owned) |
+| `--full` | full | Same as default; explicit for scripting |
+
+Unknown args rejected with a helpful message; the workflow does NOT
+silently proceed with defaults.
+
+## Composes with
+
+- `/value-prop` (tweet mode) — verb-first ≤280-char claim + sharpener
+- `/kiss` (words mode) — plain-language substitution
+- `.claude/hooks/substrate-clarity-gate.sh` — live pre-validation gate
+- `.claude/rules/skill-description-clarity.md` — per-surface clarity rule
+- `.claude/rules/context-engineering.md` — meta-rule
+
+## Distinct from
+
+- `/promote` — proposes promoting an APP-level pattern to bassclef (substrate); this workflow creates a NEW substrate skill from scratch
+- `/new-feature` — scaffolds a feature chain (canvas → spec → issue → branch); not a new substrate primitive
+- `/value-prop` — generates a value proposition for a ticket/goal/feature; this workflow USES /value-prop as one input but produces a full SKILL.md
+
+## Rules
+
+- Workflow NEVER auto-commits. Output is a draft for operator review.
+- Workflow NEVER modifies existing skills. New files only.
+- Workflow NEVER scaffolds rules, hooks, or luminaries — taxonomy gate routes to those primitives but doesn't generate them (separate concerns; deferred to v1).
+- Workflow NEVER auto-generates skill body content (Procedure, examples, etc.). Frame-only output; operator writes substance.
+- Workflow ALWAYS pre-validates against the live `substrate-clarity-gate.sh` hook before writing.
+- Workflow ALWAYS includes `## Sources read` placeholder; operator fills in.
+- Workflow ALWAYS surfaces the taxonomy decision to the operator, even when routing isn't ambiguous.
+
+## Sources read
+
+- bassclef#390 — the bassclef-evolution issue this skill closes
+- bassclef#382 — substrate-clarity-gate hook (live; pre-validation surface)
+- bassclef#377 — skill-description-clarity rule (per-surface enforcement target)
+- bassclef#371 — context-engineering rule (meta-rule)
+- `.claude/skills/value-prop/SKILL.md` — compose-with for description
+- `.claude/skills/kiss/SKILL.md` — compose-with for plain-language substitution
+- `.claude/hooks/substrate-clarity-gate.sh` — live pre-validation
+- `chronicle/2026-05-01c-substrate-clarity-gate.md` — predecessor (gate ships; this skill closes the loop)
+
+## Why this skill exists
+
+Three primitives existed before this skill:
+
+1. bassclef#371 (context-engineering rule) — meta-discipline
+2. bassclef#377 (skill-description-clarity rule) — per-surface rule
+3. bassclef#382 (substrate-clarity-gate hook) — mechanical enforcement
+
+All three react to violations. None of them produces conforming output
+from the start. Operators (and agents) wrote new skills by copying
+existing skills, which copied whatever shape the source had —
+verbose, jargon-laden, unclear scope, missing INSTEAD discipline.
+
+Even with rules loaded into every conversation, agents rationalized
+"this is what existing skills look like" and shipped non-conforming
+output. The audit at bassclef#382 closeout revealed 36 of 61 existing
+skills (59%) violate length or verb-first checks.
+
+Methodology + mechanism + workflow is the SENTINEL_bassclef_pattern made
+complete. The workflow is the positive-direction primitive — the
+shaper of new skills, with the rules loaded into its own context and
+the hook as its pre-validation surface. Engineers + operators now
+have a single dispatch (`/skill <name>`) to produce conforming
+output, not a manual copy-and-edit loop.
+
+INSTEAD of "copy an existing SKILL.md and hope," dispatch `/skill`
+and let the workflow do the shaping work. Output is conforming by
+construction.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/dist/lite/.claude/skills/smoke-test/SKILL.md

@@ -0,0 +1,100 @@
+---
+tier: lite
+name: smoke-test
+description: "Smoke test for deployed apps \u2014 health, auth redirect, critical API paths. Pass/fail gate, not a persona journey. Renamed from /test-e2e on 2026-04-15 to disambiguate from /synthetic-user."
+problem: "Deploys ship without a post-release check. Broken auth or a 500 on a critical path lands in prod."
+value: "Smoke test for deployed apps \u2014 health then auth redirect then critical API paths."
+inputs: [App URL or subdomain]
+outputs: [Pass/fail per check, Gate signal, Log per failing check]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# End-to-End Smoke Test
+
+Two-layer verification: automated tests first, then manual checks for what
+automation can't cover (visual rendering, interactive flows, auth completion).
+
+## Procedure
+
+### Step 0: Automated Smoke Tests (ALWAYS run first)
+
+Run the project's E2E test suite against local or production:
+
+```bash
+# Against local dev server (must be running)
+npx vitest run src/__tests__/e2e-smoke.test.ts
+
+# Against production (set base URL)
+E2E_BASE_URL=<production-url> npx vitest run src/__tests__/e2e-smoke.test.ts
+```
+
+If any fail → run `/diagnose` before proceeding to manual checks.
+
+### Step 1: Health Check
+
+```bash
+curl -s <app-url>/api/health | python3 -m json.tool
+```
+
+Expected: healthy status with all dependency checks passing.
+
+### Step 2: Auth Flow (requires browser)
+
+- Unauthenticated request → redirects to sign-in
+- Sign-in page renders correctly
+- After sign-in → redirects to main page (not stuck on spinner)
+- User identity visible (name, role)
+- Sign out → returns to sign-in
+- Re-sign-in works without errors
+
+### Step 3: Core Pages (requires auth)
+
+For each user-facing page:
+- Page loads without console errors
+- Data renders (not empty state when data exists)
+- Interactive elements respond (filters, pagination, navigation)
+- Click-through paths work (list → detail → back)
+
+### Step 4: API Routes
+
+For each API endpoint:
+- Protected routes require auth (401/403 without session)
+- Response shape matches expected contract
+- Pagination works if applicable
+
+### Step 5: Data Pipeline Verification
+
+Verify the backend pipeline is producing current data:
+- Check record counts by source/type
+- Check recent job runs and their status
+- Verify no stuck or failed jobs
+
+## Pass Criteria
+
+- Step 0 (automated): all tests pass
+- Steps 1-5 (manual): all checks pass
+
+Any failure → run `/diagnose` before fixing.
+
+## Maintenance
+
+When adding a new page or API route, update the E2E smoke test file:
+- New page → add auth redirect test
+- New API route → add auth gate test + response shape test
+- New public route → add 200 status test
+
+The pre-build hook reminds you; the pre-commit hook warns if you forget.
+
+## App-Specific Override
+
+If your project has a `.claude/skills/smoke-test.md` (or `test-e2e/SKILL.md`),
+it should extend this template with:
+- Specific URLs (production, staging, local)
+- Specific pages and their expected content
+- Specific API endpoints and response shapes
+- Specific pipeline verification commands (SSH, DB queries)
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.