gh-rsmdt-the-startup-plugins-start/skills/agent-delegation/reference.md

Agent Delegation Skill Reference

Complete reference for advanced delegation patterns, edge cases, and optimization strategies.

Advanced Decomposition Patterns

Multi-Level Decomposition

For very complex tasks, decompose in layers:

Layer 1: High-Level Activities

Task: Build e-commerce checkout flow

Activities:
1. Frontend checkout interface
2. Backend payment processing
3. Order fulfillment system
4. Email notifications

Layer 2: Sub-Activity Decomposition

Take Activity 2 and decompose further:

Activity: Backend payment processing

Sub-activities:
2.1 Stripe API integration
2.2 Payment validation logic
2.3 Transaction database schema
2.4 Refund handling

Execution Strategy:

• Layer 1: Mixed (some parallel, some sequential)
• Layer 2: Decompose only when agent starts Activity 2
• Don't decompose all layers upfront (overwhelming)

Dependency Graph Decomposition

For complex dependency chains:

Task: Deploy new microservice

Activity Map:
A: Write service code
B: Write unit tests (depends on A)
C: Create Docker image (depends on A)
D: Write integration tests (depends on A, C)
E: Deploy to staging (depends on B, C, D)
F: Run smoke tests (depends on E)
G: Deploy to production (depends on F)

Execution Groups:
Group 1: A (sequential)
Group 2: B, C (parallel after A)
Group 3: D (sequential after Group 2)
Group 4: E (sequential after Group 3)
Group 5: F (sequential after E)
Group 6: G (sequential after F)

Pattern: Identify critical path, parallelize where possible.

Expertise-Based Decomposition

When multiple domains are involved:

Task: Add real-time chat feature

Decompose by expertise:
1. UI/UX design (design expertise)
2. Frontend component (React expertise)
3. WebSocket server (Backend expertise)
4. Message persistence (Database expertise)
5. Security review (Security expertise)
6. Performance testing (Performance expertise)

Execution:
- Phase 1: Activity 1 (sequential)
- Phase 2: Activities 2-4 (parallel, informed by Activity 1)
- Phase 3: Activities 5-6 (parallel review after Phase 2)

Advanced Parallel Patterns

Fan-Out/Fan-In Pattern

Parallel expansion followed by sequential consolidation:

        Start
          ↓
      [Activity 1]
          ↓
    ┌─────┼─────┐
    ↓     ↓     ↓
  [A2]  [A3]  [A4]  ← Fan-out (parallel)
    ↓     ↓     ↓
    └─────┼─────┘
          ↓
     [Synthesize]  ← Fan-in (sequential)
          ↓
        Done

Example: Competitive analysis

• Fan-out: Analyze competitors A, B, C in parallel
• Fan-in: Synthesize findings into unified strategy

Pipeline Pattern

Sequential groups where each group can be parallel:

Stage 1: Research (parallel within stage)
- Market research
- Competitive analysis
- User interviews
    ↓
Stage 2: Design (parallel within stage)
- UI mockups
- API design
- Database schema
    ↓
Stage 3: Implementation (parallel within stage)
- Frontend build
- Backend build
- Database setup

Pattern: Stages are sequential, activities within each stage are parallel.

MapReduce Pattern

Parallel processing with aggregation:

Map Phase (parallel):
Agent 1: Process dataset chunk 1
Agent 2: Process dataset chunk 2
Agent 3: Process dataset chunk 3
Agent 4: Process dataset chunk 4

Reduce Phase (sequential):
Aggregate all results into final output

Example: Code analysis across modules

• Map: Each agent analyzes one module
• Reduce: Aggregate findings into project-wide report

Advanced Template Patterns

Context Accumulation Pattern

For sequential tasks, accumulate context:

Agent 1:
CONTEXT: Fresh start, no prior context
OUTPUT: Result A

Agent 2:
CONTEXT:
  - Prior results: [Result A from Agent 1]
  - Build on: [Specific insights from A]
OUTPUT: Result B (informed by A)

Agent 3:
CONTEXT:
  - Prior results: [Result A, Result B]
  - Conflicts to resolve: [Any conflicts between A and B]
  - Build on: [Insights from both]
OUTPUT: Result C (synthesizes A and B)

Key: Each agent gets relevant prior outputs, not everything.

Constraint Propagation Pattern

Cascade constraints through dependent tasks:

Agent 1 (Schema Design):
SUCCESS:
  - Uses PostgreSQL (project standard)
  - Follows naming: snake_case tables
  - All tables have created_at, updated_at

Agent 2 (API Implementation, depends on Agent 1):
CONTEXT:
  - Database constraints from Agent 1:
    * PostgreSQL only
    * snake_case table names
    * created_at/updated_at in all tables
  - Must match schema exactly

Pattern: SUCCESS criteria from earlier tasks become CONTEXT constraints for later ones.

Specification Reference Pattern

For implementation tasks, reference specs explicitly:

FOCUS: Implement user registration endpoint

CONTEXT:
  - PRD Section 3.1.2: User registration requirements
  - SDD Section 4.2: API endpoint specifications
  - SDD Section 5.3: Database schema for users table
  - PLAN Phase 2, Task 3: Implementation checklist

SDD_REQUIREMENTS:
  - Endpoint: POST /api/auth/register
  - Request body: { email, password, name }
  - Response: { user_id, token }
  - Validation: Email format, password strength (8+ chars)
  - Security: Bcrypt hashing (cost 12)

SPECIFICATION_CHECK: Must match SDD Section 4.2 exactly

Pattern: Explicit spec references prevent context drift.

File Coordination Advanced Strategies

Timestamp-Based Uniqueness

When paths might collide, add timestamps:

Agent 1 OUTPUT: logs/analysis-${TIMESTAMP}.md
Agent 2 OUTPUT: logs/research-${TIMESTAMP}.md
Agent 3 OUTPUT: logs/synthesis-${TIMESTAMP}.md

where TIMESTAMP = ISO 8601 format

Result: No collisions even if agents run simultaneously.

Directory Hierarchy Assignment

Assign each agent a subdirectory:

Agent 1 OUTPUT: results/agent-1/findings.md
Agent 2 OUTPUT: results/agent-2/findings.md
Agent 3 OUTPUT: results/agent-3/findings.md

Result: Each agent owns a directory, filenames can repeat.

Atomic File Creation Pattern

For critical files, ensure atomic creation:

OUTPUT: Create file at exact path: docs/patterns/auth.md
  - If file exists, FAIL and report (don't overwrite)
  - Use atomic write (temp file + rename)
  - Verify write succeeded before marking complete

Pattern: Prevents race conditions and corruption.

Merge Strategy Pattern

When multiple agents create similar content:

Strategy: Sequential merge

Agent 1: Create base document
Agent 2: Read base, add section 2
Agent 3: Read base + section 2, add section 3

Each agent:
DISCOVERY_FIRST: Read current state of document
FOCUS: Add my section without modifying others
OUTPUT: Updated document with my section added

Pattern: Sequential additions to shared document.

Scope Validation Advanced Patterns

Severity-Based Acceptance

Categorize scope creep by severity:

Minor (Auto-accept):

• Variable name improvements
• Comment additions
• Whitespace formatting
• Import organization

Medium (Review):

• Small refactors related to task
• Additional error handling
• Logging additions
• Documentation updates

Major (Reject):

• New features
• Architecture changes
• Dependency additions
• Breaking changes

Value-Based Exception Handling

Sometimes scope creep is valuable:

Agent delivered:
✅ Required: Authentication endpoint
⚠️ Extra: Rate limiting on endpoint (not requested)

Analysis:
- Extra work: Rate limiting
- In EXCLUDE? No (not explicitly excluded)
- Valuable? Yes (security best practice)
- Risky? No (standard pattern)
- Increases scope? Minimally

Decision: 🟡 ACCEPT with note
  "Agent proactively added rate limiting for security.
   Aligns with best practices, accepting this valuable addition."

Pattern: Auto-accept valuable, low-risk extras that align with project goals.

Specification Drift Detection

For implement tasks, detect drift from specs:

Validation:
1. Check FOCUS matches PLAN task description
2. Check implementation matches SDD requirements
3. Check business logic matches PRD rules

Drift detected if:
- Implementation differs from SDD design
- Business rules differ from PRD
- Features not in PLAN added

Report:
📊 Specification Alignment: 85%
✅ Aligned: [aspects that match]
⚠️ Deviations: [aspects that differ]
🔴 Critical drift: [major misalignments]

Retry Strategy Advanced Patterns

Progressive Refinement

Refine template progressively across retries:

Attempt 1 (Failed - too vague):

FOCUS: Add caching

Attempt 2 (Failed - still ambiguous):

FOCUS: Add Redis caching for API responses
EXCLUDE: Don't cache user-specific data

Attempt 3 (Success - specific enough):

FOCUS: Add Redis caching for public API endpoints
  - Cache GET requests only
  - TTL: 5 minutes
  - Key format: api:endpoint:params:hash
  - Invalidate on POST/PUT/DELETE to same resource

EXCLUDE:
  - Don't cache authenticated user requests
  - Don't cache admin endpoints
  - Don't implement cache warming
  - Don't add Redis cluster setup (single node for now)

CONTEXT:
  - Redis already configured: localhost:6379
  - Use ioredis client
  - Follow caching pattern: docs/patterns/caching-strategy.md

Pattern: Each retry adds specificity based on previous failure.

Agent Type Rotation

If specialist fails, try different angle:

Attempt 1: Backend specialist
  - Focused on technical implementation
  - Failed: Too technical, missed user experience

Attempt 2: UX specialist
  - Focused on user flows
  - Failed: Too high-level, missed technical constraints

Attempt 3: Product specialist
  - Balanced user needs with technical reality
  - Success: Right blend of perspectives

Pattern: Rotate expertise angle based on failure mode.

Scope Reduction Strategy

If task too complex, reduce scope progressively:

Attempt 1 (Failed - too much):
FOCUS: Build complete authentication system
  - Registration, login, logout, password reset
  - OAuth integration
  - Two-factor authentication

Attempt 2 (Failed - still complex):
FOCUS: Build basic authentication
  - Registration, login, logout

Attempt 3 (Success - minimal):
FOCUS: Build login endpoint only
  - POST /auth/login
  - Email + password validation
  - Return JWT token

Pattern: Reduce scope until agent succeeds, then expand incrementally.

Edge Cases and Solutions

Edge Case 1: Circular Dependencies

Problem: Agent A needs Agent B's output, Agent B needs Agent A's output

Detection:

Activity A depends on B
Activity B depends on A
→ Circular dependency detected

Solutions:

1. Break the cycle:

   Original:
   A (needs B) ↔ B (needs A)
   
   Refactored:
   C (shared foundation) → A (builds on C) → B (builds on A)
   

2. Iterative approach:

   Round 1: A (with assumptions about B)
   Round 2: B (using Round 1 A)
   Round 3: A (refined with actual B)
   

3. Merge activities:

   Single agent handles both A and B together
   (They're too coupled to separate)
   

Edge Case 2: Dynamic Dependencies

Problem: Don't know dependencies until runtime

Example:

Task: Analyze codebase

Don't know which modules exist until discovery
Can't plan parallel structure upfront

Solution - Two-phase approach:

Phase 1: Discovery (sequential)

Agent 1: Discover project structure
OUTPUT: List of modules

Result: [moduleA, moduleB, moduleC, moduleD]

Phase 2: Analysis (parallel, dynamic)

For each module in result:
  Launch analysis agent

Agent A: Analyze moduleA
Agent B: Analyze moduleB
Agent C: Analyze moduleC
Agent D: Analyze moduleD

Pattern: Sequential discovery, dynamic parallel execution.

Edge Case 3: Partial Agent Availability

Problem: Some specialist agents unavailable

Example:

Planned:
- Frontend specialist (available)
- Backend specialist (available)
- DevOps specialist (NOT AVAILABLE)

Solution - Fallback delegation:

If specialist unavailable:
1. Try broader domain agent (general-purpose)
2. Try sequential breakdown (smaller tasks)
3. Handle directly if simple enough
4. Escalate to user if critical

Example execution:

DevOps work:
  Attempt 1: DevOps specialist → UNAVAILABLE
  Attempt 2: Backend specialist with DevOps context → SUCCESS
  Reasoning: Backend specialist has some DevOps overlap

Edge Case 4: Agent Response Conflicts

Problem: Parallel agents return conflicting recommendations

Example:

Agent 1 (Security): "Use bcrypt with cost 14 (maximum security)"
Agent 2 (Performance): "Use bcrypt with cost 10 (reasonable security, better performance)"

Solution - Conflict resolution:

1. Present to user:

⚠️ Agent Conflict Detected

Topic: Bcrypt cost factor
Agent 1 (Security): Cost 14 (maximize security)
Agent 2 (Performance): Cost 10 (balance security/performance)

Trade-off:
- Cost 14: ~200ms hashing time, highest security
- Cost 10: ~50ms hashing time, strong security

Recommendation needed: Which priority matters more?

2. Specification arbitration:

Check specs:
- SDD Section 5.2: "Use bcrypt cost factor 12"
→ Use specification value (12)
→ Both agents adjusted to match spec

3. Synthesis agent:

Launch Agent 3 (Architect):
FOCUS: Resolve conflict between security and performance recommendations
CONTEXT:
  - Security recommendation: cost 14
  - Performance recommendation: cost 10
  - Trade-offs: [details]
OUTPUT: Final recommendation with reasoning

Edge Case 5: Resource Constraints

Problem: Can't launch all parallel agents simultaneously (rate limits, memory, etc.)

Solution - Batched parallel execution:

Activities: [A1, A2, A3, A4, A5, A6, A7, A8]
Constraint: Maximum 3 parallel agents

Execution:
Batch 1: A1, A2, A3 (parallel)
  → Wait for completion
Batch 2: A4, A5, A6 (parallel)
  → Wait for completion
Batch 3: A7, A8 (parallel)
  → Complete

Pattern: Maintain parallelism within constraints.

Performance Optimization

Minimize Context Size

Don't pass everything to every agent:

❌ Bad - Full context:

CONTEXT:
  - Entire PRD (50 pages)
  - Entire SDD (40 pages)
  - All prior agent outputs (30 pages)

✅ Good - Relevant context:

CONTEXT:
  - PRD Section 3.2 (User authentication requirements)
  - SDD Section 4.1 (API endpoint design)
  - Prior output: Authentication flow diagram from Agent 1

Pattern: Extract only relevant portions, reference docs by section.

Parallel Batching

Group related parallel tasks:

Don't:
Launch 20 individual research agents

Do:
Launch 4 research agents, each handles 5 topics

Benefits:

• Fewer coordination overhead
• Better context utilization
• Faster overall completion

Early Termination

Build termination conditions into templates:

TERMINATION:
  - Completed successfully
  - Blocked by missing dependency X
  - Information not publicly available
  - Maximum 3 attempts reached
  - ERROR: [specific error conditions]

Pattern: Let agents fail fast instead of hanging.

Integration with Other Skills

With Documentation Skill

When agents discover patterns:

Agent completes task
  ↓
Discovers reusable pattern
  ↓
Documentation skill activates
  ↓
Pattern documented in docs/patterns/
  ↓
Reported back to orchestrator

Coordination: Agent-delegation creates prompts, documentation skill handles pattern storage.

With Specification Review Skill

For implementation tasks:

Agent completes implementation
  ↓
Agent-delegation validates scope
  ↓
Specification review skill validates against PRD/SDD
  ↓
Both validations pass → Complete

Coordination: Agent-delegation handles scope, spec-review handles alignment.

With Quality Gates Skill

At phase boundaries:

Phase completes
  ↓
Agent-delegation confirms all tasks done
  ↓
Quality gates skill runs DOD checks
  ↓
Both pass → Proceed to next phase

Coordination: Agent-delegation manages execution, quality-gates validates quality.

Debugging Failed Delegations

Symptom: Agents ignore EXCLUDE

Diagnosis:

• EXCLUDE too vague
• Agent sees value in excluded work
• Conflict between FOCUS and EXCLUDE

Fix:

Before:
EXCLUDE: Don't add extra features

After:
EXCLUDE: Do not add these specific features:
  - OAuth integration (separate task)
  - Password reset flow (separate task)
  - Two-factor authentication (not in scope)
  Any feature not explicitly in FOCUS is out of scope.

Symptom: Parallel agents conflict

Diagnosis:

• Hidden shared state
• File path collision
• Dependency not identified

Fix:

Review parallel safety checklist:
- Independent tasks? → Check dependencies again
- Unique file paths? → Verify OUTPUT sections
- No shared state? → Identify what's shared

If any fail → Make sequential or coordinate better

Symptom: Sequential too slow

Diagnosis:

• False dependencies
• Over-cautious sequencing
• Could be parallel with coordination

Fix:

Re-analyze dependencies:
- Must Task B use Task A's output? → True dependency
- Could Task B assume Task A's approach? → False dependency

If false dependency:
  → Make parallel with coordinated assumptions

Symptom: Template too complex

Diagnosis:

• Too many constraints
• Context overload
• Agent confused by detail

Fix:

Simplify:
1. Keep FOCUS to essentials
2. Move details to CONTEXT
3. Provide examples instead of rules

Before (overwhelming):
FOCUS: [20 lines of detailed requirements]

After (simplified):
FOCUS: [2 lines of core task]
CONTEXT: [Details and constraints]

Best Practices Summary

1. Decompose by activities, not roles
2. Parallel by default, sequential only when necessary
3. Explicit FOCUS/EXCLUDE, no ambiguity
4. Unique file paths, verify before launching
5. Minimal context, only relevant information
6. Auto-accept safe changes, review architectural ones
7. Maximum 3 retries, then escalate
8. Early termination, fail fast when blocked
9. Validate scope, check FOCUS/EXCLUDE adherence
10. Document patterns, activate documentation skill when discovered

Common Patterns Quick Reference

Pattern	When to Use	Structure
Fan-Out/Fan-In	Parallel research → synthesis	Parallel → Sequential
Pipeline	Stages with parallel within	Sequential stages, parallel tasks
MapReduce	Large dataset processing	Parallel map → Sequential reduce
Progressive Refinement	Retry with more detail	Retry N adds specificity
Batched Parallel	Resource constraints	Groups of parallel tasks
Context Accumulation	Sequential with learning	Each task gets prior outputs
Constraint Propagation	Dependent implementations	SUCCESS → next CONTEXT
Specification Reference	Implementation tasks	Explicit PRD/SDD references

---

This reference covers advanced scenarios beyond the main skill. Load this when dealing with complex coordination, optimization, or edge cases.