continuous-improvement
CLAUDE.md9 starsChanged 8 months agoMITView on GitHub
Project-local rules for AI coding agents. Global rules live in ~/.claude/CLAUDE.md. This file only adds what is specific to this repo.
- Deletes or force-pushes
- Commits and pushes
In this repository3 other files it gives its agents.
- AGENTS.mdAGENTS.md
- llms.txtllms.txt
- continuous-improvementSkill
The file
We split this CLAUDE.md into the rules it gives an agent
10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 14
When the user references prior work (PR #X, last session's fix), verify it exists with gh pr view X or git log before acting on the …
- Distinctive: line 15
Use TDD for new features: failing test → code → verify.
- Very specific: line 19
After any code change, run npm run verify:all (18 content invariants + typecheck: skill-mirror, skill-tiers, skill-law-tag, skill-count, …
- Very specific: line 21
Run all commands from repo root.
- Distinctive: line 22
Never claim "verified" or "done" without the passing output.
- Very specific: line 28
After editing .mts: npm run build regenerates the .mjs.
- Distinctive: line 38
Never push directly to
main: Every change — including doc-only, lockfile-only, release commits — goes through a feature branch + PR. - Very specific: line 39
After merge, fast-forward main: git switch main && git pull --ff-only origin main.
- Very specific: line 48
Never edit files inside third-party/<name>/ directly — those are verbatim upstream copies.
- Very specific: line 57
Ask recall first — it searches the observation log across all sessions and finds matching past failures without anyone having curated them.
≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
CLAUDE.md — continuous-improvement
Project-local rules for AI coding agents. Global rules live in ~/.claude/CLAUDE.md. This file only adds what is specific to this repo.
Repository
- npm package
continuous-improvement(Claude Code plugin + GitHub Action transcript linter) - Marketplace at
.claude-plugin/marketplace.jsonships 5 plugins: 1 native + 4 vendored companions (Obra superpowers, addy/agent-skills, ruflo-swarm, oh-my-claudecode). pm-skills is out-of-band per docs/THIRD_PARTY.md. - Source layout:
skills/,commands/,hooks/,agents/,bin/,lib/,templates/,instinct-packs/,synthetic-checks/,third-party/,plugins/continuous-improvement/.
Think Before Acting
- For any non-trivial request, produce a short plan before editing files. Under the 7 Laws this is Law 2.
- When the user references prior work (
PR #X,last session's fix), verify it exists withgh pr view Xorgit logbefore acting on the assumption. - Use TDD for new features: failing test → code → verify. The native tdd-workflow skill enforces RED-GREEN-REFACTOR strictly — pre-test code is deleted.
Verification Discipline
- After any code change, run
npm run verify:all(18 content invariants + typecheck: skill-mirror, skill-tiers, skill-law-tag, skill-count, skill-count-prose, command-count, test-count, invariant-count, docs-substrings, everything-mirror, routing-targets, doc-runtime-claims, test-imports-only, landing-version, scripts-citation-drift, third-party-shape, tool-count, reconcile-parity, typecheck). Anything below that is incomplete. - For doc-only or template-only changes,
npm run typecheckis the floor. - Run all commands from repo root. Verify CWD with
pwdif a previous step may have changed it. - Never claim "verified" or "done" without the passing output. Silence is not a pass.
Build pipeline (CRITICAL)
.mtsfiles undersrc/are the source..mjsfiles inbin/,lib/,test/are generated bytsc.- Direct edits to
.mjsfiles are wiped on nextnpm run buildand fail CI'sgit diff --exit-code -- bin test lib pluginsinvariant. PR #66 was rejected for exactly this; PRs #73/#74 shipped the fix. - After editing
.mts:npm run buildregenerates the.mjs. Commit both.
Environment Notes (Windows + Git Bash + PowerShell)
- Shell is Git Bash on Windows.
jqis not installed — use Node, PowerShell, or vendored helpers for JSON parsing. autocrlf=trueproduces 40+ phantom modifications ongit statusafter a clean checkout. Never stage withgit add .orgit add -A. Stage by explicit filename. Usegit diff --stat(notgit status) to see real content drift.- CLAUDE.md is case-sensitive on the filesystem when checked into Git. Always uppercase.
Git & Release Workflow
- Never push directly to
main. Every change — including doc-only, lockfile-only, release commits — goes through a feature branch + PR. The PR flow is mandatory and the harness has historically caught direct-push attempts. - After merge, fast-forward
main:git switch main && git pull --ff-only origin main. Squash-merge is the default (gh pr merge <N> --squash --delete-branch). git push --force-with-leaseandgit reset --hard origin/Xare gated. If a rebase diverges, supersede via a new branch + new PR — do not force-recover.- Release trains are vulnerable to auto-merge ordering hazards: GitHub orders by CI-completion time, not PR number. A release PR can land before its dependency lockfile/refactor PR and leave a stale base. When chaining release PRs, gate the release on the lockfile PR completing first.
third-party vendoring contract
- The 5 vendored companions (
third-party/superpowers/,third-party/addy-agent-skills/,third-party/ruflo-swarm/,third-party/oh-my-claudecode/,third-party/mattpocock-skills/) are pinned-SHA snapshots. - Each snapshot must carry
MANIFEST.md(SHA + version),OUR_NOTES.md(drift radar + integration scope),CLAUDE.md(read-only guard). - To refresh a snapshot:
node bin/refresh-third-party.mjs <name>from a worktree offorigin/main. - Never edit files inside
third-party/<name>/directly — those are verbatim upstream copies. Cross-cutting integration code lives outside the snapshot.
Single source of truth
- Exactly one
CLAUDE.mdat repo root (this file). Do not createclaude.md(lowercase) — Windows treats them as the same file but Git treats them as distinct. - Plugin manifests at
.claude-plugin/marketplace.jsonandplugins/continuous-improvement/.claude-plugin/plugin.jsonare generated bybin/generate-plugin-manifests.mjs. Source ispackage.json+marketplace.jsonplus discovery walk.
Past Mistakes → docs/past-mistakes.md
Ask recall first — it searches the observation log across all sessions and finds matching past failures without anyone having curated them. The doc is the curated subset: each mistake paired with the invariant that now enforces it. Newest entry 2026-08-07 (safety-guard claimed enforcement it never shipped).
Deferred → docs/deferred.md
⚠️ Logged, not dropped. Open items: token-budget-advisor / strategic-compact / handoff / superpowers retirement decisions, and the skill-distill empty-verify-output data-model call.
Companion skills (enforce these rules at the tool boundary)
| Rule | Enforcing skill |
| Think Before Acting | gateguard — blocks Edit/Write/Bash before grounding; CI_GATEGUARD_TARGET_LOCK=block also refuses writes outside the project root |
| Verification Discipline | verification-loop — per-project ladder via templates/verify-ladder.example.json; hooks/typecheck-stop.mjs — opt-in Stop-boundary typecheck gate (off by default; CLAUDE_TYPECHECK_GATE=block re-prompts the model with tsc failures) |
| Build pipeline | bin/check-everything-mirror.mjs + verify:generated script |
| 7 Laws routing | proceed-with-the-recommendation — walks recommendation lists under all 7 Laws |
| Recommendation shape | wild-risa-balance — 5+2 floor + R-I-S-A filter |
| Goal-Driven Execution | goal-monitor + hooks/goal-drift-stop.mjs — Stop-boundary drift gate (warn by default; CLAUDE_GOAL_DRIFT_GATE=block enforces) |
CLAUDE.md text tells humans the rule. Skills make the agent obey it. Keep both layers.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

