@thebassclef/lite 1.0.4 → 1.1.0

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

@@ -0,0 +1,228 @@
+---
+tier: lite
+name: skills
+description: "Browse the skill catalog live. Every skill grouped by discovery cluster with descriptions, modes, and key chains. Reads SKILL.md frontmatter directly so the catalog explains itself."
+problem: "Bassclef ships around 99 skills. Adopters don't know which one fits their moment."
+value: "The catalog live. Every skill grouped by discovery cluster. Descriptions optimized for scan."
+inputs: [Optional filter — cluster name or phase or keyword]
+outputs: [Skills grouped by cluster, Description per skill, Tier tag per skill]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# /skills
+
+## What you get
+
+The full catalog of every bassclef skill installed in the current repo. Grouped into six discovery clusters. Descriptions and mode variants come from each skill's frontmatter. No hardcoded list. You browse the catalog by cluster, by phase, or by named key chain.
+
+Under the clusters I show cross-references. These are skills useful in more than one cluster. Plus a phase view. Skills map to Inception, Elaboration, Construction, and Transition. Plus six named key chains that sequence skills for common goals. The chains are UX Translation, Failure, Verification, Prototype, Session Lifecycle, and Product Shaping.
+
+The catalog reads live from disk on every invocation. What you see is what your session has. When bassclef ships a new skill, the next `/skills` run picks it up. When a local skill overrides a bassclef default, the local wins.
+
+Descriptions come from each skill's frontmatter `description:` field. Modes and tiers and sizes auto-render from `modes:` / `tiers:` / `sizes:` frontmatter per bassclef#515. Cross-references and phase mapping come from `strategy/agent-choreography.md` Section 2.
+
+## When to use it
+
+Run `/skills` at session start when you are new to bassclef and want to see everything. Run it mid-session when you are planning a workflow. Run it after `bassclef-sync` pulls in a substrate update to see what changed.
+
+Skip it when you already know the skill name. When you want a specific skill, run it directly. When you want the skill matching a goal ("how do I add auth?"), run `/howdoi`. That skill ranks matches by intent instead of grouping by cluster.
+
+## FAQ
+
+### How do skills get grouped into clusters?
+
+Six clusters. Mutually exclusive by primary intent. Each skill lands in exactly one primary cluster. Skills useful in more than one cluster show up under Cross-references with a rationale.
+
+The six clusters — Strategy & Spec, Architecture & Design, Testing, Cross-cutting gates, Session lifecycle, Transition & comms. Documented in `CLAUDE.md` under "Skills — by cluster".
+
+The cluster view answers "what am I trying to do?" The phase view (secondary) answers "where in the SDLC am I?".
+
+### Where do the descriptions come from?
+
+Each `.claude/skills/*/SKILL.md` file has YAML frontmatter with `description:`. I read that field live. No hardcoded list. If you edit a description in a SKILL.md file, running `/skills` in the next session shows the update.
+
+### What are modes / tiers / sizes?
+
+Some skills expose variants — `/kiss` has modes (scope, words); `/value-prop` has sizes (tweet, brief, verbose); `/shape` has tiers (quick, light, medium, full). When a skill declares these in frontmatter as `modes:` / `tiers:` / `sizes:`, I render the list under the skill's row so you see the variants at a glance.
+
+Skills documenting variants only in body text (legacy shape) will not auto-render the suffix — that's the audit gap bassclef#515 closes.
+
+### What are the key chains?
+
+Six named chains that sequence multiple skills for common goals — UX Translation, Failure Chain, Verification Chain, Prototype Chain, Session Lifecycle, Product Shaping. Each chain lists the skills in order with a one-line note on when to run it. The chains are documented in bassclef's convention; new chains land as this catalog grows.
+
+### Does /skills modify anything?
+
+No. Read-only. It scans SKILL.md files, formats the output, and returns.
+
+## Details below the fold
+
+### Procedure
+
+**Step 1 — Scan skills.**
+
+Read every `.claude/skills/*/SKILL.md` file. For each, extract from YAML frontmatter:
+
+- `name` — the slash command
+- `description` — what it does
+- `requires` — prerequisites (cli, files, network, level) if present
+- `modes:` / `tiers:` / `sizes:` — declared variants
+
+If the project inherits bassclef via `--add-dir`, also scan the bassclef skills directory. Deduplicate by name — local overrides bassclef.
+
+**Step 2 — Cross-reference choreography.**
+
+Read `strategy/agent-choreography.md` Section 2 (Skill-to-Agent Mapping Table) to determine for each skill:
+
+- Primary agent — who typically invokes it
+- Phase — when in the SDLC it fires
+
+For skills not in the choreography table, infer phase from content or mark as "Any".
+
+**Step 3 — Format output.**
+
+Render two views — Discovery by Cluster (primary) and Phase (secondary).
+
+#### 3a: Discovery by Cluster (primary, mutually exclusive)
+
+Six clusters. Each skill lands in exactly one. Skills useful in adjacent clusters go under 3a-cross.
+
+```
+## Discovery by Cluster
+
+### Strategy & Spec — shaping what to build
+/canvas, /spec, /value-prop, /new-feature, /promote, /kiss
+
+### Architecture & Design — system, code, UX
+/architect-review, /pattern-review, /decompose, /frontend-design,
+/riff-prototypes, /tech-prototype, /ux-migration, /luminary,
+/stage, /launch, /shape, /refactor-input, /interpret-input,
+/objectory-decompose, /agent-research-spawn, /pattern-trace,
+/use-case, /user-stories, /personas, /value-prop-canvas,
+/jtbd-tasks, /task-scenarios, /ia-model, /interaction-design
+
+### Testing — verify something works
+/verify, /test-integration, /smoke-test, /visual-review,
+/visual-qa, /synthetic-user
+
+### Cross-cutting gates — fire across every phase
+/temperance, /diagnose, /quick-fix, /auto-fix, /whats-the-plan
+
+### Session lifecycle — boot, orient, end
+/autonomous, /longrun, /sprint, /whereami, /skills,
+/substrate-check, /sdlc-checkpoint, /session-log, /retro,
+/session-end, /clean-artifacts, /onboard-repo, /init,
+/state, /loop, /schedule, /roadmap-reconcile
+
+### Transition & comms — ship and tell
+/deploy-prod, /release-notes, /journal, /journal-mine,
+/journal-export, /feynman, /incident-report, /launch-preview,
+/bind-subdomain, /prototype-gallery, /provision-deploy-host,
+/secrets-bootstrap, /skill, /build, /promote, /review, /security-review
+```
+
+Include each skill's one-line description from frontmatter. When frontmatter declares `modes:` / `tiers:` / `sizes:`, render the variants inline.
+
+#### 3a-cross: Cross-references (skills in more than one cluster)
+
+Render skills useful in adjacent clusters with rationale:
+
+```
+## Cross-references
+
+- **/sprint** (primary: Session lifecycle) — also useful for Strategy & Spec
+  orientation; reads whereami + open issues + active goal to surface what's
+  next, which is itself a scope-shaping moment.
+- **/longrun** (primary: Session lifecycle) — also useful for Cross-cutting
+  gates; auto-fires /temperance + /retro + /promote at phase boundaries.
+- **/promote** (primary: Transition & comms) — also useful for Strategy &
+  Spec; promotes app-level patterns to bassclef-evolution issues.
+- **/kiss** (primary: Strategy & Spec) — also useful for Cross-cutting gates;
+  scope mode compresses scope at decision boundaries; words mode is a
+  mechanical vocabulary pass.
+- **/skill** (primary: Transition & comms) — also useful for Cross-cutting
+  gates; scaffolds new skills with the live clarity-gate check.
+```
+
+#### 3b: Phase view (secondary)
+
+Group skills by SDLC phase:
+
+```
+## Skills Catalog (N skills)
+
+### Inception
+| Skill | Description | Agent | Produces |
+|-------|-------------|-------|----------|
+
+### Elaboration
+...
+
+### Construction
+...
+
+### Transition
+...
+
+### Any Phase
+...
+```
+
+For each skill, derive Produces from the skill's content.
+
+**Step 4 — Highlight key chains.**
+
+```
+## Key Chains
+
+**UX Translation Chain** (Elaboration):
+/jtbd-tasks → /task-scenarios → /ia-model → /interaction-design
+
+**Failure Chain** (Any):
+observe failure → /temperance → /diagnose → fix → /verify
+
+**Verification Chain** (Construction):
+/temperance → build → /verify → commit → /visual-review (if UI)
+
+**Prototype Chain** (Elaboration → Construction):
+/riff-prototypes → select direction → /ux-migration → /frontend-design
+
+**Session Lifecycle**:
+/autonomous start → work → /session-log → /retro → /session-end
+
+**Product Shaping**:
+/canvas → /spec → issues → /sprint
+```
+
+**Step 5 — Show usage tips.**
+
+```
+## Tips
+
+- Run `/skills` at any time to see what's available
+- Skills fire automatically via hooks and agent choreography — you rarely need to invoke most of them by name
+- `/temperance` and `/verify` are MUST gates — they fire on every non-trivial change whether you invoke them or not
+- `/diagnose` is mandatory before any fix — the pre-build hook enforces this
+- New to bassclef? Start with `/sprint` to see current work, then `/autonomous` to understand the full system
+```
+
+### Rules
+
+- Always read SKILL.md files live — no hardcoded list
+- If a skill has `requires:` in frontmatter, show prerequisites
+- Keep output scannable — tables, not paragraphs
+- Read-only skill — this never modifies files
+
+### Refs
+
+- `CLAUDE.md` — cluster taxonomy source of truth
+- `strategy/agent-choreography.md` — phase mapping source
+- `/howdoi` — sister skill; intent-search alternative to catalog browse
+- `/luminary` — sister catalog for luminaries
+- `/hooks` — sister catalog for hooks
+- bassclef#515 — modes/tiers/sizes audit that surfaces variants in the catalog
+
+## 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/spec/SKILL.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+name: spec
+description: "Turn a canvas or issue into a structured spec. Names the What, the Why, and the acceptance list. Downstream skills read the spec as source-of-truth."
+problem: "Canvases sketch a product. Tickets ask for features. The bridge to code doesn't exist."
+value: "One spec that names the What and the Why and the acceptance list. Downstream skills read it."
+inputs: [A canvas path or issue ref or scope description]
+outputs: [Spec doc at specs/YYYY-MM-DD-slug.md, Acceptance list, Reference block]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Spec — Generate Structured Spec from Canvas or Issue
+
+Bridge the gap between product thinking (canvases) and engineering work (GitHub Issues).
+
+## ADR-consult — fire before scope confirmation (per bassclef-upstream#424)
+
+Read every relevant ADR in `architecture/decisions/` before confirming scope. If your scope deviates from any ADR's decision or constraints, surface the deviation as the first agenda item — operator decides amend-ADR vs. revise-scope.
+
+Per `.claude/rules/adr-discipline.md`. Mechanism: `adr-discipline-check.sh` fires on substantive architectural edits (wired in `.claude/settings.json` since bet 28a WU-1). The Tier 0 test for this step greps for the literal header `## ADR-consult — fire before scope confirmation` in each of `/build /launch /spec /decompose /shape /longrun`.
+
+## Input
+
+The user provides either:
+- A canvas filename from `strategy/canvases/`
+- A GitHub Issue number
+- A verbal description of what needs to be specified
+
+## Steps
+
+1. Read the source material (canvas, issue, or user description)
+2. Read `templates/spec-template.md` for the format
+3. Read `design/object-model.md` to understand existing domain objects
+4. Generate a structured spec:
+
+```markdown
+# Spec: {Feature Name}
+
+## Context
+Link to canvas or issue. Why this exists.
+
+## Requirements
+
+### Must Have
+- [ ] Requirement — Acceptance: {specific testable condition}
+
+### Should Have
+- [ ] ...
+
+### Won't Have (this round)
+- ...
+
+## Design
+- User flow (step by step)
+- Object model impact (new objects, changed objects)
+- Interface contract (API shape, component props)
+
+## Technical Approach
+- Key files to create or modify
+- Dependencies on existing code
+- Migration needs
+
+## Patterns Used
+
+(Required when spec drives Construction work. Layer 2 of bassclef#478 traceability.)
+
+| Pattern | Catalog path | Implementing file/class | Why this pattern |
+|---------|--------------|--------------------------|------------------|
+| <Name> | `patterns/<shelf>/<source>/<slug>.md` | `src/.../<file>.ts` :: `<ClassName>` | <one-line rationale> |
+
+State "No load-bearing patterns" if applicable. See `.claude/rules/pattern-annotation.md`.
+
+## Open Questions
+- Anything needing human decision before building
+
+## Steps enumerated
+
+(REQUIRED for specs that feed /build per bassclef#367. Optional for
+bassclef-evolution shaping specs.)
+
+### WU-N — <imperative title>
+**Story refs:** US-NNN
+**Branch:** feature/<goal-slug>-stack-N-<wu-slug>
+**Acceptance:**
+- [ ] <testable, inherited from story>
+**Estimated:** ~Nt turns
+```
+
+## Output
+
+Write to `specs/{YYYY-MM-DD}-{slug}.md` (or `docs/specs/` in app repos)
+
+## Rules
+
+- Every Must Have needs at least one testable acceptance criterion
+- Not "works correctly" but "returns HTTP 200 with JSON body containing dealId"
+- If source is too vague, list what questions need answering — don't invent requirements
+- Reference existing objects from the object model; flag when new objects are needed
+- When UI is involved, note that UX translation chain is needed
+- **Specs that feed /build MUST include a `## Steps enumerated` section** with `### WU-N` entries (per bassclef#367). /build's Phase 1 parser greps for this exact heading; missing it → /build refuses with exit 4. Bassclef-evolution shaping specs may omit this section with a brief note explaining why.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.