Skip to content

AGENTS.md: dedupe the section 2 state tree into its declared owners#641

Open
jbassiri wants to merge 1 commit into
kunchenguid:mainfrom
jbassiri:slim-agents-md-core
Open

AGENTS.md: dedupe the section 2 state tree into its declared owners#641
jbassiri wants to merge 1 commit into
kunchenguid:mainfrom
jbassiri:slim-agents-md-core

Conversation

@jbassiri

@jbassiri jbassiri commented Jul 16, 2026

Copy link
Copy Markdown

Motivation

AGENTS.md is loaded in full by every firstmate session (CLAUDE.md is a symlink to it), so its byte size is a fixed token cost paid at every session start. This PR removes the one remaining block that duplicates content the repo already assigns to other owners, reducing that always-loaded cost without touching any rule.

What changed

Section 2 ("Layout and state") still inlined an exhaustive state/ + config/ file tree that restates exact child-file fields, even though the repo already assigns that content elsewhere:

  • Section 2's own opening line names docs/configuration.md as "the single owner of the operational-home layout, configuration schemas, and reference state map", and each producing script's header/--help as the owner of exact child fields and mutation mechanics.
  • docs/configuration.md ("Operational home layout and state") assigns child fields to producer script headers and deliberately keeps wake/watcher/away-mode/X state "rather than being duplicated into one exhaustive state tree here".

So the inline tree was the last remaining duplicate of content the one-owner rule (per firstmate-coding-guidelines) assigns to docs/ and script headers. It is replaced with a concise pointer to those owners. Preserved inline: the two boundaries that bind at every turn (projects/ is read-only; state/ watcher/sub-supervisor/wake internals are never hand-edited) and the CLAUDE.md / .claude/skills symlink facts.

Size

bytes
AGENTS.md before 44,901
AGENTS.md after 38,023

A 6,878-byte (~15%) reduction in the always-loaded surface.

Not a rewrite

This is a pure dedupe of reference detail; no safety boundary, prime directive, or ownership pointer was weakened, dropped, or reworded. The two load-bearing section-2 facts that were interleaved in the tree (state/<id>.status is a wake event; data/captain.md/data/learnings.md canonicity) are untouched. The sections the repo marks as always-loaded operational contracts (task lifecycle, supervision) are left exactly as-is.

Validation

bin/fm-lint.sh passes (shellcheck 0.11.0). The instruction-ownership and cross-reference tests pass, including fm-instruction-owners (which asserts the section-2 owner pointer, the always-loaded contracts, and the retained safety phrases), fm-no-mistakes-ownership, fm-stow-contract, and fm-ensure-agents-md. No test asserts the removed tree's contents. The CLAUDE.md -> AGENTS.md and .claude/skills -> ../.agents/skills symlinks are untouched.

AGENTS.md is loaded in full by every firstmate session (CLAUDE.md is a
symlink to it), so its size is a fixed per-session token cost. Section 2
still inlined an exhaustive state/ + config/ file tree that restates exact
child-file fields, even though the repo already assigns that content to
other owners:

- Section 2's own opening line names docs/configuration.md as "the single
  owner of the operational-home layout, configuration schemas, and reference
  state map", and each producing script's header/--help as the owner of exact
  child fields and mutation mechanics.
- docs/configuration.md's "Operational home layout and state" section states
  the child fields belong to producer script headers and deliberately keeps
  wake/watcher/away-mode/X state "rather than being duplicated into one
  exhaustive state tree here".

The inline tree was therefore the last remaining duplicate of content the
one-owner rule assigns elsewhere. Replace it with a concise pointer to those
owners, preserving the two boundaries that bind at every turn inline
(projects/ is read-only; state/ watcher/sub-supervisor/wake internals are
never hand-edited) and the CLAUDE.md / .claude/skills symlink facts.

No safety rule, prime directive, or ownership pointer was weakened or dropped;
this is a pure dedupe of reference detail. AGENTS.md: 44901 -> 38023 bytes.
@jbassiri
jbassiri force-pushed the slim-agents-md-core branch from ca4471a to 609097a Compare July 16, 2026 15:47
@jbassiri jbassiri changed the title Slim AGENTS.md core; move deep mechanics to agent-only reference skills AGENTS.md: dedupe the section 2 state tree into its declared owners Jul 16, 2026
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