docs: add AGENTS.md

[shaokeyibb]

Summary

Maka already reads AGENTS.md — buildWorkspaceInstructionsPromptFragment injects it into the system prompt — but the repository has never had its own. An agent working here starts with nothing but the source tree.

It covers what the AGENTS.md format is for: project overview, repository layout, setup, development workflow, testing, code style, build and release, the CI gate list, PR conventions, and a working method. Commands are written out rather than deferred to package.json, because they are the executable part and CI catches them when they drift; prose that other documents own — contribution policy, architecture — stays a link.

Some of it is only recorded in code today: that every workspace tests against compiled dist/ rather than src/, that Biome formats the tree except apps/desktop and packages/ui because desktop's source-contract tests regex-match exact source shapes, and that workspace instructions load from exactly cwd and ~/.maka with no ancestor walk.

CLAUDE.md is a symlink to it. Each agent CLI reads one filename — Claude Code reads CLAUDE.md, Codex reads AGENTS.md, Gemini CLI reads GEMINI.md — so one canonical file plus a link avoids two copies that drift. apache/airflow does the same.

Verification

npm run check:asf-headers, npm run lint, npm run format:check all pass. Every path the file links to was checked to exist.

The file is 13,091 characters, which is in the normal range for this format — apache/kafka is 9.7 KB, apache/iceberg 13 KB, apache/airflow 35 KB.

Known interaction

With the symlink present, Maka injects the same content twice — once as AGENTS.md, once as CLAUDE.md — because readWorkspaceInstructions reads every candidate name and never compares them:

without symlink   blocks = project/AGENTS.md
with symlink      blocks = project/AGENTS.md, project/CLAUDE.md

That is a pre-existing gap rather than something this PR introduces, and it is filed separately. Other agents avoid it either by reading a single filename (Claude Code, Codex, Gemini CLI), by first-match-wins (opencode, Pi), or by content-digest deduplication (DeepSeek Harness, which ships the same symlink). If reviewers would rather not land the symlink before that fix, dropping CLAUDE.md from this PR is a one-file change and the rest stands on its own.

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code — surveyed the repo and comparable projects, drafted the file, and verified each claim against the file it names.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

No runtime source changes, but this file is prompt input for Maka sessions run in this repository, so adding it changes model behaviour here. Flagging it rather than treating the checkbox as docs-only.

---

Question for maintainers: the workspace-instruction size cap

MAX_WORKSPACE_INSTRUCTION_FILE_CHARS is 6000 and MAX_WORKSPACE_INSTRUCTIONS_PROMPT_CHARS is 14000, so Maka truncates this file at roughly 46% of its length and appends [instructions truncated]. Everything from "Build, packaging and release" onward is cut.

An earlier revision of this PR was compressed to fit. That turned out to be the wrong trade: it removed the install step, the build command, how to run tests, and any statement of what Maka is — which is most of what the format exists to provide. Optimising a file whose audience is every agent against one consumer's cap degraded it for all of them.

The cap also looks low against comparable projects. Of the ASF repositories that ship an AGENTS.md, apache/kafka (9.7 KB), opendal (8.5 KB), seatunnel (7.3 KB), pekko (7.3 KB), doris (12 KB), iceberg (13 KB), flink (23 KB), spark (20 KB), superset (16 KB), camel (33 KB) and airflow (35 KB) all exceed 6000 characters; only paimon, datafusion and gravitino fit under it. For comparison, Claude Code loads a CLAUDE.md up to 4 MiB. The mandatory ASF licence header alone consumes 793 characters, 13% of the current per-file budget.

Three options, and I do not have a strong view on which is right:

1. Raise the caps. Simplest, but the prompt budget is a real constraint and someone has to choose the new number.
2. Exempt the repository's own instruction files from the per-file cap, keeping only the total prompt budget.
3. Leave it and accept truncation, on the basis that the cap protects the prompt from arbitrary user files and this repository is not special.

Happy to open a separate issue if this is worth pursuing; it is out of scope for this PR either way.

[Copilot]

Pull request overview

Adds repository-level guidance for coding agents through AGENTS.md.

Changes:

• Documents testing, formatting, generated files, licensing, and workflow conventions.
• Links to existing setup, contribution, architecture, and tooling documentation.
• Includes notes to clarify the CLAUDE.md symlink claim and @maka/eval test command.

Suppressed comments (6)

AGENTS.md:33

• buildWorkspaceInstructionsPromptFragment does not search ancestor directories: it reads only the exact session cwd (plus ~/.maka) and the three filenames there. Calling this the “nearest” file is misleading for a session started in a nested directory, where the repository-root AGENTS.md is not loaded; please document the actual scope.

Maka reads this file itself — `buildWorkspaceInstructionsPromptFragment` injects the nearest
`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` into the system prompt — so it is live product input, not
only documentation. It is also truncated past 6000 characters, which is the hard reason to keep it
short.

AGENTS.md:82

• Generated artifacts are not limited to *.generated.ts: the repository also generates the theme artifacts, the surface/test inventories, and apps/desktop/bundled-tools.json. As written, an agent can miss those and hand-edit build outputs; describe the suffix as one naming convention and include the other generated classes.

- **Some files are generated.** They match `*.generated.ts`; regenerate rather than hand-edit.

AGENTS.md:85

• “Every source file” contradicts the header policy: it deliberately excludes generated files, third-party source, fixtures, templates, and other non-Maka files; for example, packages/core/src/model-metadata.generated.ts is under src/ but is excluded. Following this advice could add headers to byte-sensitive or regenerated files, so qualify the rule and link the exclusion policy.

- **Every source file needs the ASF license header.** `npm run check:asf-headers` audits the whole
  checkout, so stray untracked files can fail it. `node scripts/asf-license-headers.mjs write` adds
  missing headers.

AGENTS.md:33

• This file explicitly says it is injected into the system prompt, so adding it changes model prompt behavior for sessions in this repository even though no runtime source changed. That conflicts with the checklist's “Does this PR entail a change in behavior? No”; mark it Yes or clarify that the checkbox excludes prompt inputs.

Maka reads this file itself — `buildWorkspaceInstructionsPromptFragment` injects the nearest
`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md` into the system prompt — so it is live product input, not
only documentation. It is also truncated past 6000 characters, which is the hard reason to keep it
short.

AGENTS.md:56

• The heading is broader than the documented test contract: @maka/eval's test:dist also runs several python3 harbor/test_*.py suites directly from source. Scope this section to TypeScript/Node tests so contributors editing those Python tests are not given a false workflow.

## Tests run from `dist/`, not `src/`

AGENTS.md:52

• The opening paragraph says this file avoids restating documentation owned elsewhere, but this section repeats the Runtime Host and Runtime Event Log invariants already stated in ARCHITECTURE.md:24 and ARCHITECTURE.md:45. Keeping a second copy can drift; replace it with a pointer to those sections or move the agent-specific warning into the architecture owner.

- **Runtime Host is the only execution authority.** Desktop, TUI, CLI, and eval all execute through
  it. A change that seems to need its own runtime is a design discussion, not an implementation
  detail.
- **The Runtime Event Log is the source of truth**, and sessions, UI, model context, and recovery
  are projections over it. Context pruning and compaction change what the next inference sees; they

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Astro-Han]

Reviewed at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff.

Coverage: every factual claim the document makes about this repository, checked against the working tree at this head. Not covered: wording and style, and GitHub UI behaviour (for example how a PR title actually renders in a squash commit).

Result: no P0–P3 findings. Everything checked was accurate.

Spot-check of what was verified

• Node engines >= 22.19.0, and ci.yml on node 24.
• Grep shells out to rg via packages/runtime/src/workspace-executor.ts:457.
• The layout table's 10 workspaces plus scripts/ match the root workspaces field.
• The build order in the doc, core → storage → mcp → runtime → runtime-host → computer-use → eval → cli → ui → desktop, matches the root build script exactly, including computer-use before eval.
• Every script named in the doc exists: dev, dev:full, rebuild, test:dist, test:dist:serial, lint, format, format:check, typecheck, check:asf-headers, check:release, check:asf-npm, check:asf-source, astryx:theme, astryx:surface-inventory:write, windows:inventory, release:cli:pack, smoke, and the release:asf:source|verify|sign trio.
• "Tests run from dist/" matches each package's test = clean + build + node --test dist/…; @maka/eval correctly has only test:dist and chains the Python harbor suites.
• Biome's dual role, the absence of any ESLint/Prettier config, and the single-quote / always-semicolon / 2-space / 100-column settings. The formatter excludes apps/desktop and packages/ui while still linting them, with the reason commented at biome.jsonc:50; licenses/** and bundled-tools.json are excluded as byte-sensitive.
• ASF header counts measured at this head: 2745 covered / 130 excluded, against the doc's "about 2,750 / about 130".
• Squash is the only merge method enabled on the repository.
• The CONTRIBUTING.md policy the doc paraphrases — AI review does not count, and the Generated-by trailer requirement — matches the source.
• "Maka reads it": buildWorkspaceInstructionsPromptFragment injects it into the system prompt, and readWorkspaceInstructions reads only files directly under the given root, so the stated scope (session cwd plus ~/.maka, no ancestor traversal) is correct. CLAUDE.md is a symlink to AGENTS.md.

Why this is a comment and not an approval

Hosted checks have not run on this head — check-runs total_count is 0. Not-run is not green, so the CI gate is not cleared regardless of the review outcome. Happy to convert this to an approval once checks go terminal green.