continuous-improvement
AGENTS.md9 starsChanged 8 months agoMITView on GitHub
Project-local rules for AI coding agents. Global rules live in ~/.Codex/AGENTS.md. This file only adds what is specific to this repo.
- Deletes or force-pushes
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository3 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- llms.txtllms.txt
- continuous-improvementSkill
The file
We split this AGENTS.md into the rules it gives an agent
9 rules. About 0 are common, 3 are distinctive, and 6 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.
6
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.
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.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
AGENTS.md — continuous-improvement
Project-local rules for AI coding agents. Global rules live in ~/.Codex/AGENTS.md. This file only adds what is specific to this repo.
Repository
- npm package
continuous-improvement(Codex plugin + GitHub Action transcript linter) - Marketplace at
.Codex-plugin/marketplace.jsonships 5 plugins: 1 native + 4 vendored companions (Obra superpowers, addy/agent-skills, ruflo-swarm, oh-my-Codex). 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.- AGENTS.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-Codex/,third-party/mattpocock-skills/) are pinned-SHA snapshots. - Each snapshot must carry
MANIFEST.md(SHA + version),OUR_NOTES.md(drift radar + integration scope),AGENTS.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
AGENTS.mdat repo root (this file). Do not createAGENTS.md(lowercase) — Windows treats them as the same file but Git treats them as distinct. - Plugin manifests at
.Codex-plugin/marketplace.jsonandplugins/continuous-improvement/.Codex-plugin/plugin.jsonare generated bybin/generate-plugin-manifests.mjs. Source ispackage.json+marketplace.jsonplus discovery walk.
Past Mistakes
Dated entries. Roll older than 60 days into docs/audits/archive-<quarter>.md.
| Date | Mistake | Lesson | Enforcement |
| 2026-05-06 | Observer field-name bug — pre-2026-05-06T00:38Z observations.jsonl rows have empty output_summary because the field was named tool_output instead of tool_response. | Live-patched on host, PR #67 merged as a477ec1. | Ignore historical event field on rows before that timestamp. |
| 2026-05-08 | Direct .mjs edit (PR #66) — bypassed the .mts source, was wiped by tsc, failed verify:generated. | .mts is source; .mjs is generated. | verify:generated invariant + this file's "Build pipeline" section. |
| 2026-05-08 | Auto-merge ordering hazard during release train — GitHub orders by CI completion time, not PR number; release PR landed before its dependency lockfile PR, left base stale. | Gate the release PR on dependency PRs completing first. | This file's "Git & Release Workflow" section. |
| 2026-05-09 | agent-skills/ stray full-clone at repo root duplicated third-party/addy-agent-skills/. | Vendored snapshots are the single source of truth; never re-clone upstream at repo root. | .gitignore rule + this file's "third-party vendoring contract" section. |
| 2026-05-17 | PR #151 first commit shipped a stale test/run-synthetic.test.mjs because the .mts source had its mkdirSync import removed during code-review cleanup but the previously-built .mjs was already staged. CI's verify:generated caught it; fix shipped as follow-up commit 3eedea3. | "Build once at the start" is a trap when the .mts is edited again post-build. Treat npm run build + git add as one atomic step — rerun the build before every stage of .mts changes, even tiny ones like dropping an unused import. | verify:generated invariant (Linux CI) + this file's "Build pipeline" section + memory feedback_mts_is_source.md rebuild-before-stage section. |
| 2026-05-17 | PR #151 plan doc claimed the runner pre-flights BASE_URL/BASELINE_URL and exits 2 if unset; the implementation instead chose a pure-aggregator design (checks self-report exit 2). The code-reviewer subagent flagged the divergence as HIGH. | When implementation diverges from the spec-subagent's plan mid-build, update the plan doc to match the shipped code — do not back-fit code to the stale plan. Surface the divergence explicitly in the PR description. | Stage 2 code-reviewer subagent under subagent-driven-development + memory feedback_plan_doc_matches_impl.md. |
| 2026-06-03 | Adversarial audit of the 3 new Law-7 features (goal-monitor, recall, skill-distillation) on the PR #154 branch found 14 verified defects (3 HIGH) that passed verify:all + the 715-test suite — all input-validation / fail-open boundary gaps: an empty ## Goal Keywords section forced false drift; the recall since filter leaked undated rows; a distill candidate id built from raw tool names flowed into a draft path (traversal). | Green gates do not prove boundary safety. New parser/scorer/index code needs explicit edge-case tests for empty/malformed/undated input and must fail closed on time and identity boundaries. | Regression tests in the goal-state/recall-index/skill-distill/mcp-server suites + audit doc docs/audits/2026-06-03-new-feature-audit.md + the Deferred list below. |
| 2026-07-10 | The v3.20.0 npm package and generated plugin omitted scripts/, so bundled skills cited helpers that consumers did not receive. The citation checker passed when the whole surface was absent. | Distribution contracts must inspect the packed artifact, compare generated copies, execute one consumer path, and reconcile inventory entries in both directions. | distribution-artifacts.test.mts + dual-tree verify:scripts-citation-drift. |
| 2026-07-10 | Gateguard classified every unquoted @{...} token as a Git selector and blocked valid PowerShell hashtables. | A syntax gate must validate the distinguishing grammar before denying a command. | Hashtable, quoted-brace, comment-only, and Git date-selector regressions in gateguard-hook.test.mts. |
| 2026-07-10 | Query-cost and typecheck Stop hooks inspected tracked diffs only, so new untracked migrations and TypeScript files bypassed both gates. | Changed-file gates must include git ls-files --others --exclude-standard. | Untracked-file cases in both hook suites. |
| 2026-07-10 | The Windows installer accepted any executable answering bash --version; WSL Bash then failed on the native C:/... hook paths written to settings. | Probe the exact capability the installed command needs before writing any target. | Installer path-read probe + incompatible-Bash integration test. |
| 2026-07-10 | Landing release markers stayed at v3.14.0 after package v3.20.0, and the mobile hero nowrap rule overflowed a 375 px viewport. | Tie landing markers to package.json in CI and verify the smallest supported viewport. | verify:landing-version + landing mobile regression + 375/768/1440 browser checks. |
| 2026-07-10 | Marketplace lifecycle hooks and npx hook registrations still invoked Bash; Windows resolved WSL Bash, which could not open the native paths. The remaining 5-second host budget also cancelled valid cold Node starts under load. | Use Node entrypoints when Node is already required, migrate installer-owned legacy rows, and size host timeouts from observed cold-start latency. | hook-runtime-portability.test.mts + no-Bash, legacy-migration, and minimum-timeout cases. |
| 2026-07-10 | Windows committed new generated CLIs and copied plugin helpers as 100644; the Linux build normalized them to 100755 and failed verify:generated after all tests passed. | New generated executables need their Git mode recorded explicitly from Windows. | git update-index --chmod=+x on new CLI and helper artifacts + Linux generated-diff CI gate. |
| 2026-07-10 | The v3.20.1 and v3.20.2 releases passed PR CI but stopped before publish because npm v12 returned npm pack --json as a package-name-keyed object on Linux while the artifact test required an array or direct result object. | Release tests must normalize every supported CLI output shape used by the trusted-publishing environment. | Array, direct-object, and keyed-object regression in distribution-artifacts.test.mts + release workflow test gate. |
| 2026-07-10 | The v3.20.3 release passed every build and test gate but npx npm@latest publish crashed before registry contact because npm 12's temporary npx install lacked sigstore. | Pin the proven npm 11.18.0 publisher, install it before publish, and call it directly instead of reinstalling through npx. | release-workflow.test.mts pins version, step order, and direct npm publish. |
Deferred
⚠️ Logged, not dropped. Action or close each explicitly.
2026-06-03 — new-feature audit (docs/audits/2026-06-03-new-feature-audit.md)
Four verified-but-unfixed findings remain from the PR #154 feature audit, left to the feature owner — each is a design choice, a latent gap with no live bug, or broader than a surgical fix. (NaN threshold #2 closed via 4ef2e83; overlapping n-gram #10 closed via c19e9f3; window:0 #3, ASCII-tokenizer #6, and limit:0 #13 closed 2026-06-03 via /proceed on branch fix/goal-monitor-boundary-edges — see annotations below.) Two new follow-ups added by the completeness sweep.
- goal-state window:0/negative → default 30 (MED): treats an explicit out-of-range window as "unset". Defensible as invalid→default; decide clamp vs reject. — CLOSED by
6207648:scoreObservationsnow throwsRangeErroron a non-positive-integer window (reject chosen over clamp);ci_goal_checkpre-validateslimit. - goal-state keyword substring match (LOW):
.includesmatchestestinsidelatest. Intentional fuzzy heuristic (4-char min + stopwords). - recall tokenize ASCII-only (MED):
/[^a-z0-9]+/drops CJK/Cyrillic/accents; same pattern in goal-state. Switch both to/[^\p{L}\p{N}]+/utogether. — CLOSED byd2001ac: both scorers now split on/[^\p{L}\p{N}]+/u; the goal-state pure-digit filter was hardened to/^\p{N}+$/uin0161b80. - skill-distill empty verify output = success (MED):
output === ""counts as a pass. NOT a clean fix — silent-success commands (tsc --noEmit) legitimately emit nothing; needs a data-model decision. - skill-distill NaN-ts gap split (MED): unparseable timestamps suppress the time-gap split, merging unrelated runs. Degrades draft mining only (drafts never auto-apply). — CLOSED by
b4f2eaf(PR #189):extractTrajectoriesnow treats a valid→invalid or invalid→valid timestamp pair as a trajectory boundary (fail-closed); consecutive invalid timestamps stay together. Regression tests insrc/test/skill-distill.test.mts. - skill-distill overlapping n-gram count (LOW):
occurrencescounts windows, not distinct runs;minSessionsis the real guard. Add a contract-pinning test. — CLOSED byc19e9f3: regression test pins thatoccurrencescounts every matching window;minSessionsstays the single-session guard. - mcp getRecentObservations limit:0 (LOW):
slice(-0)reads the whole history; output stays bounded downstream. Clamplimit<=0. Confirmed not unit-testable as-is:mcp-server.mtshas noimport.metamain guard, so importing it to test the internal fn would start the server — needs an entry-point refactor (guard + export) or handler seeding first. — CLOSED by08cdbae(clamp insidegetRecentObservations, covers all callers incl.ci_observations) +6207648(ci_goal_checkguard); integration-tested throughtools/callincc265e8(the entry-point-refactor blocker was sidestepped by driving the spawned server, not importing it). - manifest generator skill-discovery glob (MED):
/^[a-z][a-z0-9-]*\.md$/would silently drop a future skill with an uppercase/underscore/leading-digit name whileverify:allstays green. No live bug (3 new skills compliant). Align with the tier-lint filter. — CLOSED by2fde059: generator now uses the same loose filterfile.endsWith(".md") && file !== "README.md"as the tier-lint discovery. - goal-state KEYWORD_MIN_LENGTH=4 vs short-word scripts (MED): the unicode tokenizer (
d2001ac) now keeps Korean/Thai tokens, but the 4-char floor drops them anyway (Korean technical words are ~2 chars), so a Korean/Thai goal still extracts zero keywords and scores all work as drift. Lower the floor for those scripts or add a script-aware threshold. New follow-up from the 2026-06-03 completeness sweep. — CLOSEDc71a6b9:keywordMinLengthFor()returns 2 for tokens containing Hangul syllables (\p{Script=Hangul}), keeping the global 4-char floor for all other scripts. Regression test insrc/test/goal-state.test.mtspins 2-char and 3-char Hangul keywords. - recall Thai combining-mark fragmentation (LOW):
/[^\p{L}\p{N}]+/utreated Thai combining marks (Unicode\p{M}) as delimiters, fracturing Thai words into garbled length-2/3 fragments that recall then indexed. — CLOSED747451a: bothrecall-indexandgoal-statenow split on/[^\p{L}\p{N}\p{M}]+/u; regression tests insrc/test/recall-index.test.mtsandsrc/test/goal-state.test.mtspin Thai words with tone/vowel marks. Goal-state's 4-char floor now accepts length-4+ Thai keywords.
Flaky (not a regression): test/hook.test.mjs "completes within 2000ms" is an environmental wall-clock flake on a loaded Windows host (2.5–4.2s under heavy concurrent load; passes at 725/725 when the host is quiet). Do not inflate the budget to mask it.
Companion skills (enforce these rules at the tool boundary)
| Rule | Enforcing skill |
| Think Before Acting | gateguard — blocks Edit/Write/Bash before grounding |
| Verification Discipline | verification-loop — per-project ladder via templates/verify-ladder.example.json |
| 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) |
AGENTS.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.

