agent-context-budget
Use when an agent task needs bounded context packets, checkpoint-aware compaction, a fresh-session primer, or policy-controlled child results without loading raw logs into the primary session.
SKILL.mdskills/agent-context-budget/SKILL.md
GitHubagent-context-budget
Keep the primary session small while lanes do the reading and writing. There
is no second budget source: native mode follows the host's limits and the caps
written into each brief; harness mode takes every number from the policy
referenced by the current TaskCheckpoint. The "roughly 2 KB" in the
description says when to use this skill; it is not a limit.
Do not use this skill to summarize away unresolved failures, human decisions, raw scientific evidence, or security findings.
Before launching lanes
- Put a return cap in every brief: status, short summary, files changed, checks run, risks, blockers. Long output goes to a file and the lane returns the path. Raw logs, transcripts, and full diffs never come back inline.
- Reading lanes return conclusions with
file:linereferences, not file dumps. Name exact files and line ranges in the brief. - Choose model tiers before launch: a cheap tier for mechanical lanes (pattern edits, scaffolds, bulk reads), a strong tier for review, verdicts, root-cause analysis, security, and governance. Never switch a lane's model silently after a failure.
- Background lanes notify on completion. Keep working and read the result then; do not poll.
- For a follow-up, continue the lane that already holds the context instead of starting a fresh one.
Host mechanics (parallel calls, background runs, per-lane model, return schemas) are in native lanes.
What goes into a brief
Only decision-relevant material:
- goal and acceptance contract;
- explicit files and tools in scope;
- direct evidence paths;
- current recorded human decisions;
- relevant interfaces or schemas.
Keep raw logs and complete artifacts at their paths. Include a short failure excerpt only when the next action needs it.
Before context runs out
Write a fresh-session primer: goal, current state, decisions and who made them, open questions, evidence paths, next step. Keep unresolved failures, human decisions, and security findings visible. Compaction changes the active context, not cumulative usage or failure history.
Durable decisions (formerly agent-shared-memory)
Memory output is proposal-only. Repository state, current evidence, and
recorded human decisions outrank memory; recall systems are optional caches.
Native mode may write a proposal file and nothing else under .coord/;
applying an approved proposal needs the signed approval of harness mode.
- Write a proposal to
.coord/memory-proposals/<proposal-id>.jsonwith an immutableaction(operation, target_ref, summary, evidence_refs). - Supersede, archive, and delete need a specific
target_ref. A proposal with no evidence refs stays pending. - Only an explicit human approval, recorded with actor, decision, timestamp, rationale, affected action hash, and trusted-host HMAC authorization, lets a proposal be applied. Decline, timeout, and revise are not approval.
- Applying appends one new event to
.coord/memory.yml. It never edits an existing event; a resolution, correction, or supersession is a new append-only event. - Never report an unapproved proposal as a canonical decision. Delegated executors never receive the signing key.
Full schema and apply rules: references/coord_memory_schema.md.
Harness mode
Applies when AGENT_COLLAB_POLICY is configured, or a round spans sessions or
tools, runs unattended, or must resume.
Validate:
agent-collab policy validate --policy <policy-ref> --json agent-collab checkpoint validate --checkpoint <checkpoint-ref> --jsonRecord the observed metrics in the checkpoint. Never estimate a lower number to fit the policy.
Before each child spawn and after each returned result, run:
agent-collab policy evaluate \ --policy <policy-ref> \ --checkpoint <checkpoint-ref> \ --jsonObey the decision:
continuewithspawn_allowed=true: build the bounded packet.checkpoint: write the checkpoint and primer. A v2 slice with auto_continue advances atomically under the same goal; v1 returns control. For a v2 action-scopecontext_compaction_required, do local context maintenance without asking for renewed approval: keep full artifacts, acceptance evidence, failures, and authorization; build a smaller linked packet or use native compaction; record measured sizes; re-evaluate. Do not spawn or advance a slice while this gate is pending.stoporspawn_allowed=false: do not spawn. Respect the v2 scope; an exhausted action still allows safe primary-agent diagnosis.
A configured but unreadable policy stops the run. If the harness package is unavailable, do not start an autonomous loop; prepare packets for human-controlled execution instead.
Multi-cycle loop rules (retry counting, failure identity, no-progress cycles) are in references/harness-loop.md.
Outputs (scratch by default): .coord/context_<NNN>.md (shape in
references/harness-loop.md),
.coord/session_primer.md, and the updated checkpoint. Promote a checkpoint
snapshot only when the repository needs it for resume, shipping, or
acceptance evidence. Agent boundaries do not imply commits.
Invariants
- Policy values have one machine-readable source; the stricter of the policy and the host's native limit wins.
- Reserve capacity for required independent review.
- No silent retry, model switch, context discard, or result truncation. A capped return that points to the full output is not truncation.
- Missing evidence is reported as missing. A decline, cancellation, timeout,
error, or
nullresult remains non-success. - Recall systems may suggest context; they never override repository state or recorded human decisions.