kaizen
AGENTS.md6 starsChanged 45 days agoMITView on GitHub
Read .kaizen/notes/Project/Index.md before planning or building, then open the notes it lists for the area you touch. When you change a file listed in a note's sources, update that note, or run /kaizen docs. @.kaizen/notes/Project/Index.md <!-- /kaizen:docs --> When a request is what one of the kaizen skills does, invoke that skill first instead of doing the work inline: kaizen-concept for concepts, mockups or design options before a build; kaizen-explore to question an idea before planning; kaizen-deck, kaizen-video, kaizen-book and…
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 32,671 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 repository12 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- kaizen-conceptSkill
- kaizen-exploreSkill
- kaizen-helpSkill
- kaizenSkill
- kaizen-bookSkill
- kaizen-deckSkill
- kaizen-gameSkill
- kaizen-videoSkill
- disk-cleanupSkill
- kaizen-computerSkill
- lemo-opuscarSkill
The file
We split this AGENTS.md into the rules it gives an agent
4 rules. About 0 are common, 0 are distinctive, and 4 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
4
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 4
Read .kaizen/notes/Project/Index.md before planning or building, then open the notes it lists for the area you touch.
- Very specific: line 13
When a request is what one of the kaizen skills does, invoke that skill first instead of doing the work inline: kaizen-concept for …
- Very specific: line 41
Every doc, one line each — docs/README.md
- Very specific: line 44
Every setting, commented — skills/kaizen/config.default.yml
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 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
<!-- kaizen:docs -->Project docs
Read .kaizen/notes/Project/Index.md before planning or building, then open the notes
it lists for the area you touch. When you change a file listed in a note's sources,
update that note, or run /kaizen docs.
@.kaizen/notes/Project/Index.md
<!-- /kaizen:docs -->Kaizen skills first
When a request is what one of the kaizen skills does, invoke that skill first instead
of doing the work inline: kaizen-concept for concepts, mockups or design options
before a build; kaizen-explore to question an idea before planning; kaizen-deck,
kaizen-video, kaizen-book and kaizen-game for a pitch deck, a video, a book or
a game. The skill holds the steps and the quality bar the work needs.
Project structure
kaizen is TypeScript on Bun with zero runtime dependencies. The CLI has no build step —
cli/*.ts runs as-is. The web front end ships prebuilt in web/dist/ (board.js, notebook.js, popup.js, term.js, video.js, annotate.js, and the stylesheets ui.css, board.css,
notebook.css, popup.css) and the bot's bot/web/app.js; rebuild them with
bun run build:web after editing any TypeScript or stylesheet (web/ui/) under web/ (or bot/web/app/) (a test fails when a bundle
is stale).
| Path | What it is |
cli/ | Installer and runtime behind every kaizen command. install.ts is the CLI entry; state.ts is the run engine; web.ts the board server; dashboard.ts the terminal board; sources.ts request sources; settings.ts config; notes.ts the notebook. Tests live beside the code as *.test.ts. |
skills/ | The workflow as Agent Skills folders: kaizen/ holds SKILL.md plus the spec*.md stage contracts, adapters.md and config.default.yml; kaizen-help/ beside it; media/ holds the bundled media skills kaizen-deck/, kaizen-video/ (footage editing and from-scratch films), kaizen-book/. |
agents/ | Codex subagents the workflow dispatches: kaizen-planner.md, kaizen-builder.md, kaizen-reviewer.md. |
commands/ | The /kaizen-* slash commands, one markdown file each. |
web/ | Board and notebook front end: the page shells (html/: board.html, notes.html, popup.html are 12-line shells for one React App each in pages/board, pages/notebook, pages/popup; video.html is a whole page), one entry folder per app (notebook/, popup/, term/, video/, annotate/: the annotator's page script), the board's React layers and bridge (ui/, components/, pages/, lib/, board/), and dist/, the generated bundles. See web/README.md. |
bot/ | Kaizen Bot — a separate private package (chat server, agent runtime, desktop packaging) with its own tests and package.json. |
docs/ | User and internal docs, indexed in docs/README.md. |
design.md | Design notes for the repo. |
.kaizen/ | This repo's own runs and sessions. Read state.json before touching a run. |
Where to look
- Every doc, one line each —
docs/README.md - The guide: board, sources, settings, installer flags —
docs/guide.md - The workflow contract, stage by stage —
skills/kaizen/spec.md, withspec-plan.md,spec-build.md,spec-review.md,spec-main.mdbeside it - Every setting, commented —
skills/kaizen/config.default.yml - The full command card —
skills/kaizen-help/SKILL.md - Kaizen Bot —
bot/README.md
Development
bun install # dev dependencies only
bun test # the suite; what CI runs (Ubuntu + Windows)
bun run cli/install.ts # install from this checkout — the links point at it
bun run build:web # rebuild the bundles in web/dist
bun run dev # the board with live reload: rebuilds on every change under web/ and reloads the pageTask deliverables
For persistent task results, publish only visual screenshots (.png) as deliverable artifacts. Do not attach .md summary files or raw code files as task result artifacts.
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.

