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 (override only when needed)

Resolution order: explicit model param → agent type frontmatter → parent inheritance. (fork always runs on the parent model; an override is ignored.)

0. Self-hosted backend (a SessionStart hook says so when ANTHROPIC_BASE_URL points at the vLLM gateway): never pass model. Aliases like sonnet do not exist there; every subagent inherits the one available model.
1. Don't override specialized agent types (Explore, Plan, etc.) — their frontmatter is tuned. Leave model off.
2. For general-purpose under an expensive parent (Opus/Fable): set model: sonnet — don't pay top rates for routine subagent work.
3. opus for research, recommendation, trade-off and judgement work (also blinded eval judges) and when isolated context and reasoning beyond the parent's inline capacity are both needed. For "how should X look" questions discuss options first, do not build.
4. model: haiku only for mechanical tasks: bulk classification, format conversion, summarizing pre-filtered text. Code-semantic work → 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.