Skip to content

docs: cut AGENTS.md fixed context cost by routing prose to its owners - #1

Open
jdille wants to merge 5 commits into
mainfrom
fm/firstmate-agents-md-trim
Open

docs: cut AGENTS.md fixed context cost by routing prose to its owners#1
jdille wants to merge 5 commits into
mainfrom
fm/firstmate-agents-md-trim

Conversation

@jdille

@jdille jdille commented Aug 15, 2026

Copy link
Copy Markdown
Owner

Cuts AGENTS.md from 66,883 to 52,099 bytes (22.1 percent), 568 to 494 lines, without weakening any safety boundary.

Every firstmate session loads AGENTS.md in full before doing any work, so this is fixed context cost paid by every session of every fleet member. A new session was already starting at 45 percent context.

Method

The one-owner rule from .agents/skills/firstmate-coding-guidelines/SKILL.md: state a contract once, in its owner, and point at it from here. Every cut names the authoritative owner the reader is now sent to.

Section Change Owner readers are sent to
2 75-line layout tree replaced with the records firstmate reads or writes by name, plus a categorical pointer docs/configuration.md already declares itself single owner of the home layout and states the exhaustive state tree should not be duplicated into it; per-record detail lives in the script headers that write each record
3 Seven-stage digest enumeration dropped bin/fm-session-start.sh header, already named single owner two lines above the enumeration, documents nine stages in more detail
4 Provider-relation, quota-granularity, and authentication detail dropped quota-array-dispatch, which states in its own text that it is the single owner and that section 4 keeps only the intake boundary, load trigger, malformed-config refusal, every-candidate accounting, and strongest-reasoning and tie rules
7 Run-step mapping, custom-check file rules, and promoted-worker sequence routed out bin/fm-crew-state.sh, bin/fm-check-register.sh (which enforces and fails closed on those rules), bin/fm-promote.sh (whose header carries the sequence verbatim)
8 Acknowledgement-episode mechanism routed out; doc added to the section's owner list docs/watcher-continuity.md

docs/configuration.md line 24 explicitly specifies which facts AGENTS.md must retain for session start; that statement guided what stayed rather than personal judgment.

Deliberately not cut

Section 8 was flagged as a worst offender but is left nearly intact: most of it is the drain-and-handle contract that must be actionable mid-session with no other file loaded, since the emitted supervision block only arrives at session start. Section 7's intake and merge-authority block is untouched because docs/architecture.md line 184 explicitly assigns that contract to AGENTS.md. A smaller honest cut beats an aggressive one that loses a boundary.

Unchanged, verified byte-identical

Section 1's five hard rules, section 5, section 7's delivery-path and merge-authority block (never-merge-red, the yolo boundary, ask-user authority), section 9's escalation translation table, all of section 13's skill triggers, section 8's away-mode stub, wake-kind list, and stuck-worker trigger, sections 10 through 12, section 14, and the captain-instruction precedence rule.

Three skills show fewer total mentions (fmx-respond, process-event-sources, secondmate-provisioning). Every lost mention was traced: each was a descriptive reference inside the deleted layout tree, never a load trigger. Section numbering is unchanged, so the cross-references that name sections by number stay valid.

Review fixes included

Three defects the pipeline review caught, all fixed in this branch:

  1. 4e8bbb3 - the compressed state-machinery rule became a blanket prohibition that contradicted fmx-respond's required rm -f state/x-inbox/<request_id>.json, which would have caused a duplicate public reply on the next poll. Narrowed to permit owner-directed deletes, and both documented safe-to-delete affordances restored.
  2. bbad45f - prose compression had dropped the word "prefer" from the validate-phase rule, silently converting a preference into a directive. Restored.
  3. ec3a347 - a pointer named the wrong owner: axi status --help documents only --run and -h, while axi sync --help is what owns recover_custody, --recover, and --keep-local. Redirected.

Verification

  • bin/fm-doc-audience-check.sh passes (68 surfaces, 253 local links)
  • tests/fm-session-start.test.sh passes in full, including its AGENTS.md instruction-refresh and baseline-hash cases
  • No test asserts on AGENTS.md prose content; baselines are computed at runtime
  • Pipeline review, test, document, and lint steps all completed
  • Documentation-only change: the entire diff is one file, zero shell scripts touched

Status

Parked deliberately. This targets jdille/firstmate main and is not intended for merge.

jdille added 5 commits August 14, 2026 22:24
AGENTS.md was 66,883 bytes and is loaded in full by every session of every
fleet member before any work starts. This applies the one-owner rule from
firstmate-coding-guidelines to the prose that restated contracts already
owned elsewhere, so each fact is stated once, in its owner, and pointed to
from here.

Section 2: replace the 75-line exhaustive layout tree with the records
firstmate reads or writes by name, plus a categorical pointer for the rest.
docs/configuration.md already declares itself the single owner of the home
layout and says the exhaustive state tree should not be duplicated into it;
the config/ and machinery entries are owned by that file and by the script
headers that write each record.

Section 3: drop the seven-stage digest enumeration. bin/fm-session-start.sh's
header owns the ordering and stage contents in more detail, and AGENTS.md
already named it the single owner. Kept the run-once, read-once, lock-refusal,
consent, ABSENT, and unconfirmed-network-check rules that
docs/configuration.md says AGENTS.md must retain.

Section 4: drop the provider-relation, quota-granularity, and authentication
detail owned in full by quota-array-dispatch. Kept the intake boundary,
every-candidate accounting, malformed-config refusal, and the
strongest-reasoning and tie rules that skill says AGENTS.md owns.

Section 7: point at bin/fm-crew-state.sh for the run-step-to-state mapping,
bin/fm-check-register.sh for the custom-check file requirements it enforces,
and bin/fm-promote.sh for the promoted-worker instructions its header already
carries verbatim. Consolidated the secondmate idle contract into section 6.

Section 8: point at docs/watcher-continuity.md for the acknowledgement episode
contract. The every-turn drain, wake-handling, and away-mode rules stay inline
because they must be actionable with no other file loaded.

Result: 66,883 -> 51,842 bytes, a 22.5 percent cut.

Unchanged, verified byte-identical: section 1's five hard rules, section 7's
delivery-path and merge-authority block, section 9's escalation translation
table, all of section 13's skill triggers, section 8's away-mode stub,
wake-kind list, and stuck-worker trigger, sections 10 through 12, section 14,
and the captain-instruction precedence rule.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant