@thebassclef/lite 0.0.1 → 0.1.0

package/substrate/.claude/skills/howdoi/SKILL.md

@@ -0,0 +1,105 @@
+---
+tier: lite
+name: howdoi
+description: Run an LLM-assisted intent search over bassclef skills and rules for an adopter goal. Two modes — search (top matches) and compose (matches plus suggested chains). Ranks by semantic fit; cites what each match does.
+problem: "Adopters know what they want to do but not which bassclef skill or rule fits."
+value: "One question in. A short list of the skills and rules that match your goal."
+inputs: [A one-sentence goal in plain English]
+outputs: [Ranked list of matching skills and rules, One-line reason per match]
+user_invocable: true
+disable_model_invocation: false
+modes: [search, compose]
+composes_baseline: [ash-maurya, alan-cooper]
+---
+
+# /howdoi
+
+## What you get
+
+Ask "how do I add auth?" or "how do I test my API?" or "which skill drafts a value prop?". I grep bassclef's skills, rules, and standards for your keywords, use Claude to rank the top 3 matches, and explain what each returns and why it matches. In `compose` mode, I also suggest 1-3 skill chains when your goal spans multiple skills.
+
+Modeled on the Python `howdoi` CLI (github.com/gleitz/howdoi) which searches Stack Overflow from the terminal — same shape, adapted to bassclef.
+
+## When to use it
+
+Any time you know what you want but have not identified the skill yet. New adopters use it for signup-time questions ("how do I add auth?"). Returning adopters use it to recall a skill name ("which skill drafts a value prop again?"). Mid-flow, run it when you finish one skill and need to pick the next ("I just ran /decompose — what's next?").
+
+Skip it when the intent is obvious. If you already know the skill name, run the skill directly. `/howdoi` earns its cost on ambiguous intents.
+
+## FAQ
+
+### What's the difference between search and compose?
+
+`search` (default) returns the top 3 matches with a one-line explanation of what each does. `compose` returns the same top 3 plus 1-3 suggested chains when the goal spans multiple skills. Use `search` when you want a single skill; use `compose` when you're planning a workflow.
+
+### How does the ranking work?
+
+Two stages. Stage 1 greps `.claude/skills/*/SKILL.md`, `.claude/rules/*.md`, and `standards/*.md` for keywords Claude extracts from your intent (3-5 keywords). Grep returns up to 20 candidates. Stage 2 asks Claude to score each candidate 0-10 for semantic fit against your intent. Top 3 come back with a one-line why-it-matched.
+
+Grep is the fast filter; Claude is the semantic ranker.
+
+### What if the top match is wrong?
+
+Read the top 3, not just #1. Each match carries a one-line what-it-does + why-it-matched. If none fit, rerun `/howdoi` with a different intent phrasing — the ranking is sensitive to how you frame the goal.
+
+If you keep missing, file a ticket. The gap probably means either a skill description is too vague or a skill does not yet exist for the goal.
+
+### Does compose mode always suggest chains?
+
+No. Compose mode asks Claude "does this intent span multiple skills?" and returns chains only if the answer is yes. Single-skill goals return just the top 3 matches, same shape as search mode.
+
+### Can /howdoi call other skills for me?
+
+No. `/howdoi` surfaces matches; you decide what to run. The value is discovery, not dispatch.
+
+## Details below the fold
+
+### Procedure
+
+1. Ask for the intent — one sentence or a paragraph.
+2. Claude extracts 3-5 keywords (auth, schema, test, deploy, etc.).
+3. Grep runs across `.claude/skills/*/SKILL.md`, `.claude/rules/*.md`, `standards/*.md`. Up to 20 candidates.
+4. Claude scores each candidate 0-10 for semantic fit. Returns top 3.
+5. Format output — match name, path, one-line what-it-does, why-it-matched score.
+6. In `compose` mode only — Claude checks whether the intent spans multiple skills. If yes, propose 1-3 chains with rationale.
+
+### Output shape
+
+```markdown
+# /howdoi — matches for "<your intent>"
+
+## Top matches
+
+1. **`/skill-name`** (`.claude/skills/skill-name/`) — description. Match: N/10. Why: <why it matched>.
+2. ...
+3. ...
+
+## Suggested chains (compose mode only)
+
+**Chain A — <name>:**
+`/X` → `/Y` → `/Z`
+
+Rationale: <why this sequence fits the goal>.
+```
+
+### Anti-patterns this skill prevents
+
+- Adopter gives up on discovery — grep alone misses semantic matches ("add auth" will not grep-match `/security-review` reliably). INSTEAD: LLM rank surfaces the fit.
+- Wrong-skill invocation — adopter picks a skill that looks close but does something else. INSTEAD: top 3 with what-it-does explanations lets adopter pick with context.
+- Missing composition — adopter picks one skill when the goal needs a chain. INSTEAD: `compose` mode surfaces the chain shape.
+- Over-fitting to grep — grep is a fast filter, not the final answer. INSTEAD: LLM rank considers what each skill actually does.
+
+### Refs
+
+- Ticket #654 — this skill's filing (renamed from `/i-want-to` to `/howdoi` 2026-07-07)
+- Ticket #660 — CI/TDD nudge (split from this skill's original scope)
+- Bet 2026-07-07a — this skill's ship vehicle
+- Python `howdoi` CLI — github.com/gleitz/howdoi (naming precedent)
+- `.claude/rules/skill-composition-declarations.md` — the composability discipline this skill surfaces
+- `/skills` — browse-mode alternative to search
+- `.claude/luminaries/ash-maurya.md` — adopter voice framing
+- `.claude/luminaries/alan-cooper.md` — persona-goal anchor
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/ia-model/SKILL.md

@@ -0,0 +1,108 @@
+---
+tier: lite
+name: ia-model
+description: Build information architecture from entity inventory + task flows. Derives nav structure, labeling, and screen map from objects.
+problem: "Screens get designed before the nouns behind them are named. Nav drifts across pages."
+value: "One entity map that drives every downstream screen. Nav stays clean because the model is clean."
+inputs: [Task flows from spec, Entity inventory from decompose]
+outputs: [Entity model diagram, Navigation shape, Screen inventory]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Information Architecture — Entity-Driven
+
+Build the IA from entities and their relationships. For data-heavy operator tools,
+the IA is entity-driven — screens derive from objects, not content hierarchies.
+
+## When to Use
+
+- After `/jtbd-tasks` and `/task-scenarios` — you have task flows and stories
+- When navigation feels wrong or pages overlap in purpose
+- When adding a new entity (new database model, new concept)
+- When the user says "I don't know where to find X" or "these pages feel redundant"
+- UX fitness review flags drift (new entities without UI surface, nav doesn't match)
+
+## Method: Object-Oriented UX (OOUX)
+
+### Step 1: Entity Inventory
+
+List every object the system represents:
+
+| Entity | Attributes | Relationships | UI Surface |
+|--------|-----------|---------------|------------|
+| ... | ... | ... | /path |
+
+### Step 2: Entity Relationship Map
+
+Draw the relationships (Mermaid ERD or graph).
+
+### Step 3: Screen Derivation
+
+**Each primary entity gets a list view and a detail view.** Secondary entities appear within their parent's views. This is the core OOUX principle.
+
+| Entity | List View | Detail View | Appears In |
+|--------|-----------|-------------|------------|
+| ... | /path | /path/[id] | ... |
+
+### Step 4: Navigation Structure
+
+Derive nav from the screen map. Apply Peter Morville's IA framework:
+- **Organization**: How are screens grouped?
+- **Labeling**: What do we call each nav item? Match the user's mental model.
+- **Navigation**: Primary nav (always visible) vs secondary (contextual).
+- **Search**: When is filtering better than browsing?
+
+### Step 5: Apply LATCH
+
+5 ways to organize information — pick the right one per context:
+- **L**ocation: geographic grouping
+- **A**lphabet: alphabetical (rarely useful)
+- **T**ime: chronological (recent first)
+- **C**ategory: by type or classification
+- **H**ierarchy: by importance or score
+
+## Output Format
+
+```markdown
+## Entity Inventory
+[table]
+
+## Entity Map
+[Mermaid diagram]
+
+## Screen Map
+[table: entity → list view, detail view, appears in]
+
+## Navigation Structure
+[primary nav, contextual nav, future nav]
+
+## LATCH Analysis
+[which organization scheme for which context]
+
+## Gap Analysis
+- Entities without UI surfaces
+- Screens without clear entity ownership
+- Nav items that don't map to entities or jobs
+```
+
+## Component Naming Convention
+
+UI components should be **named after domain objects**, not generic UI concepts:
+- `DealCard` not `Card`
+- `ScorePills` not `BadgeGroup`
+- `ThesisFilter` not `TabGroup`
+
+## Next Step
+
+Feeds into `/interaction-design` (state diagrams, sequence diagrams).
+
+## References
+
+- Sophia Prater, OOUX methodology (ooux.com)
+- Peter Morville & Louis Rosenfeld, *Information Architecture for the World Wide Web*
+- Abby Covert, *How to Make Sense of Any Mess*
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/interaction-design/SKILL.md

@@ -0,0 +1,112 @@
+---
+tier: lite
+name: interaction-design
+description: IA + task flows → interaction design — state diagrams, sequence diagrams, user flows. Final step in the UX translation chain.
+problem: "Nav and entities are drawn but the flow between screens is not. Devs invent transitions."
+value: "State diagrams and sequence diagrams that name every screen transition and API call."
+inputs: [IA model plus task flows]
+outputs: [State diagrams, Sequence diagrams, User flow overview]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# Interaction Design — State + Sequence + Flows
+
+Translate IA and task flows into formal interaction specifications.
+Final layer: JTBD → HTA → IA → **Interaction Design**.
+
+## When to Use
+
+- After `/ia-model` — entity map and screen map exist
+- Before building UI — need to specify states, transitions, edge cases
+- When a flow feels "off" — formalize it to find the gap
+- When handing off to implementation — engineers need state machines, not wireframes
+
+## Method 1: UML State Diagrams
+
+**The most rigorous tool.** Each screen or component mode is a state;
+user actions and system events are transitions.
+
+Use when:
+- Components with distinct modes (idle → expanded → editing)
+- Pages with conditional rendering (loading → empty → populated → filtered)
+- Async flows (idle → running → success/error)
+- Auth states (anonymous → authenticating → authenticated → expired)
+
+### Edge case checklist
+For every state diagram, ask:
+- What happens if the user **goes back** (browser back button)?
+- What happens if the user **refreshes** in this state?
+- What happens if the **session expires** while in this state?
+- What happens if **data changes** while the user is viewing it?
+- What happens on a **slow connection** (loading states)?
+- What happens on **error** (API fails, DB down)?
+
+## Method 2: UML Sequence Diagrams
+
+**Show temporal interaction** between actors: User, UI, Backend, External APIs.
+
+Use when:
+- API call chains (auth flows, multi-step wizards)
+- Async job flows (trigger → queue → worker → result)
+- Data display (page load → server component → DB → render)
+
+## Method 3: User Flows
+
+**Less formal, more communicative.** Good for stakeholder alignment.
+Flowcharts showing decision points and paths through the UI.
+
+## Method 4: Service Blueprints
+
+**Extend user flows to include backstage processes.**
+
+```
+FRONTSTAGE (user sees):     Browse → Filter → Detail → Act
+                                ↕         ↕        ↕
+BACKSTAGE (system does):    Score → Index → Enrich → Notify
+                                ↕         ↕
+SUPPORT PROCESSES:          Ingest → Classify → Deduplicate
+```
+
+## Output Format
+
+For each interaction flow:
+
+```markdown
+## Flow: [name]
+
+### State Diagram
+[Mermaid stateDiagram-v2]
+
+### Sequence Diagram (if async/multi-actor)
+[Mermaid sequenceDiagram]
+
+### Edge Cases
+- Back button: [behavior]
+- Refresh: [behavior]
+- Session expiry: [behavior]
+- Error: [behavior]
+- Slow connection: [behavior]
+
+### Traceability
+| State/Transition | HTA Task | JTBD |
+|-----------------|----------|------|
+| ... | ... | ... |
+```
+
+## The Anchoring Standard
+
+The full stack: **JTBD → HTA → UML State Diagrams → UML Sequence Diagrams**,
+with IA falling out of entity modeling in between.
+
+## References
+
+- Alan Cooper, *About Face* — Goal-Directed Design
+- Craig Larman, *Applying UML and Patterns*
+- Don Norman, *The Design of Everyday Things*
+- Jenifer Tidwell, *Designing Interfaces*
+- Jim Kalbach, *The Jobs to Be Done Playbook*
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.

package/substrate/.claude/skills/interpret-input/SKILL.md

@@ -0,0 +1,180 @@
+---
+tier: lite
+name: interpret-input
+description: "Produce a schema-validated InputArtifact from any input (text/URL/image/repo/transcript/napkin/mixed). text + repo modes work today. Other modes return schema-valid stubs (see #1427). First step of the cameo pipeline. Read-only on disk except --persist mode."
+problem: "Different sessions start with different input shapes \u2014 text or URL or image or repo or transcript."
+value: "One schema-validated artifact from any input. Downstream skills read one shape not seven."
+inputs: [Any input — text or URL or image or repo ref or transcript]
+outputs: [A schema-validated InputArtifact with kind and content]
+user_invocable: true
+disable_model_invocation: false
+modes: [text, url, image, repo, transcript, napkin, mixed]
+---
+
+# /interpret-input — Input Handler Skill
+
+First-step skill of the cameo pipeline. It takes operator input (text from phone, URLs, screenshots, repos) and returns schema-valid `InputArtifact` JSON. Downstream skills read it via the typed accessor library.
+
+This is the bassclef-side interface for the cameo fanout pipeline. Every input type maps to the same downstream payload.
+
+## When to invoke
+
+- Composer chain — `/stage <tier> "<input>"` calls this first. Operators rarely run it directly.
+- Manual fixture — `/interpret-input "<text>" --persist --slug=<custom>` saves a reference InputArtifact for tests.
+- Spot-check — see what the extractor returns for a given input before running the full chain.
+
+## What this skill is NOT
+
+<!-- FKGL-EXEMPT: technical reference table -->
+| Skill | Altitude | Output |
+|-------|----------|--------|
+| `/interpret-input` | **Input normalization** | Schema-validated InputArtifact JSON |
+| `/objectory-decompose` | OOA/D extraction | BCE matrix + actor list (consumes InputArtifact) |
+| `/stage` | Pipeline composer | End-to-end chain (dispatches /interpret-input) |
+| `/state get reference input-artifact <slug>` | Inspection | Reads existing InputArtifact via accessor |
+<!-- /FKGL-EXEMPT -->
+
+## Procedure
+
+The skill dispatches `scripts/interpret-input.sh <source> [args]`. It writes JSON to stdout, or persists to `docs/input-artifacts/<slug>.json` with `--persist`.
+
+### Usage
+
+<!-- FKGL-EXEMPT: CLI reference -->
+```bash
+bash scripts/interpret-input.sh "<source>" [--type=auto|text|url|image|repo|transcript|napkin|mixed] [--persist] [--slug=<slug>]
+```
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--type=<type>` | `auto` | Override auto-detection |
+| `--persist` | off | Write to `docs/input-artifacts/<slug>.json` (validated by state-validate.sh) |
+| `--slug=<slug>` | auto-generated | Override slug; useful for memorable fixtures |
+<!-- /FKGL-EXEMPT -->
+
+### Examples
+
+<!-- FKGL-EXEMPT: CLI examples -->
+```bash
+# Text from mobile paragraph (auto-detected as text):
+bash scripts/interpret-input.sh "Dramatically simplify and delightfully surface deals..." --persist --slug=2026-04-27-your-app-rework
+
+# URL (auto-detected):
+bash scripts/interpret-input.sh "https://example.com/spec.html"
+
+# Local repo (auto-detected via .git/ presence):
+bash scripts/interpret-input.sh /path/to/local/repo
+
+# GitHub URL as repo (must override; URL prefix wins auto-detect):
+bash scripts/interpret-input.sh https://github.com/your-org/your-app --type=repo
+
+# Stub mode for image (image extraction not yet implemented):
+bash scripts/interpret-input.sh "/path/to/screenshot.png" --type=image
+
+# Force transcript mode (auto-detection cannot tell):
+bash scripts/interpret-input.sh "speaker-tagged-prose..." --type=transcript
+```
+<!-- /FKGL-EXEMPT -->
+
+### Auto-detection
+
+With `--type=auto` (default), the wrapper inspects the source:
+
+<!-- FKGL-EXEMPT: regex reference list -->
+- `^https?://` → `url` (use `--type=repo` for github.com URLs you want walked as a repo)
+- `\.(png|jpg|jpeg|gif|webp|svg)$` → `image`
+- `\.git$` → `repo`
+- Local directory containing `.git/` → `repo` (walks the repo)
+- else → `text`
+<!-- /FKGL-EXEMPT -->
+
+Override auto-detection when it guesses wrong. Common cases: a transcript that looks like prose. A napkin the wrapper reads as a regular image. A github URL you want walked as a repo, not fetched as a page.
+
+### Intent paragraph (optional)
+
+If the source carries an intent, put it on the InputArtifact `intent` field. Plain text. Downstream composers (`/launch`, `/stage`, `/riff-prototypes`) call `/pick-luminaries` to match the intent against the luminary catalog. Adopters who load `/extract-intent` via `additionalDirectories` get richer signal. Bassclef core stays unaware of that override.
+
+### Output
+
+Without `--persist` (default): pretty-printed JSON to stdout. Exit 0 on success.
+
+With `--persist`: JSON written to `docs/input-artifacts/<slug>.json`. Stdout prints the path. The state-validate.sh PreToolUse hook checks the file against `standards/state-spine/schemas/input-artifact.schema.json` on write.
+
+## Mode status
+
+Two modes work today. Five return schema-valid stubs pending #1427.
+
+<!-- FKGL-EXEMPT: mode reference table -->
+| Mode | Status | Behavior |
+|---|---|---|
+| `text` | works | Identity — `extracted_text = source`; URL regex for `external_urls` |
+| `repo` | works | Walks local git dir or clones URL; populates `entities_seen`, `actor_candidates`, `boundary_objects`, `readme_excerpt`, `title`. Falls back to a stub if the path cannot be resolved. |
+| `url` | not yet | Target — fetch + readable text scrape (see #1427) |
+| `image` | not yet | Target — vision-based UI extraction (see #1427) |
+| `transcript` | not yet | Target — speaker-tagged actor mapping (see #1427) |
+| `napkin` | not yet | Target — hand-drawn diagram extraction (see #1427) |
+| `mixed` | not yet | Target — compose multiple extractors (see #1427) |
+<!-- /FKGL-EXEMPT -->
+
+Stubs are still schema-valid InputArtifacts. The current stub value is `extracted_text: "deferred to Phase C"` — a legacy marker string that #1427 will update. Downstream consumers should not crash on it. They may surface a warning that BCE extraction will be empty.
+
+### Repo extractor heuristics
+
+The repo extractor walks the directory. It populates `structural_hints`:
+
+<!-- FKGL-EXEMPT: extractor field reference -->
+- **`title`**: first H1 in README, or repo dirname
+- **`readme_excerpt`**: first 30 lines of README.md (or .MD/.rst/.txt)
+- **`entities_seen`**: Prisma model names + directory-pattern heuristic (a directory with ≥3 children whose name is plural-ish — e.g. `skills/` → `skill`, `discoveries/` → `discovery`, `canvases/` → `canvas`)
+- **`actor_candidates`**: role/auth keywords grep across source (admin, owner, operator, viewer, editor, member, customer, etc.)
+- **`boundary_objects`**: Next.js routes (`app/**/page.{ts,tsx}` and `pages/**/*.{ts,tsx}`) + API endpoints (`app/api/**`, `pages/api/**`)
+<!-- /FKGL-EXEMPT -->
+
+Output ships even when extraction is partial. Empty arrays mean no signal found. Downstream agents decide whether partial is enough.
+
+### Repo extractor: source resolution
+
+<!-- FKGL-EXEMPT: source resolution table -->
+| Source | Resolution |
+|---|---|
+| Local directory containing `.git/` | Use directly |
+| `<path>` passed with `--type=repo` and exists | Use directly |
+| `https://github.com/...` URL with `--type=repo` | `git clone --depth=1` to temp dir; cleanup after |
+| Source cannot be resolved (path missing, clone failed) | Returns a stub artifact |
+<!-- /FKGL-EXEMPT -->
+
+## Rules
+
+- **Read-only by default** (no `--persist`); side effect is opt-in.
+- **Schema validation is the gate** — `--persist` writes go through state-validate.sh. Invalid InputArtifacts BLOCK the write.
+- **No raw input in downstream skills** — `/objectory-decompose` MUST receive a path to an InputArtifact, not raw text.
+- **Slug uniqueness** — operator slugs override auto-generated. Do not overwrite existing fixtures. The wrapper errors if `--persist` would overwrite.
+- **Stub artifacts are valid** — downstream must handle the marker string (`extracted_text == "deferred to Phase C"`) as empty extraction + a warning.
+
+## Skipping / Aborting
+
+- Empty source: exit 2.
+- Unknown type: exit 2 (not in the type enum).
+- Schema validation failure on `--persist`: state-validate.sh BLOCKs. Surface to operator.
+- Existing slug + `--persist` would overwrite: exit 4. Operator must pass `--slug=<new>`.
+
+## Relationship to other skills + standards
+
+- `standards/input-handler-interface.md` — the interface contract this skill implements.
+- `standards/state-spine/schemas/input-artifact.schema.json` — the schema this skill produces.
+- `standards/state-spine.md` §"Storage format" — InputArtifact is a pure-JSON entity (`Shape C`).
+- `.claude/skills/objectory-decompose/SKILL.md` — primary downstream consumer.
+- `.claude/skills/preview/SKILL.md` — composer that calls this first.
+- `.claude/skills/state/SKILL.md` — `/state get reference input-artifact <slug>` reads back via accessor.
+
+## Reserved-names check
+
+`interpret-input` is NOT on `standards/reserved-skill-names.md` list.
+
+## Enforcement
+
+Methodology-level. The skill registers via bassclef-sync symlink. state-validate.sh enforces schema on `--persist` writes.
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.