# claude-booping > The system gets better from its own runs, but only through the user and when the user wants it: a lesson becomes a rule after the user takes it, not after every run. ## Rules — booping - [rule/0001 A lesson is a rule](booping/rule/0001-lessons-are-rules.md): What a run teaches is recorded as a rule with targets and a brief; only the brief reaches the targeted step, the body is read on demand. (accepted) - [rule/0004 Open questions are settled in grooming, not in develop](booping/rule/0004-questions-settled-in-grooming.md): Grooming hunts for open questions and settles them with the user before ready-for-dev; develop stops only for force majeure. (accepted) - [rule/0006 Every prompt artefact passes the information-architecture check](booping/rule/0006-information-architecture-pass.md): Before a prompt-bearing artefact is saved, every block passes four checks — scoping, duplication, configurability, hierarchy — and prose that only restates or motivates is cut. (accepted) - [rule/0007 References a plan invalidates are cleaned up in the same sprint](booping/rule/0007-stale-references-cleaned-in-sprint.md): When a plan deletes or renames something others reference, the cleanup is a milestone task of the same sprint with its own DoD, never a follow-up sweep. (accepted) - [rule/0008 Generated content is scoped to its audience](booping/rule/0008-audience-scoped-content.md): User-facing output — release notes, user docs, changelogs — includes only what that audience touches; the audience filter is specced into the task's DoD. (accepted) - [rule/0009 An agent briefing bounds what the agent returns](booping/rule/0009-bounded-agent-return-contract.md): Every agent briefing states the exact shape of the agent's reply, limited to what the orchestrator needs; groom bounds it in the task so develop's briefings inherit it. (accepted) - [rule/0010 The content of a user-facing output is locked in grooming](booping/rule/0010-output-content-locked-in-grooming.md): When a plan defines a user-facing output or log format, its exact content — fields, truncation, trailers — is settled with the user in grooming, not iterated in develop. (accepted) - [rule/0030 Planning shows the values in play and every departure from them](booping/rule/0030-planning-shows-values-in-play.md): A plan names the values that drive its choices and flags where it departs from a value or rule, so the user sees what works and can refine the values. (accepted) - [rule/0031 Corrections are logged as they happen](booping/rule/0031-corrections-are-logged.md): When the user corrects the driver, it logs the correction verbatim as a file under the vault's corrections/, so retro starts from a ready list of what is not yet handled. (accepted) - [rule/0032 Decisions are asked in prose](booping/rule/0032-approval-asked-in-prose.md): An approval, or any decision the user must understand the context to make, is asked in prose, one at a time with compact context and a counter; a multiple-choice tool only for mechanical picks. (accepted) - [rule/0033 Decisions are listed for acceptance](booping/rule/0033-decisions-listed-for-acceptance.md): Before the user accepts anything, the agent lists every decision it takes as settled, one numbered line each, marking its own proposals; an unanswered item is never accepted. (accepted) - [rule/0034 A specs review tests each record against its type](booping/rule/0034-specs-review-tests-each-record.md): A review of the specs puts every record to the type tests of the format guide and lists each failure — the type it fits or deletion — for the user to accept. (accepted) - [rule/0035 Items of one class are groomed together, never in parallel](booping/rule/0035-same-class-items-groomed-together.md): The manager grooms items of the same class in one plan, or one after another with the earlier plan in the next brief — never in parallel, where each builds its own copy of the mechanism. (accepted) - [rule/0036 An ADR is accepted after a brief](booping/rule/0036-adr-accepted-after-a-brief.md): An ADR is drafted proposed and accepted only after the owner was shown its brief and given a window to object; the answer sets the review level with its evidence. (accepted) - [rule/0037 Open items hold only what outlives the session](booping/rule/0037-open-items-outlive-the-session.md): An open item is filed only for work for later or a question that waits for the owner; session instructions, gate answers, policies and decisions are never items. (accepted) - [rule/0038 Ids in chat carry their title](booping/rule/0038-ids-carry-their-title.md): Every id said in chat — an open item, an ADR, a rule, a plan — is followed by its short title; newly filed items are listed one per line with their title. (accepted) - [rule/0039 Experiments run in stages](booping/rule/0039-experiments-run-in-stages.md): An experiment, eval or benchmark matrix runs a cheap screen, then a shortlist, then significance for finalists only, each stage sized before launch. (accepted) - [rule/0040 The ADR scorer judges its prompt alone](booping/rule/0040-adr-scorer-judges-its-prompt-alone.md): The adr-scorer runs only its body render and judges a draft ADR from the pasted parts alone; nothing it was not shown exists for it. (accepted) - [rule/0041 The manager delegates heavy reads](booping/rule/0041-manager-delegates-heavy-reads.md): The project manager never reviews an artefact, reads a long file or scans many files or logs itself; a subagent does it under a bounded return contract and the manager keeps only the verdict. (accepted) ## ADRs — claude-booping - [adr/0001 Specs are a core feature in three tiers](claude-booping/adr/0001-specs-tiers.md): Booping ships the specs format and its own specs; a global tier in the home dir and a project tier in the repo add their records, cross-tier refs go by namespace. (accepted) - [adr/0002 Procedures are playbooks behind one skill](claude-booping/adr/0002-procedures-are-playbooks.md): Every booping procedure ships as a playbook driven by the single /playbook skill; a new skill is written only for a surface /playbook cannot drive. (accepted) - [adr/0003 Bodies render at skill load, with no build stage](claude-booping/adr/0003-render-at-skill-load.md): Skill and agent bodies are rendered from templates at load time with full project context; the generated-file build stage is retired. (accepted) - [adr/0004 Config is a three-tier deep merge with no schema gate](claude-booping/adr/0004-config-three-tier-merge.md): Config merges core, global and project tiers, later winning and lists replacing; any key loads in any tier, and playbook keys live in the core file under core.{name}_playbook. (accepted) - [adr/0006 Each playbook owns its state machine; no shared lifecycle](claude-booping/adr/0006-each-playbook-owns-its-states.md): Every artifact moves only through its own playbook's states machine, written solely by playbook-transition; playbooks hand off at a status, not through a shared lifecycle. (accepted) - [adr/0007 Run-state persistence is an authored tier, and confirmation is a status](claude-booping/adr/0007-run-state-persistence-is-authored.md): A playbook's state machine is authored at one of three tiers — ephemeral, minimal, rich — never derived from the graph; a confirmation that must persist is a status transition, not a flag. (accepted) - [adr/0008 Retro and code review are separate tracks joined by plan frontmatter](claude-booping/adr/0008-tracks-join-by-frontmatter.md): A plan ends at develop's done and never moves again; retro and code review keep their own artifacts and machines and join the plan through retro and code_reviews keys. (accepted) - [adr/0009 A plan is a directory whose index.md is both plan and run artifact](claude-booping/adr/0009-plan-is-a-directory.md): A plan lives in plans/{slug}/; index.md is the plan document and the machine's artifact at once, and run sidecars sit beside it — no separate plan.md and no _runs/ workdir. (accepted) - [adr/0010 A milestone is a file handed to the worker by path](claude-booping/adr/0010-milestones-are-files.md): Each milestone is its own file in its own directory with status and feedback beside it; develop hands a worker that file's path, never a slice of the plan body. (accepted) - [adr/0011 A step is inline, assisted or detached, set by one detached field](claude-booping/adr/0011-delegation-levels.md): The runner performs most steps itself; heavy reads go to a configured researcher that is resumed, not respawned; only a step that must not enter the runner's context is detached. (accepted) - [adr/0014 External agents and surfaces wire in through config; core names no external tool](claude-booping/adr/0014-external-tools-wire-in-through-config.md): An external worker or review surface is a plain agent registered in config and steered by a targeted rule; core ships no wrapper for it and no playbook names it. (accepted) - [adr/0015 A playbook run stops for review at one gate](claude-booping/adr/0015-one-review-gate-per-run.md): Core playbooks take user decisions in-step and stop for approval once — groom at present, retro at synthesize, migrate before applying, develop only to confirm the branch. (accepted) - [adr/0016 Groom's cross-review is a detached step gated by one config key](claude-booping/adr/0016-cross-review-is-a-config-gated-step.md): A second model reviews the drafted plan once, in its own detached step, only when core.groom_playbook.cross_review_agent names an agent; null skips the step. (superseded) - [adr/0017 Vault migrations ship with the plugin, keyed by a frontmatter id](claude-booping/adr/0017-migrations-ship-with-the-plugin.md): Migrations live in the plugin's migrations/ directory; the id in migration.md frontmatter is the only authority, and the .booping marker's latest_migration is the applied watermark. (accepted) - [adr/0018 Migrations apply strictly in sequence, one commit each, after one gate](claude-booping/adr/0018-migrations-apply-in-sequence.md): Migrate asks once over the whole pending set, then applies each migration in id order through a fresh sub-agent, advancing the watermark and committing before the next; a failure stops the run. (accepted) - [adr/0019 The task tracker is a best-effort mirror of the vault](claude-booping/adr/0019-tracker-is-a-best-effort-mirror.md): The vault stays authoritative; tracker hooks run in a separate CLI, absorb the tracker's failures with a warning, and booping-tracker sync reconciles by hand. (accepted) - [adr/0020 CLI behaviour is tested by a contract corpus, not by internal unit tests](claude-booping/adr/0020-contract-corpus-over-unit-tests.md): Each CLI subcommand is specified by language-neutral cases run through bin/booping; unit tests cover only algorithmic hotspots, and prose is owned by snapshots and mdcheck. (accepted) - [adr/0021 Prompt behaviour is checked by per-step eval suites, advisory and outside CI](claude-booping/adr/0021-per-step-prompt-evals.md): Each playbook step can carry a promptfoo suite with a deterministic smoke tier and a judged regress tier; runs are proposed, not launched by steps, and post an advisory PR comment. (accepted) - [adr/0022 Develop groups milestones per worker by story points, not by count](claude-booping/adr/0022-group-milestones-by-sp.md): Develop packs milestones per worker greedily within one wave under a max_sp cap of 15 instead of max_milestones_per_agent, and sp ≥ 5 is a hard groom gate. (accepted) - [adr/0024 The specs playbook is a guide, not a menu of actions](claude-booping/adr/0024-specs-playbook-is-a-guide.md): One specs playbook explains every record type and principle plus the user's typical scenarios, and the model works out from the dialogue what to do. (accepted) - [adr/0025 Open items are a stored index; closed ones are filtered out](claude-booping/adr/0025-open-items-are-an-index.md): Every gap between specs and code, open question or conflict is an open item stored in the vault and listed by an explicit command; closed items stay and are filtered. (accepted) - [adr/0026 Corrections are logged where they happen](claude-booping/adr/0026-corrections-log.md): Each time the user corrects the model in groom, develop or code-review, a short entry with a link back to the dialogue goes into the run's corrections sidecar — the feed retro and learn read. (accepted) - [adr/0029 Each project publishes its specs site on GitLab Pages, under one index](claude-booping/adr/0029-specs-sites-on-gitlab-pages.md): A project whose vault is in its repo builds its specs site in CI to Pages; an index at the group's Pages root lists them, rebuilt on a schedule from the projects that carry a topic. (accepted) - [adr/0030 Groom drafts the whole plan in one staged pass](claude-booping/adr/0030-groom-drafts-the-whole-plan-in-one-pass.md): Groom is the plan template plus research then draft (V3a), no self-review step, without the 16 rules the model follows unprompted; the draft is one file. (accepted) - [adr/0031 A script cuts the drafted plan into milestone files](claude-booping/adr/0031-a-script-cuts-the-plan-into-milestone-files.md): The script `booping plan split` cuts the one-file plan on its milestone headings, byte for byte, into index.md and the milestone files; a model splits only what the script flags. (accepted) - [adr/0032 The owner reviews specs on the site and hands the review to an agent](claude-booping/adr/0032-specs-review-on-the-site-goes-to-the-agent.md): A review panel beside each record collects comments and a reviewed mark in the browser; an Outbox page shows and copies everything for the agent, which edits the records. (accepted) - [adr/0033 Playbooks consult the specs through a subagent](claude-booping/adr/0033-playbooks-consult-the-specs-through-a-subagent.md): A read-only subagent tells playbooks what the specs already decide, contradict or leave open. (superseded) - [adr/0034 Every playbook carries a base guidance on the specs](claude-booping/adr/0034-every-playbook-carries-a-base-guidance-on-the-specs.md): Every playbook knows what the specs are, the values, and that it reads and writes them through a subagent, applying them where they raise quality; no per-playbook scenarios. (accepted) - [adr/0035 Groom has no separate review step](claude-booping/adr/0035-groom-has-no-separate-review-step.md): A fresh Opus review lifts plan quality but adds about 10 minutes a plan (4–5 at best); the one-pass draft already meets the goal, so groom has no review step. (accepted) - [adr/0036 Autonomy is settled in prose](claude-booping/adr/0036-autonomy-is-settled-in-prose.md): A run is autonomous because the user or its launch prompt says so, not because a config key does; there is no core.autonomy. (accepted) - [adr/0037 Journal entries are vault files built from existing primitives](claude-booping/adr/0037-journal-entries-are-vault-files.md): A correction or an agent decision is one vault file with frontmatter, made by create, moved by frontmatter-update and sliced by query; an item's question is its clarify status; no journal command. (accepted) - [adr/0038 Milestone shape is an mdcheck schema](claude-booping/adr/0038-milestone-shape-is-an-mdcheck-schema.md): Groom checks each milestone file with mdcheck against a schema in the groom playbook; `booping plan check` and its code go, and mdcheck becomes a required dependency. (accepted) - [adr/0039 A session in a booping project starts pointed at the playbooks](claude-booping/adr/0039-session-start-points-to-playbooks.md): In a project with a .booping marker a SessionStart hook injects when to use playbooks and the rendered playbook table; the agent offers the fitting one, the manager by default. (superseded) - [adr/0040 Records carry a review level with evidence](claude-booping/adr/0040-review-levels-with-evidence.md): A spec record's review is its own axis beside status — none, shown, discussed, accepted — and accepted carries the owner's words and where they were said; it replaces the reviewed date. (accepted) - [adr/0041 The ADR scorer reads the specs guide and the tier's record inventory](claude-booping/adr/0041-adr-scorer-reads-the-guide-and-the-record-inventory.md): The adr-scorer gets the specs guide excerpt, the tier's value/rule/ADR inventory and the project's primitives, on Opus without tools, and answers route, overlaps, alt_score and missing. (accepted) - [adr/0042 Every request in a booping session enters through the project-manager](claude-booping/adr/0042-project-work-enters-through-the-project-manager.md): Every request in a booping project session, questions and debugging included, goes to the project-manager, which routes it and launches and orchestrates the other playbooks. (accepted) ## Conflicts — claude-booping - [conflict/0001 Plans run to the end ↔ Adjustable control](claude-booping/conflict/0001-plans-run-to-the-end-vs-adjustable-control.md): An agent that carries a plan to the end on its own pulls against a human who can review deeply and take control back; the run's autonomy mode settles which applies. (resolved) - [conflict/0002 Effective human review ↔ Plans run to the end ↔ Quality at a rational cost](claude-booping/conflict/0002-effective-review-vs-time-and-cost.md): More review checkpoints make review effective but cost run time and stops; core playbooks stop for review once, and groom runs no separate review step. (resolved) ## Ideas — claude-booping - [idea/0001 Groom offers past plans and retros as context before planning](claude-booping/idea/0001-groom-reads-past-plans-and-retros.md): Before planning, groom has a cheap researcher list past plans and retros related to the request, and reads the ones the user picks in depth. (open) - [idea/0002 Learn prefers guidance to validators](claude-booping/idea/0002-learn-prefers-guidance-over-validators.md): Learn should propose guidance that steers a step away from an issue, and propose a validator or sub-agent check only for critical cases. (open) - [idea/0003 A faster groom without losing quality](claude-booping/idea/0003-groom-depth-scales-with-task.md): Try several groom playbook variants and keep the one that runs faster with no loss in plan quality. (accepted) - [idea/0004 Trim template fields that do not help](claude-booping/idea/0004-trim-unhelpful-template-fields.md): Drop the business-goal logic from grooming and replace the retro action table's Owner column with "when to do it". (open) - [idea/0005 Booping as a web service with thin skills](claude-booping/idea/0005-web-booping-service.md): A web service owns playbook management, artefacts and execution; skills become thin clients, a tracker such as Linear is a driver, and a sandbox runs the workers. (open) - [idea/0006 Merged OSS PRs as benchmark tasks](claude-booping/idea/0006-merged-oss-prs-as-benchmark-tasks.md): Re-create small merged PRs from OSS repos as booping plans and score groom and develop by the repo's own tests. (open) - [idea/0007 Claude wires a worker agent into booping on request](claude-booping/idea/0007-guided-agent-wiring.md): The user asks Claude Code to add a native agent or a CLI-backed agent to a playbook, and Claude writes the agent, the config entry and the targeted rule. (open) - [idea/0008 Plans draft ADRs for their real forks](claude-booping/idea/0008-plans-draft-adrs.md): Where a plan meets a real design fork, groom writes an ADR draft with the alternatives and its choice, and offers it to the owner for review unless the run is autonomous. (open) - [idea/0009 Groom depth scales with the task](claude-booping/idea/0009-groom-light-path-for-small-requests.md): A small, already-decided request takes a light path to develop instead of a full groom, and groom runs its deeper work only when the task or the user asks for it. (open) ## References — claude-booping - [reference/0001 Audience](claude-booping/reference/0001-audience.md): Booping is read by three roles — users, advanced users and contributors — each coming for different things at a different depth, in a different voice. (live) - [reference/0002 Glossary](claude-booping/reference/0002-glossary.md): The canonical names for booping's concepts — one term per concept, never a synonym, used across records, docs and step bodies. (live) - [reference/0003 Documentation surfaces](claude-booping/reference/0003-documentation-surfaces.md): Booping's markdown documentation surfaces, each with its audience and the depth ceiling past which content belongs elsewhere; executed or generated markdown is not a surface. (live) - [reference/0004 Develop model comparison, April 2026](claude-booping/reference/0004-develop-model-comparison-2026-04.md): One develop diff each from Claude Opus 4.7, Minimax 2.7 and GLM 5.1 scored 9.7, 7.2 and 6.4 of 10; only Opus produced a correct, plan-compliant diff. (live) - [reference/0005 Bench finding — develop follows the plan's code sketch over a lesson](claude-booping/reference/0005-bench-develop-follows-plan-sketch-over-lesson.md): In claude-booping-bench, /develop copied the casing of the plan's code sketch instead of a loaded naming lesson in 3 of 3 reps (judgment 0.2). (live) - [reference/0006 Groom cost — playbook versus the old skill](claude-booping/reference/0006-groom-playbook-vs-skill-cost.md): On one measured request the playbook groom took 2.4× the wall time, 5.2× the main-thread API calls and 3.0× the output tokens of the old /groom skill. (live) - [reference/0007 Groom benchmark 2026-10 — variants, rule ablation, plan split](claude-booping/reference/0007-groom-benchmark-2026-10.md): What the October 2026 groom benchmark measured, what the model does without being told, what it cost and where the data lives. (live) - [reference/0008 Postmortem: the budget gate slipped into the core unasked](claude-booping/reference/0008-postmortem-budget-gate-slipped-into-core.md): On 2026-10-15 a usage-limit gate the owner never asked for reached the core through a one-line mention, a package approval and autonomous runs; removed on 2026-10-17. (live; postmortem) - [reference/0009 Prose or code probes 2026-10](claude-booping/reference/0009-prose-or-code-probes-2026-10.md): Three cheap probes on 2026-10-18 — which rule wording makes a fresh model pick prose, an existing primitive or a new CLI correctly, and how sibling items should be groomed. (live; probe) - [reference/0010 Postmortem: mechanisms built without a reader](claude-booping/reference/0010-postmortem-mechanisms-without-a-reader.md): Between 2026-10-15 and 2026-10-18 booping grew a config key and three journal CLIs that nothing needed; removed on 2026-10-18, with the rule wording and the ADR guide that let them in. (live; postmortem) - [reference/0011 Postmortem: CLI commands removed under live runs](claude-booping/reference/0011-postmortem-cli-removed-under-live-runs.md): On 2026-10-17/18 booping removed the budget, correction and defaults commands while autonomous runs in another project still called them, and those runs failed. (live; postmortem) ## Rules — claude-booping - [rule/0002 What is not in the source is marked, not invented](claude-booping/rule/0002-unknown-is-marked.md): A record or artefact states only what its source says; an open point is marked [clarify] or "not named in the source", never filled in by the agent. (accepted) - [rule/0003 The compact artefact is reviewed before the detail](claude-booping/rule/0003-compact-artefact-first.md): Where a human reviews, a run first produces a compact artefact the human can read and reorder, and builds the expensive detail only on the reviewed one. (accepted) - [rule/0005 Every step ends by naming the next one](claude-booping/rule/0005-next-step-is-named.md): A playbook step or a run that hands back to the user ends by naming the next step and how to call it; a premature call says what is missing. (accepted) - [rule/0012 Every diff is reviewed in Plannotator, never in chat](claude-booping/rule/0012-every-diff-reviewed-in-plannotator.md): In this project the code-review human step always runs through the plannotator-reviewer agent; a missing agent or a dead surface stops the run, never falls back to chat. (retired) - [rule/0013 Snapshot baselines are accepted by the user, never by a run](claude-booping/rule/0013-snapshot-baselines-accepted-by-user.md): A run never runs just snapshots-accept or writes the committed playbook reports; it leaves the drift uncommitted and names it in its final report for the user to accept. (accepted) - [rule/0015 Code review covers code files only](claude-booping/rule/0015-review-covers-code-only.md): A code review surfaces findings on code files only; documentation, plans and other prose in the diff pass unreviewed. (accepted) - [rule/0017 Structured data is rendered from config, never restated in prose](claude-booping/rule/0017-structured-data-rendered-not-restated.md): Statuses, queues, agent ids, globs and other structured values live in config or query specs and are rendered into bodies; prose never copies a literal. (accepted) - [rule/0018 Project specifics stay out of the core](claude-booping/rule/0018-project-specifics-stay-out-of-core.md): Core skills and playbooks stay stack-agnostic; whatever is specific to a project is written into that project's tier, never into the core or a user-level scope by a run. (accepted) - [rule/0019 The driver owns the vault and git; workers touch only repo code](claude-booping/rule/0019-driver-owns-vault-workers-own-code.md): The driver owns the vault, run state and commits; workers edit only repo code, never git history; a small fix goes to the session already holding its context. (accepted) - [rule/0020 Project shaping of an agent or skill is a targeted record](claude-booping/rule/0020-agent-shaping-is-targeted.md): A project adjusts a core agent or skill through a targeted rule (agent:, skill:), never through a separate extension file. (accepted) - [rule/0022 Commits are conventional with a scope](claude-booping/rule/0022-conventional-commits-with-scope.md): Commit messages follow Conventional Commits with a scope, such as feat(booping) or fix(groom). (accepted) - [rule/0023 The README Statuses section follows the states blocks](claude-booping/rule/0023-readme-statuses-follow-states.md): The README's Statuses section is a hand-kept narrative over each playbook's states block; a change to a states block revisits it in the same change. (accepted) - [rule/0024 A new procedure is a playbook, not a skill](claude-booping/rule/0024-new-procedures-are-playbooks.md): Anything procedural is added as a playbook driven by /playbook; a new skill is added only for a surface /playbook cannot drive. (accepted) - [rule/0025 Who reads the result decides prose or code](claude-booping/rule/0025-who-reads-the-result-decides.md): A command, key or check exists when code reads its result or it supplies a fact the model cannot see; the rest is prose, the default when unsure. (accepted) - [rule/0026 Step bodies are fetched on demand, not pasted into spawn prompts](claude-booping/rule/0026-step-bodies-fetched-on-demand.md): A step's body is fetched when the step runs rather than pasted into a spawn prompt, so a run's context grows with its graph, not with the sum of its step bodies. (accepted) - [rule/0027 A hermetic render repeats byte for byte](claude-booping/rule/0027-renders-reproducible.md): With macros stubbed and the config merge pinned to core and project levels, a render is identical on any machine. (accepted) - [rule/0028 Vault artefacts are plain markdown with YAML frontmatter](claude-booping/rule/0028-vault-artefacts-plain-markdown.md): Every artefact a run writes into the project vault is plain markdown with YAML frontmatter, readable in Obsidian. (accepted) - [rule/0029 Graph and render problems are reported in band, never as crashes](claude-booping/rule/0029-failures-reported-in-band.md): A graph or render problem surfaces as a STOP or Note notice in the rendered output at exit 0, never as a crash. (accepted) - [rule/0030 A prompt rule earns its place by a measured miss](claude-booping/rule/0030-prompt-rules-earn-their-place.md): An instruction enters a prompt or a targeted rule only after a minimal probe shows the model missing it; evals and benchmarks run only when the owner agrees. (accepted) - [rule/0031 Judgement runs on Opus; cheaper models only for routine with a known output](claude-booping/rule/0031-judgement-runs-on-opus.md): Every step, agent or fallback that decides — drafts, reviews, verifies a DoD, writes tests — runs on Opus; the researcher on Sonnet high; else only mechanical steps. (accepted) - [rule/0032 The booping CLI holds only generic primitives](claude-booping/rule/0032-cli-holds-only-generic-primitives.md): A booping CLI command is a primitive any playbook can use; behaviour of one playbook's domain is that playbook's script, run through its hooks. (accepted) - [rule/0033 Private sources stay in vault/notes](claude-booping/rule/0033-private-sources-stay-in-vault-notes.md): This repo is public; another project's data, local paths and raw experiment inputs are written only under the gitignored vault/notes/, and tracked records name them without linking. (accepted) ## Runbooks — claude-booping - [runbook/0001 Cut a plugin release](claude-booping/runbook/0001-cut-a-release.md): A release is a release/X.Y.Z branch bumping plugin.json and CHANGELOG.md, merged by PR into master, then tagged vX.Y.Z with a GitHub release on the merge commit. (live) - [runbook/0002 Run the eval suites and read the PR comment](claude-booping/runbook/0002-run-eval-suites.md): Evals run locally on subscription auth via just smoke/regress/eval; results land as one sticky advisory PR comment, never a gate. (live) - [runbook/0003 Accept new snapshot and contract baselines](claude-booping/runbook/0003-accept-new-baselines.md): After an intentional change, the user reads the snapshot or txtar drift and accepts it; a run or a worker never accepts a baseline itself. (live) ## Stories — claude-booping - [story/0001 Playbook driver](claude-booping/story/0001-playbook-driver.md): The /playbook skill discovers a procedure across the core, global and project levels and drives it to completion. (done) - [story/0002 Run state machines](claude-booping/story/0002-run-state-machines.md): A run's state lives in per-playbook states: machines that only the booping CLI advances. (done) - [story/0003 Layered configuration](claude-booping/story/0003-layered-configuration.md): Config is a deep merge over the core, global and project levels, and any mapping in it can be a query spec or a template tree. (done) - [story/0004 Targeted rules](claude-booping/story/0004-targeted-rules.md): An accepted rule's brief is injected into exactly the playbooks, steps, agents or skills its targets: list names. (done) - [story/0005 Plan and review templates](claude-booping/story/0005-plan-and-review-templates.md): Groom and code-review offer plan and review templates the user authored in the Project Vault or at the global level. (done) - [story/0006 User playbooks](claude-booping/story/0006-user-playbooks.md): Playbooks the user authors at the global level or in the Project Vault are discovered and run beside the core ones. (done) - [story/0007 External agents](claude-booping/story/0007-external-agents.md): Agents the plugin does not ship are wired into playbook agent slots through config and shaped per project by targeted rules. (done) - [story/0008 Template pipeline](claude-booping/story/0008-template-pipeline.md): Skill and agent bodies render in one runtime stage from src/templates/ with full project context, reproducibly when pinned. (done) - [story/0009 Quality gates](claude-booping/story/0009-quality-gates.md): just ci runs lint, typecheck, pytest, snapshots, mdcheck and e2e in order, holding the plugin's behaviour. (done) - [story/0010 pytest-txtar](claude-booping/story/0010-pytest-txtar.md): The e2e corpus's case format and sandboxed runner ship as a standalone pytest plugin on PyPI. (done) - [story/0011 Eval suites](claude-booping/story/0011-eval-suites.md): Promptfoo suites beside each step guard its contract in a deterministic and an llm-rubric tier. (done) - [story/0012 Migration shipping](claude-booping/story/0012-migration-shipping.md): The plugin ships Project Vault migrations, and every render surface is gated on a vault's applied watermark. (done) - [story/0013 Documentation site](claude-booping/story/0013-documentation-site.md): The public MkDocs reference builds strictly and publishes to gh-pages on push to master. (done) - [story/0014 Project setup](claude-booping/story/0014-project-setup.md): The setup playbook takes a repo from any state to a working booping project and re-runs without changing what is already set up. (done) - [story/0015 Project Vault migrations](claude-booping/story/0015-vault-migrations.md): The migrate playbook brings an existing Project Vault current with the plugin on one up-front approval, with one commit per migration. (done) - [story/0016 Groom](claude-booping/story/0016-groom.md): Groom shapes a feature, bug or refactor into a specified, estimated plan the user approved, ending at ready-for-dev. (done) - [story/0017 Develop](claude-booping/story/0017-develop.md): Develop executes a groomed plan one milestone group at a time through a worker agent and closes it at done or fail. (done) - [story/0018 Retro](claude-booping/story/0018-retro.md): Retro mines a finished sprint's session logs, diff and the user's feedback into a standalone retrospective. (done) - [story/0019 Learn](claude-booping/story/0019-learn.md): Learn turns retrospective findings the user confirmed into rule records in the project specs tier or CLAUDE.md entries. (done) - [story/0020 Session metrics](claude-booping/story/0020-session-metrics.md): A plan carries measured active minutes, tokens and models computed from Claude Code session logs. (done) - [story/0021 Code review](claude-booping/story/0021-code-review.md): The code-review playbook reviews a confirmed scope, collects the human verdict and applies only approved fixes. (done) - [story/0022 Task tracker](claude-booping/story/0022-task-tracker.md): The booping-tracker CLI carries every interaction with an issue tracker, and groom mirrors its run status and questions onto the tracker issue. (done) - [story/0023 Project manager](claude-booping/story/0023-project-manager.md): One manager the user talks to files every request as an item and carries it through groom, develop, review and merge, with a status computed from the vault. (done) - [story/0024 Specs review with the owner](claude-booping/story/0024-specs-review-with-the-owner.md): The system reviews the owner's specs, fixes what is plainly stale, and brings the owner only the decisions that are theirs, one at a time and kept across restarts. (done) - [story/0025 Own integration on top of booping](claude-booping/story/0025-own-integration-on-top.md): An advanced user wires their own triggers, schedules, tracker flows and usage guards on top of booping's surfaces; the core ships none of them. (done) - [story/0026 Specs first, then code](claude-booping/story/0026-specs-first-then-code.md): A decision made in the specs becomes tracked work the code follows, closed with its plan; code that ran ahead of the specs becomes work for the specs. (done) ## Values — claude-booping - [value/0001 Curated self-learning](claude-booping/value/0001-curated-self-learning.md): The system gets better from its own runs, but only through the user and when the user wants it: a lesson becomes a rule after the user takes it, not after every run. - [value/0002 Minimal effective context](claude-booping/value/0002-minimal-effective-context.md): A step gets only what it needs. - [value/0003 Single source](claude-booping/value/0003-single-source.md): Each fact, decision and piece of structured data lives in one place and is referenced or rendered from there; a decision is kept together with its reason. - [value/0004 Analysable history](claude-booping/value/0004-analysable-history.md): Plans, runs and their outcomes are kept across every project, so the history can be analysed: practices taken over from one project to another, benchmarks, quality comparison, problem analysis. - [value/0005 Stack-agnostic core](claude-booping/value/0005-stack-agnostic-core.md): The core knows nothing about a stack or a project; specifics live in the global and the project tiers. - [value/0006 A framework for playbooks](claude-booping/value/0006-a-constructor-not-a-fixed-solution.md): Booping is a framework a user digitises their own processes with — config, templates, primitives, the CLI, playbooks and evals for their steps. - [value/0007 Plans run to the end](claude-booping/value/0007-plans-run-to-the-end.md): The agent carries a plan through to the end on its own unless force majeure stops it. - [value/0008 Effective human review](claude-booping/value/0008-effective-human-review.md): Every step where a human takes part is convenient and effective for that human. - [value/0009 Adjustable control](claude-booping/value/0009-adjustable-control.md): The human can review the system deeply, or give the agent more freedom to act inside the values and boundaries. - [value/0010 Proven to work](claude-booping/value/0010-proven-to-work.md): We know the system works as it should and can guarantee it high enough to call it reliable. - [value/0011 Everything in one place](claude-booping/value/0011-everything-in-one-place.md): Everything is plain files, easy to look at from one place — for example Obsidian; symlinks back to the project repos keep it together. - [value/0012 Quality at a rational cost](claude-booping/value/0012-quality-at-a-rational-cost.md): Booping is a work tool for professionals, so the quality of the result matters. - [value/0013 Guides to the goal](claude-booping/value/0013-guides-to-the-goal.md): The system is clear to the user and leads them to the goal by the hand, while letting a professional step aside and get there their own way. - [value/0014 Comfort for non-technical users](claude-booping/value/0014-comfort-for-non-technical-users.md): How comfortable booping is for people without a strong technical background is not optimised for; they are not its audience. - [value/0015 Deterministic where code reads it](claude-booping/value/0015-deterministic-where-code-reads-it.md): What code reads, and every fact outside the model's view, is produced by code; what only a model or a human reads stays prose with a fixed format until code starts to read it. - [value/0016 Specs live with the work](claude-booping/value/0016-specs-live-with-the-work.md): Specs are updated as the work happens and applied wherever they raise the quality of a result; they never go stale or depend on the user remembering them. - [value/0017 Launching and guarding runs is userland](claude-booping/value/0017-launching-and-guarding-runs-is-userland.md): When and how development runs start — triggers, schedules, tracker and messenger integrations — and guarding usage limits are the user's, not booping's; booping offers an integration surface at most. - [value/0018 A core set for development and self-learning](claude-booping/value/0018-a-core-set-for-development-and-self-learning.md): On top of the framework booping ships core playbooks for development, self-learning among them; they are its dogfooding, built only from mechanics a user playbook gets too. - [value/0019 Projects are built along a roadmap](claude-booping/value/0019-projects-are-built-along-a-roadmap.md): Work decomposes into plans and sprints, so a project is written along its roadmap, sprint by sprint, with a manager carrying the work through.