git:20260514.1a5ac90 to git:20260831.ca20117

82 added, 156 removed. Audit A to A.

---

name: agent-context-budget

- description: Use when multi-agent work risks context overflow, memory growth, noisy logs, oversized handoffs, cross-session continuation, or parallel Codex and Gemini execution.

+ description: 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.

---

# agent-context-budget

- Context governor for multi-agent rounds. The core rule is simple:

- keep `.coord/` as the canonical state, pass agents compact packets,

- and never paste raw logs or unbounded memory into the main session.

- ## When to Use

- Use this before or during:

- - Large Codex + Gemini + Claude runs.

- - Cross-session resumes where the prior conversation is too large.

- - Any round with more than two delegate tasks.

- - Any workflow where `.coord/memory.yml`, `.ai/*_log_*.txt`, or agent

- summaries are starting to dominate the prompt.

- Not for small one-agent edits. Use the direct delegate skill instead.

- ## Default Policy

+ Prepare bounded context for a task without inventing a second budget source.

+ Numeric limits come from the policy referenced by the current TaskCheckpoint.

+ The public contract and commands are documented in

+ ../../docs/public-harness-contract.md.

- If `.coord/plan.yml` lacks `context_policy`, add this block:

+ ## Use this skill for

- ```yaml

- context_policy:

- main_session_token_budget: 3000

- task_packet_token_budget: 6000

- result_summary_word_budget: 250

- memory_digest_token_budget: 1200

- log_tail_lines_on_error: 50

- raw_log_policy: path-only

- agentmemory: optional

+ - A task that may spawn a delegated executor or reviewer.

+ - A transcript approaching its configured checkpoint boundary.

+ - A fresh session that needs a compact, evidence-linked primer.

+ - Results or logs that are too large for the primary-agent context.

- # W3 — $ cost gate per task (v0.2.2+)

- # Optional. If set, agent-acceptance-gate flags any task whose

- # codex/gemini delegate exceeded the cap. Estimated from token

- # usage × provider price (Anthropic / OpenAI / Google rates).

- # Set per-task in plan.yml tasks[].budget.max_cost_usd to override.

- default_max_cost_usd: 0.50 # default $ ceiling per task

- total_round_max_cost_usd: 5.00 # hard stop for the entire round

- ```

+ Do not use it to summarize away unresolved failures, human decisions, raw

+ scientific evidence, or security findings.

- **Why both `token` and `cost` budgets?** Token gate prevents context

- bloat (a session quality concern). Cost gate prevents runaway delegation

- spend (a financial concern). They're orthogonal: a 2k-token delegate

- call can cost $0.05 (Claude Haiku) or $0.50 (Claude Opus), so token

- count alone doesn't bound dollars.

+ ## Inputs

- Per-task override example:

+ - Goal and task id.

+ - Readable agent policy.

+ - Current TaskCheckpoint.

+ - Evidence and artifact paths needed by the next role.

+ - Optional existing .coord/plan.yml and approved memory events.

- ```yaml

- # in plan.yml

- tasks:

- - id: T1

- agent: codex

- slug: simple-refactor

- budget:

- max_cost_usd: 0.10 # this task is mechanical, cap low

- - id: T2

- agent: codex

- slug: complex-rewrite

- budget:

- max_cost_usd: 2.00 # this task needs frontier model, allow higher

- ```

+ If the policy is configured but unreadable, stop. If the optional

+ agent-collab-harness package is unavailable, do not start an autonomous loop or

+ child spawn; prepare the packet for human-controlled execution instead.

## Workflow

- 1. Read `.coord/plan.yml` and `.coord/memory.yml` if present.

- 2. Write `.coord/context_<NNN>.md` with:

- - round goal and success criteria

- - task graph and write ownership

- - per-agent context packets to include

- - context intentionally excluded

- - optional `agentmemory` recall queries, if available

- 3. Write or refresh `.coord/session_primer.md` with:

- - current decisions

- - open questions

- - active round status

- - recent artifacts by path

- - no raw logs

- 4. Enforce result packets:

- - delegate summaries are <= 250 words

- - changed files are listed by path

- - tests are listed by command + result

- - risks are explicit and short

- 5. If a log is needed, include only the path. Read the last 50 lines

- only when the corresponding `result.json` status is `error`.

- ## Optional agentmemory

- `agentmemory` is a recall cache, not the source of truth.

- - Query it only to enrich `.coord/session_primer.md`.

- - Store only compact memory candidates: accepted decisions, resolved

- open questions, artifact summaries, and final session outcomes.

- - If it is unavailable, continue with `.coord/memory.yml` only.

- - Never use vector recall as acceptance evidence. The acceptance gate

- must read `.coord/plan.yml`, result files, reconciliation, and tests.

- ## Memory Promotion Rules

- Promote only:

- - Decisions with a one-sentence `what` and `why`.

- - Open questions with a blocker and suggested next owner.

- - Artifact pointers with one-line summaries.

- - Agent session outcomes with status and result-summary path.

- Do not promote:

+ 1. Validate policy and checkpoint:

- - Raw logs.

- - Full diffs.

- - Source code.

- - Long analysis.

- - Secrets or credentials.

+ agent-collab policy validate --policy <policy-ref> --json

+ agent-collab checkpoint validate --checkpoint <checkpoint-ref> --json

- ## Output

+ 2. Record current observed metrics in the checkpoint. Do not estimate a lower

+ number to fit the policy.

+ 3. Run policy evaluation before a child spawn:

- End with:

+ agent-collab policy evaluate \

+ --policy <policy-ref> \

+ --checkpoint <checkpoint-ref> \

+ --json

- ```text

- [agent-context-budget]

- Round: <N>

- Policy: .coord/plan.yml context_policy

- Context plan: .coord/context_<NNN>.md

- Session primer: .coord/session_primer.md

- Raw logs: path-only; failure tail max 50 lines

- agentmemory: optional cache, not required

- ```

+ 4. Obey the result:

+ - continue and spawn_allowed=true: create the bounded task packet.

+ - checkpoint: write a checkpoint/primer and return control.

+ - stop or spawn_allowed=false: do not spawn; surface the reasons.

+ 5. Put only decision-relevant material in the packet:

+ - goal and acceptance contract

+ - explicit files and tools in scope

+ - direct evidence references

+ - current recorded human decisions

+ - relevant interfaces or schemas

+ 6. Keep raw logs and complete artifacts at paths. Include a short failure

+ excerpt only when it is needed to diagnose the next action.

+ 7. After a result returns, update observed metrics and evaluate again.

- ## Common Mistakes

+ ## Outputs

- - Pasting full logs into chat. Store the path; read bounded tail only

- on failure.

- - Treating memory as a transcript. Promote decisions, questions,

- artifacts, and outcomes only.

- - Giving Gemini only `.ai/` paths. Inline critical context because

- `.ai/` may be gitignored.

- - Using agentmemory as the gate. Gate with tests and `.coord/`

- artifacts.

+ - .coord/context_<NNN>.md: round-specific packet plan.

+ - .coord/session_primer.md: bounded fresh-session digest.

+ - Updated TaskCheckpoint at the plan's checkpoint_ref.

- ## Subagent review (keep main session lean)

+ These are scratch artifacts by default. Promote a checkpoint snapshot only when

+ the repository explicitly needs it for resume, shipping, or acceptance

+ evidence. Agent boundaries do not imply commits.

- **When**: ≥ 3 task packets exist and you want to verify they stayed

- within the declared `task_packet_token_budget` (default 6000 tokens

- ≈ 24 KB) without re-reading them all in the main session.

+ ## Packet shape

- **Why**: After writing `.coord/context_<NNN>.md` + `session_primer.md`,

- the main session has the policy in context but doesn't need to re-read

- every packet to verify compliance. A subagent can scan all packets

- and return only the over-budget list.

+ # Context packet — <task id>

- **Pattern**:

+ Policy

+ - policy_ref: <path>

+ - policy_hash: <sha256>

+ - checkpoint_ref: <path>

- ```

- Spawn `code-reviewer` subagent:

- - Read .coord/context_<NNN>.md (the declared per-task budgets)

- - Read each .ai/<agent>_task_<NNN>_*.md file referenced in plan.yml

- - For each, count rough tokens (word count × 1.3 as approximation)

- - Return: a single PASS/FAIL line + list of any task slugs > 120%

- of declared budget + suggested compression target

+ Goal

+ <one bounded objective>

- Main session reads only the verdict.

- ```

+ Recorded decisions

+ - <gate / actor / decision / action hash>

- If subagent reports FAIL, regenerate the over-budget packets with

- tighter prompts before invoking delegates.

+ Evidence

+ - <path or stable source locator>

- ## Commit Boundary

+ Scope

+ - may read: <paths>

+ - may write: <paths>

+ - must not touch: <paths>

- Every agent boundary is a commit boundary (see global rule:

- `~/.claude/CLAUDE.md` → "Commit Discipline for Multi-Agent Work").

+ Acceptance

+ - <runnable check>

- **Specific to this skill**: writing `.coord/context_<NNN>.md` and

- `.coord/session_primer.md` are session-setup artifacts — commit

- them as a single round-prep commit so the budget policy used for

- the round is auditable. Pattern:

+ Return contract

+ - concise summary

+ - files changed

+ - tests run

+ - risks and blockers

+ - raw logs by path only

- ```

- git add .coord/context_<NNN>.md .coord/session_primer.md

- git commit -m "context: round <N> budget plan + session primer"

- ```

+ ## Invariants

- The acceptance gate later verifies actual round consumption against

- this committed policy.

+ - Policy values have one machine-readable source.

+ - No silent retry, model switch, context discard, or result truncation.

+ - Missing evidence is reported as missing, not summarized as success.

+ - A decline, cancellation, timeout, error, or null result remains non-success.

+ - Recall systems may suggest context; they do not override repository state or

+ recorded human decisions.