docs(agents): move step rules into their skills #137

Merged

claudiomaradonna merged 1 commit from docs/trim-agents-md into main

2026-10-17 22:51:56 +02:00

motoko commented

2026-10-17 19:31:32 +02:00

Collaborator

Why

Recommendation 3. Every agent session loads all of AGENTS.md before it sees the request, plain questions included. In an adopted repo that's 2,860 words. Two problems with that:

Step-only rules ride along everywhere. Some rules act at a single step, such as the approval summary at a gate or the disclosure of a pre-existing security flaw at delivery, yet every session carries them.
Some rules need re-reading. One could even be misread: a CLAUDE file that "links to" AGENTS.md, when only an @ import or a symlink works.

The docs audit (document-reviewer) puts the saving at about 1% of a small change's cost. So this PR is for clarity, not cost.

What changed

Step rules move to the step that acts on them:
- the approval summary and the scope of going without approval go to get-approval;
- the end-of-execution summary goes to execute-plan;
- removing a record of a pre-existing flaw goes to verify-execution, and its disclosure and channel go to deliver step 1;
- linear history goes to fold-branch;
- review report names go to verify-execution and design.
AGENTS.md keeps one core bullet on pre-existing flaws, which points to those steps.
Six hard-to-read rules rewritten, meaning kept: the CLAUDE-file rule, the first Git and delivery rule, two Workflows rules, the regression-test rules (now nested under one parent), and the Members preamble.
UPGRADING.md gains a migration that carries an upgrading repo's own edits to the moved rules to their new homes. It triggers on the adopted commit's linear-history bullet, which every source commit since 2026-07-29 holds.

Result: an adopted AGENTS.md is 2,641 words, down from 2,860 (−8%).

Not done:

The security-surface list and the Members rules stay where they are. Every Brief needs the surface list, and single-repo adoption deletes Members anyway.
The test-writing rules stay in AGENTS.md, because reviewers use them too.

How to verify

These all pass on the tip: bash tests/verify-agent-config.sh (252), bash tests/check-work-folder.sh (46), .agents/hooks/shellcheck.sh repo, prettier --check '**/*.md', scripts/verify-agent-config.sh, and git diff --check main.

To see the new size, install the policy into a scratch directory with evals/install-policy.sh HEAD <dir>, then run wc -w <dir>/AGENTS.md; it should print 2,641.

The eval suite passed 6 of 6 on both main and this branch, at $9.52 against $10.04, which is within noise.

The change, security and documentation reviewers went over it in two rounds, and the change reviewer took a third for the migration trigger. Everything they raised is fixed except what is set aside below.

Considerations

Rule placement: the rules' new homes are my design choices, made under your "approve through a PR" approval. Linear history went to fold-branch rather than land.md, because a first push never reaches land.md.
Condensed reports: the saved reviewer reports in the work folder are condensed rather than kept as given. That's against the work-folder rule, as in the two previous works; it's yours to accept or change.

## Why Recommendation 3. Every agent session loads all of `AGENTS.md` before it sees the request, plain questions included. In an adopted repo that's 2,860 words. Two problems with that: - **Step-only rules ride along everywhere.** Some rules act at a single step, such as the approval summary at a gate or the disclosure of a pre-existing security flaw at delivery, yet every session carries them. - **Some rules need re-reading.** One could even be misread: a CLAUDE file that "links to" `AGENTS.md`, when only an `@` import or a symlink works. The docs audit (`document-reviewer`) puts the saving at about 1% of a small change's cost. So this PR is for clarity, not cost. ## What changed - **Step rules move to the step that acts on them:** - the approval summary and the scope of going without approval go to `get-approval`; - the end-of-execution summary goes to `execute-plan`; - removing a record of a pre-existing flaw goes to `verify-execution`, and its disclosure and channel go to `deliver` step 1; - linear history goes to `fold-branch`; - review report names go to `verify-execution` and `design`. `AGENTS.md` keeps one core bullet on pre-existing flaws, which points to those steps. - **Six hard-to-read rules rewritten, meaning kept:** the CLAUDE-file rule, the first Git and delivery rule, two Workflows rules, the regression-test rules (now nested under one parent), and the Members preamble. - **`UPGRADING.md` gains a migration** that carries an upgrading repo's own edits to the moved rules to their new homes. It triggers on the adopted commit's linear-history bullet, which every source commit since 2026-07-29 holds. Result: an adopted `AGENTS.md` is 2,641 words, down from 2,860 (−8%). Not done: - The security-surface list and the Members rules stay where they are. Every Brief needs the surface list, and single-repo adoption deletes Members anyway. - The test-writing rules stay in `AGENTS.md`, because reviewers use them too. ## How to verify These all pass on the tip: `bash tests/verify-agent-config.sh` (252), `bash tests/check-work-folder.sh` (46), `.agents/hooks/shellcheck.sh repo`, `prettier --check '**/*.md'`, `scripts/verify-agent-config.sh`, and `git diff --check main`. To see the new size, install the policy into a scratch directory with `evals/install-policy.sh HEAD <dir>`, then run `wc -w <dir>/AGENTS.md`; it should print 2,641. The eval suite passed 6 of 6 on both main and this branch, at $9.52 against $10.04, which is within noise. The change, security and documentation reviewers went over it in two rounds, and the change reviewer took a third for the migration trigger. Everything they raised is fixed except what is set aside below. ## Considerations - **Rule placement:** the rules' new homes are my design choices, made under your "approve through a PR" approval. Linear history went to `fold-branch` rather than `land.md`, because a first push never reaches `land.md`. - **Condensed reports:** the saved reviewer reports in the work folder are condensed rather than kept as given. That's against the work-folder rule, as in the two previous works; it's yours to accept or change.

motoko added 1 commit

2026-10-17 19:31:36 +02:00

docs(agents): move step rules into their skills 4e03d57aeb

Move the rules only one step acts on out of AGENTS.md, which every
session loads, into that step's skill: the approval summary and its
scope, the end-of-execution summary, a pre-existing flaw's record
removal and disclosure, linear history, and the review report names.
Rewrite the rules that needed re-reading, keeping their meaning, and
add the upgrade migration that carries a repository's own changes to
the moved rules.

claudiomaradonna merged commit 4e03d57aeb into main

2026-10-17 22:51:56 +02:00

claudiomaradonna deleted branch docs/trim-agents-md

2026-10-17 22:52:02 +02:00

No reviewers

No labels

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference

claudiomaradonna/agent-foundry!137

No description provided.

Rows
Columns