Skip to content

docs(agents): trim section 7 spawn duplication to its owners - #358

Closed
zachlandes wants to merge 1 commit into
kunchenguid:mainfrom
zachlandes:fm/memtrim-r6
Closed

zachlandes wants to merge 1 commit into
kunchenguid:mainfrom
zachlandes:fm/memtrim-r6

Conversation

@zachlandes

Copy link
Copy Markdown
Contributor

Trim section 7 Spawn duplication to its owners

Continues the AGENTS.md diet (after #253/#255/#258) with one surgical one-owner consolidation, in the same style as those PRs.
Section 7's Spawn subsection had grown to restate mechanics that already have canonical owners; this replaces each restatement with a pointer, per the one-owner rule in firstmate-coding-guidelines.

Measured size delta

Always-loaded AGENTS.md is paid by every session of every fleet member, every turn, whether or not that session hits the situation the lines describe.

Surface Before After Change
AGENTS.md (o200k_base tokens) 26,759 26,397 -362 (-1.35%)
AGENTS.md (lines) 939 936 -3

What changed (all in section 7 Spawn)

  • Runtime backend resolution - the selection order, the innermost-first auto-detection nesting, and the per-backend refusals (including codex-app as unknown) were restated nearly verbatim from docs/configuration.md "Runtime backend".
    Replaced with a pointer.
    Firstmate never computes backend resolution at spawn - the script does - and the actionable "a backend refusal is a blocker, never silently retry another backend" rule already sits on the very next line, so nothing firstmate acts on was lost.
  • Per-backend workspace scoping (herdr per-home workspaces, zellij single shared session) was likewise owned in full by that doc.
    Replaced with a pointer.
  • The <id>.meta field enumeration (harness=/model=/effort=/kind=/mode=/yolo=, secondmate home=/projects=, and the non-default backend= note) duplicated section 2's canonical <id>.meta line.
    Replaced with a section 2 pointer.
  • The grok per-task turn-end hook mechanics duplicated docs/configuration.md (the $GROK_HOME/hooks/ install plus .fm-grok-turnend pointer, teardown removal) and section 2's grok-turnend-token line.
    Removed: harness-adapters already delegates per-task turn-end hook mechanics to bin/fm-spawn.sh, and the hook is installed by spawn and removed by teardown with no firstmate action in between, so there is no wake-time trigger to preserve inline.
  • A redundant "backend=codex-app is unknown" line already stated in the spawn command block, section 2, and the runtime-backend pointer.

Safety

  • No hard rule, no section 8 always-on supervision core-loop content, and no wake-time trigger was touched.
  • Every distinctive token removed (env vars, flags, thresholds, paths) was programmatically confirmed to survive in its owner (docs/configuration.md or AGENTS.md section 2).
  • All 14 section numbers and titles are unchanged; CLAUDE.md -> AGENTS.md and .claude/skills -> .agents/skills symlinks untouched.
  • Validated locally through the no-mistakes pipeline: review, test, document, and lint each returned zero findings.

Scope note

This is deliberately one surgical theme kept independently reviewable, not a whole-file diet.
Judgment-heavy extractions that need a maintainer decision on shape (the section 14 X-mode cadence block, and the section 7 no-mistakes axi status validation state table) were intentionally left out of this PR.

Consolidates section 7's Spawn subsection restatement of already-owned
mechanics to a single owner each, per the one-owner rule.

* Runtime backend resolution, auto-detection nesting, and per-backend
  refusals were restated verbatim from docs/configuration.md "Runtime
  backend"; replaced with a pointer. Firstmate never computes backend
  resolution at spawn - the script does - and the actionable
  refusal-is-a-blocker rule already sits on the next line, so nothing
  actionable was lost.
* Per-backend workspace scoping (herdr per-home, zellij shared session)
  was likewise owned by that doc; replaced with a pointer.
* The meta-field enumeration (harness=/model=/effort=/kind=/mode=/yolo=,
  home=/projects=, non-default backend=) duplicated section 2's canonical
  <id>.meta line; replaced with a section 2 pointer.
* The grok per-task turn-end hook mechanics duplicated
  docs/configuration.md and section 2; removed. harness-adapters already
  delegates per-task turn-end hook mechanics to bin/fm-spawn.sh, and the
  hook is installed by spawn and removed by teardown with no firstmate
  action in between.
* Dropped the redundant codex-app-is-unknown line (already stated in the
  command block, section 2, and the runtime-backend pointer).

Always-loaded AGENTS.md drops from 26,759 to 26,397 tokens (o200k_base),
-362 (-1.35%). Every removed token was confirmed to survive in its owner.
@zachlandes

Copy link
Copy Markdown
Contributor Author

Superseded by #447 (8cd90fe), which removed every line this PR targeted and trimmed further — section 7 now points at bin/fm-spawn.sh's header as the single owner. Closing as redundant.

@zachlandes zachlandes closed this Jul 13, 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