Skip to content

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

docs: add budget-negotiator skill discoverability to docs (#428) (#436)

Muhammad Zeshan Malik919d6d5ec9b4
diff --git a/docs/QUICKSTART.md b/docs/QUICKSTART.md
index 5ba0e25..76f636c 100644
--- a/docs/QUICKSTART.md
+++ b/docs/QUICKSTART.md
@@ -74,6 +74,13 @@ npx @cobusgreyling/loop context --check --ledger loop-ledger.json
Exit `0` = continue · `2` = escalate to a human. The breaker trips on max iterations, the same error repeating N× in a row, too many consecutive failures, or a token budget cap. Full API: [tools/loop-context/README.md](../tools/loop-context/README.md).
+#### Token budget negotiation (`budget-negotiator`)
+
+When an L3 autonomous loop reaches ≥90% of its daily token cap in `loop-budget.md` with critical `High Priority` items remaining, it can use the [`budget-negotiator`](../skills/budget-negotiator/SKILL.md) skill to request an extension instead of an abrupt hard stop.
+
+- **Negotiation vs Hard Exit:** Standard `loop-budget` exits immediately when over cap. `budget-negotiator` calculates current ROI, drafts a structured budget bump request (`+20%` or max `+50k` tokens, once per day), and appends it to `STATE.md` under `[BUDGET NEGOTIATION]`.
+- **Human Gate Safety:** Agents are **strictly forbidden** from self-raising token caps in `loop-budget.md`. A human maintainer must explicitly approve the request by editing `loop-budget.md` before the loop can resume.
+
## 4. Audit readiness (30 seconds)
```bash
diff --git a/docs/safety.md b/docs/safety.md
index bbe5de9..e98d5ec 100644
--- a/docs/safety.md
+++ b/docs/safety.md
@@ -67,6 +67,7 @@ Always require human for:
- Dependency upgrades (supply chain risk)
- Changes touching >N files (suggest N=10)
- Third attempt failed on same item
+- Token budget extension requests: L3 loops using [`budget-negotiator`](../skills/budget-negotiator/SKILL.md) to request extra token budget when nearing daily caps. Agents **cannot** self-raise caps in `loop-budget.md` — a human must explicitly approve and edit `loop-budget.md`.
## Secrets in Prompts & Logs