AGENTS.md size budget (agents-md.maxBytes) by llima · Pull Request #66 · llima/craftar-cli

llima · 2026-10-18T11:16:38Z

Summary

Version bumped to 0.32.0, rebased onto main after Import reads a Claude rule's paths: as its scope #65 (0.31.0) merged. Merging publishes craftar@0.32.0 to npm after approval in the npm environment.
A size budget for the generated AGENTS.md: the param agents-md.maxBytes (a recipe default, the profile's params, or overrides.params in craftar.yaml / craftar.local.yaml), default 32768 (Codex's project_doc_max_bytes), 0 turns it off; an invalid value is a warning and the default applies.
Every plan over the budget warns once, naming at most 5 rule bodies by name and bytes (always-on, and scoped rules AGENTS.md embeds because no target writes them), never their content.
Opt-in failure: only an explicitly set budget makes sync --check, status (text and --json — keys unchanged, reason in warnings) and diff --exit-code with no [path] exit 1, with error: AGENTS.md is N bytes, over the budget of M set by agents-md.maxBytes and its fix. A writing sync still writes. doctor gains the check id agents-md-size (ok / warn over the default / error over a set budget), reporting the cause once.
agents-md.maxBytes is reserved from forge unify extraction and import inference, like kiro.banner.

Upgrading

No emitted byte changes. A workspace whose AGENTS.md is above 32768 bytes now gets a warning on every plan, and doctor --strict exits 1 for it (the new warn); set agents-md.maxBytes (or 0) to decide it.
sync --check's out-of-sync exit is now through process.exitCode (a piped listing is no longer cut).

Test plan

npm run typecheck — pass
npm run build — pass
npx vitest run --exclude test/ci.test.ts — 3006 passed, 8 skipped; oracle skipped (no fixture on the machine that ran it)
New tests: test/agents-md-budget.test.ts (measure, both warning forms, layers incl. recipe default and craftar.local.yaml, invalid value, top-5 with embedded scoped rules, reserved key) and test/agents-md-budget-cli.test.ts (sync --check, status, status --json, diff in every form, writing sync, doctor levels and one-cause)
Not covered by a test, by choice: two writers of AGENTS.md (only the agents-md emitter writes it today)
Rebased onto the 0.31.0 main; full suite 3047 passed, 8 skipped; confirmation review clean

Adds core and CLI tests for the agents-md.maxBytes budget feature. All tests fail as expected — the feature is not yet implemented.

Adds Plan.agentsMd field with bytes, maxBytes, explicit flag, and per-rule sizes. The emitter reports each always-on rule's byte size through a new callback.

…plicit AGENTS.md budget Adds budgetRefusalBlock helper and uses it in status, sync --check, and diff. Updates command descriptions to mention the budget.

Reports ok when within budget or budget is off, warn when over default budget, and error when over explicit budget.

Adds documentation for the AGENTS.md size budget feature in the Targets section.

Fixes regression where 'workspace in sync' was printed even when refusals were present.

Split agentsMdRefusal into message and fix parts shared with doctor. Exact messages for ok (within/off), warn (default exceeded), error (explicit).

Remove misleading comment about leading zeros and dead n < 0 check. Compute agentsMdOverBudget once in diff command.

- agents-md paragraph: where to set it, byte counting, 5 rules max - sync --check: also exits 1 for explicit budget - status: also exits 1 for explicit budget - diff --exit-code: also exits 1 for explicit budget - doctor: agents-md-size check with levels - Upgrading 'to the next release' entry

Two distinct warning formats for default vs explicit budget. The plan check is ok when agents-md-size reports the budget.

A scoped rule no target writes is embedded whole and counts toward the size; it is now listed as "(scoped, N bytes)" and the fix text names both ways to shrink the file.

…on --exit-code Same shape as the unset-params refusal: diff <path> --exit-code no longer hides the block. The budget is measured on the deduplicated plan, and the CLI tests now prove the budget alone fails.

Reserved beside kiro.banner; the key now lives with the agents-md emitter so extract.ts reads it without importing sync.ts.

The two warning forms, embedded scoped rules counted, the invalid value, diff's block in every form, doctor's one check, and the Upgrading lines for status --json and doctor --strict.

…rding One builder per message (default and set), the emitter's report is required on its context, the rule list sorts without the locale, and a file with no rule body ends the warning at the budget.

…eholder The heading follows the placeholder /open-pr renames; status's row says the listing prints before the budget block; diff's --help names the budget.

…unset parameter No block on stderr under --json: the reason is the budget line in warnings. Pins the warning with no rule body, and the test EmitBase gains the agents-md report.

Only craftar mcp's status tool and the ui's status view carry the warning; workspaces, forge impact and next sync: describe a writing sync, which still succeeds.

…nging the row The previous wording said it did not show it; the row lists every plan warning, only an unset declared parameter makes it an error.

llima added 22 commits October 18, 2026 09:15

test(agents-md): pin the AGENTS.md size budget

63e82dc

Adds core and CLI tests for the agents-md.maxBytes budget feature. All tests fail as expected — the feature is not yet implemented.

feat(agents-md): measure AGENTS.md against agents-md.maxBytes

d22d5f6

Adds Plan.agentsMd field with bytes, maxBytes, explicit flag, and per-rule sizes. The emitter reports each always-on rule's byte size through a new callback.

feat(cli): sync --check, status and diff --exit-code fail above an ex…

6191104

…plicit AGENTS.md budget Adds budgetRefusalBlock helper and uses it in status, sync --check, and diff. Updates command descriptions to mention the budget.

feat(doctor): add agents-md-size check

0ffd54a

Reports ok when within budget or budget is off, warn when over default budget, and error when over explicit budget.

docs(readme): document agents-md.maxBytes parameter

4f8e2bc

Adds documentation for the AGENTS.md size budget feature in the Targets section.

fix(cli): properly chain if-else in sync --check budget handling

4179e85

Fixes regression where 'workspace in sync' was printed even when refusals were present.

fix(doctor): agents-md-size says the size against its budget

1b4b4ec

Split agentsMdRefusal into message and fix parts shared with doctor. Exact messages for ok (within/off), warn (default exceeded), error (explicit).

refactor(agents-md): one budget parser, no stale comments

09f7dca

Remove misleading comment about leading zeros and dead n < 0 check. Compute agentsMdOverBudget once in diff command.

fix(agents-md): one wording for the budget, reported by one doctor check

5dcb72a

Two distinct warning formats for default vs explicit budget. The plan check is ok when agents-md-size reports the budget.

fix(agents-md): the budget names the scoped rules AGENTS.md embeds

9620150

A scoped rule no target writes is embedded whole and counts toward the size; it is now listed as "(scoped, N bytes)" and the fix text names both ways to shrink the file.

fix(cli): diff always prints the budget block; only the exit depends …

b2a9ea3

…on --exit-code Same shape as the unset-params refusal: diff <path> --exit-code no longer hides the block. The budget is measured on the deduplicated plan, and the CLI tests now prove the budget alone fails.

fix(extract): agents-md.maxBytes is an emitter's param, never extracted

87dc6d9

Reserved beside kiro.banner; the key now lives with the agents-md emitter so extract.ts reads it without importing sync.ts.

docs(readme): the budget's surfaces as they ship

f743462

The two warning forms, embedded scoped rules counted, the invalid value, diff's block in every form, doctor's one check, and the Upgrading lines for status --json and doctor --strict.

fix(agents-md): the budget warning reuses the error's and doctor's wo…

100830e

…rding One builder per message (default and set), the emitter's report is required on its context, the rule list sorts without the locale, and a file with no rule body ends the warning at the budget.

docs(readme): the budget's Upgrading heading is the next-version plac…

73cf0bb

…eholder The heading follows the placeholder /open-pr renames; status's row says the listing prints before the budget block; diff's --help names the budget.

fix(cli): status --json says the budget in its object, as it says an …

a5d08e7

…unset parameter No block on stderr under --json: the reason is the budget line in warnings. Pins the warning with no rule body, and the test EmitBase gains the agents-md report.

docs(readme): which views show the AGENTS.md budget, and which do not

da329d1

Only craftar mcp's status tool and the ui's status view carry the warning; workspaces, forge impact and next sync: describe a writing sync, which still succeeds.

docs(readme): craftar workspaces lists the budget warning without cha…

02c186e

…nging the row The previous wording said it did not show it; the row lists every plan warning, only an unset declared parameter makes it an error.

docs(readme): where craftar workspaces lists the budget warning

4918f83

chore: update version

38a860b

fix(readme): restore D17/D19 sentence in drift row lost during rebase

82ef5a7

llima force-pushed the feat/agents-md-budget branch from df61993 to 82ef5a7 Compare October 18, 2026 12:32

llima merged commit 5031cd8 into main Oct 18, 2026
8 checks passed

Navigation Menu

Repository navigation

AGENTS.md size budget (agents-md.maxBytes) - #66

AGENTS.md size budget (agents-md.maxBytes)#66
llima merged 22 commits into
mainfrom
feat/agents-md-budget

llima commented Oct 18, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

llima commented Oct 18, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Upgrading

Test plan

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

llima commented Oct 18, 2026 •

edited

Loading