recursive-harness

Configure or explain Recursive Guard, a separately trusted Codex plugin that is inert unless a repository explicitly adds a reviewed .recursive-guard.json policy. Use when a user wants opt-in protection for instruction, provider, hook, or other sensitive repository paths without replacing existing agent configuration.

EXPERIMENTAL. Explore alternative solutions or draft a measurable roadmap as a preview, while preserving existing project instructions and requiring an exact-target approval record before any tracked-file or external action. Use when the user asks to brainstorm, incubate an idea, or preview a roadmap. Do not use it as autonomous build or mutation authority.

Coordinate concurrent agents through collision-safe local claims, bounded leases, idempotent handoffs, and a read-only Mission projection without changing the project or contacting an external service. Use when multiple sessions or worktrees need explicit ownership and handoff evidence.

Produce a deterministic structural scorecard, run a fixed Atlas-style query, inspect an eval corpus without executing repository code, or emit a review-only proposal diff. Use when a user asks for portable evidence about a repository, its tests or instructions, eval-corpus health, or a proposed verification change without modifying the project.

Capture corrections and follow-ups in private local state, select a compact retrospective, inspect promotion candidates, or emit a review-only learning diff. Use when a user corrects an agent, asks to remember a workflow lesson, requests a retrospective, or wants to improve reusable instructions without silently changing the current repository.

Capture corrections and follow-ups in private local state, select a compact retrospective, inspect promotion candidates, or emit a review-only learning diff. Use when a user corrects an agent, asks to remember a workflow lesson, requests a retrospective, or wants to improve reusable instructions without silently changing the current repository.

Use immediately when no installed skill covers a reusable domain, or when feedback, a mistake, or a better process shows that an existing skill is incomplete or wrong. Record the first observation, create or amend a private candidate, and dogfood it now. Follow provenance to the canonical skill instead of forking it. Recurrence strengthens evidence but never delays a proven correction.

Configure or explain Recursive Guard, a separately trusted Codex plugin that is inert unless a repository explicitly adds a reviewed .recursive-guard.json policy. Use when a user wants opt-in protection for instruction, provider, hook, or other sensitive repository paths without replacing existing agent configuration.

Use immediately when no installed skill covers a reusable domain, or when feedback, a mistake, or a better process reveals that an existing skill is incomplete or wrong. Record the first observation, create or amend a private candidate, and dogfood it on the triggering case now. Follow provenance to improve the canonical skill instead of forking it. Recurrence strengthens evidence but never delays a proven correction.

Record falsifiable predictions, score outcomes, inspect calibration and a compact scorecard, or audit/delete Recursive Observe's private local evidence. Use when a user asks to track whether an agent task succeeds, measure confidence, review prediction accuracy, or manage Observe data without changing the current repository.

Choose HOW one git repo lives inside another — submodule vs subtree vs gitignore+materialize-hook vs vendor-and-commit. Trigger when you reach for `git submodule`/`git subtree`, weigh a "repo inside a repo", need a sub-project (plugin/lib with its own repo) to ALSO live here AND ride into worktrees, or want a vendored dep that stays updatable. Each trades worktree presence vs in-place dev vs history ownership; pick blind → empty submodule, or a plugin missing from worktrees. NB `.worktreeinclude` canNOT carry a nested-repo dir (verified). Defers to vendoring-skills + worktree.

The per-feature build→review discipline — run it on ANY non-trivial build/feature/fix/refactor (anything with a definition of done or that changes behavior) so you stop re-prompting it and stop shipping green-but-wrong code. Sequence: align on intent → criteria+predict → write FAILING example + PROPERTY tests → fresh-context review of spec+tests BEFORE coding → build to green → verify in practice end-to-end → capture eval → PR. A conductor that COMPOSES calibration/critic/verify/eval-capture — never reimplements them. Skip only trivial one-liners, pure lookups, read-only analysis.

Use while DRIVING a harness change onto trunk — opening/merging PRs, especially several at once (a roadmap or /retro batch), or the moment a guard unexpectedly BLOCKS a git/gh/bin-harness command mid-flow. Encodes the operating mechanics the enforcement guards + GitHub impose that aren't obvious until they bite: stacked-PR merge order, running locked-path commands cleanly, and what to expect at the human gate. Pairs with harness-pr (the PR template), windows-host-paths (token mechanics), worktree.

Turn one big goal into a dated, sequenced, measurable ROADMAP.md you stick to. Trigger when the user wants to roadmap / scope out / plan / sequence a multi-feature goal, says "turn this idea into a plan", or keeps iterating with no deadline or win condition. A commitment device vs exploration-loop drift: frame -> decompose -> map deps/risks -> sequence into time-boxed milestones -> hand each feature to build-loop. Each milestone gets a deadline, done-criteria, and a hypothesis you score. Skipping it = endless iteration, no ship date. Single feature -> use build-loop.

Use to answer a question about how THIS harness is wired — "what enforces / guards X", "how does Y work", "what depends on Z / what breaks if I change it", "is there a path from A to B", "what's orphaned or load-bearing", "which spec governs FILE". Answer by traversing the cartograph graph (cartograph/extract.py --query / --context), citing the file each result names (Read it to pin the line), NOT by grepping. The harness is wired by lifecycle triggers + settings.json + /cmd pointers, which an import-grep misses but the graph models. Read-only.

Use the MOMENT a git/worktree/file/PowerShell op is unexpectedly BLOCKED, silently no-ops, or reports a "protected system path" on a path you KNOW is valid: the repo lives at a SPACE-containing path (D:\GitHub Projects\recursive-harness) and first-space-naive parsers truncate it and hit the wrong target with NO error — fix structurally, don't re-quote. ALSO use when composing a command/script for the USER to run: their shell is Windows PowerShell 5.1 (not bash: `&&` errors, `/d/` paths and `.sh` shebangs fail), NOT the assistant's Bash tool. Pairs with worktree + harness-authoring.

Generate distinct solutions to ONE problem, then pick. Trigger when the user wants to brainstorm, explore/compare options, name/design/architect something, asks for ideas, OR wants to INVENT, find a breakthrough, or solve from first principles when known options disappoint. Mode 1 (solution arena): parallel agents across orthogonal stances, divergence guard, side-by-side pick. Mode 2 (invention forge): frame to invariants, diverge on invention vectors, recombine, adversarial filter w/ prior-art search, loop to grounded breakthrough. Skipping yields an anchored answer or confident reinvention.

Predict-then-score protocol. Use at the START of any non-trivial task (multi-file change, debugging session, design decision, anything you could be wrong about) to log a falsifiable prediction, and at the END to score it. Also use when the user asks "how confident are you", when choosing between approaches, or when /calibrate reports overconfidence in a category. This protocol IS the harness's verified self-awareness; skipping it makes your judgement unmeasurable.

Standards for writing or modifying the harness's own artifacts — skills, commands, agents, hooks, user-model entries. Use whenever /retro routes a learning into a new or edited artifact, when promoting a project-level learning upstream, or when refactoring existing skills. Encodes budgets, provenance, falsifiability, and the duplication check. Writing an artifact without this skill produces lint failures and junk-drawer drift.

Use the moment you fix a bug, see a failure recur, or are about to re-fix code you've touched before. `heal.py fix` logs the bug + scored attempt in ONE call (the low-friction primary path); `heal.py match` recalls prior FALSIFIED hypotheses for a file/error before you re-fix, so you don't re-derive dead ends. A per-repo bug+attempt ledger keyed by cwd makes a root defect resurfacing 'in a different shape' visible across sessions. Pull the web via /heal — never pushed. Pairs with stuck-detection (the in-session ladder); this is the cross-session memory.

The learning-extraction procedure behind /retro and /meta-retro. Use when a significant task completes, when the Stop gate or 3-corrections nudge fires, when the user expresses frustration or strong approval, or when you finish anything you'd handle differently next time. Converts session experience into reviewed harness diffs — this is the ONLY mechanism by which the system improves, so under-triggering it means not learning.

Consultant procedure for authoring self-contained loop prompts. Trigger when the user asks for a prompt that runs "until it's done/verified/bug-free", wants /goal + /loop templates, says "loop Claude until X is finished", needs a fuzzy goal turned into checkable done-criteria, or returns with a failed loop-run to autopsy. Forges wishes into 3-7 binary Definition-of-Done criteria, per-iteration verification, a state artifact, a stuck protocol, and three exits (success/budget/blocked). AUTHORS loop prompts as deliverables — NOT the built-in /loop runner, NOT build-loop.

End-to-end procedure for turning a charter (GOAL.md or inline brief) into a validated, managed venture: predict, scaffold the subproject, stand up a markdown PM board, fan out a strategy-IP workflow, build the MVP contract-first with tests-as-you-go, validate LIVE (not just unit tests), run an adversarial-review workflow and fix findings, write the venture ledger, branch+commit and score. Trigger when the user asks to build/spin up/stand up a company, product, MVP, or venture end-to-end, or runs /venture. Skipping it yields demos without validation gates or a ledger.

Use the moment the same error, test failure, or rejection happens TWICE in a row, when you notice retry-with-minor-variation behavior, when elapsed effort is 2x your prediction, or when you're about to try the same approach "one more time but harder". Encodes the stop/strategy-switch/escalate ladder. Trigger proactively — by the third identical failure you are burning context and user trust.

Create + manage git worktrees in this harness — when to isolate vs when one is overhead, how to EnterWorktree/ExitWorktree (they live at .claude/worktrees/<name>), and the gotchas that bite here: results don't auto-merge to main; state/ is gitignored so `harness` writes in a worktree miss the main ledger; committed memory/ rides in; shared DB/ports aren't isolated; the guard protects the trunk, not a worktree's own copies. Use whenever a second session opens, independent tasks fan out, or file-mutating agents run beside other work — the user never asks for a worktree or recites a gotcha.

Use when designing or building a NEW project/system FOR the user — especially anything described as autonomous, self-governing, agentic, or self-improving. THIS harness's governance invariants (human-in-the-loop approval, a write-locked enforcement layer only a human PR may change, human-seeded work) are facts of the recursive-harness repo, NOT universal best practice. Importing them by reflex can negate a sub-project whose premise is autonomy. Before designing a sub-project's governance/safety, confirm whether a human gate is a real requirement or a cage you're copying.

Snapshot a just-completed task into the regression corpus (evals/corpus/). Use after any task where the user accepted the result AND future harness changes could plausibly regress it — recurring task shapes, tasks that needed corrections before acceptance, anything involving taste the user articulated. Also use when /meta-retro reports a category with misses but no eval coverage. Without corpus growth, "harness improvement" is unmeasurable drift.

The anti-auto-memory router. Use this EVERY time you notice something worth remembering — a repeated mistake, a user correction, a procedure that worked, a preference, a project quirk — and especially whenever you feel the urge to "just note this down" in CLAUDE.md or memory. Also use during /retro to classify each mined learning. Routing prose into the wrong artifact is the primary failure mode of this harness; when in doubt, trigger this skill.

Catalog + decision procedure for choosing a programming language. TRIGGER whenever you are about to pick, default, recommend, or assume a language for new work — a greenfield project/service/script/CLI/library, a component in a polyglot system, a rewrite or port, or when a user asks "what should I build this in". Also when weighing two stacks, or judging whether an existing language still fits a new requirement. Don't default to Python/JS from habit: consult the catalog (references/index.md) so the pick is matched to domain, hard constraints, stack, and ecosystem — with tradeoffs stated.

Use at the END of any task that generated deferred work — the "next steps", "you could also", "want me to…", unfixed-nit, or parked-for-later items. Instead of reciting them at the user (which overloads them — their stated correction), capture each via `harness followup add` and end with a single count line. Also use when the user says follow-ups overwhelm them, or asks to defer/park something. Surfacing the list is always a PULL (/followups), never a push.

Procedure for importing a THIRD-PARTY Claude Code skill (a SKILL.md pack from GitHub etc.) into this harness. Use when the user asks to "install/add/vendor a skill", points at an external skill repo, or wants a skill pack available across the fleet. Covers trunk-vs-account placement, slimming heavy media, provenance for re-vendoring, and the lint B3 allowlist when the skill exceeds the body cap. Skipping it leads to tens of MB of binaries in the trunk, a CI-breaking oversized SKILL.md, or a forked brain.