agent-completion-discipline
Agent Completion Discipline — Commit Before Summary
Section titled “Agent Completion Discipline — Commit Before Summary”Resolves: unity#74 (tail-of-thought stop — agent exits without committing pending work at >150K tokens)
COMMIT BEFORE YOU SUMMARIZE. Any agent that has made edits, written files, or completed implementation work MUST commit + push those changes BEFORE composing any narrative summary, wrap-up, or report.
Order (mandatory): dispatch pending Writes → git add + commit + push → THEN summarize.
Budget checkpoint (MANDATORY for sub-agents) — RELATIVE to the agent’s budget, NEVER a flat token number. Fire at whichever ceiling comes first:
- % of the agent’s model context window — ~75% of a ≤200K window (≈150K); ~55% of a 1M window (≈550K) (tighten the % as the window grows). A flat “150K” is wrong on a large window (fires at ~15%) — derive from the agent’s
model:; check themodel:when authoring/updating it. - ~80% of
maxTurns— tool-heavy work (multi-PR merges, refactors) hits the turn cap before any token cap (theonekit-core#528:maxTurns: 45reached at ~200K tokens). SizemaxTurnsto the task.
On reaching either: (1) git status → commit any changes NOW; (2) dispatch pending Writes; (3) only then resume or summarize.
Read-only investigators — RETURN partial findings, never stop silent
Section titled “Read-only investigators — RETURN partial findings, never stop silent”For a read-only agent whose deliverable IS its returned summary (an Explore/researcher/scout with no files to write or commit), the failure mode is the mirror image of the one above: it reads and reasons up to the budget ceiling, then stops without returning anything — total loss, because there is no committed partial on disk to recover (unity#524).
On reaching the budget checkpoint (same ceilings as above), such an agent MUST compose and RETURN a partial-findings summary instead of stopping silently — structured as: audited X of Y (what was covered); findings so far …; not-yet-read: …. A truncated-but-present summary is recoverable by the orchestrator; a silent stop is not.
The built-in
Exploreagent has no kit-editable body — this rule is the lever, inherited through the orchestrator’s spawn brief. When spawning a read-only investigator for a large surface, state the return-partial-on-budget expectation in the brief.
Anti-pattern
Section titled “Anti-pattern”“Let me check one more thing before committing…” near a budget ceiling is the symptom — interrupt it; commit first, investigate after.
unity#74: 7/8 sub-agent stops reached 168–212K tokens mid-investigation and exited completed without committing (needed finisher agents). theonekit-core#528: a flat threshold mis-fires — ~15% on a 1M opus, and ignores maxTurns.