diff --git a/journal/2026-07-08.md b/journal/2026-07-08.md new file mode 100644 index 0000000..7a38717 --- /dev/null +++ b/journal/2026-07-08.md @@ -0,0 +1,13 @@ +--- +summary: Daily session log +tags: [scope/global, type/log] +--- + +## Session — 2026-07-08T13:27:54Z + +**Project:** /home/jared/dev/cc-os +**Reason:** prompt_input_exit +**Vault notes touched:** +/home/jared/Documents/SecondBrain/reference/orchestration-prompting-claude-5-era.md +/home/jared/Documents/SecondBrain/reference/agent-orchestration-patterns.md +/home/jared/Documents/SecondBrain/reference/zsh-path-variable-collision.md diff --git a/reference/agent-orchestration-patterns.md b/reference/agent-orchestration-patterns.md index b7dcf0c..4a9d9ee 100644 --- a/reference/agent-orchestration-patterns.md +++ b/reference/agent-orchestration-patterns.md @@ -152,3 +152,4 @@ Return: {"status": "updated|skipped|ambiguous", "changes": [...]} ## Related - [[reference/agent-orchestration-cookbook]] — concrete walkthroughs, token budgets, error recovery patterns +- [[orchestration-prompting-claude-5-era]] — model-generation-specific prompting guidance (Fable 5 / Opus 4.8 / Sonnet 5); why delegation thresholds must be re-keyed when the main-loop tier changes diff --git a/reference/orchestration-prompting-claude-5-era.md b/reference/orchestration-prompting-claude-5-era.md new file mode 100644 index 0000000..5b9d602 --- /dev/null +++ b/reference/orchestration-prompting-claude-5-era.md @@ -0,0 +1,107 @@ +--- +type: reference +subtype: pattern/framework +title: "Orchestration prompting for Claude 5-era models (Fable 5, Opus 4.8, Sonnet 5)" +summary: "What Anthropic's model-page guidance says about delegation, token efficiency, and rule phrasing for current-generation orchestrators — and how it invalidates delegation rules written for cheaper/older main-loop models. Answers: how should an orchestrator rule doc be written when the main loop is a top-tier model?" +tags: + - type/reference + - domain/ai-agents + - domain/orchestration + - tool/claude-code +scope: global +last_updated: 2026-07-08 +date: 2026-07-08 +last_reviewed: 2026-07-08 +related: + - agent-orchestration-patterns + - agent-orchestration-cookbook + - os-orchestration-ws1-session-audit-results +source: cc-os +--- + +# Orchestration prompting for Claude 5-era models + +Sources: Anthropic model pages (prompting-claude-fable-5, prompting-claude-opus-4-8, +prompting-claude-sonnet-5, claude-prompting-best-practices), fetched 2026-07-08. Community +claims below are marked `[unverified claim]`. + +## The meta-finding (why this note exists) + +**Delegation rules go stale when the main-loop model tier changes, even if every rule is still +individually true.** A rule doc written to prevent over-delegation on a sonnet main loop +(where direct work is cheap and Opus 4.6-era models over-spawned) actively suppresses +delegation on a Fable/top-tier main loop, where every direct tool call is billed at the most +expensive rate. The threshold question is not "is this task big enough to delegate?" but +"does this work need main-loop-tier judgment?" — cost asymmetry between the orchestrator and +the cheapest adequate executor must be *explicit in the rule text*, not implied. + +## Load-bearing guidance from the model pages + +1. **Calibrated trigger phrasing, both directions.** On 4.6+ models, absolutist wording + ("CRITICAL: you MUST...") over-fires; plain "use X when Y" is correct. Crucially, the + canonical best-practices delegation snippet pairs a *positive* trigger list ("use subagents + when parallel / isolated context / independent workstreams") with a *negative* one ("work + directly for simple tasks, sequential ops, single-file edits, shared-state steps"). + A rule doc phrased negative-first ("delegate ONLY when...") is read literally by these + models and suppresses delegation in every gray zone. + +2. **Literal instruction-following.** Opus 4.8/Sonnet 5/Fable 5 do not silently generalize + an instruction beyond its stated scope. A threshold like "≤2-tool-call ops are direct" + licenses 3+-call direct work forever unless something *obligates* delegation above some + line — write both sides of the boundary. + +3. **Model biases differ by generation and must be steered per-model:** Fable 5 dispatches + parallel subagents *readily* and sustains async communication with them (recommended + pattern: "delegate independent subtasks and keep working while they run" — non-blocking); + Opus 4.8 *under*-delegates by default and needs explicit "spawn multiple in the same turn + when fanning out" nudges; Opus 4.6 *over*-delegated. The same orchestration text lands + differently per main-loop model. + +4. **Effort is the primary within-model cost dial** — the docs give no cross-tier + haiku/sonnet/opus decision table at all; they treat `effort` as the main quality/cost + lever. An orchestration policy that routes only by model tier is missing a lever: mechanical + subagent work → low effort, hard verify/judge stages → high/xhigh (where the harness + exposes it, e.g. Workflow `agent()` opts). + +5. **Long-lived / batched subagents amortize cost.** Fable 5 page: long-lived subagents that + keep context across subtasks save time and cost via cache reads and avoid bottlenecking on + the slowest agent. Combine with the batching economics in [[agent-orchestration-patterns]] + (tool tax ~20–25K tokens per spawn; batch 5–8 similar items per specialist; reuse a live + agent for follow-ups instead of spawning fresh). + +6. **Front-load the task spec.** Opus 4.8/Sonnet 5: token use rises in interactive settings + because the model re-reasons after each user turn; a complete task/intent/constraints + statement in the first turn is cheaper and better than progressive disclosure. Applies + equally to subagent prompts: one complete grouped prompt beats iterative follow-ups. + +7. **Grounding and downgrade honesty.** Fable 5 page's "audit each claim against a tool + result" pattern nearly eliminated fabricated status reports in Anthropic's testing — + the same mechanism as subagent model self-report (subagents know their model ID; launch + results don't show it). + +## Community pattern (context, not evidence) + +The "Fable-5 orchestrator" community pattern (pasqualepillitteri.it, 2026-07-02) matches the +above architecture — Fable plans/synthesizes, pinned-model personas execute, orchestrator +generates only 10–20% of tokens, "5–10× savings" `[unverified claim]` (all cost figures +asserted without methodology; the one external attribution, "MindStudio 80–90% shift with no +quality loss," has no citation). Its mechanical details (frontmatter-pinned `model:` in +`~/.claude/agents/`, description-driven delegation) are real Claude Code mechanics; its +numbers are not evidence. + +## How to apply + +When writing or reviewing an orchestrator rule doc: +- State the cost asymmetry explicitly and key the delegation threshold to the main-loop tier + (models know their own model ID, so tier-conditional rules are implementable). +- Pair positive and negative delegation triggers; never "only when." +- Add a batching rule (group related subtasks into one agent prompt; reuse live agents) and an + async rule (keep working while subagents run). +- Re-audit the rule doc whenever the default main-loop model changes generation — evidence + gathered under the old economics (e.g. "direct work was often superior") may no longer bind. + +## Related + +- [[agent-orchestration-patterns]] — batching economics, tool tax, decision framework +- [[agent-orchestration-cookbook]] — concrete walkthroughs +- [[os-orchestration-ws1-session-audit-results]] — the audit evidence gathered under pre-Fable economics diff --git a/reference/zsh-path-variable-collision.md b/reference/zsh-path-variable-collision.md new file mode 100644 index 0000000..2e58a30 --- /dev/null +++ b/reference/zsh-path-variable-collision.md @@ -0,0 +1,27 @@ +--- +type: reference +subtype: pattern/framework +title: "zsh: assigning a variable named path silently corrupts $PATH" +summary: "In zsh, the lowercase array variable path is linked to $PATH; assigning path=... in a script or session clobbers the executable search path and causes unrelated command-not-found failures. Use another name (tpath, fpath_ — but note fpath is also linked)." +tags: + - type/reference + - tool/zsh + - domain/shell-scripting +scope: global +last_updated: 2026-07-08 +date: 2026-07-08 +source: cc-os +--- + +# zsh: `path` is linked to `$PATH` + +zsh ties certain lowercase array variables to their uppercase scalar counterparts: +`path`↔`PATH`, `fpath`↔`FPATH`, `cdpath`↔`CDPATH`, `mailpath`↔`MAILPATH`, `manpath`↔`MANPATH`. +Assigning any of them (e.g. `path="/some/file"` as an innocent loop variable) silently +replaces the executable search path for the rest of the script/session. Symptom: unrelated +tools start failing with command-not-found after a script ran. + +**Rule:** in zsh scripts (including throwaway audit/eval scripts driven from Claude Code, +whose Bash tool runs zsh on this machine), never use `path`, `fpath`, `cdpath`, `manpath` +as variable names. Discovered 2026-07-08 during the Fable orchestration mini-audit +(scripts fixed by renaming to `tpath`).