agentleFS
naimkatimannaimkatiman/continuous-improvement/CLAUDE.md

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

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
  1. Very specific:

    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 …

    line 14
  2. Distinctive:

    Use TDD for new features: failing test → code → verify.

    line 15
  3. Very specific:

    After any code change, run npm run verify:all (18 content invariants + typecheck: skill-mirror, skill-tiers, skill-law-tag, skill-count, …

    line 19
  4. Very specific:

    Run all commands from repo root.

    line 21
  5. Distinctive:

    Never claim "verified" or "done" without the passing output.

    line 22
  6. Very specific:

    After editing .mts: npm run build regenerates the .mjs.

    line 28
  7. Distinctive:

    Never push directly to main: Every change — including doc-only, lockfile-only, release commits — goes through a feature branch + PR.

    line 38
  8. Very specific:

    After merge, fast-forward main: git switch main && git pull --ff-only origin main.

    line 39
  9. Very specific:

    Never edit files inside third-party/<name>/ directly — those are verbatim upstream copies.

    line 48
  10. Very specific:

    Ask recall first — it searches the observation log across all sessions and finds matching past failures without anyone having curated them.

    line 57

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

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.json ships 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 with gh pr view X or git log before 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 typecheck is the floor.
  • Run all commands from repo root. Verify CWD with pwd if a previous step may have changed it.
  • Never claim "verified" or "done" without the passing output. Silence is not a pass.

Build pipeline (CRITICAL)

  • .mts files under src/ are the source. .mjs files in bin/, lib/, test/ are generated by tsc.
  • Direct edits to .mjs files are wiped on next npm run build and fail CI's git diff --exit-code -- bin test lib plugins invariant. PR #66 was rejected for exactly this; PRs #73/#74 shipped the fix.
  • After editing .mts: npm run build regenerates the .mjs. Commit both.

Environment Notes (Windows + Git Bash + PowerShell)

  • Shell is Git Bash on Windows. jq is not installed — use Node, PowerShell, or vendored helpers for JSON parsing.
  • autocrlf=true produces 40+ phantom modifications on git status after a clean checkout. Never stage with git add . or git add -A. Stage by explicit filename. Use git diff --stat (not git 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-lease and git reset --hard origin/X are 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 off origin/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.md at repo root (this file). Do not create claude.md (lowercase) — Windows treats them as the same file but Git treats them as distinct.
  • Plugin manifests at .claude-plugin/marketplace.json and plugins/continuous-improvement/.claude-plugin/plugin.json are generated by bin/generate-plugin-manifests.mjs. Source is package.json + marketplace.json plus 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)

RuleEnforcing skill
Think Before Actinggateguard — blocks Edit/Write/Bash before grounding; CI_GATEGUARD_TARGET_LOCK=block also refuses writes outside the project root
Verification Disciplineverification-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 pipelinebin/check-everything-mirror.mjs + verify:generated script
7 Laws routingproceed-with-the-recommendation — walks recommendation lists under all 7 Laws
Recommendation shapewild-risa-balance — 5+2 floor + R-I-S-A filter
Goal-Driven Executiongoal-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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.