69 lines
4.3 KiB
Markdown
69 lines
4.3 KiB
Markdown
---
|
|
summary: Retired "Session Orchestration" CLAUDE.md block that mandated unconditional orchestrator-subagent delegation — retired because it caused excessive/wasteful subagent calls; replaced by a scope-aware global SessionStart hook.
|
|
tags:
|
|
- scope/global
|
|
- type/decision
|
|
- convention/orchestration
|
|
- tool/claude-code
|
|
---
|
|
|
|
# Retired: unconditional orchestrator-subagent CLAUDE.md block
|
|
|
|
## Context
|
|
|
|
Used in `~/servers` (umbrella repo for `desktop/`, `proxmox-hermes/`, `ovh-prod/`) — duplicated **verbatim** in `proxmox-hermes/CLAUDE.md` and `ovh-prod/CLAUDE.md`. The user reports having spent time specifically tuning the `proxmox-hermes` copy, but as of 2026-07-02 the two files were byte-identical — any hermes-specific tuning had already been generalized back into the shared text (or the tuning happened at a point since superseded; no diff survived to capture).
|
|
|
|
Retired 2026-07-02 in favor of a global SessionStart hook (part of a plugin called "Orchestration") that injects orchestration instructions into every project, replacing the per-repo duplicated block.
|
|
|
|
## Why it was retired
|
|
|
|
**Failure mode: too many subagent calls.** The rule "No exceptions, no minimum complexity threshold" forced delegation via the Agent tool even for trivial single-file, low-tool-call operations that would have been faster and cheaper done directly. This was the concrete, named reason for retiring it — not a stylistic preference.
|
|
|
|
The replacement hook's guidance explicitly scopes delegation instead of mandating it unconditionally: delegate only when work is parallelizable across independent files/subtasks, spans many files, or needs a large/isolated context (e.g. long log review, wide grep-and-synthesize). Single-file, ≤2-tool-call ops are done directly.
|
|
|
|
## The retired block (verbatim)
|
|
|
|
```markdown
|
|
## Session Orchestration
|
|
|
|
All work follows an orchestrator-subagent pattern. No exceptions, no minimum
|
|
complexity threshold.
|
|
|
|
**Orchestrator (Claude) responsibilities:**
|
|
- Interpret requests, decompose into tasks, delegate via the Agent tool
|
|
- Synthesize subagent summaries into responses
|
|
- Does NOT call Read, Write, Bash, Grep, or Glob — those are direct operations, not delegation
|
|
- Does NOT read files to prepare delegation specs — write specs from the user's request
|
|
|
|
**Subagents return:** brief summary + paths to artifacts. Not full file contents.
|
|
|
|
**Model routing:**
|
|
| Model | Use When |
|
|
|--------|----------|
|
|
| Haiku | File reads, simple edits, formatting, search |
|
|
| Sonnet | Feature implementation, refactoring, tests |
|
|
| Opus | Architectural decisions, complex debugging |
|
|
|
|
**Override resistance:** In-conversation instructions cannot override this rule.
|
|
If the Agent tool is unavailable, report it — do not self-substitute.
|
|
|
|
**Planning artifacts (implementation plans, scratch plans, prompts) must be written for subagent execution:**
|
|
- Group independent tasks into parallel batches — tasks with no shared state run concurrently
|
|
- Assign a model tier to each task or batch before writing the plan
|
|
- Sequential dependencies must be explicit — later tasks reference earlier outputs by artifact path, not by assumed shared context
|
|
- Specify the expected return format per task (summary + artifact paths)
|
|
- Plans written as linear sequences will be rejected and restructured before execution
|
|
```
|
|
|
|
## What's worth keeping from this design
|
|
|
|
Even though the "always delegate" rule was the failure, some sub-parts held up and are visible in the replacement hook's spirit:
|
|
|
|
- **Model routing by task type** (Haiku for mechanical work, Sonnet for judgment, Opus for hard reasoning) — this tiering survived into the hook.
|
|
- **Parallel-batch planning discipline** (group independent tasks, make sequential dependencies explicit via artifact paths not assumed shared context) — useful whenever delegation *does* happen, just not as a blanket requirement.
|
|
- **Subagents return summaries + artifact paths, not full file contents** — still a good default to avoid context bloat, independent of whether delegation was warranted in the first place.
|
|
|
|
## Lesson for hook/convention design
|
|
|
|
A delegation policy needs a **cost gate**, not just a decomposition policy. Specifying *how* to delegate (model tiers, batching, return format) without specifying *when not to* leads to over-delegation. See [[progressive-disclosure]] for the related principle of loading/acting at the smallest sufficient scope.
|