AGENTS.md git:20261013.abbf471A

Immutable. This exact content never changes and is served at /api/v1/blob/cdfa3f2f141c9848.

# fable-baton: Agent instructions

> Canonical instructions for all coding agents (Claude Code, Codex, GitHub Copilot). Codex reads this directly; Claude and GitHub Copilot use pointer files when present.

fable-baton is a Claude Code plugin that turns Fable 5 into a token-frugal orchestrator: Fable keeps judgment (intent, architecture, tradeoffs, review) while tiered subagents on Opus, Sonnet, and Haiku do the labor. It ships four agents (`scout`/Haiku, `executor`/Sonnet, `architect`/Opus, `verifier`/Haiku), a orchestration policy injected via a SessionStart hook, and enforcement hooks (SessionStart, UserPromptSubmit, PostToolUse) that keep nudging delegation through a session.

Repo layout:
- `agents/`: the four tiered subagent definitions (`architect.md`, `executor.md`, `scout.md`, `verifier.md`)
- `hooks/`: `hooks.json` plus the shell scripts (`session-start.sh`, `prompt-nudge.sh`, `inline-counter.sh`) that enforce delegation
- `policy/orchestration.md`: the orchestration policy text injected at session start
- `skills/baton-setup/`: the one-time setup skill that sets the default model to `best`
- `.claude-plugin/`: `plugin.json` (plugin manifest) and `marketplace.json`
- `assets/`: README images/GIFs

No package manifest / build step; this is a plugin distributed as plain files (Markdown, JSON, shell). CI (`.github/workflows/ci.yml`) validates JSON files, lints for em/en dashes, checks shell syntax (`bash -n hooks/*.sh`), and smoke-tests the hooks by running them directly with `CLAUDE_PLUGIN_ROOT=.` set.

## Project memory (distilled)

<!-- Curated snapshot of prior agent session knowledge (2026-07-17). Claude's private memory remains canonical; update via Working notes. -->

- Repo moved to `~/Git/fable-baton` from `~/Downloads` on 2026-07-10; GitHub remote is realgarit/fable-baton, made public 2026-07-13.
- fable-baton is a Claude Code plugin making Fable 5 a token-frugal orchestrator with tiered agents (scout=Haiku, executor=Sonnet, architect=Opus, verifier=Haiku), a SessionStart policy hook, and a baton-setup skill.
- Core product goal: stop the mid-session "switcheroo" where Fable's quota runs dry and Opus silently takes over. Inverted model: Fable spends tokens on judgment only; Opus/Sonnet/Haiku work below it as subagents; Fable keeps holding context. Tiering is meant to generalize to more models later.
- Repo rule: no em/en dashes anywhere (dash-lint enforced in CI), plain hyphens only. Also applies to any user-facing prose (posts, README, docs): no "not X, it's Y" constructions, no labeled sections in prose, no AI-marketing phrases (dive into, unleash, game-changing, leverage, optimize, unlock potential), short plain sentences, admit limitations plainly.
- No mention of the source notes the design came from, in any file.
- v1.1.0 added security-context routing: in security sessions, hands-on work is delegated from the first step so Fable only sees agent reports.
- v1.2.0 (2026-07-10) added a UserPromptSubmit per-prompt reminder hook, a 3-consecutive-inline-calls tripwire, and a "skills define what, not who" rule. Built after a real session showed SessionStart-only injection loses salience and invoked skills' imperative steps can override the policy.
- v1.3.0 (2026-07-10) added a PostToolUse inline-call counter hook (hooks/inline-counter.sh): counts consecutive Bash/Read/Grep/Glob/Edit/Write/NotebookEdit calls per session, resets on Agent/Task, injects a delegation notice at threshold (FABLE_BATON_TRIPWIRE, default 4, re-nudges every 6). Chose PostToolUse additionalContext over PreToolUse deny because hooks fire in subagents too and hard-blocking would break them. Known limitation: subagent calls may share the parent session's counter; the notice text tells subagents to ignore it in that case.
- v1.4.0 (2026-07-21) added session-model tier adaptation: session-start.sh reads the model from the SessionStart hook input, persists the tier to /tmp/fable-baton-tier-<session>, and appends policy/adapt-{sonnet,opus,haiku}.md to the base policy; prompt-nudge.sh and inline-counter.sh read the tier file and adapt their text. Fable or unknown/missing model falls back to the base policy unchanged. v1.4.1: live testing on Claude Code 2.1.216 showed the SessionStart payload carries NO model field (docs list it as optional), so detection falls back to the transcript: both session-start.sh and prompt-nudge.sh scan the last 256KB of transcript_path for the newest non-sidechain assistant message's message.model. Fresh startup sessions have an empty transcript, so the adaptation arrives via prompt-nudge from turn 2 (announced once, tracked in /tmp/fable-baton-adapted-<session>); resumed sessions get it at SessionStart. A mid-session model change (the switcheroo) is detected and re-announced. Rationale: on a Sonnet session, executor is a lateral hand-off and architect (Opus) is an upward escalation, so the fable-tier nudges would push hand-offs that save nothing.
- v1.4.3 (2026-07-27) added an Opus branch to the inline-counter tripwire message, so Opus sessions get wording that points at the cheaper agents instead of architect.
- v1.5.0 (2026-07-27) added policy/adapt-unknown.md, a self-apply fallback injected at SessionStart when the model cannot be detected (fresh startup sessions have no model in the payload and an empty transcript), with transcript detection from turn 2 confirming or correcting it.
- Git flow rule: never commit to main directly. Always: feature branch, push, open PR with gh, watch CI on the PR, merge (squash, delete branch), then watch the post-merge main run until green. CI (.github/workflows/ci.yml) validates JSON, dash-lint, and hook smoke tests.
- 2026-07-13 benchmark (Claude Code 2.1.197, plugin v1.3.0, off vs on, 12 headless runs): plugin does not reduce total API cost (roughly equal, slightly higher on small tasks), but Fable 5's own output tokens dropped 44% on a spec'd feature task and 38% on a code review task, with work shifting to Sonnet/Haiku/Opus. Honest framing: value is preserving Fable quota and avoiding the switcheroo, not total cost savings. Results are in the README Benchmark section (added via PR #12).
- Plugin was submitted to the official Claude plugin directory (platform.claude.com/plugins/submit) and to community awesome-lists; awaiting review as of 2026-07-10.

## Cross-agent conventions

- This file (`AGENTS.md`) is the single source of truth for agent instructions in this repo. `CLAUDE.md` and `.github/copilot-instructions.md` are pointers to it; never edit them, never duplicate content into them.
- Shared repository skills live in `.agents/skills/` (one folder per skill with a `SKILL.md`). Codex scans this location natively. Keep any `.claude/skills/` compatibility bridge pointer-only or generated from this directory; never maintain two independent sources. New shared skills always go in `.agents/skills/`.
- Claude-specific subagent definitions live in `.claude/agents/`. If you are not Claude Code, you may read them as role/process guidance.
- Session continuity across tools: before ending substantial work in ANY tool (Claude Code, Codex, Copilot), record durable context (decisions made, gotchas discovered, in-progress state worth resuming) in the "Working notes" section below, or fold it into the relevant section above. This is the shared memory between agents.

## Working notes

- 2026-10-13: Version 1.5.2 includes the hook interpreter/mode fix from contributor PR #24. CI on Linux and macOS invokes the registered commands from an installed path containing spaces after stripping execute bits, and verifies startup policy, persisted tier, prompt nudge, counter notice and reset. Existing direct script tests alone did not cover the packaging defect.


- 2026-10-08: Dependabot alerts/security updates are enabled. Version updates run
  weekly on Monday at 06:00 Europe/Zurich for the manifests in .github/dependabot.yml.
  Minor/patch updates are grouped, majors stay separate, and merging remains review-driven.
  Routine versions have a seven-day cooldown; security updates are not delayed.


<!-- Any agent: append short dated notes here (YYYY-MM-DD, note). Prune notes when stale or once folded into the sections above. -->

- 2026-09-16 - Codex-first layout sweep: repository-local shared skills use `.agents/skills/` as the canonical source. Any `.claude/skills/` path is only a compatibility bridge or generated mirror.