CLAUDE.md git:20260906.c24fbe5A

Immutable. This exact content is served forever at /api/v1/blob/11d83487b7daefd2.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this repository is

The Working Genius plugin itself: a Claude Code plugin — 22 skills under `skills/` and three subagents under `agents/`, distributed through the plugin marketplace (`.claude-plugin/`). The skills are prose, plus three things only Claude Code reads that ride inside the same folders (below); nothing here is held back for another client (user ruling, 2026-09-05). There is no runtime, no build and no test suite; the one script is the format's instrument, `skills/genius-file/measure.py`, which counts and never decides — a fork must be able to carry the whole thing as plain folders, and still can. Dogfood work files (`.genius/`) are gitignored and never shipped.

## Commands

There is nothing to build or run. Four checks matter when editing skills:

- **Count characters, never bytes.** `python3 skills/genius-file/measure.py count <file>` is the instrument and this one-liner is what it does; any number that enters a skill or a record comes from one of these and not from `wc -m` (which counts bytes under most non-interactive locales) or `awk length()`:
  ```
  python3 -c "import sys;print(len(open(sys.argv[1],encoding='utf-8').read()))" <file>
  ```
- **Relative links between skill files must resolve** (`agents/inventor.md`, `../tenacity/agents/reviewer.md`, `FILE-FORMAT.md`, `../genius-file/BACKLOG-FORMAT.md`). A one-off check:
  ```
  python3 -c "import re,os,glob;print([(f,t) for f in glob.glob('skills/**/*.md',recursive=True) for t in re.findall(r'\]\(([^)#]+)(?:#[^)]*)?\)',open(f,encoding='utf-8').read()) if not t.startswith('http') and '<' not in t and t!='CONTRACT.md' and not t.endswith('.log.md') and not os.path.exists(os.path.join(os.path.dirname(f),t))])"
  ```
- **Frontmatter must parse, and the instrument must not fail.** The preloads and the two prompt hooks live in YAML frontmatter, and a stray indent drops the whole block without a word; `measure.py` is injected into four commands and a skill whose injected command fails is aborted whole, so it exits 0 on an empty directory and on a malformed snapshot; `stop-judge.py` blocks a stop only on a clear verdict, so it exits 0 on garbage and on an absent `claude`. One check for all three:
  ```
  python3 -c "import yaml,glob;[yaml.safe_load(open(f,encoding='utf-8').read().split('\n---\n')[0][4:]) for f in glob.glob('skills/*/SKILL.md')+glob.glob('skills/*/agents/*.md')];print('frontmatter ok')" && python3 skills/genius-file/measure.py status >/dev/null && printf 'x' | python3 skills/genius-file/stop-judge.py && echo 'instruments ok'
  ```
- **Release.** Any change under `skills/` or `.claude-plugin/` that merges to `main` bumps `version` in `.claude-plugin/plugin.json` in the same change — marketplace clients detect updates only through that number. A skill added or removed moves the count in README's first line.

## Architecture

**One skill = one folder** `skills/<name>/SKILL.md`, frontmatter `name`, `description`, optional `argument-hint`. `disable-model-invocation: true` marks a command only the user types (`/genius`, `/architect`, `/designer`, `/compact`, `/distill`, `/reconcile`, `/triage`, `/waitwhat`, `/setup-working-genius`); the six stage skills and the discipline skills (`genius-file`, `record-prose`, `errata`, `decision-record`, `domain-glossary`, `blindspot`, `diagnose`) are model-invoked. **The three subagents** — `skills/invent/agents/inventor.md` (spawned by `/invent`, one per angle), `skills/enable/agents/builder.md` (by `/enable`'s coordinator, one per slice), `skills/tenacity/agents/reviewer.md` (by `/enable` at a slice close and `/tenacity` at close-out) — are Claude Code plugin agents, declared by path in `plugin.json`'s `agents` field: frontmatter `name` and `description`, and no `tools` list, because the agent inherits everything the session has and a list only names less (the reviewer's read-only discipline is a rule in its body, not a grant; `Bash` could write anyway). The body is the subagent's system prompt and carries the discipline, while the spawning skill's task message carries the parameters (the problem and angle, the slice and where to build, the diff and what it is judged against). They live inside the skill that spawns them, not in a top-level `agents/`, so a skill, its task message and its agent's brief change in one folder. The body still stands alone as a brief, because the preload (below) is context and not a guarantee — that it reaches a spawned agent is unmeasured. The skill names what the message must carry; the agent names what it hands back — one home each.

**Three things only Claude Code reads**, each inside the folder of the skill that uses it: `/genius`, `/compact`, `/reconcile` and `/distill` inject the instrument's output before the model reads — `status`, `snapshots`, `links`, `distill` — and their `allowed-tools` pre-approves exactly that command, because an injected command that would prompt aborts the invocation (`anchors <slug>` is run by the session at a close instead, pre-approved in `/enable` and `/tenacity`, because an injection is taken at invocation and a close comes later); the three agents preload the discipline skills by scoped name (`workinggenius:genius-file`, …), so the skills are the home and the body restates only what a brief must; and two judges, one `command`-type hook, `skills/genius-file/stop-judge.py`, registered by `/enable` (`Stop` and `SubagentStop` matched on the builder) and `/tenacity` (`Stop`) — by invocation, never by installation, because a plugin-level `hooks/hooks.json` fires in every session with the plugin enabled, flow or not, and the flow never hijacks a request that didn't enter it. The judge blocks only a turn announcing its own next dispatch with nothing running in the background, or a builder's claim of done with no `command → result` line; three free checks settle most stops (`stop_hook_active`, a running subagent, no work at enablement or tenacity — the one frontmatter field it reads), and only then a fast model reads the turn's last message, never the transcript, through a nested `claude -p` with hooks, skills, tools and MCP off; every failure of its own allows the stop. Claude Code ignores, with a warning, hooks written in a plugin agent's own frontmatter, so the builder's judge lives with the skill that spawns it. **Measured, 2026-09-05, all through a live two-turn session driven by the Agent SDK:** a skill's `prompt`-type `Stop` hook is removed the moment its condition is first met, so it guarded only the invoking turn — whatever the docs say about the rest of the session; a `command`-type hook registered by the same skill fired on both turns, which is why the judges are one; `${CLAUDE_PLUGIN_ROOT}` is substituted in a skill's frontmatter hook command and `${CLAUDE_SKILL_DIR}` is not; and `claude -p --bare` reads no OAuth login, so the nested call runs without `--bare`. A plugin-level `hooks/hooks.json` prompt hook also registers and persists (measured), and is not used, for the reason above. This reopens 275ed4f this far and no further (user ruling, 2026-09-05): what died there was a parser demanding gate blocks in work files; what returned is a model reading the same message a person would, at an action point, adding no line to any file. Two runs by hand are on record (2026-09-05 and 2026-09-06, the same picking-robot warehouse scheduler built through the whole flow, the records in those commits' messages): 47 judge decisions — 34 stops allowed as pauses on background work, 11 model-judged allows, 2 allowed for no work in build — no block and no false block, and no stall for a judge to catch, so the runs show the judges cost nothing and prove nothing about the failure they name. One more run by hand, or `claude plugin eval` when it opens, is still owed; until then they are experiments, not a layer to extend. The judge text is copied into `enable` and `tenacity` deliberately: a frontmatter cannot point.

**The flow** is six commands the user types in order — `/wonder → /invent → /discern → /galvanize → /enable → /tenacity` — with `/genius` as the map. The flow never advances itself and never hijacks a request that didn't enter it; a stage the user doesn't type has no section in the work file, and that absence is the record.

**The work file is the whole handoff between sessions**, and its design is the part that takes several files to see. One piece of work = `.genius/<slug>/` holding three files with three growth laws: the snapshot `<slug>.md` grows by *scope* and has a 6000-character ceiling (Slices roster excluded); the log `<slug>.log.md` grows by *time* and is append-only; `CONTRACT.md` grows by *slice count* and holds the brief, seams, pinned values, each slice's acceptance criteria (their one home — the snapshot's slice line only links them) and the conventions the build established. Compaction routes each snapshot line by one question — *does this line still constrain work that isn't finished?* — under one invariant: nothing leaves the snapshot except into the log or `CONTRACT.md`, with a link left behind. Cross-work files at `.genius/` (`BACKLOG.md` + `BACKLOG.log.md`, `DECIDED.md`, `HISTORY.md`) have their own format. Where this is written: `genius-file/FILE-FORMAT.md` (the shape), `genius-file/BACKLOG-FORMAT.md`, `genius-file/FORMAT-EDGES.md` (the measurements behind the rules, with commit hashes).

**Two layers run through every file the flow writes**: what *binds* (snapshot, contract, `DECIDED.md`, `CONTEXT.md`, backlog seeds) is rewritten in place when wrong; what *records* (any log, any done file) is appended to and never edited. `errata` owns that rule; `/reconcile` sweeps drift against the repo; `/compact` and `/distill` are the retroactive passes. There is one format, and no recognition of older ones: a file in another shape is read for what it holds and brought to the format when next written to.

**Each rule has exactly one home**, and other skills point at it rather than restate it — the compaction question and its destinations in FILE-FORMAT, the sentence discipline in `record-prose`, the correction moves in `errata`, the seed shape in BACKLOG-FORMAT. When editing, change the owning file and check the pointers; a rule copied into a second skill drifts the first time either is edited.

## How skills are written

- Concept first: each skill carries its purpose, its failure mode, the concept in one bold line, and one threshold that must be honestly true before the next stage. Stage skills also carry a short `## How it runs` list. Every rule states its why in the same sentence; a constraint that can't name its reason doesn't land.
- Action constraints are where the measured value lives and stay firm (interview is live dialogue, red before green, fresh verification, wounds found never manufactured, findings carry evidence). Taxonomies are floors, not scripts.
- Killed designs stay killed unless measured evidence reopens them. Before proposing express paths, sizing calls, autonomy modes, gate checklists in work files, hooks or scripts that parse a work file's prose or decide anything (the judge reads one frontmatter field to know whether to ask; the decision is the model's), skip bookkeeping, or old-format recognition, read the git history — `0cc21de`, `925accf`, `275ed4f`, `f8897e9` each record a ruling and its kill-reason. Reopening one costs a counter-example somebody measured, named against the leg it breaks.
- Commit messages carry the reasoning — what was observed, what changed, why — because the repo has no other record of its rulings.