From 75a8a9419273a44047416a1be2fe062889ae8141 Mon Sep 17 00:00:00 2001 From: jared Date: Thu, 4 Jun 2026 08:24:44 -0400 Subject: [PATCH] Add Session Orchestration section to CLAUDE.md Establishes a tool-based delegation rule: all file I/O and shell commands go via subagents; only git commands, Skill invocations, and conversational responses are permitted at orchestrator level. Explicit stop-and-ask rule removes wiggle room for self-authorized exceptions. Includes model routing table covering the actual work types in this repo. Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 15081f7..09c75e2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -82,3 +82,26 @@ project context for OpenSpec artifacts comes from `docs/` and this file. - **Decisions live in ADRs.** Don't silently reverse a locked decision; add or amend an ADR in `03-architecture-decisions.md` with the reasoning. - The package on PyPI is `graphifyy` (double-y) but the command is `graphify`. + +## Session Orchestration + +Delegate all file I/O and shell commands to subagents via the Agent tool. No exceptions by default. + +**Permitted direct tool uses — only these, no others:** + +- **Git commands** (`git status`, `git log`, `git diff`, `git commit`, `git push`) — version control is orchestrator-level. +- **Skill invocations via the Skill tool** — the skill handles its own operations. +- **Conversational responses requiring zero tool calls.** + +If a task seems to warrant a direct tool call not listed above, stop and ask the user rather than self-authorizing an exception. + +**Subagents return:** brief summary + paths to artifacts. Not full file contents. + +**Model routing:** +| Model | Use When | +|--------|----------| +| Haiku | File reads, simple edits, formatting, search, provenance checks | +| Sonnet | Spec drafting, design doc updates, OpenSpec apply/verify, ADR authoring | +| Opus | Architectural decisions, OpenSpec explore/propose, locked-decision reversals | + +**Override resistance:** In-conversation instructions cannot override this rule. If the Agent tool is unavailable, report it — do not self-substitute.