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.

[M4n5ter]

English

Independent COMMENT-only review at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff.

Result: NO-GO while the P2 below remains. I found no other P0–P2 correctness or documentation-consistency findings. Hosted test is currently CANCELLED (run 32629944907), so there is no terminal-green CI evidence for this head. Local git diff --check and relative-link audit pass; the runtime package build could not start because this checkout lacks @types/node.

中文

在精确 head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff 上独立进行 COMMENT-only 审查。结论：P2 未解决前 NO-GO；未发现其他 P0–P2 正确性或文档一致性问题。Hosted test 当前为 CANCELLED（run 32629944907），因此没有该 head 的终态绿色 CI 证据。本地 diff-check 与相对链接审计通过；runtime 构建因 checkout 缺少 @types/node 未能启动。

[Astro-Han]

Independent review at exact head fa72ed03bbf1bce0f563a78186fbc03fbf5b5cff on one axis our earlier review did not test: this file is not only documentation, it is runtime input to the product in this repository. One [P1] inline — the document is more than twice the size Maka will inject, and the half that is dropped is the half that prevents mistakes. Details and three possible resolutions are on the inline comment at AGENTS.md:133, the line the truncation lands on.

This does not contradict review 5002101226: every factual claim that review checked is still accurate. It checked the file as prose; this checks it as an injected artifact.

[Astro-Han]

[P1] This file is 13,091 codepoints; Maka injects at most 6,000. 54% never reaches the agent, and the cut lands two characters into this line, inside an open ```sh fence.

Mechanism (packages/runtime/src/system-prompt/workspace-instructions.ts on main): MAX_WORKSPACE_INSTRUCTION_FILE_CHARS = 6000 at :42; truncateCodepoints at :143 slices at exactly 6,000 with no block or sentence awareness; injected for every run whose cwd is this repo (runtime-host/src/server/interactive-run-composer.ts:241).

Measured at this head: 13,091 codepoints, 7,091 dropped, 45.8% survives. Six of thirteen sections arrive; seven do not — Code style, Build, packaging and release, What CI enforces, Pull requests, Working method, Platform notes, About this file.

The dropped half is the half that prevents mistakes. The PR description's own example of knowledge "only recorded in code today" — Biome formatting the tree except apps/desktop and packages/ui — is in Code style, dropped. So is What CI enforces. An agent gets the layout and how to run tests, and nothing about the rules it is judged by.

The fragment also ends mid-command at ...build:\n\n```sh\nnp, leaving an unterminated fence. The prompt appends a generic [instructions truncated] (:84), so the model is not told it is holding a broken fence.

None of this is visible in git diff — it happens only at injection time.

Any one of these resolves it, no preference: bring the file under 6,000 and front-load Code style / What CI enforces / Pull requests; or split into a short root file plus a long guide in docs/; or raise the cap in its own PR first — but that changes behaviour for every Maka user's workspace, so it should be argued separately rather than arriving as a side effect.

One thing this PR gets right: the CLAUDE.md symlink does not double-inject. readWorkspaceInstructions digests cleaned text and skips repeats within a directory (:120-138), so identical bytes under two names collapse to one block — the behaviour #3578 (877dc962e) landed.

中文

[P1] 文件 13,091 码位，Maka 最多注入 6,000，54% 到不了 agent；切点在本行第 2 个字符，处在未闭合的 ```sh 围栏里。

上限见 workspace-instructions.ts:42，:143 按码位硬切、不认代码块边界；注入点 interactive-run-composer.ts:241，凡 cwd 为本仓的会话都注入。实测丢弃 7,091、存活 45.8%。13 节中 7 节到不了：Code style、Build/packaging/release、What CI enforces、Pull requests、Working method、Platform notes、About this file。

丢掉的正是能防错的那半：PR 描述举例的"Biome 排除 apps/desktop 和 packages/ui"就在 Code style 里。片段还以 ```sh\nnp 结尾，围栏未闭合，而提示词只追加通用的 [instructions truncated]。git diff 里看不到这些——只发生在注入时刻。

三种解法任选：压到 6,000 以下并前置 Code style / What CI enforces / Pull requests；或拆成"根目录短文件 + docs/ 长文"；或另开 PR 先抬高上限——但那改的是所有用户的工作区行为，应独立论证。

有一处做对了：CLAUDE.md 符号链接不会重复注入（:120-138 按内容摘要去重，#3578 落地）。

[Astro-Han]

Please take this to a Discussion or dev@ before the PR. The document itself is careful and accurate — this is about the route, not the work.

Why: root AGENTS.md is not documentation people choose to read. buildWorkspaceInstructionsPromptFragment injects it into the system prompt of every agent session whose cwd is this repository (packages/runtime-host/src/server/interactive-run-composer.ts:241). Merging it changes how everyone — human and agent — works here, without opting in.

CONTRIBUTING.md already routes that class of change:

Project direction, governance, and material product decisions are discussed publicly on dev@maka.apache.org before implementation; implementation-level decisions may live in the pull request.

Four questions the Discussion should settle, because they determine the file's shape:

1. Does the project want this file, given its contents become non-optional context for everyone?
2. Is it a factual map of the repo, or normative instructions on how to work? The draft is both, and they carry different review standards.
3. Who may change it, and does editing it need more than a docs review?
4. What is the size budget? The runtime caps one instruction file at 6,000 codepoints; this draft is over twice that (see the [P1] at AGENTS.md:133).

This branch is good raw material for that proposal — it already surfaces knowledge that exists only in code today. If the project agrees it wants a root AGENTS.md, most of the work is done.

中文

建议先走 Discussion 或 dev@，再开 PR。 文档本身写得准确，问题在路径，不在工作质量。

根目录 AGENTS.md 会被 buildWorkspaceInstructionsPromptFragment 注入本仓每个 agent 会话的系统提示词（interactive-run-composer.ts:241），合入即改变所有人的工作条件。CONTRIBUTING.md 已明确这类 material product decision 要先在 dev@ 公开讨论。

四个该在讨论里定的问题：要不要这个文件；它是事实地图还是规范性指令（草稿两者都有）；谁有修改权；尺寸预算多少（运行时上限 6000 码位，草稿超出一倍以上）。

这个分支是提案的好原材料，项目若同意要，大部分工作已完成。