AgentSkillsCN

agentic-workflow

代理式工作流模式

SKILL.md
--- frontmatter
name: agentic-workflow
description: Agentic Workflow Pattern
user-invocable: false

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 .maestro/cache/agents/<stage>/ for injection into subsequent agents
  • •Main conversation is pure orchestration — no heavy lifting, only coordination

Workflow Stages

1. Research Agent

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

Output to: .maestro/cache/agents/planner/<task>-research.md
""")
  • •Enforce NIA as the research layer
  • •Output: Research findings

2. Planning Agent

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

Output to: .maestro/cache/agents/plan-agent/<task>-plan.md
""")
  • •Receives: Research agent output as context
  • •Output: Implementation plan

3. Validation Agent

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

Output to: .maestro/cache/agents/validate-agent/<task>-validated.md
""")
  • •Reviews plan against research
  • •Output: Validated plan with amendments

4. Implementation Agent

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

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

Output summary to: .maestro/cache/agents/implement-agent/<task>-implementation.md
""")
  • •Receives: Validated plan + research context
  • •TDD: Failing tests first
  • •Output: Implementation + tests

5. Review Agent

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

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

Output to: .maestro/cache/agents/review-agent/<task>-review.md
""")
  • •Cross-references all artifacts
  • •Confirms tests pass
  • •Output: Review summary

Agent Progress Monitoring

bash
# Watch for system reminders:
# "Agent a42a16e progress: 6 new tools used, 88914 new tokens"

# Poll for output files:
find .maestro/cache/agents -name "*.md" -mmin -5

# Check task file size growth:
wc -c /tmp/claude/.../tasks/<id>.output

Stuck detection:

  1. •Progress reminders stop arriving
  2. •Task output file size stops growing
  3. •Expected output file not created after reasonable time

Directory Structure

code
.maestro/cache/agents/
├── planner/
│   └── <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

  1. •Never use TaskOutput - floods context with 70k+ token transcripts
  2. •Always run_in_background=true - isolates agent context
  3. •File-based handoff - each agent reads previous agent's output file
  4. •Poll, don't block - check file system for outputs, don't wait
  5. •TDD in implementation - failing tests first, then make them pass

Source

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