@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/.claude/skills/whats-the-plan/SKILL.md

@@ -0,0 +1,202 @@
+---
+tier: lite
+name: whats-the-plan
+description: "Declare the chain of skills you intend to run for the current task or next stretch of work. Invokable at any natural response point. Composes with /temperance (scope) and /sprint (ticket-level) \u2014 dispatch-path level."
+problem: "Multi-skill chains dispatch without declaring the plan. Operator can't audit mid-flight."
+value: "Declares the chain of skills you intend to run. Invokable before you start."
+inputs: [Current task or scope description]
+outputs: [Ordered skill chain, Rationale per step, Alternative chains]
+user_invocable: true
+disable_model_invocation: false
+---
+
+# What's the Plan
+
+Declare the sequence of skills, tool calls, and artifacts you intend
+to produce for the current task. Stated **before** execution, not
+retrospectively. Re-declared when the plan changes materially.
+
+## When to Invoke
+
+- **Operator asks**: "what's the plan?", "how are you going to tackle this?", "show me the chain"
+- **Operator types**: `/whats-the-plan`
+- **Self-invoke** (before a non-trivial chain): when the next stretch of
+  work involves ≥3 skills OR touches production code OR spans ≥1 hour.
+  This is the analogue of `/temperance` firing on the first edit — but
+  for sequencing, not scope
+- **Plan change mid-task**: when a skill output forces a swap (new
+  interface surfaces, test fails, operator redirects) — re-declare
+  with a `was → now` delta
+
+## What this skill is NOT
+
+| Skill | Operates at | Time | Output |
+|-------|-------------|------|--------|
+| `/sprint` | Ticket/scope level | Session start | Issues + time budget + iteration name |
+| `/temperance` | Approach/scope | Before edit | Right-thing + right-way questions |
+| `/whats-the-plan` | **Dispatch path** | **Any natural response point** | **Ordered skill chain + swap-points** |
+| `/chronicle` | Narrative | Session end | Retrospective log |
+
+The four compose. A typical session:
+
+```
+/sprint             → "next: finish iteration X, ~60 turns"
+/temperance         → "building Y; right thing because Z; simplest path is W"
+/whats-the-plan     → "chain: /decompose → build → /verify → commit"
+[execute]
+/chronicle          → "what happened, decisions, open threads"
+```
+
+## Procedure
+
+### 1. Read inputs
+
+Before declaring, know:
+
+- **Current task** — the thing operator just asked for, or the next
+  scope in the active iteration goal
+- **Active iteration goal** — `docs/iteration-bets/` (latest) — governs
+  what's in-scope and what stop-points exist
+- **Applicable gates** — any of: `/temperance`, `/diagnose`, `/verify`,
+  `/visual-review`, `/decompose` (per `sdlc-gates.md` and
+  `oo-ad-entry-point.md`)
+- **Relevant rules** — `artifact-ingestion.md` dictates sources-read
+  block; `design-direction.md` dictates approval-respect; other rules
+  may insert steps (e.g., `prototype-workflow.md` inserts render +
+  confirm before commit for prototype edits)
+
+### 2. Enumerate the chain
+
+List skills, tool calls, and artifact writes in execution order. Use
+`→` between steps. Group by phase if the chain crosses phases.
+
+### 3. Name swap-points
+
+A swap-point is a conditional fork: "if skill X produces finding Y,
+insert skill Z before the next step." Swap-points are where the plan
+may branch based on outputs you don't have yet.
+
+List the top 2–3 swap-points the chain is sensitive to. More than 3
+signals the chain is under-specified and needs shaping first.
+
+### 4. State stop conditions
+
+Where does this chain end? Options:
+- **Operator review point** — "stop before PR open"
+- **Gate** — "stop at /verify output; commit blocks on green"
+- **Natural boundary** — "one WS complete; next WS is separate chain"
+- **Time budget limit** — "stop at 20 turns; re-shape if incomplete"
+
+### 5. State what's NOT in this chain
+
+Adjacent work you're deliberately excluding. This is the sequencing
+analogue of `/temperance`'s "what you're NOT doing" question.
+
+## Output format
+
+```
+## Plan (YYYY-MM-DD HH:MM UTC)
+
+**Task**: [one-line description]
+**Iteration**: [goal name, or "none — ad-hoc"]
+
+**Chain**:
+1. /temperance — gate scope + approach
+2. /decompose — identify interfaces (if Construction)
+3. [build step] — edit [paths]
+4. /verify — match change type to verification
+5. commit — conventional message
+
+**Swap-points**:
+- If /decompose surfaces new cross-cutting concern → insert /pattern-review before build
+- If /verify fails visual → insert /visual-review before commit
+- If operator redirects scope → re-run /whats-the-plan with delta
+
+**Stops at**: [operator review point / gate / natural boundary]
+**Appetite**: ~N turns, ~M min
+**Not in this chain**: [adjacent work excluded]
+```
+
+## Re-declare format
+
+When the plan changes materially mid-task, emit a delta (not a full
+re-print). Material change = new skill inserted, skill removed, or
+stop-point moved. Trivial reordering within the declared chain does
+not trigger re-declare.
+
+```
+## Plan update (YYYY-MM-DD HH:MM UTC)
+
+**Was**:  /temperance → /decompose → build → /verify → commit
+**Now**:  /temperance → /decompose → /pattern-review → build → /verify → /visual-review → commit
+
+**Why**: /decompose surfaced [specific interface] — triggers
+/pattern-review swap-point. /verify scope now includes UI, pulling
+/visual-review in per post-build gate.
+```
+
+## Rules
+
+- **Declare before execute**, not after. A plan declared after the
+  chain ran is a log entry, not a plan.
+- **One plan per coherent task**, not one per turn. Multi-turn
+  execution under a single declared plan is the common case.
+- **Re-declare on material change only**, not on every adjustment.
+  Chain chatter reduces the signal.
+- **Plan must reference sources** (per `artifact-ingestion.md`) if the
+  chain involves producing a canvas, spec, ADR, or prototype. The
+  plan itself is a lightweight produce-ahead-of-execution artifact.
+- **Skill chain steps presented to operator MUST follow
+  `.claude/rules/plan-enumeration-needs-value-props.md`** — each step
+  in the chain carries a tweet (claim + why-it-matters), not a bare
+  skill name. Bare "/temperance → /diagnose → /verify" is not a plan;
+  each step needs to say what it buys.
+- **Do not declare a plan you know you won't follow**. If the chain is
+  genuinely uncertain, say so: "Plan unclear; running /temperance +
+  /diagnose first to shape." That is itself a valid plan.
+
+## Chronicle integration
+
+When the session chronicle is written, the main-task plan declaration
+SHOULD be linked or quoted. Plan → execution → reference-back is the
+loop that makes plan declaration load-bearing rather than theatrical.
+
+If the plan changed during execution, chronicle notes the delta
+(which swap-points fired, which didn't).
+
+## Operator-facing behavior
+
+When operator types `/whats-the-plan`:
+- If a plan was declared recently (same task, no material change):
+  re-display the current plan
+- If no plan exists or task has shifted: run the procedure and declare
+- If operator asks "what's the plan?" in conversation: same procedure,
+  slight framing adjustment — phrase as response, not bassclef output
+  block, but include the chain + swap-points + stops-at
+
+## Relationship to other rules
+
+- `sdlc-gates.md` — declared plan must include gate skills where
+  applicable; hook-enforced gates are not optional plan steps
+- `artifact-ingestion.md` — plans that will produce generative output
+  must name sources the chain will read
+- `design-direction.md` — plan changes after operator approval require
+  operator reconciliation, not agent-unilateral re-planning
+- `oo-ad-entry-point.md` — Construction chains that edit `src/` must
+  include `/decompose` or explicit trivial-work deferral
+- `iteration-goal-brief-completeness.md` — plans delegated to subagents
+  are briefs; this skill outputs the brief
+
+## Enforcement
+
+V1: methodology-level. Operator invokes or Claude self-invokes based
+on the triggers above.
+
+V2 (future): rule `plan-declaration-required.md` + hook that fires
+BLOCKED when a ≥3-skill chain executes without a preceding
+`/whats-the-plan` output in session. Not in v1 scope — shipping the
+skill first lets us learn where auto-fire helps vs. spams.
+
+## 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/whereami/SKILL.md

@@ -0,0 +1,307 @@
+---
+name: whereami
+description: "Show project state in one glance \u2014 phase, active goal, agents in flight, subsystem progress, gate checklist, freshness. Reads docs/whereami.md. Run at session start before /sprint to orient."
+problem: "Project state lives across whereami and iteration goals and chronicles and git. No single-glance view."
+value: "Phase and active goal and agents in flight and gate progress \u2014 one page."
+inputs: [Optional freshness flag]
+outputs: [Current phase and iteration, Active agents, Subsystem status, Gate progress]
+tier: lite
+user_invocable: true
+disable_model_invocation: false
+modes: [default]
+composes_with: [sprint, whats-the-plan]
+---
+
+# /whereami
+
+## What you get
+
+A one-glance answer to "where is the project right now?" read from `docs/whereami.md`. You see phase, goal, agents, subsystems, gates, and freshness. Scannable in about 20 seconds. The skill never writes. `/session-end` owns the writes.
+
+**Tier gate (bassclef#740 Task 1.8).** `/whats-the-plan` ships at `tier: standard`. Lite adopters skip it. Print skip note. Resolve tier via `lib/tier-check.sh`.
+
+## When to use it
+
+Type `/whereami` at session start. Type it when someone drops in cold. Type it when something feels off. Type it before `/whats-the-plan` so the plan cites the active goal.
+
+The skill also fires self-triggered at session start. That is the rule at `.claude/rules/whereami-load-bearing.md`.
+
+## When NOT to use
+
+Do not use `/whereami` for scope at ticket level. That is `/sprint`. Do not use it for dispatch-path planning. That is `/whats-the-plan`. Do not use it for wiring checks. That is `/substrate-check`. Do not use it to modify state. The skill is read-only.
+
+## FAQ
+
+### How does /whereami differ from /sprint, /whats-the-plan, and /substrate-check?
+
+Four skills, four altitudes:
+
+| Skill | Altitude | Output |
+|---|---|---|
+| `/whereami` | Project state | Phase + goal + agents + freshness |
+| `/sprint` | Ticket / scope | Open issues + proposed sprint |
+| `/whats-the-plan` | Dispatch path | Ordered skill chain |
+| `/substrate-check` | Wiring | PASS / WARN / FAIL on files + hooks + CLIs |
+
+Session-start order: `/whereami`, then `/sprint`, then `/whats-the-plan`, then execute.
+
+### What does /whereami read?
+
+<!-- FKGL-EXEMPT: structured accessor spec -->
+Preferred is JSON via the accessor:
+
+```bash
+bash scripts/state.sh get whereami
+# or
+source lib/state.sh && state_whereami_get
+```
+
+Returns parsed JSON. Use this when `docs/whereami.json` exists (spine v0+).
+
+Fallback is markdown at `docs/whereami.md`. Body is operator narrative per `.claude/rules/accessor-library-discipline.md`.
+
+Schema at `standards/whereami-schema.md`. Spine v0 schema at `standards/state-spine/schemas/whereami.schema.json`. If both sources are missing or the session-start hook surfaced whereami-stale BLOCKED, resolve the BLOCKED first. Do not fabricate state.
+<!-- /FKGL-EXEMPT -->
+
+### What are the 8 schema sections?
+
+1. Project phase.
+2. Active goal (path, phase within goal, started date, previous goal, next goal).
+3. Active agents.
+4. Subsystem phases (table).
+5. Gate progress (by SDLC phase).
+6. Risk register pointer.
+7. Last updated (timestamp + session).
+8. Configuration pointer.
+
+### How does /whereami compute freshness?
+
+| Age of `last_updated` | Signal | Behavior |
+|---|---|---|
+| Less than 3 days | Green | Report normally |
+| 3-7 days | Warn | Report + flag refresh at session end |
+| 7 days or more | BLOCKED | Surface BLOCKED; refuse work until resolved |
+| Missing | BLOCKED | Suggest scaffolding from template |
+
+### What is the auto-update footer?
+
+<!-- FKGL-EXEMPT: structured render spec -->
+Reads `.bassclef-source.json` `auto_sync`. Defaults to `false` when the file or field is absent. Renders one:
+
+- "Auto-update: ON — your skills, rules, and agents stay current with bassclef at every session start."
+- "Auto-update: OFF — bassclef isn't pulling its own changes into your repo. Turn on any time by saying 'enable auto-sync' or editing `.bassclef-source.json`."
+
+This is Layer 1 of the Discovery Cascade per bassclef#939. Adopters see the off state on every orientation and opt in when ready.
+<!-- /FKGL-EXEMPT -->
+
+### What is the installed line?
+
+<!-- FKGL-EXEMPT: structured render spec -->
+Reads `.bassclef-source.json` `installed_sha` and `installed_at`. Renders one:
+
+- "Installed: abc1234 (3 days behind today) — 2026-06-13T08:30:00Z"
+- "Installed: abc1234 (up to date) — 2026-06-16T20:35:00Z"
+- "Installed: (no sync recorded — the next successful bassclef-sync will record installed_sha + installed_at)"
+
+Short SHA is the first 7 chars. Delta in days is `floor((now - installed_at) / 86400)`. Adopters see install version + staleness on every orientation.
+<!-- /FKGL-EXEMPT -->
+
+## Details below the fold
+
+<!-- FKGL-EXEMPT: procedure + spec content -->
+
+### Procedure
+
+**Step 1 — Read whereami.** `bash scripts/state.sh get whereami` for spine v0. Falls back to `docs/whereami.md` on pre-spine repos. If both fail or a whereami-stale BLOCKED fired, resolve BLOCKED first per `.claude/rules/blocked-items.md`.
+
+**Step 2 — Extract the 8 sections** listed above.
+
+**Step 3 — Compute freshness** per the FAQ table.
+
+**Step 4 — Report.** Scannable form. 20 seconds. Orientation, not a dump.
+
+### Output format
+
+```
+## Whereami — [repo-name] ([age of last_updated])
+
+**Phase**: [Inception | Elaboration | Construction | Transition]
+**Goal**: [goal name OR "between goals"]
+  ↳ Phase within goal: [Step N | "—"]
+  ↳ Started: [YYYY-MM-DD] | Previous: [goal path]
+**Active agents**: [role on branch OR "None"]
+
+**Subsystems**:
+| Subsystem | Phase | Last goal | Notes (first 6 words) |
+
+**Gate progress**:
+  Inception    ✅ COMPLETE (YYYY-MM-DD)
+  Elaboration  ✅ COMPLETE (YYYY-MM-DD)
+  Construction 🔄 IN PROGRESS ([N of M] items checked)
+  Transition   ⏳ PENDING
+
+**Next goal candidate**: [one-line from whereami next-goal field]
+
+**Last updated**: [ISO] ([N days ago]) — [session filename]
+
+---
+**Auto-update**: ON | OFF — [one-line state]
+
+**Installed**: [short_sha] ([N days behind today] | up to date) — [installed_at ISO date]
+```
+
+### Freshness block (prepended when applicable)
+
+- Warn (3-7 days): `whereami last updated N days ago; refresh at session end (MUST tier).`
+- BLOCKED (7+ days): `whereami-stale; resolve via session-start refresh OR defer explicitly.`
+- BLOCKED (missing): `whereami-missing; resolve by copying templates/whereami-template.md; then fill phase + goal + last_updated.`
+
+### Skipping and aborting
+
+- Read-only. Never modify `docs/whereami.md`.
+- If `last_updated` is unparseable: report WARN. Point at the schema.
+- If no active goal: report "between goals". Include the next-goal candidate from the schema.
+- If a schema section is missing: report WARN. Cite the schema. Do not invent.
+
+### Self-check step
+
+Before posting the report:
+
+1. Touch `state/markers/turn-prose-surface/status_update.marker`.
+2. Read the draft against `standards/bassclef-internal-jargon.md` BLOCK terms.
+3. Rewrite BLOCK matches in plain English.
+4. Post the response.
+
+The Stop hook `.claude/hooks/turn-prose-kiss-check.sh` catches misses.
+
+### Common failure modes
+
+- **Missing file.** No `docs/whereami.md` and no `docs/whereami.json`. Surface BLOCKED. Suggest the template. Operator fills phase + goal + last_updated.
+- **Stale entry.** `last_updated` more than 7 days old. Surface BLOCKED. Refuse work until refresh OR explicit deferral.
+- **Schema drift.** A section is missing or malformed. Report WARN. Cite the schema. Do not invent.
+- **Accessor unavailable.** `bash scripts/state.sh get whereami` fails on pre-spine repo. Fall back to markdown.
+- **Auto-update ambiguous.** `.bassclef-source.json` missing. Default to OFF. Render the opt-in path.
+
+### Grace window on old vocabulary
+
+Old planning-skill vocabulary still works through 2026-10-31. See `standards/vocabulary-migration.json` for the substitution table and `.claude/rules/we-dont-break-adopters.md` for the discipline. Existing schema field names keep working during the grace window; renamed field names ship in a sibling migration.
+
+<!-- /FKGL-EXEMPT -->
+
+## Examples
+
+<!-- FKGL-EXEMPT: sample output -->
+
+**Green orientation (fresh whereami, active goal):**
+
+```
+## Whereami — bassclef-upstream (2 hours ago)
+
+**Phase**: Construction
+**Goal**: 2026-07-19k — Shape e foundation
+  ↳ Phase within goal: WU-3 of 3
+  ↳ Started: 2026-07-19 | Previous: 2026-07-19j
+**Active agents**: Builder on feature/2026-07-19k-wu3-whereami-adr-044-refactor
+
+**Gate progress**: Construction 🔄 IN PROGRESS (7 of 12 items checked)
+
+**Next goal candidate**: #801 Wave 1 expansion (5 remaining Wave 1 skills)
+
+**Last updated**: 2026-07-19T22:15+0100 — 2026-07-19h-goal-19j-adr-044-unified-skill-template.md
+
+---
+**Auto-update**: ON — your skills, rules, and agents stay current with bassclef at every session start.
+
+**Installed**: 2ceb53b7 (up to date) — 2026-07-19T18:10:00Z
+```
+
+**Warn orientation (5 days since update):**
+
+```
+🟡 warn — whereami last updated 5 days ago (warn threshold: 3)
+         Refresh at session-end (MUST tier).
+
+## Whereami — bassclef-upstream (5 days ago)
+[normal output follows]
+```
+
+**BLOCKED orientation (missing file):**
+
+```
+🛑🛑🛑 BLOCKED 🛑🛑🛑
+whereami-missing — docs/whereami.md not found.
+Resolve: cp templates/whereami-template.md docs/whereami.md
+         (then fill phase + goal + last_updated)
+```
+
+<!-- /FKGL-EXEMPT -->
+
+## Anti-patterns and INSTEAD
+
+| Anti-pattern | INSTEAD |
+|---|---|
+| Rebuilding project state from session logs + git log each session | Read `docs/whereami.md` via the accessor |
+| Silencing a stale BLOCKED banner and proceeding | Surface the BLOCKED. Resolve or defer per rule |
+| Filling in plausible state for a missing section | Report WARN. Cite the schema. Do not fabricate |
+| Writing to `docs/whereami.md` from `/whereami` | Read-only. `/session-end` owns writes |
+| Dumping the full whereami content into the response | Scannable 20-second orientation. Reader opens the file for detail |
+
+## Composes with
+
+- `/sprint` — reads whereami as primary source. `/whereami` is the lighter surface.
+- `/whats-the-plan` — cites the goal and phase this skill surfaces.
+- `/session-end` — writes whereami at close. This skill only reads.
+- `/substrate-check` — validates schema conformance. This skill reports state.
+
+## Distinct from
+
+- `/sprint` — scope proposals at ticket level. Runs after `/whereami`.
+- `/whats-the-plan` — dispatch-path plan. Cites `/whereami` as input.
+- `/substrate-check` — wiring PASS / WARN / FAIL. Different question.
+- `/session-end` — writes whereami. `/whereami` never writes.
+
+## Rules
+
+- Orientation in one glance. Scannable, not a dump.
+- Read-only. Never writes. `/session-end` owns writes.
+- Always surface the hook's BLOCKED block. Do not silence stale or missing signals.
+- Composes with `/sprint` and `/whats-the-plan`. Whereami sits upstream.
+- No fabrication. Say so when a section is missing. Do not fill plausible state.
+
+## Test cases
+
+<!-- FKGL-EXEMPT: structured test spec -->
+| ID | Prompt | Expected behavior |
+|---|---|---|
+| T1 | `/whereami` on a fresh whereami (< 3 days) | Green orientation with all 8 sections + auto-update + installed |
+| T2 | `/whereami` when `last_updated` is 5 days old | Warn block prepended; normal output follows |
+| T3 | `/whereami` when `docs/whereami.md` is missing | BLOCKED block; scaffold suggestion; refuses work until resolved |
+| T4 | `/whereami` when a schema section is missing | WARN cite of schema; no invented content |
+| T5 | `/whereami` when `.bassclef-source.json` is absent | Auto-update: OFF default; opt-in path rendered |
+<!-- /FKGL-EXEMPT -->
+
+## Sources read
+
+- `.claude/rules/whereami-load-bearing.md` — session-start read discipline this skill honors
+- `.claude/rules/blocked-items.md` — BLOCKED protocol on stale or missing whereami
+- `.claude/rules/accessor-library-discipline.md` — accessor or direct read policy
+- `.claude/rules/plain-english-discipline.md` — master rule for output prose
+- `.claude/rules/we-dont-break-adopters.md` — vocabulary grace window
+- `standards/whereami-schema.md` — artifact format
+- `standards/state-spine.md` — accessor architecture
+- `standards/state-spine/schemas/whereami.schema.json` — spine v0 schema
+- `templates/whereami-template.md` — scaffolding source
+- `standards/bassclef-internal-jargon.md` — self-check wordlist
+- `.bassclef-source.json` — `auto_sync` and `installed_sha` source of truth
+- bassclef-upstream#939 — Discovery Cascade Layer 1 (auto-update footer)
+- bassclef-upstream#1037 WU-V4 — `installed_sha` + `installed_at` fields
+- ADR-040 planning-skill vocabulary and lite profile
+- ADR-044 unified SKILL body template
+
+## Why this skill exists
+
+Sessions that rebuild project state from session logs plus git log cost 20-40 turns per orientation. They also drift into the wrong active goal. Operators returning after a break need one file, one skill, one 20-second answer. `/whereami` makes that answer invocable. The rule at `.claude/rules/whereami-load-bearing.md` needs a mechanism, not just an obligation. Without `/whereami`, session-start orientation reproduces the archaeology anti-pattern the rule closes.
+
+## 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/AGENTS.md

@@ -0,0 +1,79 @@
+---
+tier: lite
+description: Cross-tool agent context for sunj-labs repos.
+---
+# Agents
+
+Cross-tool agent context for sunj-labs repos. This file is readable by
+Claude Code, Cursor, Copilot, and other AI tools — it's the universal
+agent briefing.
+
+## Active agents (10)
+
+| Agent | Role | Model | Tools | Authority |
+|-------|------|-------|-------|-----------|
+| Orchestrator | Air traffic control | haiku | Read, Write, Glob, Grep, Bash, WebSearch | Sequencing, routing. Cannot override any role's decisions. |
+| Shaper | Problem framing | opus (Inception) / sonnet | Read, Write, Glob, Grep, WebSearch | Scope, appetite, risk register. Cannot implement. |
+| PM | Commercial viability | sonnet | Read, Write, Glob, Grep, WebSearch | Value sequencing, viability hypotheses. Cannot implement or architect. |
+| Creative Director | Visual language | sonnet | Read, Write, Glob, Grep, WebSearch | Brand, tone, design tokens. Cannot implement. |
+| Architect | System design | sonnet | Read, Write, Glob, Grep, WebSearch | ADRs, C4 diagrams. Cannot implement in Construction. |
+| Designer | User experience | sonnet | Read, Write, Glob, Grep, WebSearch | UX judgment, concept validation. Cannot implement. |
+| Builder | Implementation | sonnet | All | Implements within ADR constraints. Cannot override ADRs. |
+| Reviewer | Code review | haiku | Read, Glob, Grep | Approve/block PRs. Read-only — cannot modify code. |
+| Deployer | Release management | haiku | Read, Write, Glob, Grep, Bash | Ships only. Cannot write application code. |
+| Closer | Administrative | haiku | Read, Write, Glob, Grep, Bash | Documents and closes. Cannot build. |
+
+## Restricted-permission agents (3)
+
+These agents have intentionally limited tool access for safety.
+
+### ReadOnly Explorer
+
+```yaml
+name: explorer
+tools: [Read, Glob, Grep]
+purpose: Codebase exploration and research without modification risk
+use_when: "Investigating unfamiliar code, answering questions about architecture, onboarding"
+```
+
+### Security Auditor
+
+```yaml
+name: security-auditor
+tools: [Read, Glob, Grep]
+purpose: Security review — scan for vulnerabilities, secrets, auth gaps
+use_when: "Pre-launch security review, dependency audit, auth matrix check"
+constraints:
+  - Read-only — cannot modify code, only report findings
+  - Checks against OWASP top 10, auth matrix, tenant isolation
+  - Reports to Architect for ADR-level decisions
+```
+
+### Docs Writer
+
+```yaml
+name: docs-writer
+tools: [Read, Write, Glob, Grep]
+purpose: Documentation only — chronicles, specs, release notes, READMEs
+use_when: "Session-end artifacts, backfill missing chronicles, write specs from canvases"
+constraints:
+  - Cannot run Bash commands
+  - Cannot modify source code (only .md files)
+  - Cannot create or modify hooks, skills, or rules
+```
+
+## Agent definitions
+
+Full agent definitions with luminaries, checkpointing rules, and
+persona details are in `.claude/agents/*.md`. This file is the summary
+for cross-tool consumption.
+
+## Guardrails
+
+All agents are bound by `.claude/rules/guardrails.md`:
+- Never push to main without PR review
+- Never deploy to production without human approval
+- Never expand scope beyond declared appetite
+- Never skip a hard gate
+- Save state before ending
+- Flag ambiguity rather than assuming

package/dist/lite/CLAUDE-lite.md

@@ -0,0 +1,85 @@
+---
+tier: lite
+description: What this is. A trimmed version of bassclef for solo adopters running one project. Ships 14 core skills plus 15 rules for session hygiene, safety, plain English, and PR shape. Full bassclef ships 90 skills and 76 rules for cross-project operators.
+---
+# bassclef-lite
+
+**What this is.** A trimmed version of bassclef for solo adopters running one project. Ships 14 core skills plus 15 rules for session hygiene, safety, plain English, and PR shape. Full bassclef ships 90 skills and 76 rules for cross-project operators.
+
+**How to think about it.** bassclef-lite gives you enough to run a session cleanly — open, orient, gate, do work, ship, close. As you outgrow it, upgrade to standard bassclef (all substrate, no changes needed on your end; just switch the source pointer).
+
+## Substrate (lite)
+
+| Component | Count | Location |
+|---|---|---|
+| Skills | 17 | `.claude/skills/*/SKILL.md` (14 core + 3 supporting: `kiss`, `value-prop`, `luminary`) |
+| Rules | 15 | `.claude/rules/*.md` (auto-loaded via `additionalDirectories`) |
+| Hooks | 14 | `.claude/hooks/*.sh` |
+| Standards | 20 | `standards/*.md` |
+| ADRs | 5 | `architecture/decisions/ADR-*.md` |
+| Agents | 4 | `.claude/agents/*.md` (architect, builder, designer, reviewer) |
+| Luminaries | 4 | `.claude/luminaries/*.md` |
+| Templates | 3 | `templates/*.md` |
+
+## Skills — 14 core
+
+Session lifecycle: `/onboard-repo`, `/whereami`, `/sprint`, `/skills`, `/howdoi`, `/session-end`, `/session-log`.
+Gates: `/temperance` (before work), `/verify` (after work), `/diagnose` (when it breaks).
+Do the work: `/longrun` (long sessions), `/state-a-problem`, `/release`, `/promote`.
+
+Supporting: `/kiss` (plain English), `/value-prop` (flash/tweet/brief), `/luminary` (design lenses).
+
+## Rules — 15 auto-loaded
+
+Session hygiene: `blocked-items`, `sdlc-gates`, `session-artifacts`, `artifact-ingestion`, `whereami-load-bearing`.
+Safety: `destructive-operations`, `state-schema-validation`.
+Composition: `skill-description-clarity`, `skill-composition-declarations`, `pattern-annotation`, `assert-only-after-verify`.
+Plain English: `plain-english-discipline`, `operator-facing-prose`.
+PR shape: `pr-body-shape`, `pr-strategy`.
+
+## SDLC flow
+
+```
+Canvas → Spec → Design → Issue → Branch → PR → CI → Deploy → Observe
+```
+
+Gates run before and after: `/temperance` before a non-trivial change; `/verify` after. `/diagnose` when something breaks.
+
+## Conventions
+
+- Conventional commits: `type: description` (feat, fix, docs, refactor, test, ci, chore, security)
+- One branch per issue; squash merge; delete branch after merge
+- PR titles ≤72 chars; PR bodies open with `**Problem (≤500 chars):**`
+
+## Key files
+
+- `.claude/rules/sdlc-gates.md` — the gate protocol
+- `.claude/rules/blocked-items.md` — BLOCKED: protocol
+- `.claude/rules/session-artifacts.md` — chronicle + journal obligations at session end
+- `standards/tier-tag-schema.md` — `upstream | lite | standard | ultra`
+- `templates/chronicle-template.md` — session log shape
+- `templates/whereami-template.md` — project state file shape
+
+## What NOT to do
+
+- **Don't push to main without PR review**, even solo. Main-protection catches surprise typos.
+- **Don't skip `/temperance` on non-trivial work.** It costs 30 seconds and catches wrong-shape ideas before you code them.
+- **Don't ship code without `/verify`.** The gate reads your change and points you at what you missed.
+- **Don't use bassclef-internal jargon** in operator-facing prose (PR bodies, chronicles, issues). Plain English. Grade 10. Subject-verb-object.
+
+## About prose citations to files not in lite
+
+Lite skills and rules sometimes cite rules or ADRs that ship only in standard bassclef. That is by design (per canvas 2026-07-19-bassclef-lite Q1). The rules that matter at runtime load through `additionalDirectories` — the sync template writes that setting into your `.claude/settings.json`. Governance rules fire when their trigger conditions match. You do not need the file on disk.
+
+Curious lite adopters can read the full standard-tier substrate at github.com/sunj-labs/bassclef. Prose citations point there.
+
+## Upgrading to standard bassclef
+
+When your work spans multiple projects, or you need adopter-QA discipline, or you hit the limits of 14 skills — flip `.bassclef-source.json` to point at the standard bassclef repo. All 90 skills, 76 rules, 61 hooks land at next session-start. No adopter action beyond the pointer flip.
+
+## See also
+
+- `docs/curation/2026-07-17b-lite-curation-notes.md` — how these 14 skills were picked (Voyage embeddings + luminary lens)
+- `docs/curation/2026-07-17b-lite-candidate-pool.md` — the 25-skill cosine shortlist that fed the lens pass
+- ADR-040 — planning skill vocabulary + lite profile (source decision)
+- ADR-041 — adopter-count-based grace-window (when full compat discipline returns)