Quickstart

This page narrates a femto session against the reference multi-tenancy pack — what each actor does, what state lives on disk, and what the gate decision looks like at emit time.

Session capture pending

Real screenshots and a verbatim transcript ship with Tier 4, after the first live calibration run. Until then this walkthrough describes the flow against the contract — the steps are load-bearing; the framing around them is not yet frozen.

1. Install

/plugin marketplace add patrickmvla/femto
/plugin install femto@femto-marketplace

/plugin install drops the plugin’s MCP server declaration, hooks, and subagents into your Claude Code environment. Run the two commands above inside any Claude Code session — click the copy button and paste at the prompt.

2. Opt the repo in

Commit a .femto/config.yaml at the repo root listing the packs that apply:

packs:
  - multi-tenancy

Per-repo opt-in is deliberate. The disconnection cost is social and process-visible — not a keyboard shortcut — so a pressured engineer cannot silently skip the gate.

3. The session

Session sequence: Engineer → Main Opus → Reader → Probe (MCP) → Grader → Hook. Main Opus calls femto_start_session, Reader writes required reads, Probe loops until every required KC hits its turn minimum, Grader scores, Hook gates at emit time. — One femto session, six actors, one gate

Six actors are involved in one session. Their boundaries are deliberate — the probe is not the grader; the grader is not the hook.

Engineer describes the problem (stack trace, prose, logs). Normal Claude Code usage.
Main agent (Opus) recognises the domain, calls femto_start_session. A new .femto/session-<id>/ directory is written with an initial state.json.
Reader subagent (Haiku) writes the required reads declared by the pack — for multi-tenancy that’s a schema sweep, an RLS-policy sweep, and a session-binding sweep. Each output is a markdown file with inline source citations.
Probe (MCP server) loops over the required KCs. Every turn the engineer specifies the fix at domain level; the server records kcs_touched and turn count. The probe continues asking even on correct answers until every required KC has hit its turn minimum — the checklist, not the LLM’s verdict, decides when the probe ends.
Grader subagent (Opus, separate model/context) receives the rendered probe log and the reads, scores each turn’s correctness, and writes grader.md with YAML frontmatter. The grader never sees live dialogue state — only the serialized log.
PreToolUse hook fires before the next Edit / Write / Bash. It reads grader.md from disk, checks per-required-KC mastery against the pack’s threshold, and either allows the tool call or blocks with a structured message pointing at which KC fell short and how to retry.

4. What blocked looks like

The hook block message names the failing KC and the measured mastery, and it surfaces the three retry paths:

/femto retry-reads — re-dispatch the reader subagent if a required read is missing or malformed.
/femto retry-probe — continue the Socratic probe for the KC that fell short.
/femto status — show the current session’s phase, KC coverage, and grader verdicts.

The block is deterministic — not an LLM decision. The agent cannot talk the hook into letting it through.

5. What ships to disk

Everything femto knows about a session lives at .femto/session-<id>/:

state.json — current phase, KC coverage, CC session binding.
reads/*.md — reader subagent outputs with citations.
probe-log.md — rendered turn log fed to the grader.
grader.md — grader verdict with per-turn correctness and per-KC mastery.
events.jsonl — OTel-aligned session lifecycle events.

.femto/ is gitignored by the plugin’s template. Sessions older than the configured retention window (default 30 days) are reaped automatically.

6. Calibrating your own pack

The harness that produces the published metrics is the same one any contributor runs locally. See Contributing for the pack layout, and the calibration doc for the full run-flow, claude setup-token flow, and the three mandatory disclosure conditions.

7. Adding your own pack (org-local)

For compliance-grade or org-specific rules (HIPAA, PCI, SOC2, NIST SP800 controls, internal policies, bespoke KCs), write a pack in your repo and femto will load it alongside the shipped ones.

Create .femto/packs/<pack-id>/ at your repo root with the same shape as a shipped pack:

.femto/packs/org-hipaa-access/
├── pack.json
├── kcs/
│   └── <kc-id>.md
└── tests/
    └── <test-case-id>.md

Validate the pack before the first session:

bunx femto-validate-pack .femto/packs/org-hipaa-access

Reference the pack id in your .femto/config.yaml the same way you reference shipped packs. Femto’s MCP server discovers org-local packs automatically when the directory exists.

Trust boundary. Org-local packs receive the structural Gate 1 guarantees — no-designed-in-bypass, probe-before-emit, grader-separated — but their reliability numbers are not published on femto’s hosted Metrics page. That surface is operator-curated for shipped packs only. You can still run bunx femto-harness run .femto/packs/<pack-id> locally to calibrate against your own test cases and publish the report to your internal dashboards.

ID collision. If an org-local pack reuses the id of a shipped pack, the shipped pack wins. Pick a distinct id (an org- prefix is a useful convention).

See Concepts § Three content tiers for the design rationale and Contributing § Authoring an org-local pack for the full authoring guide.