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/-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/-research.md

Use RP-CLI to analyze the target codebase section.

Generate implementation plan informed by research.

Output to: .claude/cache/agents/plan-agent/-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/-plan.md

Read: .claude/cache/agents/oracle/-research.md

Review plan against research findings and best practices.

Output to: .claude/cache/agents/validate-agent/-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/-validated.md

Read: .claude/cache/agents/oracle/-research.md

TDD approach: Write failing tests FIRST, then implement.

Run tests to verify.

Output summary to: .claude/cache/agents/implement-agent/-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/-implementation.md

Read: .claude/cache/agents/validate-agent/-validated.md

Read: .claude/cache/agents/oracle/-research.md

Cross-reference implementation against plan and research.

Run tests to confirm passing.

Output to: .claude/cache/agents/review-agent/-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