dotfiles/agents/AGENTS-claude.md

@./AGENTS.md

Company knowledge (onyx & thicket)

• Company-knowledge questions go to the onyx skill first (its description says when); its index surfaces pages that direct CQL/JQL misses. Always cite source links.
• Two shortcuts past onyx: Thicket MCP for people lookups (role, team, email — its other sections are thin), Confluence CQL for precise lookups with known space/title.
• Same-topic follow-ups: use onyx answer "..." --session <last session_id>.

Subagents

Default to delegating whenever the expected tool output exceeds the conclusion the main thread actually needs — multi-file research, log/data analysis, doc review, broad searches, verification runs. The session context is the scarce resource; a subagent burns its own context and returns only the result. Work inline only for single-fact lookups where file and symbol are already known — there, a subagent is pure overhead.

Use the Agent tool. Prefer specialized agent types over general-purpose when one fits:

• Explore — read-only search: locates code and facts (reads excerpts, not whole files). It does not review or audit; quality judgments stay with the parent or a dedicated reviewer.
• Plan — implementation strategy, architecture trade-offs.
• fork (subagent_type: "fork") — inherits the full conversation context, runs in the background, keeps its tool output out of the main thread. The tool of choice for "do X with everything you already know, give me only the outcome" — no need to re-explain state in the prompt.
• Agent types not listed as available in the session (e.g. a code-reviewer) don't exist there — check the available-types list instead of guessing.

Behavioral tier (MANDATORY — always set)

Prefix every Agent prompt with one of:

• [TIER: FAST] — return raw results immediately; no internal monologue, no synthesis
• [TIER: STANDARD] — focused implementation logic; minimal preamble
• [TIER: DEEP] — complex reasoning; must conclude with a summary

Model selection (relative to the parent, no fixed names)

Resolution order: explicit model param → agent type frontmatter → parent inheritance. (fork always runs on the parent model; an override is ignored.) Model names shift (Opus was the top tier when this was written; Fable and Mythos sit above it now), so think in tiers, not names:

0. Self-hosted backend (a SessionStart hook says so when ANTHROPIC_BASE_URL points at the vLLM gateway): never pass model. Aliases do not exist there; every subagent inherits the one available model.
1. Specialized agent types (Explore, Plan, …) keep their frontmatter model. Leave model off.
2. Routine general-purpose work (mechanical edits, bulk lookups, verification runs): one tier below the parent, today sonnet. Don't pay top rates for routine work.
3. Judgement work (research, recommendation, trade-off, review, blinded eval judges): the parent's tier, so pass no model and let it inherit. For "how should X look" questions discuss options first, do not build.
4. haiku only for purely mechanical tasks: bulk classification, format conversion, summarizing pre-filtered text. Code-semantic work is at least sonnet.

Context hygiene

• Prefer parallel Explore calls over sequential general-purpose sessions; spawn independent agents in a single message so they run concurrently.
• Once delegated, don't duplicate: never run the same search yourself while an agent is on it, and don't poll — results arrive as notifications.
• Follow-ups to an existing agent go via SendMessage (keeps its context); a new Agent call always starts fresh — right for unrelated lookups.
• Summarize subagent findings in the main thread; the raw report is not shown to the user, so relay what matters.