From bed5f8ee76892a97c83a584be41268750592cb11 Mon Sep 17 00:00:00 2001
From: Gavin Staniforth <gsdevme@users.noreply.github.com>
Date: Fri, 4 Sep 2026 08:59:16 +0100
Subject: [PATCH] feat(models): add Fable orchestration/delegation policy

Add a Claude Code-scoped topic defining Fable as the orchestrator that
delegates work to cheaper opus/sonnet worker agents via the Agent tool,
with per-tier reasoning effort, task-type routing, and token rules.

Place models.md first in TOPIC_FILES so it leads both the Claude
@-imports and the Codex concatenation, and update the tests and README
layout to match.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 Makefile         |  2 +-
 README.md        |  1 +
 models.md        | 50 ++++++++++++++++++++++++++++++++++++++++++++++++
 tests/apply.bats |  4 ++++
 4 files changed, 56 insertions(+), 1 deletion(-)
 create mode 100644 models.md

diff --git a/Makefile b/Makefile
index 075185f..6fcdd00 100644
--- a/Makefile
+++ b/Makefile
@@ -1,7 +1,7 @@
 REPO_ROOT := $(abspath $(dir $(lastword $(MAKEFILE_LIST))))
 DEST_HOME ?= $(HOME)
 AGENTS_FILE ?= $(REPO_ROOT)/.agents/AGENTS.md
-TOPIC_FILES := commits.md task-starting.md planning.md code-comments.md
+TOPIC_FILES := models.md commits.md task-starting.md planning.md code-comments.md
 
 .PHONY: apply test
 
diff --git a/README.md b/README.md
index 49b6a0c..b018aa3 100644
--- a/README.md
+++ b/README.md
@@ -33,6 +33,7 @@ The repository keeps topics as separate files and the Makefile's ordered
 
 ```
 <repository>/
+├── models.md
 ├── commits.md
 ├── task-starting.md
 ├── planning.md
diff --git a/models.md b/models.md
new file mode 100644
index 0000000..a1c7300
--- /dev/null
+++ b/models.md
@@ -0,0 +1,50 @@
+# Model delegation
+
+**Claude Code only.** This topic applies to the Claude Code session model
+(Fable), the Agent tool, and teammates. Codex has no equivalent mechanism and
+can ignore it.
+
+## Delegation policy (read first)
+
+Fable is the orchestrator, not the worker. It is the most expensive tier —
+spend its tokens only on decomposition, judgment calls, synthesis, and talking
+to the user. Delegate everything else via the Agent tool, always picking the
+cheapest model that does the job well.
+
+- `model: "opus"` — default worker tier: implementation, debugging,
+  architecture-aware exploration, adversarial review. Prefer `claude-opus-4-8`
+  over `claude-opus-5-0` for this tier.
+- `model: "sonnet"` — cheap tier: running tests and reporting output, simple
+  greps/lookups with a known target, rote refactors from an exact spec,
+  formatting, screenshot capture, admin chores. If getting it slightly wrong is
+  cheap to catch, use sonnet.
+
+## Reasoning effort per tier
+
+- **Fable** (orchestrator / session model) — medium.
+- **opus** (`claude-opus-4-8`) worker — high.
+- **sonnet** worker — high.
+
+## Delegation by task
+
+- **Exploration/research** — never read broadly yourself; spawn Explore agents
+  (opus) with tightly scoped questions and consume their synthesized reports.
+  Trivial "find the file that defines X" lookups can go to sonnet.
+- **Implementation** — for any multi-file change, spawn general-purpose agents
+  (opus) with exact file paths, the relevant doctrine from this file, and a
+  definition of done (tests to run). Independent changes get parallel agents in
+  one message.
+- **Verification/review** — adversarial review and blast-radius checks go to
+  opus agents; plain test runs and lint passes go to sonnet agents.
+- **Fable edits directly** only when the change is small — one or two files, in
+  already-known locations.
+
+## Token rules
+
+- Don't echo file contents or long diffs back to the user; report conclusions.
+- Give agents file paths and constraints up front so they don't rediscover this
+  file's contents; paste the relevant doctrine into the prompt.
+- Batch independent agent launches in a single message so they run
+  concurrently.
+
+Project-level `CLAUDE.md` may override this.
diff --git a/tests/apply.bats b/tests/apply.bats
index 1d630c6..e1a8c42 100644
--- a/tests/apply.bats
+++ b/tests/apply.bats
@@ -38,6 +38,7 @@ expected_claude() {
   printf '%s\n\n' '<!-- managed-by: agent-dotfiles -->'
   printf '%s\n\n' '# Global preferences'
   printf '%s\n\n' 'Each topic is imported from the agent-dotfiles repository.'
+  printf '@%s/models.md\n' "$active_repo"
   printf '@%s/commits.md\n' "$active_repo"
   printf '@%s/task-starting.md\n' "$active_repo"
   printf '@%s/planning.md\n' "$active_repo"
@@ -47,6 +48,8 @@ expected_claude() {
 expected_agents() {
   printf '%s\n' '<!-- managed-by: agent-dotfiles -->'
   printf '%s\n\n' '<!-- Generated by make apply. Do not edit directly. -->'
+  cat "$active_repo/models.md"
+  printf '\n'
   cat "$active_repo/commits.md"
   printf '\n'
   cat "$active_repo/task-starting.md"
@@ -62,6 +65,7 @@ make_fixture_repo() {
   mkdir -p "$active_repo/scripts"
   cp "$repo_root/Makefile" "$active_repo/Makefile"
   cp "$repo_root/scripts/apply.sh" "$active_repo/scripts/apply.sh"
+  cp "$repo_root/models.md" "$active_repo/models.md"
   cp "$repo_root/commits.md" "$active_repo/commits.md"
   cp "$repo_root/task-starting.md" "$active_repo/task-starting.md"
   cp "$repo_root/planning.md" "$active_repo/planning.md"