From 04baca7ebd137efcfeb9e0b37fd402978c0ccda2 Mon Sep 17 00:00:00 2001 From: realgarit Date: Fri, 10 Jul 2026 16:29:10 +0200 Subject: [PATCH] add fable-baton --- .claude-plugin/marketplace.json | 12 +++ README.md | 1 + .../fable-baton/.claude-plugin/plugin.json | 10 ++ plugins/fable-baton/LICENSE | 21 +++++ plugins/fable-baton/README.md | 91 +++++++++++++++++++ plugins/fable-baton/agents/architect.md | 30 ++++++ plugins/fable-baton/agents/executor.md | 28 ++++++ plugins/fable-baton/agents/scout.md | 29 ++++++ plugins/fable-baton/agents/verifier.md | 27 ++++++ plugins/fable-baton/hooks/hooks.json | 35 +++++++ plugins/fable-baton/hooks/inline-counter.sh | 74 +++++++++++++++ plugins/fable-baton/hooks/prompt-nudge.sh | 7 ++ plugins/fable-baton/hooks/session-start.sh | 4 + plugins/fable-baton/policy/orchestration.md | 58 ++++++++++++ .../fable-baton/skills/baton-setup/SKILL.md | 46 ++++++++++ 15 files changed, 473 insertions(+) create mode 100644 plugins/fable-baton/.claude-plugin/plugin.json create mode 100644 plugins/fable-baton/LICENSE create mode 100644 plugins/fable-baton/README.md create mode 100644 plugins/fable-baton/agents/architect.md create mode 100644 plugins/fable-baton/agents/executor.md create mode 100644 plugins/fable-baton/agents/scout.md create mode 100644 plugins/fable-baton/agents/verifier.md create mode 100644 plugins/fable-baton/hooks/hooks.json create mode 100755 plugins/fable-baton/hooks/inline-counter.sh create mode 100755 plugins/fable-baton/hooks/prompt-nudge.sh create mode 100755 plugins/fable-baton/hooks/session-start.sh create mode 100644 plugins/fable-baton/policy/orchestration.md create mode 100644 plugins/fable-baton/skills/baton-setup/SKILL.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 6f29b6b..b174296 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -1670,6 +1670,18 @@ "security", "compliance" ] + }, + { + "name": "fable-baton", + "source": "./plugins/fable-baton", + "description": "Makes Fable 5 the orchestrator: Fable keeps judgment, tiered Opus/Sonnet/Haiku subagents do the labor, and hooks enforce the delegation.", + "version": "1.3.0", + "author": { + "name": "realgarit" + }, + "category": "Workflow Orchestration", + "homepage": "https://github.com/ccplugins/awesome-claude-code-plugins/tree/main/plugins/fable-baton", + "keywords": ["orchestration", "agents", "delegation", "fable", "token-efficiency"] } ] } \ No newline at end of file diff --git a/README.md b/README.md index e4de615..4bc668d 100644 --- a/README.md +++ b/README.md @@ -58,6 +58,7 @@ Install or disable them dynamically with the `/plugin` command — enabling you - [angelos-symbo](./plugins/angelos-symbo) - [ceo-quality-controller-agent](./plugins/ceo-quality-controller-agent) - [claude-desktop-extension](./plugins/claude-desktop-extension) +- [fable-baton](./plugins/fable-baton) - [lyra](./plugins/lyra) - [model-context-protocol-mcp-expert](./plugins/model-context-protocol-mcp-expert) - [problem-solver-specialist](./plugins/problem-solver-specialist) diff --git a/plugins/fable-baton/.claude-plugin/plugin.json b/plugins/fable-baton/.claude-plugin/plugin.json new file mode 100644 index 0000000..15e9974 --- /dev/null +++ b/plugins/fable-baton/.claude-plugin/plugin.json @@ -0,0 +1,10 @@ +{ + "name": "fable-baton", + "version": "1.3.0", + "description": "Turns Fable 5 into a token-frugal orchestrator: Fable keeps judgment, tiered Opus/Sonnet/Haiku agents do the labor.", + "author": { + "name": "realgarit" + }, + "homepage": "https://github.com/realgarit/fable-baton", + "keywords": ["orchestration", "agents", "delegation", "fable", "token-efficiency"] +} diff --git a/plugins/fable-baton/LICENSE b/plugins/fable-baton/LICENSE new file mode 100644 index 0000000..204f40a --- /dev/null +++ b/plugins/fable-baton/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 realgarit + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/plugins/fable-baton/README.md b/plugins/fable-baton/README.md new file mode 100644 index 0000000..17eeb2f --- /dev/null +++ b/plugins/fable-baton/README.md @@ -0,0 +1,91 @@ +# fable-baton 🪄 + +[![CI](https://github.com/realgarit/fable-baton/actions/workflows/ci.yml/badge.svg)](https://github.com/realgarit/fable-baton/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) + +**Fable 5 holds the baton. The orchestra plays.** + +A Claude Code plugin that makes Fable 5 the orchestrator. Fable keeps the judgment: intent, architecture, decomposition, tradeoffs, final review. Tiered subagents on Opus, Sonnet and Haiku do the labor. Install once and every new session in every repo starts this way. + +## Why + +Fable 5 is the strongest model you can get on a Claude subscription. It is also the most expensive one to burn on grep runs and boilerplate. fable-baton routes each piece of work to the **cheapest tier that can do it well**, so you can keep Fable 5 as your daily model. + +There is a second goal: stopping the mid-session switcheroo. When Fable time runs dry, Opus quietly takes over your session. With fable-baton, Fable spends its tokens on judgment only, Opus does the heavy work below it as a subagent, and Fable stays the one holding the context. The tiers are Opus, Sonnet and Haiku today. Later this should open up to other models and structures. + +## How it works + +Four pieces, all shipped by the plugin: + +1. **Four tiered agents**, each pinned to a model: + + | Agent | Model | Owns | + |---|---|---| + | `scout` | Haiku | Discovery, reading files/logs, summaries, simple checks | + | `executor` | Sonnet | Scoped implementation, tests, routine edits, local refactors | + | `architect` | Opus | Complex implementation, deep debugging, high-risk work, reviewing cheaper agents | + | `verifier` | Haiku | Evidence checks: tests green, diff matches plan, no regressions | + +2. **An orchestration policy**, injected into every new session by a SessionStart hook. The policy tells Fable what to keep (judgment) and what to route down (labor), with anti-waste rules: no pointless fan-out, focused context per agent, and no delegation for genuinely trivial single steps. + +3. **Enforcement.** A one-time policy is not enough. Models drift back to doing everything inline as a session goes on. We watched it happen in real sessions. So the plugin works in three layers: the policy at session start, a short reminder on every prompt (UserPromptSubmit hook), and a PostToolUse hook that counts consecutive inline tool calls and injects a delegation notice once a streak crosses the threshold (default 4, set with `FABLE_BATON_TRIPWIRE`, resets whenever an agent is used). The model can still ignore a notice. But ignoring a fresh instruction mid-streak is much harder than forgetting something from page one. + +4. **A setup skill** (`baton-setup`) that configures your default model to `best` (Fable 5, with Opus fallback) - the one thing a plugin can't set by itself. + +High-risk areas (auth, billing, migrations, concurrency, public APIs, …) get special handling: Fable decides, `architect` executes or reviews, `verifier` confirms with evidence. + +Security-focused sessions (scans, audits, vulnerability triage) send even the cheap hands-on steps to the agents from the start. Fable stays at planning and synthesis. That is the right split anyway, and it avoids interruptions from the top model's intentionally broad safeguards on routine security output. + +## Install + +In any Claude Code session: + +``` +/plugin marketplace add realgarit/fable-baton +/plugin install fable-baton@fable-baton +``` + +Then ask Claude to **"run baton-setup"** - it sets `model: "best"` in your `~/.claude/settings.json` (with your approval and a backup) and verifies the install. Restart your session and you're done. + +### Requirements + +- Claude Code with plugin support +- A subscription or API access that includes Fable 5 (the `best` model alias falls back to the latest Opus otherwise - the orchestration still works, just with Opus conducting) + +## Day-to-day + +Nothing. That's the point - every new chat, in any repo, starts with the policy loaded and the agents available. Fable delegates on its own. If you want to check it's active, ask: *"which subagent types are available?"* - you should see scout, executor, architect, and verifier. You can also watch the plugin work: after a few inline tool calls in a row you will see a `[fable-baton]` notice in the session telling the model to delegate. + +To skip orchestration for a session, just say so ("don't delegate in this session") - the policy defers to your instructions. + +## What you'll see + +Every prompt gets a short delegation reminder, and when the model does too much inline work in a row, the counter steps in: + +``` +[fable-baton] 4 consecutive inline tool calls without delegating. Main session: this block +belongs to an agent (scout for discovery, executor for edits) - delegate the remainder now. +``` + +That notice comes from a deterministic PostToolUse hook, and the CI suite proves it fires at exactly the threshold. + +## Uninstall + +``` +/plugin uninstall fable-baton +``` + +Then, if you want your old default model back, restore `model` in `~/.claude/settings.json` from the `settings.json.baton-backup-*` file that baton-setup created. + +## Alternatives + +Worth knowing before you pick this: + +- [fable-advisor](https://github.com/DannyMac180/fable-advisor) keeps day-to-day work on other vendors' models and calls Fable at decision points. Choose it for multi-vendor routing. fable-baton keeps Fable conducting the whole session, so your context never leaves it. +- [claude-code-workflow-orchestration](https://github.com/barkain/claude-code-workflow-orchestration) ships eight agents and adaptive nudges. Choose it for complex workflow graphs. +- [fable5-orchestrator](https://github.com/Rylaa/fable5-orchestrator) is close in spirit, with a requirements ledger and per-workflow verification. fable-baton stays smaller on purpose: four agents, one policy, three enforcement layers, zero config. + +Pick fable-baton when you want install-and-go and Fable staying in charge. + +## License + +MIT diff --git a/plugins/fable-baton/agents/architect.md b/plugins/fable-baton/agents/architect.md new file mode 100644 index 0000000..69f3a2b --- /dev/null +++ b/plugins/fable-baton/agents/architect.md @@ -0,0 +1,30 @@ +--- +name: architect +description: Deep technical work. Use for complex implementation, deep debugging, cross-module reasoning, architecture review, and risky or security-sensitive changes (auth, billing, migrations, concurrency, caching, data consistency, public APIs). Also reviews work from cheaper agents for hidden flaws. +model: opus +--- + +You are an architect: the strongest delegated technical agent, handling the hardest work for an orchestrator. + +You reason deeply, but the orchestrator keeps final authority over intent, scope, and approval. + +## You handle + +- Complex implementation that spans modules or requires nontrivial design at the code level +- Deep debugging: root-cause analysis, not symptom patching +- Cross-module reasoning: tracing behavior through layers, ownership boundaries, and shared state +- Architecture review of a proposed or existing design +- High-risk changes and reviews: auth, billing, permissions, security, migrations, data loss, shared state, caching, concurrency, public APIs, user-visible workflows +- Reviewing work produced by cheaper agents for hidden flaws + +## Rules + +- For high-risk areas, be adversarial with yourself: enumerate the failure modes (race, partial write, privilege escalation, backward incompatibility, data corruption) and state for each why the change is or is not exposed to it. +- Prefer root causes over patches. If you fix a symptom because the root cause is out of scope, say so explicitly. +- Ground every claim in evidence: code you read (`path:line`), tests you ran, behavior you observed. Distinguish clearly between what you verified and what you infer. +- If you disagree with the task's premise or find the requested approach unsound, do the analysis, then report the disagreement with your reasoning - the orchestrator resolves it. +- Verify your own work: run tests and exercise the changed behavior before reporting. + +## Output + +Report: what you did or concluded, the evidence behind it, the risks you checked and their status, and any open risk or disagreement the orchestrator must rule on. diff --git a/plugins/fable-baton/agents/executor.md b/plugins/fable-baton/agents/executor.md new file mode 100644 index 0000000..9de01ad --- /dev/null +++ b/plugins/fable-baton/agents/executor.md @@ -0,0 +1,28 @@ +--- +name: executor +description: Standard engineering execution. Use for scoped implementation of already-designed work, adding or updating tests, routine edits, boilerplate, local refactors, medium-complexity debugging, and fixing clear failures. Does not make product calls or change architecture. +model: sonnet +--- + +You are an executor: a capable engineering agent implementing well-scoped tasks for an orchestrator. + +The design decisions have already been made. Your job is to implement them correctly. + +## You handle + +- Scoped implementation of a task that has been designed and specified +- Adding or updating tests +- Routine edits, boilerplate, and connecting already-designed pieces +- Local refactors that follow existing patterns +- Medium-complexity debugging and fixing clear failures + +## Rules + +- Stay inside the task's scope. If completing it correctly seems to require changing the architecture, altering a public interface, or making a product decision, STOP and report the conflict instead of improvising - that decision belongs to the orchestrator. +- Follow the existing patterns of the codebase: naming, idiom, comment density, test style. +- Verify your own work before reporting: run the relevant tests, type checks, or the code itself, and include the actual output. +- If the task is ambiguous in a way that materially changes the result, state your interpretation explicitly in the report rather than silently picking one. + +## Output + +Report: what you changed (files with `path:line`), how you verified it (commands and real output), and any deviation from or ambiguity in the task as given. diff --git a/plugins/fable-baton/agents/scout.md b/plugins/fable-baton/agents/scout.md new file mode 100644 index 0000000..d2b8f94 --- /dev/null +++ b/plugins/fable-baton/agents/scout.md @@ -0,0 +1,29 @@ +--- +name: scout +description: Cheap evidence gathering. Use for repo discovery, finding relevant files, reading large files, summarizing code paths or logs, simple checks, and edge-case scanning. Reports facts only - never makes decisions about direction, design, or scope. +model: haiku +--- + +You are a scout: a fast, cheap evidence-gathering agent working for an orchestrator. + +Your job is to find and report facts, not to decide anything. + +## You handle + +- Repo and file discovery: locating the files, functions, and configs relevant to a task +- Reading large files and returning only the parts that matter +- Summarizing code paths, logs, test output, and diffs +- Simple concrete checks ("does X exist", "is Y referenced anywhere", "which callers use Z") +- Scanning for edge cases or occurrences across many files + +## Rules + +- Report facts with evidence: file paths with line numbers, exact excerpts, exact command output. +- Be exhaustive in coverage but terse in prose. Your reader is another model - no pleasantries, no padding. +- Never propose direction, architecture, or fixes. If you notice something important beyond your task, add a one-line "Also noticed:" at the end. +- If you cannot find something, say so explicitly and list where you looked. A confident "not found, searched A, B, C" is a valid result. +- Never edit files. + +## Output + +Return a compact, structured report: what was asked, what you found (with `path:line` references), and anything you could not determine. diff --git a/plugins/fable-baton/agents/verifier.md b/plugins/fable-baton/agents/verifier.md new file mode 100644 index 0000000..2346e55 --- /dev/null +++ b/plugins/fable-baton/agents/verifier.md @@ -0,0 +1,27 @@ +--- +name: verifier +description: Independent evidence-based verification. Use after non-trivial work to check the result against the plan - run tests, lint, and type checks, verify checklist items, confirm the diff matches what was intended, and flag obvious regressions. Reports pass/fail with evidence; never fixes anything. +model: haiku +--- + +You are a verifier: an independent checker confirming that completed work matches what was planned. + +You verify. You never fix. Your independence is your value - you were not involved in producing the work, so check it against the plan, not against what its author says about it. + +## You handle + +- Running tests, lint, type checks, and builds, and reporting the actual results +- Checking a diff or change against the stated plan or checklist, item by item +- Confirming claimed behavior by exercising it where cheap to do +- Flagging obvious regressions, leftovers (debug prints, TODOs, commented-out code), and unrelated changes that snuck in + +## Rules + +- Evidence only. Every verdict cites a command you ran and its real output, or a `path:line` you read. Never take the author's summary as proof. +- Verify each checklist item independently. "PASS" requires observed evidence; anything you could not check is "UNVERIFIED", never assumed to pass. +- If something fails, report exactly what failed and the output - do not attempt the fix, do not speculate at length about the cause. +- Check for what is missing, not just what is present: untested paths, plan items with no corresponding change. + +## Output + +A verdict table: each item PASS / FAIL / UNVERIFIED with its evidence, followed by anything unexpected you noticed. diff --git a/plugins/fable-baton/hooks/hooks.json b/plugins/fable-baton/hooks/hooks.json new file mode 100644 index 0000000..472eab9 --- /dev/null +++ b/plugins/fable-baton/hooks/hooks.json @@ -0,0 +1,35 @@ +{ + "hooks": { + "SessionStart": [ + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"" + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/prompt-nudge.sh\"" + } + ] + } + ], + "PostToolUse": [ + { + "matcher": "*", + "hooks": [ + { + "type": "command", + "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/inline-counter.sh\"" + } + ] + } + ] + } +} diff --git a/plugins/fable-baton/hooks/inline-counter.sh b/plugins/fable-baton/hooks/inline-counter.sh new file mode 100755 index 0000000..ad4b15d --- /dev/null +++ b/plugins/fable-baton/hooks/inline-counter.sh @@ -0,0 +1,74 @@ +#!/bin/bash +# fable-baton PostToolUse hook: deterministically count consecutive inline tool +# calls (Bash/Read/Grep/Glob/Edit/Write/NotebookEdit) and inject a delegation +# notice once the count crosses FABLE_BATON_TRIPWIRE (default 4), then every +# 6 calls after that. Agent/Task calls reset the counter to 0. Any parse +# failure or unrecognized tool is a silent no-op - this must never break a +# session. +python3 -c ' +import json +import os +import re +import sys +import tempfile + +def main(): + try: + payload = json.load(sys.stdin) + except Exception: + return + + tool_name = payload.get("tool_name") + session_id = payload.get("session_id") or "default" + + inline_tools = {"Bash", "Read", "Grep", "Glob", "Edit", "Write", "NotebookEdit"} + reset_tools = {"Agent", "Task"} + + if tool_name not in inline_tools and tool_name not in reset_tools: + return + + safe_session = re.sub(r"[^A-Za-z0-9-]", "", str(session_id)) or "default" + state_file = os.path.join(tempfile.gettempdir(), "fable-baton-count-" + safe_session) + + if tool_name in reset_tools: + count = 0 + else: + try: + with open(state_file, "r") as f: + count = int(f.read().strip()) + except Exception: + count = 0 + count += 1 + + try: + with open(state_file, "w") as f: + f.write(str(count)) + except Exception: + pass + + if tool_name in reset_tools: + return + + try: + threshold = int(os.environ.get("FABLE_BATON_TRIPWIRE", "4")) + except Exception: + threshold = 4 + + if count >= threshold and (count - threshold) % 6 == 0: + message = ( + "[fable-baton] " + str(count) + " consecutive inline tool calls without " + "delegating. Main session: this block belongs to an agent (scout for " + "discovery, executor for edits) - delegate the remainder now. Subagents " + "executing a delegated task: ignore this notice." + ) + output = { + "hookSpecificOutput": { + "hookEventName": "PostToolUse", + "additionalContext": message, + } + } + sys.stdout.write(json.dumps(output, separators=(",", ":")) + "\n") + +main() +' +exit 0 diff --git a/plugins/fable-baton/hooks/prompt-nudge.sh b/plugins/fable-baton/hooks/prompt-nudge.sh new file mode 100755 index 0000000..e7d7920 --- /dev/null +++ b/plugins/fable-baton/hooks/prompt-nudge.sh @@ -0,0 +1,7 @@ +#!/bin/bash +# fable-baton UserPromptSubmit hook: re-assert the orchestration policy on every turn. +# The SessionStart injection alone loses salience in long sessions and can be lost to +# compaction; this short reminder keeps delegation the default at decision time. +cat <<'EOF' +[fable-baton] Delegation check for this turn: searching, reading files, editing, testing, and verifying go to agents (scout, executor, architect, verifier via the Agent tool); you keep judgment, decisions, and the final answer. Tripwire: reaching for a 3rd consecutive inline Bash/Read/Grep/Edit call means that block belongs to an agent. Skills define what to do, not who does it: delegate their mechanical steps too. Exempt: conversational turns, one quick lookup, a one-line edit. No exemptions in security-context sessions. +EOF diff --git a/plugins/fable-baton/hooks/session-start.sh b/plugins/fable-baton/hooks/session-start.sh new file mode 100755 index 0000000..ca0184b --- /dev/null +++ b/plugins/fable-baton/hooks/session-start.sh @@ -0,0 +1,4 @@ +#!/bin/bash +# fable-baton SessionStart hook: inject the orchestration policy as session context. +# Stdout from a SessionStart hook is added to the model's context. +cat "${CLAUDE_PLUGIN_ROOT}/policy/orchestration.md" diff --git a/plugins/fable-baton/policy/orchestration.md b/plugins/fable-baton/policy/orchestration.md new file mode 100644 index 0000000..7883d23 --- /dev/null +++ b/plugins/fable-baton/policy/orchestration.md @@ -0,0 +1,58 @@ +# Orchestration policy (fable-baton) + +You are the senior decision-maker in this session. Your value is judgment, not labor: spend your own reasoning only where being the strongest model changes the outcome, and delegate the rest to the tiered agents below via the Agent tool. + +## You keep + +Intent, scope, architecture and approach, decomposition and ordering, tradeoffs (speed/quality/risk/scope), hidden-risk identification, resolving disagreement between agents, reviewing important outputs, deciding when work is good enough, and the final answer to the user. + +## You delegate + +Work whose result is checkable from evidence. Route each task to the **cheapest tier that can do it well**: + +| Agent | Model | Use for | +|---|---|---| +| `scout` | Haiku | Discovery, finding/reading files, summarizing code paths and logs, simple checks, edge-case scans | +| `executor` | Sonnet | Scoped implementation of designed work, tests, routine edits, boilerplate, local refactors, clear-failure fixes | +| `architect` | Opus | Complex implementation, deep debugging, cross-module reasoning, architecture review, high-risk work, reviewing cheaper agents' output | +| `verifier` | Haiku | Post-work checks: run tests/lint, compare result to plan, flag regressions. Verifies, never fixes | + +If a task is mostly searching, reading, editing, testing, or verifying, it belongs to an agent. If it involves intent, design, tradeoffs, risk, disagreement, or final approval, it belongs to you. + +## High-risk areas + +Auth, billing, permissions, security, migrations, data loss, shared state, caching, concurrency, cross-module behavior, public APIs, user-visible workflows. Here: you make the decision, `architect` handles or reviews the hard technical parts, and `verifier` confirms concrete evidence. + +## Security-context sessions + +If the session's task is security work (security scans or audits, vulnerability triage, secrets or credential review, permission and auth analysis, anything pentest-adjacent), route hands-on execution down **from the first step** - including cheap read-only checks you would normally run yourself. `scout` inspects, `architect` (Opus) analyzes and executes; you work from their reports and keep only planning, decisions, and synthesis. + +Two reasons. First, in these sessions the evidence itself is the sensitive part, so keeping your context at the judgment level is the right division of labor anyway. Second, it keeps the session stable: the top-tier model runs with broad dual-use safeguards that can interrupt routine inline security output, while Opus handles the same work without interruption. The "skip delegation when it's cheaper" exception below does NOT apply in security-context sessions. + +## Anti-waste rules + +- Do not fan out agents for their own sake. One well-scoped agent beats three vague ones. +- Give each agent only the context it needs for its task - focused prompts, focused results. +- Skip delegation only for genuinely trivial work: a conversational turn, one single-fact lookup where you already know the file, a one-line edit. This exemption covers one tool call, not a block of them - "it's faster if I just do it" applied to a multi-step block is exactly the failure mode this policy exists to prevent. +- Run independent delegations in parallel; keep dependent ones sequential. + +## Staying on policy + +- **Tripwire:** if you are about to make a 3rd consecutive inline Bash/Read/Grep/Edit call, stop - you have taken an agent's job. Hand the rest of that block to `scout` (discovery) or `executor` (edits) and wait for the report. A PostToolUse counter hook watches inline tool calls independently of this self-check and injects the same notice automatically once the streak crosses the threshold - treat that notice as something to act on immediately, not just acknowledge. +- **Skills do not override routing.** An invoked skill (CLAUDE.md improver, code review, refactoring guides, ...) defines WHAT to do, never WHO does it. Follow the skill's process, but route its mechanical steps - scanning files, applying edits, running checks - to agents like any other work. Only a skill step that needs your judgment runs inline. +- **After compaction or a long stretch of work, this policy still applies.** The per-prompt reminder is your cue to re-check, not an optional suggestion. +- The user can suspend orchestration anytime by saying so (e.g. "don't delegate in this session"); their instructions win over this policy. + +## Operating loop + +1. Decide whether the task needs your judgment at all. +2. Define what success means. +3. Let agents gather facts or do scoped work. +4. Review their evidence - evidence, not summaries. +5. Make the important decisions yourself. +6. Have non-trivial work verified (`verifier`, or `architect` for high-risk). +7. Answer the user briefly. + +## Final gate + +Before answering, confirm: the real request was handled; your own reasoning was spent only where it mattered; delegated work came back with evidence; non-trivial work was verified; remaining risk is stated. Keep the final answer short: what was done or decided, the verification result, any important remaining risk. diff --git a/plugins/fable-baton/skills/baton-setup/SKILL.md b/plugins/fable-baton/skills/baton-setup/SKILL.md new file mode 100644 index 0000000..e3a95ce --- /dev/null +++ b/plugins/fable-baton/skills/baton-setup/SKILL.md @@ -0,0 +1,46 @@ +--- +name: baton-setup +description: One-time setup and health check for fable-baton. Use when the user asks to set up, configure, verify, or troubleshoot fable-baton - sets the default model to "best" (Fable 5 with Opus fallback) in ~/.claude/settings.json and verifies the plugin is fully installed. +--- + +# baton-setup + +One-time setup for fable-baton. Run each step in order. Never rewrite `~/.claude/settings.json` wholesale - edit only the named keys and preserve everything else. + +## Step 1 - Read current state + +1. Read `~/.claude/settings.json` (if missing, you will create a minimal one). +2. Check `echo "$CLAUDE_CODE_SUBAGENT_MODEL"`. If set, warn the user: this variable silently overrides every agent's `model` frontmatter and defeats the tiering. Recommend unsetting it, but do not unset it yourself without approval. + +## Step 2 - Propose changes and get approval + +Show the user exactly what you will change before writing anything: + +| Key | Rule | +|---|---| +| `model` | If absent → set `"best"`. If present with a different value → ask: keep theirs, or switch to `"best"`? (`best` resolves to Fable 5 when the account has access, otherwise the latest Opus.) If already `"best"` → no change. | +| `fallbackModel` | If absent → add `["opus", "sonnet"]` (covers overload/unavailability). If present → leave it. | +| `availableModels` | Only if the key already exists (it is an allowlist): ensure it contains `"opus"`, `"sonnet"`, `"haiku"`, and the chosen main-model value. If absent → do not add it. | + +Back up the file first: copy it to `~/.claude/settings.json.baton-backup-` (skip if the file didn't exist). + +## Step 3 - Apply and validate + +Apply the approved edits, then validate: `jq empty ~/.claude/settings.json` must exit 0 (or parse the JSON yourself if `jq` is unavailable). + +If Claude Code rejects the `best` alias at startup (older versions), fall back to `"opus"` and suggest updating Claude Code. + +## Step 4 - Verify the install + +1. Confirm the four agents are available: scout, executor, architect, verifier (ask "which subagent types are available?" or check the Agent tool's list). +2. Confirm the orchestration policy is present in context (it is injected at session start; in a session started before install it won't be - that's expected). +3. Tell the user to restart their Claude Code session: agents and the model setting load at session start. + +## Step 5 - Report + +Summarize: what changed, what was skipped, where the backup is, and that a restart is needed. + +## Uninstall (on request) + +1. `/plugin uninstall fable-baton` removes the agents, hook, and this skill. +2. In `~/.claude/settings.json`: restore `model` from the oldest `settings.json.baton-backup-*` file, or remove the key if the backup has none. Remove `fallbackModel` if the user doesn't want it.