---
name: goal-quench
description: >-
  Wraps /goal with a tiered safety + orchestration ladder. core (default): a token budget gate (pre-run estimate), mid-run budget thresholds, and an automatic post-run quality verification via pipeline-conductor — closing /goal's two gaps (Haiku evaluates completion, pipeline-conductor evaluates correctness). pro: adds context-doctor token reduction and agent-composer goal decomposition. max: adds plugin-recommender capability-gap fill and cross-ecosystem-synergy-detection pre-validation. The Phase-1 budget verdict auto-recommends the mode. Triggered by "goal with quality gate", "safe goal", "goal-quench", "orchestrate this goal", or before running /goal on high-stakes tasks.
user-invocable: true
allowed-tools: ["Read", "Write", "Bash", "Grep"]
model: sonnet
complexity_routing:
  base: sonnet
  escalate_when:
    - pro_mode       # orchestration: context-doctor + agent-composer decomposition
    - max_mode       # + external discovery: plugin-recommender + synergy pre-validation
  high: opus
  # NOTE: CC switches models per-turn by task weight, not per-skill invocation.
  # With `/model opusplan`: Opus activates on plan-mode turns (reasoning, decomposition);
  # Sonnet handles execution turns (tool calls, edits). Both appear in session jsonl.
  # Without opusplan: all turns use the session model regardless of mode.
---

# goal-quench — /goal with Token Budget + Quality Gate

`/goal` runs until Haiku says "done" — but Haiku only checks completion, not quality. Without a budget ceiling, sessions can exhaust tokens silently. goal-quench adds three things that /goal currently lacks:

1. **Pre-run**: token-budget-gate estimate — know the cost before committing
2. **Mid-run**: budget threshold awareness — signal before exhaustion (instructional; not mechanically enforced)
3. **Post-run**: pipeline-conductor — verify quality before accepting "done"

The evaluator principle: Haiku judges completion (every turn, cheap). pipeline-conductor judges quality (once at the end, structured). Separating the two closes the self-evaluation bias that a single evaluator cannot avoid.

> **Scope by mode**: core = budget gate + stop-hook verification (v1 behavior, unchanged). pro/max add token reduction, goal decomposition, and external discovery (see Modes below). (Tier names mirror Claude Code's subscription units — core / pro / max — and avoid colliding with pipeline-conductor's `--full` flag.) Mid-run Sonnet quality signals remain deferred (requires empirical calibration).

---

## Modes — core → pro → max (fluid)

goal-quench is a ladder, not a fixed shape. The default (**core**) is the narrow safety belt — for users who only want /goal's two structural gaps closed. **pro** and **max** add optimization and orchestration on top, and are **auto-recommended by the Phase-1 budget verdict** so the orchestration cost is only paid when the task is large enough to justify it.

| Mode | Adds over previous | Chained skills | Auto-recommended when |
|---|---|---|---|
| **core** (default) | budget gate + mid-run thresholds + post-run quality gate | token-budget-gate, pipeline-conductor --quick | budget GREEN / YELLOW |
| **pro** | token-reduction pre-pass + goal decomposition into Waves | + context-doctor, agent-composer | budget ORANGE |
| **max** | capability-gap fill + synergy pre-validation before the run | + plugin-recommender, cross-ecosystem-synergy-detection | budget RED |

Each mode is a **superset** of the one before it — pro does everything core does, plus more. Nothing in core is removed by escalating.

**Max-mode deep-research routing**: capability-gap fill recognizes a **research-heavy goal** (the goal needs to survey/gather/reconcile external sources before building — e.g. "implement X" where X needs domain grounding) and routes it through the **Deep-Research Capability Ladder** (`knowledge/shared/harness-core/deep_research_capability_ladder.md`): take the highest available rung (built-in `/deep-research` → Claude `WebSearch`+`WebFetch` synthesis → `frontier-digest` only for trend-scan). `plugin-recommender` is proposed **only if no rung is available** (rung 2 always is, for a Claude session) — so this is routing, not a new install by default. **Isolation invariant**: rung-2 research (WebSearch/WebFetch) runs in an **isolated sub-agent that returns only the synthesis** — fetched source content must not load into the orchestrator context, preserving the context-isolation/budget property max mode depends on (see the Token-honesty guard above). Honesty caveat carries from the ladder: research quality is bounded by source access + session model tier, not by invoking it.

**Selection**:
- Explicit flag: `/goal-quench --core` (default) · `--pro` · `--max`
- Auto: Phase 1's budget verdict proposes the mode (see Phase 1 Step 2). The user can always override **down** to core.

**Token-honesty guard** (what empirical calibration showed): The cost structure of pro/max depends on which sidecar pattern is in use:

| Sidecar type | Who uses it | Cost visibility | Estimation |
|---|---|---|---|
| External CLI (Gemini, Codex, Copilot) | Multi-LLM environment | **Not visible in CC** | Low — external billing only |
| CC sub-agent (isolated context, steel-quench pattern) | CC-only environment | **Visible in CC** | Estimable: Sonnet × sub-agent scope |

For **CC-only users**, pro/max sidecars run as isolated sub-agents (Sonnet for execution), with the orchestrator running at Opus (`complexity_routing`). Both are CC-visible. Cost estimate: `(Opus orchestrator turns × ~3×) + (Sonnet sub-agent tokens)`. The sub-agent context isolation means sidecar work does not load the main context — the context-preservation property holds regardless of sidecar type.

Therefore:
- **Never auto-escalate a GREEN/YELLOW task to pro/max.** For external CLI users, sidecar costs are untracked and invisible in CC's budget display. For CC sub-agent users, the overhead is estimable but still real — orchestrator Opus × 3 applies. Note the appropriate caveat when disclosing cost.
- **Model escalation cost**: With `/model opusplan`, Opus activates on plan-mode turns and Sonnet handles execution turns — both CC-visible in session jsonl under `message.model`. External CLI sidecar fees are additional and invisible to CC; state both when present.
- **RED is no longer a dead-end.** v1 hard-blocked RED ("split manually"). v2 turns RED into the **on-ramp to max** — agent-composer decomposes the over-budget goal into sequential sub-goals automatically.

---

## Triggers

- `/goal-quench`
- "run /goal with a quality gate", "safe goal run", "goal with verification"
- "I want to use /goal but worried about tokens", "goal with budget control"
- "goal-quench", before any long /goal session
- `/goal-quench --pro`, `/goal-quench --max`, "orchestrate this goal", "decompose this goal", "optimize then run this goal"
- "this goal is too big for one run", "find a tool for this goal if FH lacks one" (→ max mode)
- Automatically proposed when user mentions `/goal` on tasks estimated > 15K tokens
- Mode is auto-recommended by the Phase-1 budget verdict (GREEN/YELLOW → core, ORANGE → pro, RED → max)

---

## One-Time Setup (required)

**Claude Code runtime**: merge the Stop-hook snippet from `templates/goal-quench-hook-setup.md` into `.claude/settings.json`, and gitignore the two state files. Recovery flags exist for hook failures: `/goal-quench --verify` (Phase 3 only, manual trigger) and `/goal-quench --recover` (interrupted /goal — promotes `.active` → `.pending`).

**Codex runtime**: do not replace Codex's native goal/session capability with goal-quench state files — use `fh-gate`/`fh-goal` as post-run governance wrappers instead.

> **Detail**: See `SKILL_detail.md §Setup` — CC hook snippet + gitignore lines, hook-failure/interrupted-run recovery commands, Codex runtime commands — read when performing one-time setup or recovery.

---

## Phase 1 — Pre-run Gate

### Step 1. Collect task description

Ask: *"What will you run with /goal? Describe the task and expected scope."* Collect: task description, target files or directories, expected output.

**Pre-flight rule (pro/max only)**: verify required chained skills (context-doctor, agent-composer) are installed before proposing pro/max. If any is missing, **fall back to core and warn**: "Pro/max mode requires `{skill}` — not installed. Running in core mode instead."

> **Detail**: See `SKILL_detail.md §Phase1-Blocks` — pre-flight check bash, token-budget-gate invocation contract, state file format, threshold injection block, hand-off output — read when executing Phase 1 Steps 1–5.

### Step 2. token-budget-gate estimate

Run token-budget-gate against the task description (invocation contract in §Phase1-Blocks). If the skill is not installed, use this fallback estimator and note `budget_source: fallback-heuristic` in `.active`:

```
< 5 files changed, no new architecture  → GREEN  (< 10K)
5–20 files or new module/feature        → YELLOW (10K–30K)
20+ files or cross-system refactor      → ORANGE (30K–60K)
Full-project migration or rewrite       → RED    (> 60K)
```

**Session overhead factor (empirical, N=10, 2026-06-01–06-03)**: the tiers estimate *task* tokens only. Actual full CC session tokens average 4.7× the task estimate (range 1.3×–10.5×) for harness-heavy projects. Multiply task estimate by 4× for FH-density projects to get the expected session total — this informs the mode recommendation, not the go/no-go thresholds.

Map the verdict to a go/no-go decision:

| token-budget-gate verdict | goal-quench action |
|---|---|
| GREEN (< 10K) | Proceed without comment |
| YELLOW (10K–30K) | Proceed — note estimated cost, suggest /goal scope if possible |
| ORANGE (30K–60K) | Propose **pro mode** as the cheaper path: "This is expensive. Run as a single /goal, or let pro mode optimize (context-doctor) + decompose (agent-composer) it?" Proceed in core only if the user declines orchestration. |
| RED (> 60K) | Propose **max mode** instead of a hard block: "Too big for one /goal run. Route through max mode — agent-composer decomposes into sequential sub-goals, plugin-recommender fills any capability gaps." Hard-block only if the user declines orchestration. |

On RED: **accept max mode** (recommended) → Phase 1.5 decomposition recovery path; **decline orchestration** → goal-quench halts, writes no `.active`, and will not gate or verify a session started without its active file.

### Step 3. Write state file

Create `.claude/goal-quench.active` (format in §Phase1-Blocks). `target_files` is the **verification artifact** — what pipeline-conductor will evaluate in Phase 3. Specify explicitly if known; otherwise write `"inferred from git diff"` and Phase 3 resolves via `git diff {start_commit}..HEAD` (captures interim commits).

> **Control flow (core vs pro/max)**: in **core** mode, proceed directly Step 3 → Step 4. In **pro/max** mode, run **Phase 1.5 (orchestration) here — after Step 3, before Step 4** — then return to Step 4. The `composed_plan` field in `.active` stays `n/a` until Phase 1.5 fills it.

### Step 4. Inject mid-run budget thresholds

Before the user runs /goal, output the threshold instruction block (50% progress note · 70% re-prioritize · 85% stop-and-ask · 95% stop-and-commit — full block in §Phase1-Blocks) so Claude carries it into the /goal session.

### Step 5. Hand off to /goal

Output the ready message (budget verdict + estimated tokens + "run `/goal {your condition}`" — template in §Phase1-Blocks).

---

## Phase 1.5 — Pro / Max Orchestration Layer

> Runs only in `--pro` or `--max` mode (auto-proposed on ORANGE/RED budget, or user-selected). **Skipped entirely in core mode** — core hands off straight to /goal after Step 5.

The ordering is deliberate: optimize the context first (cheapest win), then decompose, then — only if a capability gap remains — reach outside FH.

### Step A — context-doctor (token-reduction pre-pass) · pro + max

Invoke context-doctor on the target scope before /goal runs (generates/updates `.claudeignore`, flags over-read files, recommends `/clear` timing). **Re-estimate** the budget after the pre-pass. If the verdict drops (e.g., ORANGE → YELLOW), offer to step back down to core (see Simplification Guards — post-optimization step-down).

### Step B — agent-composer (goal decomposition) · pro + max

Hand the task description to agent-composer in compose-only mode → Wave plan with capability-fit scoring (agent-composer Step 0.2). For RED-origin runs this decomposition is the recovery path v1 lacked.

**Sub-goal execution (user-driven, not automatic)**: `/goal` is user-invoked — goal-quench cannot programmatically loop over sub-goals. Write the plan to `.claude/goal-quench.queue` (format in §Queue-Format) and instruct the user to invoke `/goal-quench` once per sub-goal. Each invocation pops the first `remaining` item, runs it as an independent core-mode run, then moves it to `completed`. When `remaining` is empty, delete the queue file. (Parallel sub-goal execution is deferred — sequential is the v2 contract.)

goal-quench does **not** re-implement agent-composer's gates — its destructive-action gate (Step 2.7) and per-wave fan-out cap apply as-is.

> **Detail**: See `SKILL_detail.md §Queue-Format` — queue file format, plan-ready output text, sidecar `.active` fields — read when writing the queue (Step B) or the sidecar fields (Step D).

### Step C — plugin-recommender + synergy pre-validation · max only

Triggered only when agent-composer Step 0.2 reports a capability **GAP** (`fit_score < 0.5` on a required-weight sub-task):
1. `plugin-recommender` searches FH + Codex + Claude Code marketplaces for a fitting skill/agent.
2. For each candidate, `cross-ecosystem-synergy-detection` pre-validates fit + overlap **before anything is installed**.
3. User decides: install / skip / general-purpose fallback (agent-composer's degraded-composition rule applies — `⚠️ degraded: [role]`).

max mode never installs anything silently — discovery and synergy-check are surfaced for approval first.

### Step D — scope-driven sidecar configuration · pro + max

Runs after Step C (or after Step B if no capability gap). Selects an adversarial sidecar based on the task's quality-risk profile — distinct from Step C's capability-gap sidecar. Step D's sidecar addresses **blind-spot risk**: the generator and reviewer sharing the same reasoning distribution.

> **Availability resolution**: "if available" below is decided by the canonical Tier 1→2→3 recipe in `knowledge/shared/harness-core/multi_model_sidecar_strategy.md §Sidecar Engine Resolution Protocol` — discovery is automatic, invocation stays value-gated. Tier 3 (Claude sub-agent) guarantees this step never hard-fails even with zero external CLIs/keys.

**Scope → sidecar routing table**:

| Task scope signal | Sidecar | Invocation point |
|---|---|---|
| Code quality review / new SKILL.md / governance gate change | `steel-quench` cross-provider challenger (Gemini sidecar if available; Tier 3 Claude sub-agent fallback) | Post-/goal, before pipeline-conductor |
| Architecture design / cross-project dependency | `agent-composer` multi-model panel (if external CLIs available; otherwise single-Claude sub-agent) | Parallel to /goal as separate Agent |
| External publication / marketplace-gate / skill release | `sim-conductor` + `steel-quench` Wave 5 | Post-/goal quality gate |
| No signal match (default) | None — pipeline-conductor handles quality alone | — |

Write the resolved `sidecar:` + `sidecar_rationale:` fields to `.active` (format in §Queue-Format). Output one line: *"Sidecar: {config} — {rationale}"*. Do not ask for confirmation; the user may override via `/goal-quench --sidecar none`.

**Dispatch-failure triage (saturation disguise)**: a sidecar dispatch failing with a 1M-context / usage-credits error late in a long run may be reporting *session context saturation*, not a billing gate (measured 2026-06-12). Triage order: compact — flushing handoff state to disk first — → retry the dispatch once → only then take the headless `claude -p` fallback (credit-pool cost) or an inline at-floor pass.

### Hand-off

After orchestration, **update** (not re-create) `.claude/goal-quench.active` — add `mode:` and `composed_plan:` lines alongside existing budget fields. Re-creating the file loses the `start_commit` field. Then proceed to threshold injection (Phase 1 Step 4) and hand off to /goal. Phase 3 verification runs as in core — `pipeline-conductor --quick` for pro, `--full` for max.

---

## Phase 2 — Mid-run (during /goal execution)

goal-quench does not directly control /goal execution. The budget thresholds injected in Phase 1 are instructions Claude follows during the /goal session: track approximate consumption against the estimate, execute the corresponding action at each threshold (50/70/85/95%), self-enforced without waiting for goal-quench.

**Threshold enforcement caveat**: Claude cannot reliably read its own real-time token consumption — thresholds are instructional approximations, not mechanically enforced. For hard enforcement, see the Anthropic feature request (--budget flag).

**Queue mode (per-sub-goal threshold scope)**: each `/goal-quench` invocation from the queue is an independent core-mode run — thresholds are re-injected fresh against that sub-goal's own Phase 1 estimate, not inherited from the outer pro/max run.

**What goal-quench cannot do in v1** (requires native Anthropic support): hard token ceiling (--budget), auto-checkpoint commits (--checkpoint), mid-run Sonnet quality signal. These gaps are the basis for the feature request (`knowledge/shared/harness-core/goal_quench_anthropic_issue.md`).

---

## Phase 3 — Post-run Verification

### Claude Code path

When /goal stops, the Stop hook: detects `.active` → copies to `.pending` → removes `.active` → prints the verification-pending notice.

On the next Claude response, check `.claude/goal-quench.pending` **with a freshness guard** (bash in §Phase3-Bash):
- **Fresh (< 4 hours)**: **automatically run pipeline-conductor** before responding to any other request — `--quick` for core/pro, `--full` for max (the `mode:` field in `.pending` selects). Not optional — pending verification takes priority.
- **Stale (> 4 hours)**: warn — "A stale goal-quench.pending exists from {timestamp}. Run `/goal-quench --verify` to re-evaluate, or delete it to clear." Do not auto-trigger verification on stale state.

### Codex path

After the Codex goal completes, run `fh-gate` on changed files (commands in §Phase3-Bash). Treat `BLOCKED`/`ESCALATE` the same as the Claude path.

> **Detail**: See `SKILL_detail.md §Phase3-Bash` — freshness guard bash, verification-artifact resolution bash, Codex gate commands — read when executing Phase 3.

### Verification flow

Resolve the verification artifact from `.pending` — explicit `target_files`, or `git diff {start_commit}..HEAD` when inferred (bash in §Phase3-Bash; empty target = hard error). Run pipeline-conductor on the artifact and gate on the result:

| pipeline-conductor verdict | goal-quench action | Delete `.pending`? |
|---|---|---|
| `CLEAN (--quick)` | Output: "Quality gate passed (--quick). Safe for local iteration and internal commits. Run pipeline-conductor --full before external release or PR." Log tokens. | **Yes — immediately** |
| `PENDING` | Proceed with caution. Output pending items. Recommend: "Resolve before any external release." | **Yes — immediately** |
| `BLOCKED` | Block commit. Output blocking items. Ask: "Fix and re-run /goal, or accept partial completion?" | **Only after user acknowledges** |
| `ESCALATE` | Surface to user for decision. Do not auto-delete — preserve state until user explicitly decides. | **Only after user decision** |

**Deletion rule**: On BLOCKED or ESCALATE, `.pending` must survive until the user makes an explicit decision — deleting before that loses the recovery anchor.

**Deadlock prevention**: While `.pending` exists (BLOCKED/ESCALATE), the next-turn verification check runs ONCE per turn only. After the first verification output, suppress further auto-trigger until the user explicitly acts. If the user starts a new `/goal-quench` run while `.pending` exists, warn and do not silently overwrite with a new `.active`.

Record actual token usage in `tracks/_meta/goal_quench_{YYYY-MM-DD}.md` for calibration (regardless of verdict).

### Step 3-c — Sidecar verdict gate (pro + max, when sidecar ≠ none)

After pipeline-conductor completes, read `sidecar:` from `.pending`. If non-none, gate on the sidecar's verdict before advancing to Done When:

| Sidecar | Wait for | Failure action |
|---|---|---|
| `steel-quench-crossprovider` | Wave 2 convergence: PASS or CONDITIONAL_PASS | FAIL → reopen Phase 2, surface blocking findings to user |
| `agent-composer-panel` | Panel findings file written + incorporated into pipeline-conductor context | Not yet written → re-run pipeline-conductor with panel findings |
| `sim-conductor` + `steel-quench-w5` | Both: sim-conductor Area A PASS **and** steel-quench W5 convergence PASS | Either FAIL → block Done When; surface failing verdict |

This gate is **blocking** — Done When cannot be reached until the sidecar verdict is resolved. Record `sidecar_findings_count` in the calibration record before closing.

---

## Calibration Record

After each goal-quench run, append a calibration entry to `tracks/_meta/goal_quench_{YYYY-MM-DD}.md`. Baseline (N=10, 2026-06-01–06-03, Sonnet): mean actual/estimate ratio 4.7× — systematic underestimation from session overhead. Target: 10 prospective runs per mode before treating mode comparison as reliable.

> **Detail**: See `SKILL_detail.md §Calibration-Record` — full YAML entry format, actual_tokens collection script, calibration baseline notes — read when appending the post-run record.

---

## Simplification Guards

- Do not activate goal-quench for exploratory or single-turn tasks — only for /goal sessions.
- If the user runs /goal without going through goal-quench setup, propose retroactively: "Run /goal-quench --verify to quality-check the output."
- `--verify` mode: skip Phase 1+2, go directly to Phase 3 verification using current session scope.
- **core is the default and the floor** — never auto-escalate a GREEN/YELLOW task to pro/max. Sidecar CLI costs (external, untracked in CC) apply in pro/max — auto-escalation requires ORANGE/RED budget or explicit user flag.
- **pro/max are supersets of core, not replacements** — a user who wants only the v1 safety belt stays in core and sees no orchestration.
- **Post-optimization step-down**: if a pro/max run's re-estimated budget drops to GREEN/YELLOW after context-doctor trims (Phase 1.5 Step A), offer to drop back to core — don't run orchestration the trimmed scope no longer needs.
- Phase 1.5 does not re-implement the gates of the skills it chains (agent-composer's destructive/fan-out gates, plugin-recommender's install approval) — it defers to them.

---

## Chains

- `token-budget-gate` — Phase 1 cost estimation (all modes)
- `context-doctor` — Phase 1.5 Step A token-reduction pre-pass (pro + max)
- `agent-composer` — Phase 1.5 Step B goal decomposition into Waves (pro + max)
- `plugin-recommender` — Phase 1.5 Step C capability-gap fill (max only, GAP-triggered)
- `cross-ecosystem-synergy-detection` — Phase 1.5 Step C pre-validation of discovered candidates (max only)
- `pipeline-conductor` — Phase 3 quality gate (`--quick` for core/pro, `--full` for max; called by Stop hook)
- `field-harvest` — capture calibration data as reusable pattern after 10 runs

---

## Done When

```
Phase 1: token-budget-gate verdict output + mode resolved (core default, or pro/max via budget verdict / explicit flag)
+ .claude/goal-quench.active written (with mode: field) + thresholds injected
+ If pro/max: Phase 1.5 ran — context-doctor pre-pass + agent-composer plan;
  max additionally: GAP-triggered plugin-recommender + cross-ecosystem-synergy-detection pre-validation
+ Phase 3 (on next response after /goal): .pending file detected + pipeline-conductor run
  (--quick for core/pro, --full for max)
+ Verification verdict output (CLEAN/PENDING/BLOCKED/ESCALATE)
+ If sidecar invoked (pro/max Step D): Step 3-c sidecar verdict resolved (PASS/CONDITIONAL_PASS) before closing
+ .pending file deleted + calibration record appended
```

Verdict: PASS (CLEAN verification) | CONDITIONAL_PASS (PENDING verification) | FAIL (BLOCKED verification) | ESCALATE (user decision required on partial completion)

**Completion-claim discipline (Ralph — no silent partial completion):** a PASS/CONDITIONAL_PASS
verdict must **enumerate, not assert** — (a) **evidence artifact**: the pipeline-conductor verification
verdict + the calibration record path; (b) **failed/skipped checks by name** (which pipeline axes /
sidecars FAILED or were skipped). This list is **not self-asserted** — reconcile it against the resolved
mode's in-scope axis/sidecar set: a list shorter than (in-scope − passed) is incomplete, not PASS (an
empty list is valid only when every in-scope check passed). This is the mechanical anchor that keeps the
clause off a judge-only path; (c) **explicit residual risk beyond what the mode-qualifier already states**
(e.g. an axis that ran but on degraded input). A verdict that omits any of the three is **incomplete, not
PASS**. (Convergent sister evidence: oh-my-claudecode Ralph "refuses silent partial completion"; Hermes
Agent `/goal` per-turn completion judge.)