Agentic Workflow Pattern

Standard multi-agent pipeline for implementation tasks.

Architecture Principles

• Use run_in_background: true for all agents to keep main context minimal

• Use Task tool (never TaskOutput ) to avoid receiving full agent transcripts

• Agents write outputs to .claude/cache/agents/<stage>/ for injection into subsequent agents

• Main conversation is pure orchestration — no heavy lifting, only coordination

Workflow Stages

1. Research Agent

Task(subagent_type="oracle", run_in_background=true, prompt=""" Query NIA Oracle (via /nia-docs skill) to verify approach and gather best practices.

Output to: .claude/cache/agents/oracle/<task>-research.md """)

• Enforce NIA as the research layer

• Output: Research findings

2. Planning Agent

Task(subagent_type="plan-agent", run_in_background=true, prompt=""" Read: .claude/cache/agents/oracle/<task>-research.md Use RP-CLI to analyze the target codebase section. Generate implementation plan informed by research.

Output to: .claude/cache/agents/plan-agent/<task>-plan.md """)

• Receives: Research agent output as context

• Output: Implementation plan

3. Validation Agent

Task(subagent_type="validate-agent", run_in_background=true, prompt=""" Read: .claude/cache/agents/plan-agent/<task>-plan.md Read: .claude/cache/agents/oracle/<task>-research.md Review plan against research findings and best practices.

Output to: .claude/cache/agents/validate-agent/<task>-validated.md """)

• Reviews plan against research

• Output: Validated plan with amendments

4. Implementation Agent

Task(subagent_type="agentica-agent", run_in_background=true, prompt=""" Read: .claude/cache/agents/validate-agent/<task>-validated.md Read: .claude/cache/agents/oracle/<task>-research.md

TDD approach: Write failing tests FIRST, then implement. Run tests to verify.

Output summary to: .claude/cache/agents/implement-agent/<task>-implementation.md """)

• Receives: Validated plan + research context

• TDD: Failing tests first

• Output: Implementation + tests

5. Review Agent

Task(subagent_type="review-agent", run_in_background=true, prompt=""" Read: .claude/cache/agents/implement-agent/<task>-implementation.md Read: .claude/cache/agents/validate-agent/<task>-validated.md Read: .claude/cache/agents/oracle/<task>-research.md

Cross-reference implementation against plan and research. Run tests to confirm passing.

Output to: .claude/cache/agents/review-agent/<task>-review.md """)

• Cross-references all artifacts

• Confirms tests pass

• Output: Review summary

Agent Progress Monitoring

Watch for system reminders:

"Agent a42a16e progress: 6 new tools used, 88914 new tokens"

Poll for output files:

find .claude/cache/agents -name "*.md" -mmin -5

Check task file size growth:

wc -c /tmp/claude/.../tasks/<id>.output

Stuck detection:

• Progress reminders stop arriving

• Task output file size stops growing

• Expected output file not created after reasonable time

Directory Structure

.claude/cache/agents/ ├── oracle/ │ └── <task>-research.md ├── plan-agent/ │ └── <task>-plan.md ├── validate-agent/ │ └── <task>-validated.md ├── implement-agent/ │ └── <task>-implementation.md └── review-agent/ └── <task>-review.md

Key Rules

• Never use TaskOutput - floods context with 70k+ token transcripts

• Always run_in_background=true - isolates agent context

• File-based handoff - each agent reads previous agent's output file

• Poll, don't block - check file system for outputs, don't wait

• TDD in implementation - failing tests first, then make them pass

Source

• Session 2026-01-01: SDK Phase 3 implementation using this pattern