Cap Table

Cap-Table Skill

Model cap-table mechanics for founders so they understand what their term sheets, SAFEs, and convertible notes actually do to their ownership — before they sign. Produce rule-pack-cited math for SAFE conversion, convertible-note conversion, priced-round dilution, option-pool top-ups, anti-dilution, and Israeli ↔ Delaware flips. Every counsel-review item links back to a primary source (YC SAFE primer, NVCA model docs, Israeli Companies Law / Income Tax Ordinance, etc.). Tone is founder-first: a candid coach who's read the documents you can't be expected to read.

Skill Metadata

• Author: lool-ventures
• Version: managed in founder-skills/.claude-plugin/plugin.json
• Compatibility: Python 3.10+ and uv for script execution.
• Rule pack: consumes cap-table-rules.json at script runtime.
• Exports (full pipeline, in cap-table-{slug}/):
• inputs.json + scenarios.json → financial-model-review (cross-validates revenue/dilution scenarios)
• cap_state.json → ic-sim (IC partners ask about dilution exposure)
• counsel_packet.json → fundraise-readiness (overall readiness scorecard)
• report.json → fundraise-readiness, future cross-document-consistency skill
• Exports (fast-assess mode, in cap-table-{slug}-fastassess/):
• fast_assess_only.json — sentinel marking that fast-assess ran (no canonical artifacts). See [references/sentinel-schema.md](references/sentinel-schema.md). Future cross-skill consumers MUST check for this sentinel before treating a missing canonical artifact as "cap-table never ran."
• report_fast_assess.md — founder-facing markdown deliverable
• Imports:
• market-sizing:sizing.json — sanity-check that the planned raise + cap is consistent with modeled SAM/SOM
• financial-model-review:report.json — current revenue scale + runway, to gate scenario plausibility

Skill Execution Model (READ FIRST)

This skill runs inline in the main thread (not as a sub-agent). The main thread has full tool access including Bash, and is responsible for orchestrating the full pipeline: running producer scripts, persisting artifacts, and dispatching the cap-table sub-agent at specific moments.

Two dispatch contexts for the sub-agent:

• Context A — Per-step analytical dispatch (Mitigation 1): Used ONLY for document-extraction lanes. Cap-table math is fully deterministic and rule-driven, so Context A is reserved for tasks that genuinely need semantic extraction from natural-language documents:
• INSTRUMENT_EXTRACTION — extract terms from a PDF/DOCX SAFE, note, term sheet, or option plan
• SPREADSHEET_STRUCTURE_DETECTION — identify which cells encode founders / preferred / options / convertibles in a freeform spreadsheet that doesn't match the Carta schema

The sub-agent returns structured JSON. The main thread pipes the JSON through the validation producer (extract_instrument.py / extract_cap_table.py), which enforces the anti-hallucination gate. The sub-agent does NOT write artifacts directly.

• Context B — Post-compose coaching dispatch (POSTCOMPOSECOACHING): After compose_report.py writes report.md + report.json, the sub-agent is dispatched with the structured coaching_payload inlined. It performs Grep idempotency, edits report.md at the per-run uuid marker to add ## Coaching Commentary, Grep-verifies all canonical artifacts share the same run_id, and returns a success/blocked payload.

Why this model: In Cowork, sub-agents have a restricted tool allowlist (no Bash). By keeping orchestration in the main thread and dispatching sub-agents only for analytical or post-compose tasks that use only Read/Edit/Glob/Grep, the pipeline works correctly in both Claude Code (CLI) and Cowork.

Tolerant JSON extraction protocol (Context A): After dispatching the sub-agent, capture its final assistant message. The sub-agent should return raw JSON, but may wrap it in `json ... ` fences or add a prose preamble. Extract JSON tolerantly:

1. If the message is wrapped in a `json ... ` (or plain ` ... ` ) fence, strip the fence first.
2. Try to parse the stripped text directly as JSON.
3. If that fails, walk through the text looking for the first { character and try json.JSONDecoder().raw_decode(text[i:]) — this is brace-aware and handles nested objects correctly (unlike regex, which truncates on the first }).
4. If extraction fails entirely, re-prompt the sub-agent with: "Your previous reply could not be parsed as JSON. Return ONLY the JSON object — no markdown fences, no prose preamble."

> See founder-skills/references/skill-execution-model.md for the full inline-skill execution model (3 dispatch contexts, Mitigation 1+2, producer contract, Cowork quirks, per-symptom triage).

Input Formats — Four Lanes

Each lane produces normalized instruments.json and/or cap_state.json plus an extraction_audit.json trail. The main thread picks the lane from the founder's input type.

• Lane 1 — Single instrument (PDF / DOCX). Typical: 5–15 page SAFE, term sheet, convertible note, option plan, or Articles of Association. Main thread reads via the Read tool (native PDF support, up to 20 pages per call; longer docs use pages parameter). For SAFEs/notes/term-sheets/option-plans: dispatch Context A INSTRUMENT_EXTRACTION; pipe returned JSON through extract_instrument.py. For AoAs: dispatch Context A ARTICLES_OF_ASSOCIATION_EXTRACTION; pipe returned JSON through extract_aoa.py which validates + merges preferred-series terms into inputs.json.preferred_series[]. User confirmation via AskUserQuestion before math runs.
• Lane 2 — Carta XLSX export. Typical: multi-sheet XLSX (Securities, Convertibles, Stakeholders). extract_cap_table.py --mode=carta reads the sheet-name fingerprint and maps known columns → canonical schema. User confirms ambiguous mappings. See references/carta-pulley-mapping.md for the column-mapping table. Pulley is not yet supported end-to-end (--mode=pulley is a stub that returns a structured blocker pointing to --mode=freeform); restore when a real Pulley XLSX is available to verify against.
• Lane 3 — Freeform spreadsheet (founder's Excel). Arbitrary structure. extract_cap_table.py --mode=freeform extracts cells + sheet structure. Dispatches Context A SPREADSHEET_STRUCTURE_DETECTION to identify cell semantics. Validation gate enforces per-field confidence before commit.
• Lane 4 — Structured JSON paste / conversational. Founder pastes pre-built JSON or describes their cap-table in chat. Direct heredoc into inputs.json / instruments.json; still flows through extract_cap_table.py --mode=validate for schema enforcement.

Available Scripts

All scripts live at ${CLAUDE_PLUGIN_ROOT}/skills/cap-table/scripts/:

• extract_instrument.py — Validates Lane-1 sub-agent output against the per-instrument schema; anti-hallucination gate (per-field confidence; "did you find this verbatim in the document"). Accepts: safe, convertible_note, convertible_loan_agreement (Israeli CLA), convertible_security (YC pre-SAFE form), term_sheet, option_plan, warrant, non_instrument.
• extract_aoa.py — Validates Lane-1 sub-agent output for Articles of Association (separate sub-context ARTICLES_OF_ASSOCIATION_EXTRACTION). Per-preferred-series field gates; detects 4 Israeli AoA counsel-review items (israeli_aoa.* rule pack domain): drag-along 1x, full-ratchet anti-dilution. With --inputs flag, merges validated preferred_series block into inputs.json.preferred_series[] with extraction provenance stamp.
• extract_cap_table.py — Lane-2/3/4 cap-table extraction; modes: carta, pulley, freeform, validate. Emits cap_state.json + instruments.json + extraction_audit.json.
• cap_state.py — Reads inputs.json + instruments.json; computes as-converted totals; writes cap_state.json. Validates per the §11 schema. Note: the YC Company Capitalization denominator scoping (Gotcha #1) is enforced here — as_converted_totals.* is the pre-financing snapshot.
• rule_audit.py — Two-phase: --phase=pre_math writes the gating block (per-rule, per-instance status + scope + overlays) BEFORE math runs; --phase=post_math composes watchlist + counsel-review items AFTER math. Math producers consume the gating block.
• run_scenario.py — Solver / orchestrator (NOT a fixed chain). Builds a dependency graph; classifies independent vs coupled computations; algebraic resolution first, fixed-point iteration as fallback for non-linear systems (discount-only SAFEs). Convergence threshold + max iterations are parameterized.
• safe_conversion.py — SAFE conversion math (cap-only, cap-plus-discount, discount-only, uncapped-MFN). Binds rule-pack inputs per the §5.1 binding table (see design doc).
• note_conversion.py — Convertible-note conversion math (cap, discount, both, repay, extend, counsel-review, override branches). Binds rule-pack inputs per the §5.2 binding table.
• priced_round.py — Priced-round math (pre-money, new-money, pool top-up, anti-dilution). Coupled with SAFE/note conversion via the solver.
• option_pool.py — Option-pool top-up math (rule pack option_pool.pre_money_topup). Uses target_basis denominator.
• anti_dilution.py — BBWA / full-ratchet anti-dilution (Gotcha #2 enforced here).
• flip_scenario.py — Israeli ↔ Delaware flip mechanics (v0.1: share-for-share 1:1 only — see Gotcha #7).
• counsel_packet.py — Extracts counsel-review items from rule_audit.json into a standalone counsel-handoff packet.
• compose_report.py — Assembles all artifacts into report.md + report.json (with embedded coaching_payload block). Cross-artifact validation; emits per-uuid coaching insertion marker.
• visualize.py — Generates report.html (self-contained, vendored Chart.js + inline SVG).
• explore.py — Generates explorer.html (polished interactive scenario tool; demo/video-friendly).
• _dispatch_json.py — Tolerant JSON extraction for Context A returns.

Also available from ${CLAUDE_PLUGIN_ROOT}/scripts/ (shared):

• founder_context.py — Per-company context management (init/read/merge/validate)
• find_artifact.py — Resolves artifact paths by skill name, artifact filename, optional company slug

Run with: python3 ${CLAUDE_PLUGIN_ROOT}/skills/cap-table/scripts/.py --pretty [args]

Available References

Read as needed from ${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references/:

• cap-table-reference.md — Domain primer: SAFE mechanics, note mechanics, anti-dilution formulas, §102/3(i)/85A/104H/103K, IIA royalty mechanics, BBWA formula, counsel-review semantics. Read before implementing any math producer.
• cap-table-rules.json (v0.2.8+) — The executable reference layer; 44 rules across 9 domains with formulas, inputs, outputs, source citations, datewindow semantics, behaviortarget (script_formula / validation_rule / warning_rule / counsel_review_flag / benchmark / source_note). Every math producer loads this at start.
• cap-table-rules.schema.json — JSON Schema for the rule pack (Draft 2020-12). The schema description on counsel_review is the authoritative definition of "reliance boundary, not confidence score" (see Gotcha #9).
• schemas/ — JSON Schemas (Draft 2020-12) for every artifact: inputs.schema.json, instruments.schema.json, cap_state.schema.json, scenarios.schema.json, rule_audit.schema.json, counsel_packet.schema.json. Each producer script validates against the matching schema.
• carta-pulley-mapping.md — Per-vendor column-mapping table for Lane 2 extraction.

Artifact Pipeline

Every cap-table engagement deposits structured JSON artifacts into a working directory. The final step assembles them into a report and validates consistency. This is not optional.

| Step | Artifact | Producer | |------|----------|----------| | 1 | founder context | founder_context.py read/init | | 2 | inputs.json | Agent heredoc or extract_*.py (Lane 4 / Lanes 1–3) | | 3 | instruments.json | extract_instrument.py (Lane 1) or extract_cap_table.py (Lane 2/3/4) | | 4 | cap_state.json | cap_state.py | | 5 | extraction_audit.json | extract_*.py trail | | 6 | rule_audit.json (gating block) | rule_audit.py --phase=pre_math | | 7 | scenarios.json | run_scenario.py (solver; consumes gating block from Step 6) | | 8 | rule_audit.json (watchlist + counsel items) | rule_audit.py --phase=post_math | | 9 | counsel_packet.json + counsel_packet.md | counsel_packet.py | | 10 | comparisons.json (when ≥2 scenarios) | compose_report.py | | 11 | report.md + report.json (with coaching_payload block) | compose_report.py --write-md | | 12 | report.html | visualize.py | | 13 | explorer.html | explore.py | | 14 | ## Coaching Commentary appended to report.md | Context B sub-agent (POSTCOMPOSECOACHING) |

Rules:

• Deposit each artifact before proceeding to the next step.
• Math producers consume rule_audit.json.gating[R][I] for rule-applicability decisions — NOT the rule pack directly. The two-phase split is what makes this work.
• For producer-script artifacts, the agent supplies JSON on stdin where applicable; the script schema-validates against references/schemas/.schema.json. Never write artifacts directly via Write or Edit — always pipe through the producer script so metadata.run_id is injected and schemas are enforced.
• compose_report.py enforces that all required artifacts share the same run_id and emits STALE_ARTIFACT warnings on mismatch.

Keep the founder informed with brief, plain-language updates at each step. Never mention file names, scripts, or JSON. After each major step (extraction, scenarios, counsel), share a one-sentence finding before moving on.

Workflow

Step 0: Path Setup

SCRIPTS="${CLAUDE_PLUGIN_ROOT}/skills/cap-table/scripts"
REFS="${CLAUDE_PLUGIN_ROOT}/skills/cap-table/references"
SHARED_SCRIPTS="${CLAUDE_PLUGIN_ROOT}/scripts"
ARTIFACTS_ROOT="${ARTIFACTS_ROOT:-$(pwd)/artifacts}"
mkdir -p "$ARTIFACTS_ROOT"

# Per-run identifier — used by every producer's --run-id. Stays constant
# across the whole engagement (compose enforces parity).
RUN_ID="${RUN_ID:-$(date -u +%Y%m%dT%H%M%SZ)}"

If CLAUDE_PLUGIN_ROOT is empty OR the path it resolves to does not exist in your environment (in Claude Cowork it substitutes to a host-side path that is not present inside the session VM — test with ls), fall back: Glob for **/skills/cap-table/scripts/cap_state.py, strip to get SCRIPTS, derive REFS and SHARED_SCRIPTS. In Claude Cowork this is always the case — don't retry the substituted path; go straight to the Glob fallback. If Glob returns multiple matches, prefer the one under a plugin mount (.remote-plugins/ or the plugins cache) over any workspace copy. If Glob returns nothing, locate it with Bash: find / -path '*/skills/cap-table/scripts/cap_state.py' 2>/dev/null | head -5.

After Step 1 (when the company slug is known), derive REVIEW_DIR. Two modes:

• Full pipeline (default — when the founder shared a document, asked for the full review, counsel packet, or interactive explorer, OR when there's no existing full review for this slug): REVIEW_DIR="$ARTIFACTS_ROOT/cap-table-$SLUG".
• Fast-assess mode (Phase O — short directional answer to a conversational question, no document attached, no explicit "full review" request): REVIEW_DIR="$ARTIFACTS_ROOT/cap-table-$SLUG-fastassess". Run quick_assess.py (Step 5-fast) instead of Steps 2–11. Total wall-clock under 60 seconds.

Slug discipline: Use the slug returned by founder_context.py VERBATIM in directory names — never invent ad-hoc suffixes (e.g. appending -seed, -round, or any other qualifier). Downstream find_artifact.py lookups resolve by that

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: lool-ventures
• Source: lool-ventures/founder-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.