@thebassclef/lite 1.0.3 → 1.1.0

package/dist/lite/standards/writing-guide.md

@@ -0,0 +1,213 @@
+---
+tier: lite
+description: Technical. Direct. For the next agent or session picking up the work.
+---
+
+# Writing Guide — Chronicles & LinkedIn
+
+## Two audiences, two registers
+
+### Chronicles (internal)
+
+Technical. Direct. For the next agent or session picking up the work.
+
+- Name files, functions, skills, hooks by their actual names
+- Include commit refs, issue numbers, file paths
+- Be factual, not promotional — record what happened
+- Open Threads is the most important section
+
+### LinkedIn (external)
+
+Personal. Specific. Story-first. For people who build, invest in, or
+evaluate technology-driven operating models.
+
+---
+
+## LinkedIn Style Guide
+
+### Voice & Tone
+
+First person. Tell the story of what happened. Let the reader draw
+the lesson from the story — don't hand them a pre-digested thesis.
+
+The voice is a builder-operator who has done hard things, learned from
+failures, and shares the specifics openly. Not a consultant summarizing
+from the outside. Not a brand speaking in third person. A person.
+
+The primary voice reference is Sanjay's own writing:
+- "Purpose Has Color" (Medium) — sensory, metaphorical, rooted in
+  lived experience. Santorini blue, Ducor pool, "bluetiful." Charming.
+- "Life Is Too Short to Ship Products That Don't Make a Difference"
+  (Medium) — direct, operational, warm. "Crumple up the stuff that
+  doesn't work, fast." Flywheel as a living thing, not a framework.
+
+These are the anchor. When in doubt, reread them.
+
+Bezos, Jassy, and Collison are secondary references — study how they
+actually write, not the sanitized version LinkedIn thinks they sound
+like. Bezos shareholder letters are full of "we were wrong about this."
+Jassy names the actual service that failed. Collison thinks out loud.
+They share Sanjay's commitment to specificity and naming the real thing.
+But the tone, the warmth, the sensory texture — that's Sanjay's own.
+
+**The sound of it right**:
+- "I built something with three knobs and couldn't remember what two of them did."
+- "Purpose does not charm. Purpose agitates, roils, and compels."
+- "Crumple up the stuff that doesn't work, fast. Build and ship the ones that do, fast."
+- "Charming." (one word, dry, lets the reader smile)
+- "When the person who built the thing can't say what it does without consulting the docs, the thing has a problem."
+
+**The sound of it wrong** (processed cheese — ban these patterns):
+- "Every unnecessary configuration axis in an autonomous system is a governance gap disguised as flexibility." (What does this mean? Who talks like this?)
+- "This taxonomy IS the org chart for your AI workforce." (Thesis statement masquerading as insight)
+- "The most secure, auditable autonomous systems are the ones with the smallest configuration surface." (Corporate whitepaper voice)
+- Any sentence containing: "taxonomy," "governance gap," "ungoverned states," "configuration surface," "enterprise economics," "capital efficiency" as the *point* of the sentence rather than a detail inside a story
+
+### The "Monday morning" test
+
+Read the sentence out loud. Would you say this to a smart friend over
+coffee on a Monday morning? If it sounds like a keynote slide or a
+consulting deck, rewrite it. The friend would interrupt and say "what
+does that actually mean?"
+
+### Story structure, not thesis structure
+
+**Wrong** (thesis-first):
+> Configuration sprawl is governance debt. Every axis you add multiplies
+> the ungoverned states in your system.
+
+**Right** (story-first):
+> I tried to explain my own configuration model on a Monday morning and
+> couldn't. "Standard sequential orchestrator-gated" — what does that
+> even mean? That's when I knew something was wrong.
+
+The thesis can appear — but earned, at the end, after the story makes
+it feel inevitable. Not announced at the top.
+
+### Sentence rhythm
+
+Mix short and long. Short for emphasis. Long when building momentum.
+
+- "So I deleted it." (punchy — the action)
+- "Three axes became two. Twelve combinations became four. The manifest lost a field." (triplet — acceleration)
+- "If I'm steering the session myself, I naturally call in a few agents as needed. If I let the system run itself overnight, it needs the full team. I don't configure that. It just falls out." (longer — builds the logic, then lands)
+
+Avoid: every sentence the same length. Avoid: every paragraph the same
+number of sentences. Rhythm creates feeling. Monotone creates pablum.
+
+### First person, always
+
+Use "I" freely. This is a person writing about things they built and
+broke and learned from. Not a company blog. Not a thought leadership
+platform. A person.
+
+- "I was proud of it for about a week."
+- "I sat with the actual usage."
+- "I was asking myself to decide something the system already knew."
+
+"We" is fine when it genuinely means a team. Never use "we" as a
+corporate "we" that means nobody in particular.
+
+### Metaphors from life, not business school
+
+**Right**: volcanoes, pool water, crayon names, org charts, Monday mornings,
+being unable to explain something to yourself, knobs on a dashboard
+
+**Wrong**: "governance primitives," "coordination frameworks," "configuration
+surfaces," "compliance architectures"
+
+The metaphor should make the reader *see* something. If they have to
+look up the metaphor, it's not a metaphor — it's jargon.
+
+### Technical vocabulary — when to use it
+
+Name real things when they're part of the story: "the manifest,"
+"worktree," "the pre-commit hook," "the boot sequence." These are
+concrete. The reader can picture them.
+
+Don't name abstractions that only exist in your framework: "governance
+substrate," "quality gates," "specification quality." These are labels
+for ideas, and the ideas should be shown through story, not labeled.
+
+**Exception**: If a concept earns its name by being explained through
+a story first, you can name it at the end. "We call this temperance —
+a mandatory pause before the system acts" works because the story
+showed what temperance *is* before naming it.
+
+### What goes in each post
+
+- **What actually happened** — the specific situation, not a category
+- **What went wrong or surprised you** — the tension that makes it a story
+- **What you did about it** — the action, told simply
+- **What it felt like** — the Monday morning confusion, the pride that
+  lasted a week, the "oh" moment when you saw the coupling
+- **The pattern** (earned, at the end) — what someone else might recognize
+  in their own work
+
+### What to leave out
+
+- Thesis statements as openers (earn them)
+- "The key takeaway is..." (the reader gets to decide)
+- Consultant-speak transitions ("Let's examine," "Consider the following")
+- Abstract categories where a specific example would do
+- Sentences that could appear in any company's blog post
+
+### Length
+
+600-1200 words. But only if every paragraph earns its place.
+A 600-word post that tells one story well beats a 1200-word post
+that makes three abstract points.
+
+### Structure
+
+1. **Hook** (1-2 lines) — a specific moment, a confession, something
+   that happened. Not a thesis. Not a question designed to sound profound.
+2. **The story** — what happened, in enough detail that the reader is
+   there with you. Include the wrong turns, the confusion, the feeling.
+3. **The turn** — the moment you saw it differently. This is the heart
+   of the post.
+4. **The pattern** (earned) — what this means beyond your specific
+   situation. Keep it to 2-3 sentences. Trust the reader.
+
+### Two audience variants
+
+Each notable moment can produce two posts:
+
+**Variant A (Board / PE / Search)**: The same story, but land on the
+operating implications. What does this mean for how you run a company,
+evaluate a technology investment, or assess an operator? Use analogies
+to org design, capital allocation, or operational discipline. But still
+tell the story first.
+
+**Variant B (Engineering)**: The same story, with more technical detail.
+Show the code diff, the configuration before and after, the specific
+failure mode. Engineers want to learn something they can apply. But still
+tell the story — engineers hate corporate abstractions even more than
+PE partners do.
+
+### The audience recommendations table
+
+Every draft file includes:
+
+```markdown
+| # | Variant | Title | Primary audience | Hook strength | Publish priority |
+|---|---------|-------|-----------------|--------------|-----------------|
+```
+
+Rate hook strength honestly. "Very strong" = specific, surprising,
+or confessional. "Strongest" = makes the reader stop scrolling.
+"Medium" = solid but expected.
+
+### Feynman Sidebar Convention
+
+When a post references a technical concept that deserves a plain-English
+explanation, flag it:
+
+```
+[FEYNMAN: concept name]
+```
+
+Run /feynman afterward. Weave it in or use it as a comment-thread follow-up.
+The Feynman explanation should sound like you're explaining it to a
+sharp friend who works in a different field — not dumbing it down,
+just making it vivid.

package/dist/lite/templates/chronicle-template.md

@@ -0,0 +1,75 @@
+---
+tier: lite
+session_id: {YYYY-MM-DD}-{HHMM}
+project: {active project}
+agent: personal
+status: completed
+tags: [relevant, tags]
+started_at: {ISO 8601 — from session-end hook or /tmp/claude-session-timing-*}
+ended_at: {ISO 8601 — from session-end hook or current time}
+duration_minutes: {exact from hooks, or approximate as fallback}
+turns: {approximate, e.g., ~40}
+closes: [{list of issues closed, e.g., "#37", "#42"}]
+---
+
+# Session: {Title}
+
+## Entry State
+- State before this session
+
+## Work Done
+- Bullet points of accomplishments
+- Reference commits + PRs by SHA / number
+
+## Decisions Made
+- Key decisions with rationale
+
+## Open Threads
+- What's unfinished or needs follow-up
+- (most important section — what the next session reads first)
+
+## Key Files Changed
+- List of files created or modified
+
+## Gate Evidence
+
+**MUST be populated.** This section is the authoritative input for the
+5-session gate-compliance counter. An empty/missing section reads as
+"no data" and silences the compliance signal.
+
+Auto-populate from gate markers (run before writing the chronicle):
+
+```bash
+BRANCH_SLUG=$(git branch --show-current | tr '/' '-')
+[ -f "state/markers/temperance/${BRANCH_SLUG}.marker" ] && echo "temperance: yes"
+[ -f "state/markers/diagnose/${BRANCH_SLUG}.marker" ] && echo "diagnose: yes"
+[ -f "state/markers/verify/${BRANCH_SLUG}.marker" ] && echo "verify: yes"
+# For multi-branch sessions, iterate over each branch worked.
+```
+
+| Gate | Fired | Evidence | Outcome |
+|------|-------|----------|---------|
+| Temperance | {yes/no/n/a} | {marker path or "session-level (longrun)" or n/a reason} | {PASS / N/A — reason} |
+| Diagnosis | {yes/no/n/a} | {marker path; "n/a — not a fix/ branch"; or "trivial — [cause]"} | {root cause / n/a} |
+| Tests | {yes/no/n/a} | {N unit, M integration; or "n/a — docs only"} | {pass count / n/a} |
+| Verify | {yes/no/n/a} | {marker path; or "n/a — docs only"} | {PASS / N/A — reason} |
+
+### Gate skip justifications
+
+If any gate shows `no` without a valid `n/a` reason, that's a compliance
+failure (per `standards/sdlc-compliance.md`). Valid skip reasons:
+
+- **n/a** — gate doesn't apply (e.g., diagnosis on a feature branch)
+- **Degraded mode** — infrastructure unavailable; note workaround
+- **Assessed as trivial** (diagnosis only) — cause was immediately obvious; state it
+
+Invalid reasons: "ran out of time", "will do later", bare "no" with no rationale.
+
+## Promotable Patterns
+
+Did this session produce a novel diagnostic, workaround, or workflow
+improvement worth shipping to other repos? If yes:
+
+- {Pattern name}: {one-sentence description} → /promote candidate
+
+Then run /promote before session-end.

package/dist/lite/templates/deferred-action-template.md

@@ -0,0 +1,45 @@
+---
+tier: lite
+id: <ISO-ts>-<slug>
+created_by_session: <chronicle-slug>
+created_in: desktop | ephemeral-mobile | ephemeral-ci | cloud-web
+created_at: <ISO-8601 UTC>
+pending_action: <verb-phrase-slug>
+requires_capability: [<capability>, <capability>]
+priority: medium
+origin_skill: /<skill-name>
+resolves_when: |
+  <one-to-two sentences describing the end state>
+---
+
+## Context
+
+<One paragraph. Why was the work deferred? What produced it? Who needs
+it and by when? Enough for a resolver without prior session context to
+understand the gap.>
+
+## Command to execute
+
+<Exact copy-pasteable command, env vars, agent instruction. If
+multi-step, a small checklist. If operator judgment is required,
+state "operator action" and describe what the operator decides.>
+
+```bash
+# example
+npx tsx scripts/push-to-gdoc.ts \
+  --file docs/release-notes/2026-04-20-internal.md \
+  --doc-id "$CHANGELOG_DOC_ID"
+```
+
+## On completion
+
+- [ ] Verify downstream state (e.g., Google Doc shows the pushed content)
+- [ ] `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`
+- [ ] `git commit -m "chore: resolve deferred action <id>"`
+- [ ] (Optional) Note resolution in chronicle footnote if scope warrants
+
+## Cross-refs
+
+- <Related PR(s) or issue(s)>
+- <Chronicle entry that originated the deferral>
+- <Memory entries, prior deferred actions, or standards>

package/dist/lite/templates/memory-proposal-template.md

@@ -0,0 +1,77 @@
+---
+tier: lite
+id: <ISO-ts>-memory-<topic-slug>
+created_by_session: <chronicle-slug>
+created_in: ephemeral-mobile | cloud-web
+created_at: <ISO-8601 UTC>
+pending_action: apply-memory-proposal
+requires_capability: [memory-write]
+priority: medium
+origin_skill: /<skill-that-proposed-it>
+resolves_when: |
+  Proposed memory file exists at the target path and MEMORY.md index
+  references it. Proposal file git mv'd to
+  docs/deferred-actions/completed/.
+---
+
+## Context
+
+Mobile or cloud-web session identified a memory entry worth adding
+but couldn't write to `~/.claude/projects/.../memory/` (ephemeral
+sandboxes lack filesystem access to the operator's real home).
+
+Surface the proposal here; a capable desktop session reviews and
+applies it per the Command section below.
+
+## Proposed memory entry
+
+**Target path**: `~/.claude/projects/<project>/memory/<category>_<topic>.md`
+
+**Frontmatter + body** (copy-paste into the target file verbatim):
+
+```markdown
+---
+name: <one-line title>
+description: <one-line description for MEMORY.md index>
+type: <user | feedback | project | reference>
+---
+
+<memory content — follow the auto memory guide's structure for this type:
+- user: role, preferences, responsibilities, knowledge
+- feedback: rule + Why + How to apply
+- project: fact/decision + Why + How to apply
+- reference: pointer to external resource + purpose>
+```
+
+**MEMORY.md index line to append**:
+
+```
+- [<title>](<filename>.md) — <one-line hook>
+```
+
+## Command to execute
+
+Operator action. Resolving session:
+
+1. Read the proposed content above
+2. Apply it verbatim (or edit first if the content needs refinement)
+3. Verify via the auto-memory guide in the main system prompt:
+   - frontmatter fields correct for the memory type
+   - content conforms to the type's structure
+   - MEMORY.md index line added (≤150 chars)
+4. Confirm the entry works: next session-start will load MEMORY.md
+   and the index line surfaces the new entry
+
+## On completion
+
+- [ ] Memory file exists at target path with correct frontmatter
+- [ ] MEMORY.md index updated with the new entry line
+- [ ] `git mv docs/deferred-actions/<id>.md docs/deferred-actions/completed/<id>.md`
+- [ ] `git commit -m "chore: apply memory proposal <id>"`
+
+## Cross-refs
+
+- <chronicle that originated the proposal>
+- <related memory entries, if the proposal extends or contradicts existing memory>
+- `.claude/rules/session-artifacts.md`
+- `.claude/rules/deferred-actions.md`

package/dist/lite/templates/persona-template.md

@@ -0,0 +1,200 @@
+---
+tier: lite
+---
+
+# Persona — [Name]
+
+<!--
+  Bassclef persona template. Pichler-shaped with evidence-traceability.
+  Referenced by /personas skill (.claude/skills/personas/SKILL.md) and
+  validated by standards/persona-schema.md.
+
+  Delete this comment block after copy-paste.
+
+  Save location:
+    Preferred: docs/personas/{slug}.md
+    Legacy (backward-compat with /jtbd-tasks + /synthetic-user):
+      docs/design/personas/{slug}.md
+
+  The filename basename MUST match the `slug` field below.
+-->
+
+**Slug:** [url-safe-identifier]
+**Name:** [Human-readable display name]
+**Archetype:** [One-line categorical framing — e.g., "PE operator managing 50+ active deals", "Bootstrapped couple founders", "Tier-2 SaaS customer-success manager"]
+**Evidence quality:** [High | Medium | Low | — (unsourced default)]
+**Generated:** [YYYY-MM-DD] via [/psychographic-mine | /auto-user-research | manual research | operator-default]
+**Source synthesis:** [path to research doc, or "—"]
+
+---
+
+## Provenance
+
+<!--
+  Required for any persona with a claim about behavior, pain points, or
+  workflows. Every claim should trace to a source. Orphan claims
+  (claims without citation) surface as WARN in /personas validate.
+
+  If this is an operator-default, state so plainly:
+    "Operator-default; not research-backed."
+-->
+
+Persona built from:
+- **[Source 1 name]** — [link or repo-local path]. [One-line characterization of what this source establishes]
+- **[Source 2 name]** — [link]. [Characterization]
+- **[Source 3+ as applicable]**
+
+---
+
+## Goal
+
+<!--
+  REQUIRED. One sentence. What this persona is trying to accomplish
+  that the product hires to help with.
+
+  Not a feature. An outcome.
+-->
+
+[One-sentence goal. Start with a verb. End with an outcome, not a feature.]
+
+---
+
+## Role / Context
+
+<!--
+  Pichler "context" field + enough environmental grounding that
+  downstream skills can frame tasks, jargon level, and viewport
+  appropriately.
+-->
+
+- **Relationship / cohort:** [e.g., married 5+ years, solo founder, cross-functional IC]
+- **Organizational stage:** [e.g., bootstrapped pre-seed, Series B, established enterprise]
+- **Revenue / scale context:** [if applicable]
+- **Team size:** [self, 2, 10, 100+]
+- **Industry:** [specific or range]
+
+**Representative example (composite OK):** [Name + age + one-line bio so
+downstream skills can render concrete scenarios. Mark explicitly as
+composite vs. real if from research.]
+
+---
+
+## Workflows (today)
+
+<!--
+  Pichler "tasks" + "approach" combined. How they currently operate,
+  what tools they use, what rhythm they follow.
+-->
+
+### How they currently work
+
+- [Primary tool / pattern / rhythm]
+- [Secondary tools]
+- [Coordination / collaboration mechanism if relevant]
+
+### Daily or typical rhythm
+
+- [Morning routine]
+- [Workday pattern]
+- [Evening / end-of-day]
+
+---
+
+## Pain points (with evidence trace)
+
+<!--
+  Each pain should cite a source. Formatting convention:
+    > *Source trace: [source-N reference] — "[direct quote]"*
+
+  This is the evidence-traceability rule. Orphan pains (no trace)
+  are WARN in /personas validate.
+-->
+
+### P1 — [Concise pain label]
+
+[One-paragraph description of the pain — what triggers it, how it
+manifests, what it costs them.]
+
+> *Source trace: [source reference] — "[direct quote or paraphrase]"*
+
+### P2 — [Concise pain label]
+
+[Description]
+
+> *Source trace: [source reference]*
+
+### P3+ as applicable
+
+---
+
+## Workarounds they've built
+
+<!--
+  Important for JTBD reasoning and /value-prop-canvas Jobs mapping.
+  The workaround is the "status quo" alternative in the Strategyzer
+  Value Map.
+-->
+
+- [Workaround 1] — [effectiveness] — [source trace if applicable]
+- [Workaround 2] — ...
+
+---
+
+## Knowledge / jargon comfort
+
+<!--
+  Pichler "knowledge" field. Drives /synthetic-user viewport,
+  /visual-review jargon checks, /spec copy tier.
+-->
+
+- **Domain expertise:** [novice / working-knowledge / expert]
+- **Technical fluency:** [what they use confidently; what they avoid]
+- **Jargon comfort:** [specific terms known vs. need-plain-language]
+
+---
+
+## Biography
+
+<!--
+  Pichler "biography" field. Short — 2-3 sentences. Formative
+  background, not life story. Use this to give downstream skills a
+  narrative anchor for synthesis and testing.
+-->
+
+[Short biographical framing — age range, prior roles, formative influences, what brought them to this goal.]
+
+---
+
+## Quotes / voice samples
+
+<!--
+  Optional but highly valuable. Direct or paraphrased language from
+  source material. Drives /synthetic-user test narration and
+  /value-prop-canvas Gains articulation.
+-->
+
+> "[Direct quote from source]"
+> — [source reference]
+
+> "[Another quote]"
+> — [source]
+
+---
+
+## Anti-persona / NOT this persona
+
+<!--
+  Optional. Who this persona is explicitly NOT. Prevents downstream
+  skills from conflating adjacent cohorts.
+-->
+
+- NOT: [adjacent cohort that might get confused]
+- NOT: [another adjacent cohort]
+
+---
+
+## Further reading
+
+- Roman Pichler, *The Persona Template* — https://www.romanpichler.com/the-persona-template/
+- Alan Cooper, *The Inmates Are Running the Asylum* — archetype-based persona framework (complementary to Pichler)
+- Agile Alliance, *Personas* glossary — https://agilealliance.org/glossary/personas/

package/dist/lite/templates/pr-faq.md

@@ -0,0 +1,45 @@
+---
+tier: lite
+---
+
+# [Initiative Name] — Press Release / FAQ
+
+## Press Release (Written as if launching today)
+
+### Headline
+One sentence. What did we ship and why does anyone care?
+
+### Subheadline
+Who is this for and what do they get?
+
+### Problem Paragraph
+The world before this existed. Pain. Friction. Cost.
+
+### Solution Paragraph
+What we built. How it works. What changes.
+
+### Quote (You)
+Why you built it. What you believe.
+
+### How It Works
+Three steps. Maximum.
+
+### Quote (Customer)
+A fictional but realistic customer reaction.
+
+### Call to Action
+What the reader does next.
+
+---
+
+## FAQ
+
+### Customer FAQ
+Q: What does this cost?
+Q: How is my data handled?
+Q: What if it breaks something?
+
+### Internal FAQ
+Q: How long will this take to build?
+Q: What's the biggest technical risk?
+Q: What do we explicitly NOT build in v1?