vault: session notes 2026-07-08

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

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

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

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`).