@thebassclef/lite 0.0.1 → 0.1.2

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

@@ -0,0 +1,112 @@
+---
+tier: lite
+name: interaction-design
+description: "Turn IA plus task flows into interaction design \u2014 state diagrams, sequence diagrams, user flows. Final step in the UX translation chain before decompose."
+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: "Turn any input into a schema-valid InputArtifact. Modes: text, URL, image, repo, transcript, napkin, mixed. text + repo ship today. Others return valid stubs. First step of the cameo pipeline."
+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 future work.
+
+<!-- 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 |
+| `image` | not yet | Target — vision-based UI extraction |
+| `transcript` | not yet | Target — speaker-tagged actor mapping |
+| `napkin` | not yet | Target — hand-drawn diagram extraction |
+| `mixed` | not yet | Target — compose multiple extractors |
+<!-- /FKGL-EXEMPT -->
+
+Stubs are still schema-valid InputArtifacts. The current stub value is `extracted_text: "deferred to Phase C"` — a marker string a future release 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.

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

@@ -0,0 +1,209 @@
+---
+tier: lite
+name: journal
+description: "Draft a journal entry from this session's work \u2014 tuned to PE, search, and board audiences per the writing guide and brand questionnaire."
+problem: "Session work fades from memory. Insight worth sharing with PE partners or eng leaders never gets written."
+value: "Drafts a journal entry from this session's work. Tuned for PE, search, and board audiences."
+inputs: [Optional audience filter — PE or search or board]
+outputs: [Journal draft with voice per audience, Audience recommendations table]
+user_invocable: true
+disable_model_invocation: false
+requires:
+  files: [standards/writing-guide.md]
+  network: true
+---
+
+# /journal — Draft Journal Entries from Session Work
+
+Draft 3 short-form journal entries from the current session's work,
+calibrated to the operator's target audience and brand positioning.
+Publishable to LinkedIn, Substack, an internal blog, or held as
+archive.
+
+## Plain-English requirement (Phase II Trim the Fat — bassclef#559)
+
+journal entries have personal/sensory/story-driven voice (per `feedback_writing_voice` memory) — voice trumps strict rule. The substrate-clarity-gate hook treats journal entry path as ADVISORY tier: it emits notices on bassclef-internal jargon, long sentences, and passive voice but never blocks.
+
+INSTEAD of running /kiss words mechanically over draft prose: read the advisory notices and decide. Some passive voice in journal entries is fine ("the deploy was approved" reads naturally in narrative). Some long sentences carry rhythm. Pure mechanical substitution would flatten the voice.
+
+What DOES still apply: drop bassclef-internal jargon (substrate, primitive, load-bearing, composer, tier-preset). LinkedIn audiences include investors, eng leaders, board operators — none have bassclef context. If the draft uses these words, run /kiss words on those specific terms (or rewrite by hand).
+
+## Before writing
+
+1. Read `standards/writing-guide.md` — the journal-entry style guide
+2. Read the brand questionnaire from memory (if it exists) for audience,
+   tone, topics, and positioning
+3. Read the current session's chronicle entry for raw material
+4. If called after `/journal mine`: use the selected moment as primary
+   source material. Read the full chronicle for that session.
+5. Check what angles have been covered (read existing drafts in
+   `docs/operator-private/journals/`). This is **informational context, not a
+   filter** — repeating themes across posts is intentional. It builds
+   recognition. But knowing what's been said helps pick fresh angles.
+
+## Two audiences — every notable moment gets two variants
+
+Each notable decision, trade-off, or insight produces **two post variants**:
+
+### Variant A: CPTO → Board / PE / Executive Search
+
+The operator speaking to people who evaluate operating talent and back
+enterprise transformations.
+
+- **Primary audience**: PE senior partners, executive search leaders,
+  board-level decision-makers
+- **Tone**: Bezos/Jassy/Collison — calm, analytical, operator-grade
+- **Depth**: Business outcome, capital efficiency, governance model.
+  One concrete technical detail as proof, no more.
+- **Vocabulary**: "governance primitive" not "SKILL.md". "Coordination
+  framework" not "agent choreography." See writing guide.
+- **Connects to**: EBITDA, capital efficiency, operating model, scale,
+  talent leverage, risk management
+
+### Variant B: CPTO → Senior Engineers / Technical Founders
+
+The same operator speaking to people who will build or evaluate the
+technical approach.
+
+- **Primary audience**: CTOs, VP Engineering, staff+ engineers,
+  technical founders, eng managers
+- **Tone**: Thoughtful practitioner — shows the work, not just the result
+- **Depth**: Architecture decisions, trade-offs, what was tried and
+  rejected, specific patterns used. Technical enough that a senior
+  engineer learns something.
+- **Vocabulary**: Use real terms — ADRs, choreography, hooks, substrate.
+  No need to abstract. This audience knows what a pre-commit hook is.
+- **Connects to**: Engineering quality, developer experience, system
+  reliability, team velocity, technical debt management
+
+### How to pair them
+
+The same moment becomes two posts:
+- **Variant A**: "We killed three features before writing a line of code.
+  Here's why that's the highest-leverage thing a technical operator can do."
+- **Variant B**: "Our Shaper agent runs Five Whys before any spec reaches
+  Construction. Here's the gate architecture and why it caught a scope
+  creep we would have shipped."
+
+Both posts reference the same work. They land differently because they
+answer different questions: A answers "is this person a credible operator?"
+B answers "is this approach technically sound?"
+
+## Rules
+
+- **Two variants per notable moment** — label as (A: Board) and (B: Engineering)
+- **Name concepts, not implementations** in Variant A. Real terms in Variant B.
+- **Connect to enterprise economics** in Variant A. Connect to engineering
+  quality in Variant B.
+- **Bezos/Jassy/Collison tone** for Variant A. Thoughtful practitioner for B.
+- **Structure**: Hook → Setup → Body (with → arrows) → Takeaway
+- **Every post must stand completely on its own** — no "in my last post"
+  references, no series context, no callbacks. Each post works for someone
+  who has never read anything you've written before.
+- **Repetition across posts is intentional** — the LinkedIn algorithm shows
+  each post to a subset of your network. Covering the same theme from
+  different angles builds recognition. Don't avoid a topic just because
+  you've posted about it before.
+- **600-1200 words** per post
+- **3-7 posts per session** — across both variants. A session with 2 notable
+  moments produces 4 posts (2A + 2B).
+
+## Audience recommendations table (MUST — include in every draft file)
+
+Every draft file must start with a master audience recommendations table:
+
+```markdown
+| # | Variant | Title | Primary audience | Hook strength | Publish priority |
+|---|---------|-------|-----------------|--------------|-----------------|
+| 1A | Board | [title] | PE partners — "[angle]" | Strong | 1 |
+| 1B | Eng | [title] | Senior engineers — "[angle]" | Very strong | 2 |
+| 2A | Board | [title] | Board/search — "[angle]" | Medium | Hold |
+| 2B | Eng | [title] | CTOs — "[angle]" | Strong | 3 |
+```
+
+For each post, specify:
+- **Variant**: A (Board/PE) or B (Engineering)
+- **Primary audience**: PE partners, board, exec search (A) or CTOs, eng leaders, technical founders (B)
+- **Hook strength**: rate honestly. "Very strong" = contrarian or cautionary. "Strongest" = thought leadership.
+- **Publish priority**: recommended sequence with rationale, or "Hold" for article/longer form
+- **Pair notes**: which A/B posts cover the same moment — they should not publish same day
+
+End the table with:
+- **Recommended publish sequence** with rationale (alternate A/B to reach both audiences)
+- **Hold for articles** — posts that work better as longer LinkedIn articles
+- **Pairing notes** — which A and B posts are about the same moment
+
+## When a concept needs technical explanation
+
+Flag it for the /feynman skill. In the draft, mark it:
+
+```
+[FEYNMAN: concept name — for CTO sidebar]
+```
+
+After drafting all 3 posts, run /feynman on each flagged concept.
+Weave the Feynman explanation into the post or note it as a comment-thread follow-up.
+
+## Output
+
+1. Check for gaps: when was the last journal entry? Are there missed
+   sessions? **Backfill those FIRST, oldest to newest** (per session-artifacts rule).
+2. Write drafts to `docs/operator-private/journals/YYYY-MM-DD.md` with audience
+   recommendations table at the top
+3. Push drafts to the repo's journal-entry Google Doc — use `--dir` for
+   automatic chronological ordering (the script sorts by filename):
+   ```bash
+   # Batch push — script sorts YYYY-MM-DD filenames automatically
+   cd ~/src/your-org/your-app && npx tsx scripts/push-to-gdoc.ts \
+     --dir [drafts directory] \
+     --doc-id [journal_doc_id from substrate.config.md]
+
+   # Single file push (when only one new draft)
+   cd ~/src/your-org/your-app && npx tsx scripts/push-to-gdoc.ts \
+     --file [draft path] \
+     --doc-id [journal_doc_id from substrate.config.md]
+
+   # Fix out-of-order doc: clear and re-push everything sorted
+   cd ~/src/your-org/your-app && npx tsx scripts/push-to-gdoc.ts \
+     --dir [drafts directory] --replace \
+     --doc-id [journal_doc_id from substrate.config.md]
+   ```
+   Google Doc IDs (for reference — always read from substrate.config.md):
+   - Bassclef: `1f9nUSmwpFvcZhnfmYvhyNWZuElMwqfz3muWdIcwMUrA`
+   - POA: `1Gwhsh6aC6lq1jRQhGSpZ9BUNBlpdY3SNFpnIlMP97Zk`
+4. **Verify the push succeeded** — check the output for "Appended N chars"
+5. Note in the chronicle that posts were drafted and pushed
+6. If Google Doc push fails (no script, no auth): drafts stay local in
+   `docs/operator-private/journals/` AND a deferred-action entry is written so the
+   next capable session completes the push. Do not silently skip.
+
+### Deferring a failed push
+
+When the current session cannot push to the configured `journal_doc_id`
+(missing `gcloud-auth` / `google-docs-write` — typical in mobile,
+cloud-web, or a desktop session without the SA key):
+
+```bash
+TS=$(date -u +"%Y-%m-%dT%H-%M-%SZ")
+ID="${TS}-journal-gdoc-push"
+cp templates/deferred-action-template.md \
+   "docs/deferred-actions/${ID}.md"
+# Fill frontmatter:
+#   pending_action: push-journals-to-gdoc
+#   requires_capability: [gcloud-auth, google-docs-write]
+#   priority: medium
+#   origin_skill: /journal
+#   resolves_when: |
+#     Google Doc <journal_doc_id> reflects docs/operator-private/journals/ in chronological order
+# Cross-ref the draft file(s) in the body.
+git add "docs/deferred-actions/${ID}.md"
+git commit -m "chore: defer journal gdoc-push (<draft-date>)"
+```
+
+See `.claude/rules/deferred-actions.md` and
+`standards/deferred-actions-schema.md`. Silent skip violates
+`session-artifacts.md` ("silence is not deferral").
+
+## Output discipline
+
+Dispatch `/kiss words --rewrite` on your skill output before you return it. See `standards/skill-output-discipline.md` for the contract.