@thebassclef/lite 0.1.3 → 1.0.1

package/substrate/standards/writing-guide.md

@@ -1,213 +0,0 @@
----
-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/substrate/templates/chronicle-template.md

@@ -1,75 +0,0 @@
----
-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/substrate/templates/deferred-action-template.md

@@ -1,45 +0,0 @@
----
-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/substrate/templates/memory-proposal-template.md

@@ -1,77 +0,0 @@
----
-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/substrate/templates/persona-template.md

@@ -1,200 +0,0 @@
----
-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/substrate/templates/pr-faq.md

@@ -1,45 +0,0 @@
----
-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?