founder-skills: Instructions file for Claude Code

CLAUDE.md

Repository Structure

• founder-skills/ — Claude Code plugin (SDK/CLI-based)
• founder-skills/.claude-plugin/plugin.json — Plugin manifest
• founder-skills/commands/feedback.md — /founder-skills:feedback slash command (drafts a bug/idea/help/win report, hands the user a prefilled GitHub/mailto: link to submit; transmits nothing automatically)
• founder-skills/skills/market-sizing/ — Market sizing skill with scripts and references
• founder-skills/skills/deck-review/ — Deck review skill with scripts and references
• founder-skills/agents/market-sizing.md — Market sizing agent definition
• founder-skills/agents/deck-review.md — Deck review agent definition
• founder-skills/skills/ic-sim/ — IC simulation skill with scripts and references
• founder-skills/agents/ic-sim.md — IC simulation agent definition
• founder-skills/scripts/session-setup.sh — SessionStart hook (persists CLAUDE_PLUGIN_ROOT)
• founder-skills/scripts/founder_context.py — Founder context management (init/read/merge/validate)
• founder-skills/scripts/find_artifact.py — Artifact path discovery across skills
• founder-skills/scripts/insert_coaching.py — Shared Context B coaching-commentary inserter (idempotency matrix, uuid-marker replacement, run_id parity)
• founder-skills/scripts/check_handoff.py — Shared Context A file hand-off gate (typed exit codes for main-thread branching)
• founder-skills/scripts/merge_json.py — Shallow-merge of parallel sub-agent hand-off files for producer pipes
• founder-skills/scripts/md_to_commentary.py — Wraps a sub-agent's raw-markdown coaching commentary into the JSON envelope insert_coaching.py consumes (the model never hand-escapes the commentary)
• founder-skills/scripts/_founder_text.py — Shared founder-facing text policy: which internal tokens may reach a founder and how they render. Four token types, three behaviours (humanize private enums + field names; keep stable identifiers and diagnostic codes verbatim). Every skill's compose_report.py substitutes then scans with it; insert_coaching.py scans the coaching commentary. identifier_values() is cap-table-only — elsewhere an id field can hold a field name (fmr's unit_economics.metrics[].id is gross_margin), and keeping it leaves our vocabulary in the report and silences the warning.
• founder-skills/scripts/resolve_artifacts_root.py — Canonical + agent-namespace artifacts-root resolver (--agent for HANDOFF_AGENT derivation)
• founder-skills/references/ — Shared reference files (benchmarks, Israel guidance, etc.)
• founder-skills/references/brand/ — Brand tokens + Sora variable webfont (OFL) for generated HTML artifacts; embedded base64-inline so artifacts stay self-contained
• founder-skills/tests/test_market_sizing.py — Market sizing regression tests
• founder-skills/tests/test_deck_review.py — Deck review regression tests
• founder-skills/tests/test_reconcile.py — The numeric engine's 60 judgement calls, each pinned to a real corpus line
• founder-skills/tests/test_reconcile_producer.py — The engine's producer layer: the gate, the three statuses, and that only select() decides founder-visible output
• founder-skills/tests/test_ledger.py — Ledger validation, chiefly the raw-vs-value scale check
• founder-skills/tests/test_quote_match_sync.py — deck-review's copy of cap-table's matcher must not drift
• founder-skills/tests/test_ic_sim.py — IC simulation regression tests
• founder-skills/tests/test_visualize_market_sizing.py — Market sizing HTML visualization tests
• founder-skills/tests/test_visualize_deck_review.py — Deck review HTML visualization tests
• founder-skills/tests/test_visualize_ic_sim.py — IC simulation HTML visualization tests
• founder-skills/skills/financial-model-review/ — Financial model review skill with scripts and references
• founder-skills/agents/financial-model-review.md — Financial model review agent definition
• founder-skills/tests/test_financial_model_review.py — Financial model review regression tests
• founder-skills/tests/test_visualize_financial_model_review.py — Financial model review HTML visualization tests
• founder-skills/skills/competitive-positioning/ — Competitive positioning skill with scripts and references
• founder-skills/agents/competitive-positioning.md — Competitive positioning agent definition
• founder-skills/tests/test_competitive_positioning.py — Competitive positioning regression tests
• founder-skills/tests/test_visualize_competitive_positioning.py — Competitive positioning HTML visualization tests
• founder-skills/skills/cap-table/ — Cap-table skill (SAFE / note conversion, priced rounds, anti-dilution, Israeli ↔ Delaware flips)
• founder-skills/agents/cap-table.md — Cap-table agent definition (Context A extraction + Context B coaching)
• founder-skills/tests/test_cap_table.py — Cap-table regression tests (math producers + 11-gotcha regression suite)
• founder-skills/tests/test_cap_table_freeform.py — Lane-3 freeform mapper tests (freeform_mapper.map_freeform golden maps + blockers + --mode=freeform-emit CLI + the cap_state E_NO_EQUITY_BASE guard)
• founder-skills/tests/test_visualize_cap_table.py — Cap-table HTML visualization tests
• founder-skills/tests/mutation_corpus.py + test_mutation_corpus.py — Curated mutant corpus over cap-table's math producers: named defects injected into a temp-dir copy of the repo, with the cap-table selection asserted to notice (MUST_KILL) or recorded as not noticing (KNOWN_SURVIVORS). Both lists are SHRINK-ONLY. The registry lives in the non-test_* module deliberately: its mutants quote error-code literals verbatim, and inside a scanned test file those payloads make test_cap_table_guards.py's ratchets count a code as guarded that the corpus is simultaneously recording as unguarded — measured, it dropped test_error_code_assertion_ratchet below its baseline. Carries a no-op control: a comment-only mutant that must leave the selection PASSING, without which a broken harness greens every entry. The two count ratchets are --deselected from the child run — a count ratchet is not a defect detector, so a rename mutant can red it while noticing nothing. Every MUST_KILL entry names the test that must be the one to notice (killed_by, measured by running the mutant, never guessed) and a kill from anywhere else fails: this corpus has twice been caught scoring a kill for the wrong reason (a count ratchet, then a collection error — pytest exits 1 for a failed import exactly as for a failed test), so "something went red" is deliberately not accepted as "the guard noticed".
• founder-skills/tests/test_release_gating.py — The release chain, asserted rather than assumed: whenever publish-release runs, every job in its TRANSITIVE needs closure must run too. In Actions a skipped dependency SKIPS the dependent (no status function in publish-release's if:), so a condition that stops firing on a tag push does not merely stop gating — it stops the Release publishing, invisibly, and this repo has already shipped four tags with no Release. Two independent checks because they fail differently: the job if: strings are frozen verbatim beside a hand-derived tag-push truth value (an edit reds and forces re-derivation), AND a small evaluator runs the closure under a simulated tag push. The evaluator raises on an unknown context property rather than defaulting it — a silent default would green a job GitHub actually skips, i.e. the exact failure it exists to catch. Asserts WIRING, never that a job passes. Note the chain is unexercised: v0.10.0 predates the publish-release job.
• founder-skills/tests/cowork_async_subagent_filter.py — Cowork sub-agent tool-name compatibility helper (skill-quality CI; v0.4.0-regression detector)
• cowork-tests/leak_scan.py — Shared detector for founder-facing "internal plumbing" leaks in assistant narration. Ten classes: nine syntactic (script names, *.py, --flags, $vars, exit codes, W_/E_ codes, JSON, step/route labels, ALLCAPS-with-underscore) plus plumbing_verb, which is semantic. Reads a cassette or a run dir's events.jsonl — point it at the FILE, since a directory glob finds only *.json and reports a silent false-clean.
• founder-skills/tests/test_founder_facing_leaks.py — Ratchet over leak_scan.py across the committed cassettes. Gates "no NEW leaks beyond BASELINE", not zero — the cassettes predate the narration rule. Ratchet the constant DOWN after a re-record; never raise it.
  • Scope warning — a green here still does not mean the narration is clean, but the gap is now narrower than this note used to claim. Nine of the ten classes match on FORM (backticks, --flags, $vars, *.py, exit codes, W_/E_ codes, JSON, a literal route-label list, ALLCAPS-with-underscore). The tenth, plumbing_verb, is SEMANTIC: it targets the verb+object construction that only appears when narrating internals, so "gating the hand-off", "piping it through the producer" and "dispatching the sub-agent" ARE caught (measured: 3 such leaks, and zero syntactic ones, in one live run's events.jsonl). What still passes clean is internal vocabulary with no plumbing verb — "canonical artifacts", "schema-drift warning", "gap-detection pass", bare STOP/BLOCKED (no underscore), and "Gate 1 passes". That residue is the live-run/hand-read surface; it is smaller than "every plain-English mention". Do not fix it by enumerating more words — leak_scan.py's own design note says an enumerated blocklist is unwinnable, which is why the classes are class-based. Superseded advice, recorded so it is not re-derived: this note used to say never to extend the existing classes because doing so "raises the measured count on the committed cassettes and reds the suite". That was tried and is false — the ten-class total over the committed cassettes is 61 against the then-current BASELINE = 144, green, because the nine-class count had already fallen far below its own baseline. (BASELINE is now 59 — measured 2026-08-06 at test_founder_facing_leaks.py:74. It went 144 → 64 → 55, then was RAISED 55 → 59, which breaks the ratchet-down rule deliberately and once; the file's own comment states the obligation to fix the narration leak, re-record, and ratchet back below 55, not to it. Read the constant from the file, never from this line — it has now been stale twice.)
• founder-skills/tests/compose_invocations.py — Per-skill compose-script invocation registry (skill-quality CI)
• founder-skills/tests/test_cowork_async_subagent_filter.py — Helper unit tests
• founder-skills/tests/test_cowork_invariants.py — Per-agent persistence + dangerous-tool declaration invariants
• founder-skills/tests/test_cowork_harness_floors.py — Drift guards for the cowork-harness version surface: the per-site registry splitting CI SELECTORS (pinned exactly, 3.2.0) from FLOORS (recording >=3.2.0, replay ^2.1.0) — three postures, deliberately different, uses:-vs-version: major agreement (the action ref and the CLI move independently), and the derived cassette-format facts prose keeps restating wrongly. Every extraction asserts its own pattern matched, so a rotted regex reds instead of greening.
• founder-skills/tests/test_skill_orchestration.py — Per-SKILL.md frontmatter + sub-agent-cue-then-bash regression detector
• founder-skills/tests/test_compose_invariants.py — coaching_payload shape + STALE_ARTIFACT regression
• founder-skills/tests/test_insert_coaching.py — insert_coaching.py suite (6-state idempotency matrix, run_id parity, single-pass write-back, adversarial commentary)
• founder-skills/tests/test_check_handoff.py — check_handoff.py suite (typed exit paths 0/3/4/5/6, adversarial file states, tolerant receipt extraction)
• founder-skills/tests/test_merge_json.py — merge_json.py suite (merge order, --set overrides, error paths)
• founder-skills/tests/test_resolve_artifacts_root.py — Artifacts-root resolver suite (Cowork mount signatures + agent-namespace root)
• founder-skills/tests/dead_payload.py — Shared analyzer for embedded-but-unread JS payload keys. Three verdicts, because two cannot express what is known: read, unread, and unverifiable (the script indexes the payload by computed name, so no read can be attributed to a specific key). Treating dynamic access as blanket consumption hides real dead keys; treating it as death reports false ones.
• founder-skills/tests/test_dead_payload.py — Analyzer unit tests + all four embedders (three explore.py + review_inputs.py). Pins which payload objects are dynamic, so a generator switching to computed access cannot quietly reduce coverage.
• founder-skills/tests/test_dispatch_schema_drift.py — Guards a dispatch template instructing a field nothing consumes. Reads every fenced block on both prompt surfaces (templates also appear untagged and in bash heredocs; json-only sees about a third). Consumers include shared scripts, JSON schemas, and JS member access. Cannot detect shape-level drift for a name consumed elsewhere — x_axis_rationale is the obsolete authoring shape and the legitimate internal shape of positioning_scores.json — so a direct axis-shape assertion covers that regression.
• founder-skills/tests/test_html_founder_text.py — Fleet ratchet: no internal token in founder-visible text of any generated HTML. Text nodes only; attribute values and script bodies are not founder-facing prose.
• founder-skills/tests/test_compose_invariants.py also scans every delivered markdown, not just report.md — _EXTRA_DELIVERABLES names the non-compose producers (cap-table's counsel packet today). A deliverable nothing scans can say anything: counsel_packet.md shipped a raw rule-domain token to a founder while the fleet scan looked only at report.md. The cap-table fixture flags zero counsel items, so the scan seeds one — without it the packet is 315 B of boilerplate and passes with the leak present.
• founder-skills/tests/test_delivery_coverage.py — The fleet's delivery-defect coverage map, asserted rather than described. Records the known gap: the downstream half of "computed, not rendered" is gated only in competitive-positioning and financial-model-review — a third row records a Gate-1 render contract as explicitly WEAK (a string assertion over SKILL.md prose, which cannot fail a run), and does not narrow that count.
• founder-skills/tests/test_theme_sync.py — Brand-theme invariants: per-skill _theme.py copies identical, brand font present, font embeds in CSS
• founder-skills/tests/test_e2e_deck_review.py, test_e2e_financial_model_review.py, test_e2e_market_sizing.py — the three paid end-to-end lanes; LLM-driven; carry the e2e marker. Shared plumbing in tests/_e2e_harness.py — deck-review deliberately does NOT use it (it is the lane the release tag gates on; fold it in when a failure costs a re-run rather than a re-tag). One lane per changed coaching-payload builder is the rule: contract tests pin that a payload key is emitted and named on both prompts, and structurally cannot show a sub-agent reading it.
• founder-skills/tests/fixtures/ — Synthetic test inputs (deck-review compose-invariant fixtures + synthetic deck for e2e + golden expected file)
• .github/workflows/skill-quality.yml — Skill-quality CI (contract tests per-PR, e2e smoke on internal PRs only)
• artifacts/ — Persistent working directory for skill run artifacts (gitignored, created at runtime)