agentleFS
hfadhlullahhfadhlullah/kaizen/AGENTS.md

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…

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

    Read .kaizen/notes/Project/Index.md before planning or building, then open the notes it lists for the area you touch.

    line 4
  2. Very specific:

    When a request is what one of the kaizen skills does, invoke that skill first instead of doing the work inline: kaizen-concept for …

    line 13
  3. Very specific:

    Every doc, one line each — docs/README.md

    line 41
  4. Very specific:

    Every setting, commented — skills/kaizen/config.default.yml

    line 44

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

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- 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).

PathWhat 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.mdDesign 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, with spec-plan.md, spec-build.md, spec-review.md, spec-main.md beside 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 page

Task 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.

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.