Skip to content

feat(brief): add context-discipline guidance to crewmate scaffold - #1848

Open
RosanFiqri wants to merge 2 commits into
kunchenguid:mainfrom
RosanFiqri:fm/fm-ctxdisc-t1
Open

feat(brief): add context-discipline guidance to crewmate scaffold#1848
RosanFiqri wants to merge 2 commits into
kunchenguid:mainfrom
RosanFiqri:fm/fm-ctxdisc-t1

Conversation

@RosanFiqri

@RosanFiqri RosanFiqri commented Aug 7, 2026

Copy link
Copy Markdown

Summary

Adds context-discipline guidance to the crewmate brief scaffold (bin/fm-brief.sh) so future workers manage their own context window deliberately instead of accumulating until the runtime compacts for them.

Two short additions to the generated ship and scout Rules sections:

  • Worker-owned compaction at phase boundaries (new rule 8): once a worker is past roughly 150k tokens of context and reaches a natural phase boundary (setup complete, a component built, validation passed - the same boundaries the status protocol already recognizes), it writes its state down durably, then compacts itself with explicit preservation instructions.
    It never compacts mid-validation-run or while holding a gate open. Firstmate still never injects /compact into a worker from outside - it cannot see whether a worker is mid-write, mid-gate, or holding pipeline ownership, so the threshold stays the worker's own to act on.
  • Intake discipline (new rule 9): read with offset/limit rather than whole files, don't re-read an unchanged file, keep browser captures and tool output targeted.

Also strengthens the existing "Use gh-axi for GitHub operations and chrome-devtools-axi for browser operations" rule into a stated cost rule, since it was measurably ignored: a previous fleet worker drove browser work through the MCP browser path instead of chrome-devtools-axi and burned 662,300 tokens doing it - the single largest context consumer measured in that run.

Why the evidence pointed this way

A live crewmate (Sonnet 5, a long multi-phase build) was measured mid-task at 61% context, not in distress, with the runtime's own compaction buffer already reserved. But its cumulative per-tool token costs (662.3k for browser batching, 406k for file reads) exceeded the live context window, meaning that material was paid for, compacted away, and in several cases read again. Intake cost, not conversation sprawl, was the dominant cost.

A separate /usage reading on the captain's account showed context is billed per turn, not once: 76% of usage was at >150k context, and a worker sitting at high context pays a multiple of that cost on every single turn for as long as it runs.

External threshold-triggered compaction was considered and rejected

An earlier draft omitted a specific token number, reasoning that a number invites compacting on a schedule rather than at a safe moment. That's addressed here by requiring both the ~150k condition and the phase-boundary condition together - one names when it's overdue, the other says when it's safe to act.

Separately, firstmate itself never injects /compact into a worker: firstmate cannot see whether a worker is mid-file-write, mid-validation-gate, or holding pipeline ownership, so an externally triggered compaction risks landing mid-thought. Only the worker knows where its own phase boundaries are, so compaction stays worker-owned rather than becoming external machinery - consistent with AGENTS.md section 7's bar that machinery needs a demonstrated blocker, and no such blocker exists here since the runtime's own compaction already works.

Scope

Only the generated brief text changed - no new script logic, flags, configuration, or
context-inspecting machinery. The worktree-isolation assertion, status protocol, paused/blocked distinction, no-mistakes delivery contract, and ask-user escalation rule are untouched. The secondmate charter scaffold is deliberately untouched too: it's a persistent home, not a short-lived task worker with phase boundaries to compact at. AGENTS.md is untouched (owned by a separate task).

Test plan

  • bash -n bin/fm-brief.sh syntax check
  • bin/fm-lint.sh bin/fm-brief.sh (ShellCheck 0.11.0, pinned) clean
  • Generated all six scaffold variants (no-mistakes, direct-PR, local-only, --scout,
    --herdr-lab, --secondmate) into a temp FM_HOME - all generate without error, and the new guidance reads naturally in place in the ship and scout output
  • Validated end-to-end through the no-mistakes pipeline (review/test/document/lint, zero findings)

A live worker was measured mid-task with cumulative tool costs (browser
captures, file reads) exceeding the live context window, meaning that
material was paid for, compacted away, and in several cases read again.
A captain-side usage reading separately showed context is billed per turn,
so a worker sitting at high context pays that cost repeatedly for as long
as it runs.

Add two short additions to the generated ship and scout briefs: worker-owned
compaction at the next natural phase boundary once past ~150k tokens (never
externally injected, since firstmate cannot see whether a worker is
mid-file-write or holding a gate open), and intake discipline (read with
offset/limit, don't re-read unchanged files, keep captures targeted).
Also strengthen the existing gh-axi/chrome-devtools-axi rule with the
measured cost of a worker that skipped it and drove browser work through
the MCP path instead, burning 662k tokens.

External threshold-triggered compaction (firstmate polling and injecting
/compact into workers) was considered and rejected: firstmate cannot see a
worker's phase boundaries, and no demonstrated blocker justifies that
machinery over the worker owning its own compaction.
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