Domain 1: Agentic Architecture & Orchestration
27%ts-1.1Design and implement agentic loops for autonomous task execution
- The agentic loop lifecycle: send request, inspect stop_reason, execute tools, append results, repeat until end_turn.
- stop_reason is the sole authoritative signal for loop control -- not text parsing, not iteration counts.
- Tool results must be appended to conversation history so Claude can reason about the next action.
- Model-driven tool selection (Claude decides which tool based on context) is the default; pre-configured sequences are for strict compliance.
- Each iteration should include the full conversation context so Claude maintains coherent reasoning.
Decision Rules
When stop_reason === 'tool_use' → Execute the requested tool(s), append results to messages, and call Claude again.
When stop_reason === 'end_turn' → Terminate the loop and present the final response to the user.
When You need a safety guardrail against runaway loops → Add a max iteration count as a backstop, but keep stop_reason as the primary control signal.
Anti-Patterns
- Parsing response text for phrases like 'I've completed' to determine loop termination instead of using stop_reason.
- Using an arbitrary iteration cap as the primary stopping mechanism rather than a safety backstop.
ts-1.2Orchestrate multi-agent systems with coordinator-subagent patterns
- Hub-and-spoke: coordinator manages all inter-subagent communication, error handling, and information routing.
- Subagents operate with isolated context -- they do NOT inherit the coordinator's conversation history.
- The coordinator is responsible for task decomposition, delegation, result aggregation, and deciding which subagents to invoke.
- Overly narrow task decomposition by the coordinator leads to incomplete coverage of broad topics.
- Route all communication through the coordinator for observability, consistent error handling, and controlled information flow.
Decision Rules
When Multiple specialized capabilities are needed (search, analysis, synthesis) → Use coordinator-subagent pattern; coordinator delegates to specialized agents and aggregates results.
When A subagent's output needs to reach another subagent → Route through the coordinator -- never allow direct agent-to-agent communication.
When Research output is missing entire topic areas → Check the coordinator's task decomposition first -- it likely defined subtasks too narrowly.
Anti-Patterns
- Allowing direct agent-to-agent communication that bypasses the coordinator, breaking observability and error handling.
- Having the coordinator always route through the full pipeline instead of dynamically selecting which subagents to invoke.
ts-1.3Configure subagent invocation, context passing, and spawning
- The Task tool is the mechanism for spawning subagents; allowedTools must include 'Task' for the coordinator.
- Subagent context must be explicitly provided in the prompt -- subagents do NOT automatically inherit parent context.
- AgentDefinition configures descriptions, system prompts, and tool restrictions per subagent type.
- Use fork-based session management to explore divergent approaches from a shared analysis baseline.
- Spawn parallel subagents by emitting multiple Task tool calls in a single coordinator response.
Decision Rules
When A subagent needs data from a prior agent's output → Include the complete findings directly in the subagent's prompt via the coordinator.
When You need parallel research across multiple source types → Emit multiple Task tool calls in a single coordinator turn to spawn parallel subagents.
When Coordinator prompts lead to rigid subagent behavior → Specify research goals and quality criteria rather than step-by-step procedural instructions.
Anti-Patterns
- Assuming subagents inherit the coordinator's context or share memory between invocations.
- Writing step-by-step procedural coordinator prompts instead of goal-oriented ones that allow subagent adaptability.
ts-1.4Implement multi-step workflows with enforcement and handoff patterns
- Programmatic enforcement (hooks, prerequisite gates) provides deterministic guarantees; prompt instructions are probabilistic.
- When deterministic compliance is required (e.g., identity verification before financial ops), prompts alone have a non-zero failure rate.
- For multi-concern requests, decompose into distinct items, investigate each in parallel using shared context, then synthesize.
- Structured handoff summaries (customer ID, root cause, refund amount, recommended action) are essential for human escalation.
Decision Rules
When A specific tool sequence is required for critical business logic (e.g., verify customer before refund) → Use programmatic prerequisites that block downstream tools until prior steps complete.
When Customer sends a multi-concern message → Decompose into distinct concerns, investigate in parallel with shared context, then synthesize a unified resolution.
When Agent escalates to a human who lacks access to the conversation transcript → Compile a structured handoff summary with customer ID, root cause, amounts, and recommended action.
Anti-Patterns
- Relying solely on prompt instructions to enforce required tool ordering for operations with financial consequences.
- Processing multiple customer concerns sequentially, re-fetching shared context for each one.
ts-1.5Apply Agent SDK hooks for tool call interception and data normalization
- PostToolUse hooks intercept tool results for transformation BEFORE the model processes them.
- Hook patterns can also intercept outgoing tool calls to enforce compliance rules (e.g., block refunds above a threshold).
- Hooks provide deterministic guarantees; prompt instructions provide only probabilistic compliance.
- Use PostToolUse to normalize heterogeneous data formats: Unix timestamps, ISO 8601, numeric status codes.
Decision Rules
When Tools return heterogeneous formats (Unix timestamps, ISO dates, numeric codes) and the agent misinterprets them → Implement a PostToolUse hook to normalize all outputs before agent processing.
When Business rules require guaranteed compliance (e.g., refunds > $500 must be escalated) → Use a hook to intercept and block policy-violating tool calls, redirecting to the appropriate workflow.
When Third-party MCP tools return data you cannot modify at the source → Use PostToolUse hooks as a centralized normalization layer rather than prompt instructions.
Anti-Patterns
- Adding format documentation to the system prompt instead of using hooks when deterministic normalization is required.
- Creating a separate normalize_data tool the agent must remember to call, instead of automatic hook-based transformation.
ts-1.6Design task decomposition strategies for complex workflows
- Use fixed sequential pipelines (prompt chaining) for predictable multi-aspect reviews; dynamic decomposition for open-ended investigation.
- Splitting large reviews into per-file local analysis plus a separate cross-file integration pass avoids attention dilution.
- Adaptive investigation plans generate subtasks based on what is discovered at each step.
- For open-ended tasks, first map the structure, identify high-impact areas, then create a prioritized plan.
Decision Rules
When A single-pass review of 14+ files produces inconsistent depth and contradictory findings → Split into per-file analysis passes plus a separate cross-file integration pass.
When The task is predictable with known steps (e.g., multi-aspect code review) → Use prompt chaining: a fixed sequential pipeline.
When The task is exploratory with unknown scope (e.g., 'add tests to a legacy codebase') → Use dynamic decomposition: map first, identify high-impact areas, then create a prioritized adaptive plan.
Anti-Patterns
- Reviewing all files in a large PR in a single pass, leading to attention dilution and contradictory feedback.
- Using a fixed pipeline for an open-ended investigation task where subtasks depend on intermediate findings.
ts-1.7Manage session state, resumption, and forking
- Use --resume <session-name> to continue named investigation sessions across work sessions.
- fork_session creates independent branches from a shared analysis baseline for exploring divergent approaches.
- When resuming after code modifications, inform the agent about specific file changes for targeted re-analysis.
- Starting a new session with a structured summary is more reliable than resuming with stale tool results.
Decision Rules
When Prior context is mostly valid and you want to continue an investigation → Use --resume with the session name; inform Claude about any file changes since last session.
When Prior tool results are stale (significant code changes since last session) → Start a new session with an injected summary of prior findings instead of resuming.
When You want to compare two refactoring approaches from the same analysis baseline → Use fork_session to create parallel exploration branches.
Anti-Patterns
- Resuming a session after significant code changes without informing the agent, leading to stale context reasoning.
- Re-exploring the entire codebase from scratch instead of informing a resumed session about targeted changes.
Deep Dives
ts-1.1Design and implement agentic loops for autonomous task execution
ts-1.2Orchestrate multi-agent systems with coordinator-subagent patterns
ts-1.3Configure subagent invocation, context passing, and spawning
ts-1.4Implement multi-step workflows with enforcement and handoff patterns
ts-1.5Apply Agent SDK hooks for tool call interception and data normalization
ts-1.6Design task decomposition strategies for complex workflows
ts-1.7Manage session state, resumption, and forking