Ai Assisted Development

Platform Notes

• Optional helper plugins may help in some environments, but they must not be treated as required for this skill.

AI-Assisted Development Orchestration

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->

Use When

• Orchestrate AI coding agents, human reviewers, CI, and delivery workflows for professional software work. Use when coordinating AI-assisted planning, implementation, code review, modernization, documentation, or multi-agent development.
• The task needs reusable judgment, domain constraints, or a proven workflow rather than ad hoc advice.

Do Not Use When

• The task is unrelated to ai-assisted-development or would be better handled by a more specific companion skill.
• The request only needs a trivial answer and none of this skill's constraints or references materially help.

Required Inputs

• Gather relevant project context, constraints, and the concrete problem to solve; load references only as needed.
• Confirm the desired deliverable: design, code, review, migration plan, audit, or documentation.

Workflow

• Read this SKILL.md first, then load only the referenced deep-dive files that are necessary for the task.
• Apply the ordered guidance, checklists, and decision rules in this skill instead of cherry-picking isolated snippets.
• Produce the deliverable with assumptions, risks, and follow-up work made explicit when they matter.

Quality Standards

• Keep outputs execution-oriented, concise, and aligned with the repository's baseline engineering standards.
• Preserve compatibility with existing project conventions unless the skill explicitly requires a stronger standard.
• Prefer deterministic, reviewable steps over vague advice or tool-specific magic.

Anti-Patterns

• Treating examples as copy-paste truth without checking fit, constraints, or failure modes.
• Loading every reference file by default instead of using progressive disclosure.

Outputs

• A concrete result that fits the task: implementation guidance, review findings, architecture decisions, templates, or generated artifacts.
• Clear assumptions, tradeoffs, or unresolved gaps when the task cannot be completed from available context alone.
• References used, companion skills, or follow-up actions when they materially improve execution.

Evidence Produced

References

• Use the references/ directory for deep detail after reading the core workflow below.

<!-- dual-compat-end -->

Overview

Learn to orchestrate multiple AI agents (like Codex, custom sub-agents, or specialized AI tools) to work together effectively in software development.

This skill bridges prompting patterns + orchestration + sub-agent coordination for real-world AI-assisted development.

Operating Doctrine

• Treat AI as a force multiplier inside a disciplined engineering system, not as a replacement for requirements, design, review, tests, security, or ownership.
• Start every AI-assisted task with a concrete outcome, repo constraints, acceptance criteria, and verification command. Do not ask an agent to "improve" broad surfaces without a definition of done.
• Keep humans accountable for architecture, irreversible data changes, production release, security exceptions, licensing/IP decisions, and client commitments.
• Prefer small, reviewable AI work packets: one responsibility, one bounded write scope, one expected evidence artifact.
• Require codebase grounding before edits. The agent must inspect current patterns, interfaces, tests, and failure modes before proposing or changing implementation.

AI Development Workflow

1. Frame: State user value, business value, technical objective, constraints, and acceptance tests. 2. Ground: Read the smallest set of files/docs needed to understand existing behavior. 3. Plan: Split work by ownership boundaries. Identify what can be delegated and what must stay on the critical path. 4. Implement: Make narrow changes that preserve local conventions. Avoid broad rewrites unless requested. 5. Verify: Run focused tests, linters, type checks, migrations, or manual checks that match the blast radius. 6. Review: Inspect diff for hallucinated APIs, over-broad abstractions, hidden state changes, secrets, data leaks, and licensing risks. 7. Record: Capture changed files, commands run, residual risks, and follow-up work.

Agent Assignment Rules

• Use explorers for bounded codebase questions with clear expected outputs.
• Use workers for bounded implementation with disjoint file ownership. Tell workers they are not alone in the codebase and must not revert others' edits.
• Do not delegate the immediate blocking task if the main workflow cannot proceed until it returns.
• Never let two agents write the same files unless one is explicitly reviewing the other's patch.
• For generated code, require the same quality bar as human code: tests, readable names, explicit error handling, and no invented dependencies.

AI Coding Risk Controls

Evidence Required

• For code changes: diff summary, tests/checks run, and known gaps.
• For architecture or plans: decision record, alternatives considered, evaluation criteria, and economic rationale.
• For modernization: before/after behavior, migration steps, rollback plan, and compatibility notes.

What you'll learn:

• The 5 orchestration strategies for AI development
• AI-specific coordination patterns (Agent Handoff, Fan-Out/Fan-In, Human-in-the-Loop)
• Real-world examples (MADUUKA, BRIGHTSOMA apps)

Documentation Structure (Tier 2 Deep Dives):

• 📖 [orchestration-strategies.md](references/orchestration-strategies.md) - The 5 core strategies with detailed examples
• 📖 [ai-patterns.md](references/ai-patterns.md) - AI-specific orchestration patterns
• 📖 [practical-examples.md](references/practical-examples.md) - Real MADUUKA and BRIGHTSOMA projects

---

Additional Guidance

Extended guidance for ai-assisted-development was moved to references/skill-deep-dive.md to keep this entrypoint compact and fast to load.

Use that deep dive for:

• When to Use This Skill
• Core Concepts (Quick Reference)
• The 5 Orchestration Strategies (Summary)
• The 3 AI Orchestration Patterns (Summary)
• Quick Reference: When to Use Which
• Real-World Examples (Summary)
• Practical Workflow: How to Apply This Skill
• Best Practices
• Integration with Other Skills
• Summary

AI Orchestration Patterns

Purpose: Learn AI-specific orchestration patterns for coordinating multiple AI agents

Parent Skill: ai-assisted-development

---

What Are AI Orchestration Patterns?

AI orchestration patterns are proven ways to coordinate multiple AI agents to work together on software development tasks.

Think of them as design patterns, but for AI workflows instead of code structure.

---

The 3 Core AI Patterns

Pattern 1: Agent Handoff (Pipeline Pattern)

Use case: One AI agent completes work, passes output to next AI agent

Flow:

Agent A → Output (becomes input) → Agent B → Output → Agent C → Done

Example: Feature Development Pipeline

Agent 1: Requirements Agent

Prompt: "Analyze these user requests and create formal requirements document."

Input: User interviews, feature requests
Output: docs/requirements.md

Agent 2: Specification Agent (receives Agent 1 output)

Prompt: "Using the requirements document, create technical specification.

FILE TO READ: docs/requirements.md

CONTEXT: Transform requirements into implementable spec with:
- Data model
- API endpoints
- UI wireframes"

Input: docs/requirements.md (from Agent 1)
Output: docs/specs/feature-spec.md

Agent 3: Implementation Agent (receives Agent 2 output)

Prompt: "Implement the feature using the specification.

FILE TO READ: docs/specs/feature-spec.md

CONTEXT: Write complete, production-ready code following spec exactly."

Input: docs/specs/feature-spec.md (from Agent 2)
Output: Code files

Key principle: Each agent's output is the next agent's input (like a factory assembly line)

Benefits:

• Clear separation of concerns
• Each agent focused on ONE job
• Easy to debug (check output at each step)
• Traceable (spec → code → tests all linked)

---

Pattern 2: Fan-Out/Fan-In (Parallel + Combine)

Use case: Split work across multiple AI agents, then combine results

Flow:

                ┌─→ Agent A ──┐
Input (split) ──┼─→ Agent B ──┼─→ Combine → Output
                └─→ Agent C ──┘

Example: Multi-Component Documentation

Fan-Out Phase:

Agent A: Database Docs

"Generate database schema documentation.

SCAN: database/migrations/
OUTPUT: docs/database.md

ORCHESTRATION: Part of parallel fan-out (with Agents B and C)"

Agent B: API Docs

"Generate API endpoint documentation.

SCAN: app/Http/Controllers/
OUTPUT: docs/api.md

ORCHESTRATION: Part of parallel fan-out (with Agents A and C)"

Agent C: UI Docs

"Generate UI component documentation.

SCAN: resources/js/components/
OUTPUT: docs/ui.md

ORCHESTRATION: Part of parallel fan-out (with Agents A and B)"

All 3 agents run in parallel (no dependencies between them)

Fan-In Phase:

Agent D: Combiner

"Combine all documentation into unified architecture document.

FILES TO READ:
- docs/database.md (Agent A output)
- docs/api.md (Agent B output)
- docs/ui.md (Agent C output)

ORCHESTRATION: Fan-in phase (waits for all 3 agents to complete).

GENERATE:
- Master architecture document
- Cross-reference links
- Unified glossary"

Timing:

• Parallel: All 3 agents run simultaneously = 10 minutes
• Sequential would be: 10 + 10 + 10 = 30 minutes
• Savings: 67% faster

Benefits:

• Massive speedup (run in parallel)
• Independent work (no coordination needed)
• Combine at end (unified output)

---

Pattern 3: Human-in-the-Loop (Gated Approval)

Use case: AI agents generate work, human approves before continuing

Flow:

Agent 1 → Output → [HUMAN REVIEW] → Approved? YES → Agent 2
                                                 ↓ NO
                                              Revise (loop back to Agent 1)

Example: Spec → Code → Deploy with Approval Gates

Phase 1: AI Planning

Agent: Planning Agent

"Create feature specification for payment processing.

OUTPUT: docs/specs/payment-spec.md"

Output: Spec document

[GATE 1: Human Review]

• Human reads spec
• Checks: Business logic correct? Security concerns? Edge cases?
• Decision: ✅ Approve → Continue | ❌ Reject → Revise spec

---

Phase 2: AI Implementation (only if Phase 1 approved)

Agent: Implementation Agent

"Implement payment processing using approved spec.

FILE TO READ: docs/specs/payment-spec.md (APPROVED by human)

ORCHESTRATION: Phase 2 (gated - only runs after human approval)"

Output: Code files

[GATE 2: Human Review]

• Human reviews code
• Checks: Follows spec? Security ok? Tests exist?
• Decision: ✅ Approve → Continue | ❌ Reject → Fix code

---

Phase 3: AI Testing (only if Phase 2 approved)

Agent: Testing Agent

"Create tests for payment processing.

FILES TO READ:
- docs/specs/payment-spec.md (approved spec)
- app/Services/PaymentService.php (approved code)

ORCHESTRATION: Phase 3 (gated - only runs after code approved)"

Output: Test files

[GATE 3: Human Review]

• Human reviews tests
• Checks: Coverage sufficient? Edge cases tested?
• Decision: ✅ Approve → Deploy | ❌ Reject → Add more tests

Benefits:

• Safety: Human oversight at critical points
• Quality control: Catch issues before they cascade
• Learning: AI learns from human feedback
• Compliance: Some industries require human approval

When to use gates:

• Security-critical features (payment, auth, data access)
• High-risk changes (database migrations, API breaking changes)
• Compliance requirements (financial, healthcare, legal)
• Learning phase (train AI on your patterns)

---

Combining Patterns

Real-world AI workflows combine multiple patterns.

Example: Complete Feature Development with All 3 Patterns

┌─────────────────────────────────────────────────┐
│ Pattern 1: Agent Handoff (Pipeline)             │
│                                                  │
│ Agent 1: Planning → docs/specs/feature.md       │
│                          ↓                       │
│         [GATE 1: Human Review] ← Pattern 3      │
│                          ↓ (approved)            │
├─────────────────────────────────────────────────┤
│ Pattern 2: Fan-Out (Parallel)                   │
│                                                  │
│ Agent 2a: Database ──┐                          │
│ Agent 2b: API ───────┼─→ All run in parallel    │
│ Agent 2c: UI ────────┘                          │
│                          ↓                       │
│ Pattern 2: Fan-In (Combine)                     │
│                          ↓                       │
│ Agent 3: Integration → Combine all components   │
│                          ↓                       │
│         [GATE 2: Human Review] ← Pattern 3      │
│                          ↓ (approved)            │
├─────────────────────────────────────────────────┤
│ Pattern 1: Agent Handoff (Pipeline continues)   │
│                                                  │
│ Agent 4: Testing → Create comprehensive tests   │
│                          ↓                       │
│         [GATE 3: Human Review] ← Pattern 3      │
│                          ↓ (approved)            │
│ Agent 5: Deployment → Ship to production        │
└─────────────────────────────────────────────────┘

Patterns used:

• ✅ Agent Handoff (planning → implementation → testing → deployment)
• ✅ Fan-Out/Fan-In (parallel database + API + UI work)
• ✅ Human-in-the-Loop (3 approval gates)

Result: Fast, safe, high-quality feature delivery

---

Pattern Selection Guide

Combine patterns for complex workflows to get benefits of all.

---

Advanced: Meta-Orchestration

Meta-orchestration = AI agent that coordinates other AI agents

Pattern:

Meta-Agent (Orchestrator)
    │
    ├─→ Spawns Agent A for task 1
    ├─→ Spawns Agent B for task 2
    ├─→ Waits for both to complete
    └─→ Combines results

Example: Self-Orchestrating Documentation System

Meta-Agent: Documentation Orchestrator

"Analyze this codebase and generate complete documentation.

ORCHESTRATION TASK (not implementation):
1. Scan project to determine type
2. Identify what docs are needed
3. Spawn appropriate specialist agents
4. Coordinate their work
5. Combine outputs

THINK:
- What type of project is this?
- What documentation gaps exist?
- Which agents should I spawn?
- What order should they run?
- Can any run in parallel?

RETURN:
- Orchestration plan
- List of agents to spawn
- Execution order
- Expected outputs"

Output: Orchestration plan that spawns other agents

Then Meta-Agent executes the plan:

• Spawns Database Docs Agent
• Spawns API Docs Agent
• Spawns UI Docs Agent
• Waits for all 3 (parallel)
• Spawns Combiner Agent
• Returns final docs

Benefits:

• AI decides best orchestration strategy
• Adapts to project type
• No manual coordination needed
• Scales to complex projects

When to use:

• Very complex projects (20+ components)
• Variable project types (needs smart routing)
• Repeatable workflows (meta-agent learns patterns)

---

Error Handling Patterns

Pattern: Graceful Degradation

If agent fails, don't stop everything. Provide partial results.

Agent A: Complete Docs
  ↓ [FAIL: API down]
Fallback: Generate partial docs with TODOs
  → User gets 80% complete docs + manual steps

Pattern: Retry with Context

If agent fails, retry with error context.

Attempt 1: Agent generates code
  ↓ [FAIL: Syntax error]
Attempt 2: "Fix syntax error at line 42"
  ↓ [FAIL: Logic error]
Attempt 3: "Fix logic error in validation"
  ↓ [SUCCESS]

Each retry includes context from previous failure.

---

Best Practices

DO:

✅ Use Agent Handoff for sequential dependencies ✅ Use Fan-Out/Fan-In when parallelization possible ✅ Add Human Gates for high-risk work ✅ Provide clear context to each agent ✅ Log all agent interactions for debugging ✅ Set max retries to prevent infinite loops ✅ Have fallback plans for critical agents

DON'T:

❌ Don't parallelize dependent work (causes race conditions) ❌ Don't skip human review on critical features ❌ Don't assume agents understand context (be explicit) ❌ Don't forget error handling (agents will fail sometimes) ❌ Don't over-orchestrate simple tasks (use one agent when possible)

---

Summary

The 3 Core AI Patterns:

1. Agent Handoff: One agent → next agent (pipeline) 2. Fan-Out/Fan-In: Parallel work → combine (50-70% faster) 3. Human-in-the-Loop: AI work → human review → continue (safety)

Combine patterns for real-world projects.

Meta-orchestration: AI agent that coordinates other AI agents (advanced)

Error handling: Graceful degradation + retry with context

Key principle: Right agent for the job, clear handoffs, human oversight when needed

---

See also:

• ../SKILL.md - Main AI-assisted development skill
• orchestration-strategies.md - The 5 orchestration strategies
• practical-examples.md - Real-world MADUUKA and BRIGHTSOMA examples
• ../../orchestration-patterns-reference.md - General orchestration guide
• ../../prompting-patterns-reference.md - Better AI prompts

Last Updated: 2026-02-07

Orchestration Strategies for AI-Assisted Development

Purpose: Learn the 5 core strategies for coordinating multiple AI agents in software development workflows

Parent Skill: ai-assisted-development

---

Strategy 1: Sequential AI Workflow

Use when: Each AI agent needs previous agent's output

Pattern:

Agent 1 (Planning) → Output: Spec
    ↓
Agent 2 (Coding) → Input: Spec, Output: Code
    ↓
Agent 3 (Testing) → Input: Code, Output: Tests
    ↓
Agent 4 (Review) → Input: Spec + Code + Tests, Output: Feedback

Example: Feature Development

Phase 1: Planning (Agent: Claude in Plan Mode)

Prompt:

"Create a detailed specification for user authentication.

CONTEXT: Multi-tenant SaaS
CONSTRAINTS:
- JWT authentication
- Session management
- RBAC support

RETURN as structured spec with:
- User stories
- Acceptance criteria
- Data model
- API endpoints"

Output: docs/specs/auth-spec.md

Phase 2: Implementation (Agent: Claude in Code Mode)

Prompt:

"Implement user authentication using the specification.

FILE TO READ: docs/specs/auth-spec.md

CONTEXT: Read the spec and implement EXACTLY as specified.
ORCHESTRATION: This is Phase 2 of the pipeline (depends on Phase 1 spec).

CONSTRAINTS:
- Follow Laravel conventions
- Write complete code (no placeholders)
- Include error handling"

Output: Code files created per spec

Phase 3: Testing (Agent: Claude in Test Mode)

Prompt:

"Create comprehensive tests for user authentication.

FILES TO READ:
- docs/specs/auth-spec.md (what to test)
- app/Http/Controllers/AuthController.php (what code to test)

ORCHESTRATION: This is Phase 3 (depends on Phase 1 spec + Phase 2 code).

CREATE tests for:
- Registration flow
- Login flow
- Token validation
- Session management"

Output: Test files

Phase 4: Review (Agent: Claude in Review Mode)

Prompt:

"Review the authentication implementation.

FILES TO READ:
- docs/specs/auth-spec.md (requirements)
- app/Http/Controllers/AuthController.php (implementation)
- tests/Feature/AuthTest.php (tests)

ORCHESTRATION: This is Phase 4 (final review after all work done).

CHECK:
- Spec compliance
- Code quality
- Test coverage
- Security concerns"

Output: Review report with findings

Total Time: 60 minutes (15 + 25 + 15 + 5)

---

Strategy 2: Parallel AI Execution

Use when: AI agents work on independent components

Pattern:

                ┌─→ Agent 2a: Backend Code ──┐
Agent 1 (Spec) ─┼─→ Agent 2b: Frontend Code ──┼─→ Agent 3 (Integration)
                └─→ Agent 2c: Documentation ──┘

Example: Full-Stack Feature Development

Phase 1: Specification (Sequential)

Agent: Planning Agent

"Create specification for product catalog feature.

OUTPUT: docs/specs/product-catalog.md
INCLUDE:
- Backend API endpoints
- Frontend UI requirements
- Documentation needs"

Output: Spec defining all three components

Phase 2: Implementation (Parallel - 3x faster!)

Agent 2a: Database Agent (Parallel)

"Create database schema for product catalog.

READ: docs/specs/product-catalog.md
FOCUS: Only database (tables, indexes, constraints)
ORCHESTRATION: Can run in PARALLEL with Agents 2b and 2c

OUTPUT:
- Migration file
- Model file"

Time: 20 minutes

Agent 2b: API Agent (Parallel)

"Create API endpoints for product catalog.

READ: docs/specs/product-catalog.md
FOCUS: Only API layer (controllers, routes, validation)
ORCHESTRATION: Can run in PARALLEL with Agents 2a and 2c

OUTPUT:
- Controllers
- Routes
- API tests"

Time: 20 minutes

Agent 2c: UI Agent (Parallel)

"Create frontend components for product catalog.

READ: docs/specs/product-catalog.md
FOCUS: Only UI components (React/Vue)
ORCHESTRATION: Can run in PARALLEL with Agents 2a and 2b

OUTPUT:
- Product list component
- Product detail component
- Add/Edit forms"

Time: 20 minutes

Parallel Execution: All 3 agents run simultaneously = 20 minutes total Sequential would be: 20 + 20 + 20 = 60 minutes Savings: 67% faster (40 minutes saved!)

Phase 3: Integration (Sequential after Phase 2)

Agent: Integration Agent

"Integrate all product catalog components.

READ:
- Database migrations (Agent 2a output)
- API controllers (Agent 2b output)
- UI components (Agent 2c output)

ORCHESTRATION: This is Phase 3 (runs AFTER all Phase 2 agents complete).

TASKS:
- Wire UI to API
- Test end-to-end flow
- Fix integration issues"

Time: 15 minutes

Total Time: 20 (parallel) + 15 (integration) = 35 minutes vs Sequential: 60 + 15 = 75 minutes Improvement: 53% faster

---

Strategy 3: Conditional AI Routing

Use when: Different AI agents handle different project types

Pattern:

Analyze Project
  │
  ├─ IF (legacy codebase) → Refactoring Agent
  ├─ ELIF (greenfield) → Architecture Agent
  ├─ ELIF (API integration) → Integration Agent
  └─ ELSE → Ask human

Example: Project Documentation

Phase 1: Project Analysis

Agent: Analysis Agent

"Analyze this project and determine documentation needs.

SCAN:
- README.md
- Tech stack
- Existing docs/

RETURN:
- Project type (API, Full-Stack, CLI, Library)
- Current documentation state
- Recommended documentation strategy"

Output: Analysis report with routing decision

Phase 2: Documentation (Conditional)

IF project type = "API":

Agent: API Documentation Agent

"Generate OpenAPI/Swagger documentation.

ORCHESTRATION: Conditional path for API projects only.

SCAN:
- Routes
- Controllers
- Request/Response schemas

OUTPUT: docs/api-spec.yaml"

ELIF project type = "Full-Stack":

Agent: Full-Stack Documentation Agent

"Generate comprehensive docs for full-stack app.

ORCHESTRATION: Conditional path for full-stack projects only.

GENERATE:
- Architecture diagram (HLD)
- Database schema docs
- API documentation
- Frontend component docs
- Deployment guide

OUTPUT: Complete docs/ directory"

ELIF project type = "CLI":

Agent: CLI Documentation Agent

"Generate CLI tool documentation.

ORCHESTRATION: Conditional path for CLI tools only.

GENERATE:
- Command reference
- Installation guide
- Usage examples
- Troubleshooting

OUTPUT: Complete CLI manual"

ELSE:

Human intervention: Ask user what type of documentation they need.

Benefits:

• Right agent for the job (specialized expertise)
• No wasted effort on irrelevant docs
• Faster execution (focused scope)

---

Strategy 4: Looping AI Iteration

Use when: AI agent needs to refine output until quality threshold met

Pattern:

┌──────────────────┐
│ Agent generates  │
│ output           │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Quality check    │◄──┐
│ Passes? Y/N      │   │
└────────┬─────────┘   │
         │             │
    ┌────┴────┐        │
    │ NO      │ YES    │
    ▼         ▼        │
 Refine    Done     Loop back
 again               (max 3×)
    └────────────────┘

Example: Code Generation with Quality Loop

Phase: Code Generation with Quality Loop

Iteration 1:

Agent: Code Generator

"Generate user registration endpoint.

REQUIREMENTS:
- Email validation
- Password hashing
- Duplicate email check
- Return JWT token

QUALITY CRITERIA:
- PSR-12 code style
- 100% test coverage
- Zero security vulnerabilities
- Clear error messages"

Quality Check (Automated):

php -l file.php          # Syntax check
phpcs file.php           # Code style
phpstan analyze          # Static analysis
phpunit tests/           # Test coverage

IF quality < 100%: → Loop back to Code Generator with error feedback

Iteration 2 (if needed):

Agent: Code Generator

"Fix the following issues in registration endpoint:

FAILED CHECKS:
- Code style: Missing return types
- Security: Password minimum length not enforced
- Test: Edge case missing (empty email)

REFINE the code to fix these issues."

Quality Check Again:

[Run same checks]

IF quality = 100%: → Done! Move to next phase

Max iterations: 3 (prevent infinite loops)

Exit condition: Quality >= 100% OR iterations >= 3

Benefits:

• Ensures high-quality output
• Iterative refinement (like human review)
• Automated quality gates
• Prevents shipping bad code

---

Strategy 5: Retry with Fallback

Use when: AI agent might fail due to external dependencies

Pattern:

Attempt 1 → Success? YES → Done
            ↓ FAIL
Attempt 2 → Success? YES → Done
            ↓ FAIL
Attempt 3 → Success? YES → Done
            ↓ FAIL
Fallback strategy → Done (degraded mode)

Example: External API Integration

Phase: Fetch and Document External API

Attempt 1:

Agent: API Integration Agent

"Fetch OpenAPI spec from external API and generate client code.

API URL: https://api.external.com/openapi.json

ORCHESTRATION: This may fail (network/auth issues). Retry up to 3 times.

GENERATE:
- API client class
- Request/Response models
- Usage documentation"

Possible failures:

• Network timeout
• Authentication error
• Rate limit exceeded

IF FAIL → Wait 5 seconds → Retry

Attempt 2:

[Same prompt]

RETRY CONTEXT: Previous attempt failed with [error]. Trying again with longer timeout.

IF FAIL → Wait 10 seconds → Retry

Attempt 3:

[Same prompt]

RETRY CONTEXT: Second attempt failed. This is final attempt before fallback.

IF FAIL → Fallback:

Fallback Strategy:

Agent: Fallback Documentation Agent

"External API fetch failed after 3 attempts.

FALLBACK TASK:
1. Use cached OpenAPI spec (if available)
2. Generate basic client code with TODOs
3. Document manual steps for user to complete

OUTPUT:
- Partial client code
- Manual integration guide
- Troubleshooting steps"

Benefits:

• Handles transient failures gracefully
• Doesn't give up immediately
• Provides degraded functionality if needed
• User still gets value (partial output + guide)

Best Practices:

• Exponential backoff (5s, 10s, 20s)
• Max 3 retries (prevent infinite loops)
• Always have fallback plan
• Log all attempts for debugging

---

Combining Strategies

Real-world projects use MULTIPLE strategies together.

Example: Complete Feature Development

Phase 1: Planning (Sequential)
  → Agent: Planning Agent

Phase 2: Implementation (Parallel)
  ├─→ Agent 2a: Database
  ├─→ Agent 2b: API
  └─→ Agent 2c: UI

Phase 3: Quality Loop (Looping)
  → Agent: Code Review Agent
  → LOOP until quality >= 90%

Phase 4: Integration (Sequential)
  → Agent: Integration Agent

Phase 5: External Deps (Retry)
  → Agent: API Integration Agent
  → RETRY up to 3 times
  → FALLBACK if all fail

Phase 6: Documentation (Conditional)
  → IF (API project) → API Docs Agent
  → ELIF (Full-Stack) → Full-Stack Docs Agent

Total strategies used: All 5 (Sequential + Parallel + Looping + Retry + Conditional)

Result: Robust, efficient, high-quality AI-assisted development

---

Summary

The 5 Strategies:

1. Sequential: One agent after another (most common, simple, reliable) 2. Parallel: Multiple agents simultaneously (50-70% faster) 3. Conditional: Different agents for different scenarios (smart routing) 4. Looping: Iterate until quality threshold (ensure high quality) 5. Retry: Handle failures gracefully (external dependencies)

When to use each:

Combine strategies for complex projects to get benefits of all.

---

See also:

• ../SKILL.md - Main AI-assisted development skill
• ai-patterns.md - AI-specific orchestration patterns
• practical-examples.md - Real-world MADUUKA and BRIGHTSOMA examples
• ../../orchestration-patterns-reference.md - General orchestration guide
• ../../prompting-patterns-reference.md - Better AI prompts

Last Updated: 2026-02-07

Practical AI Orchestration Examples

Purpose: Real-world examples of AI agent orchestration using actual student projects

Parent Skill: ai-assisted-development

---

Overview

This guide shows real AI orchestration applied to two actual applications:

1. MADUUKA: Franchise inventory synchronization system 2. BRIGHTSOMA: AI-powered exam generation platform

Both examples use multiple AI agents coordinated through orchestration patterns.

---

Example 1: MADUUKA - Franchise Inventory Sync

Project: Multi-tenant franchise inventory management Challenge: Sync inventory across multiple franchise locations AI Orchestration Used: Sequential + Parallel + Human-in-the-Loop

Business Context

Problem:

• Multiple franchise locations
• Each has own inventory
• Need to sync stock levels across locations
• Handle conflicts (same item updated at 2 locations)
• Track inventory movements between franchises

Technical Requirements:

• Multi-tenant database (tenant isolation)
• Real-time sync (webhooks or polling)
• Conflict resolution (last-write-wins vs manual)
• Audit trail (who moved what when)
• API for mobile app

AI Orchestration Workflow

Agent 1: Requirements Agent (Sequential)

Prompt:

"Analyze franchise inventory sync requirements and create technical specification.

BUSINESS CONTEXT:
- Multi-tenant SaaS (each franchise = tenant)
- Inventory items have: SKU, quantity, location_id, tenant_id
- Sync scenarios:
  1. Location A updates quantity → sync to central DB
  2. Location B requests item → check all locations
  3. Transfer: Location A → Location B (decrement A, increment B)

TECHNICAL CONSTRAINTS:
- MySQL 8.x with tenant_id in all tables
- Laravel 10 backend
- Real-time sync (max 5 second delay)
- Conflict resolution: last-write-wins + log conflicts

OUTPUT: Create structured spec with:
- Data model (tables, columns, indexes, relationships)
- Sync algorithm (step-by-step logic)
- API endpoints (routes, requests, responses)
- Conflict resolution rules
- Audit trail requirements

FILE: docs/specs/inventory-sync-spec.md"

Output: docs/specs/inventory-sync-spec.md (comprehensive specification)

Time: 15 minutes

[GATE 1: Human Review]

• Check: Is the data model correct? Tenant isolation enforced?
• Check: Does sync algorithm handle conflicts properly?
• Decision: ✅ Approved (or ❌ Revise spec)

---

Agents 2a, 2b, 2c: Implementation (Parallel)

Now that spec is approved, spawn 3 agents to work in parallel:

Agent 2a: Database Agent

Prompt:

"Create database schema for inventory sync.

READ: docs/specs/inventory-sync-spec.md

FOCUS: Database layer only (migrations, models, stored procedures)

ORCHESTRATION: This runs in PARALLEL with Agents 2b and 2c

CREATE:
1. Migration: inventory_items table
   - Columns: id, tenant_id, sku, name, quantity, location_id, updated_at
   - Indexes: (tenant_id, sku), (location_id), (updated_at)
   - Constraints: quantity >= 0, foreign keys

2. Migration: inventory_movements table (audit trail)
   - Columns: id, tenant_id, item_id, from_location_id, to_location_id, quantity, moved_by, moved_at
   - Indexes: (tenant_id, moved_at), (item_id)

3. Model: InventoryItem.php (with tenant scope)
4. Model: InventoryMovement.php (with tenant scope)
5. Stored procedure: sp_transfer_inventory (atomic transfer)

CONSTRAINTS:
- Tenant isolation (tenant_id in all queries)
- Foreign keys with CASCADE
- Timestamps for audit trail

FILES:
- database/migrations/YYYY_MM_DD_create_inventory_tables.php
- app/Models/InventoryItem.php
- app/Models/InventoryMovement.php
- database/procedures/sp_transfer_inventory.sql"

Time: 20 minutes

---

Agent 2b: API Agent

Prompt:

"Create API endpoints for inventory sync.

READ: docs/specs/inventory-sync-spec.md

FOCUS: API layer only (controllers, routes, requests, validation)

ORCHESTRATION: This runs in PARALLEL with Agents 2a and 2c

CREATE:
1. POST /api/inventory/sync
   - Receives inventory updates from franchise location
   - Validates tenant_id, location_id, SKU, quantity
   - Detects conflicts (compare updated_at)
   - Logs conflict if detected
   - Updates inventory
   - Returns success/conflict response

2. GET /api/inventory/availability/{sku}
   - Returns item availability across all locations for tenant
   - Aggregates quantity from all locations
   - Returns per-location breakdown

3. POST /api/inventory/transfer
   - Transfers inventory between locations
   - Validates: from_location has sufficient quantity
   - Uses sp_transfer_inventory (atomic)
   - Creates audit trail (inventory_movements)
   - Returns success/failure

CONSTRAINTS:
- Tenant isolation (all queries scoped to tenant_id)
- Input validation (Laravel FormRequest)
- JSON responses (consistent format)
- Error handling (422 for validation, 409 for conflicts)

FILES:
- app/Http/Controllers/Api/InventoryController.php
- app/Http/Requests/InventorySyncRequest.php
- app/Http/Requests/InventoryTransferRequest.php
- routes/api.php (register routes)"

Time: 20 minutes

---

Agent 2c: Testing Agent

Prompt:

"Create comprehensive tests for inventory sync.

READ: docs/specs/inventory-sync-spec.md

FOCUS: Tests only (unit + integration)

ORCHESTRATION: This runs in PARALLEL with Agents 2a and 2b

CREATE:
1. Unit tests for InventoryItem model
   - Test tenant scoping
   - Test relationships
   - Test validation rules

2. Unit tests for InventoryMovement model
   - Test audit trail creation
   - Test relationships

3. Integration tests for inventory sync API
   - Test scenario: Location A syncs quantity → DB updated
   - Test scenario: Conflict detected → logged + last-write-wins
   - Test scenario: Transfer A → B → quantities updated atomically
   - Test scenario: Availability check → correct aggregation
   - Test scenario: Tenant isolation → Tenant A cannot see Tenant B data

4. Test edge cases
   - Negative quantity (should fail)
   - Transfer more than available (should fail)
   - Concurrent updates (conflict resolution)
   - Non-existent SKU (should create or fail based on spec)

CONSTRAINTS:
- Use Laravel factories for test data
- Use database transactions (rollback after each test)
- Test both success and failure paths
- Assert: HTTP status codes, JSON structure, database state

FILES:
- tests/Unit/Models/InventoryItemTest.php
- tests/Unit/Models/InventoryMovementTest.php
- tests/Feature/Api/InventorySyncTest.php
- database/factories/InventoryItemFactory.php"

Time: 20 minutes

---

Parallel Execution:

• All 3 agents (2a, 2b, 2c) run simultaneously
• Total time: 20 minutes (not 60!)
• Speedup: 67% faster than sequential

---

Agent 3: Testing Agent (Sequential after Agent 2)

Prompt:

"Run all tests and verify inventory sync implementation.

ORCHESTRATION: This runs AFTER Agents 2a, 2b, 2c complete (sequential).

TASK:
1. Run migrations: php artisan migrate
2. Run all tests: php artisan test --filter=Inventory
3. Check coverage: php artisan test --coverage
4. Verify: All tests pass, >80% coverage

IF tests fail:
  - Report failures to human
  - Human reviews and decides: fix or revise spec

IF tests pass:
  - Generate test report
  - Mark phase complete

FILE: docs/reports/inventory-sync-test-report.md"

Time: 10 minutes

[GATE 2: Human Review]

• Check: All tests passing? Coverage sufficient?
• Check: Edge cases handled correctly?
• Decision: ✅ Approved for production | ❌ Fix issues

---

Agent 4: Review Agent (Sequential after Agent 3)

Prompt:

"Review entire inventory sync implementation for quality and security.

READ:
- docs/specs/inventory-sync-spec.md (requirements)
- database/migrations/ (database implementation)
- app/Models/ (models)
- app/Http/Controllers/Api/InventoryController.php (API)
- tests/ (test coverage)
- docs/reports/inventory-sync-test-report.md (test results)

ORCHESTRATION: This is final review phase (sequential after all work done).

CHECK:
1. Spec compliance: Does code match spec?
2. Tenant isolation: Is tenant_id enforced everywhere?
3. Security: SQL injection risks? XSS? CSRF?
4. Performance: Are indexes correct? N+1 queries?
5. Error handling: All edge cases handled?
6. Code quality: PSR-12? Type hints? Docblocks?
7. Tests: Coverage sufficient? Edge cases tested?

RETURN:
- Compliance report (spec vs implementation)
- Security findings (critical, high, medium, low)
- Performance recommendations
- Code quality score (0-100)
- Approval: YES/NO with rationale

FILE: docs/reports/inventory-sync-review-report.md"

Time: 15 minutes

[GATE 3: Final Human Review]

• Check: Review agent findings acceptable?
• Decision: ✅ Ship to production | ❌ Address critical findings

---

Total Time Breakdown

If all sequential: 15 + 20 + 20 + 20 + 10 + 15 = 100 minutes + 15 min reviews = 115 minutes

With orchestration: 75 minutes

Savings: 40 minutes (35% faster)

---

Example 2: BRIGHTSOMA - AI Exam Question Generation

Project: AI-powered exam generation for teachers Challenge: Generate high-quality exam questions from curriculum content AI Orchestration Used: Looping + Retry + Human-in-the-Loop

Business Context

Problem:

• Teachers need exam questions based on curriculum
• Questions must be: relevant, appropriate difficulty, no duplicates
• Support multiple question types (MCQ, True/False, Short Answer, Essay)
• Questions must be tagged (topic, difficulty, bloom's taxonomy level)
• Generate answer keys and rubrics

Technical Requirements:

• AI generates questions (GPT-4, Claude, or Gemini)
• Quality validation (relevance, grammar, difficulty)
• Deduplication (no repeated questions)
• Export to PDF (formatted exam + answer key)

AI Orchestration Workflow

Agent 1: Question Generator (Looping)

Prompt:

"Generate exam questions from curriculum content.

CONTEXT:
- Subject: Biology
- Topic: Cell Biology (Mitosis and Meiosis)
- Target: Grade 10 students
- Difficulty: Medium
- Question types: 10 MCQ + 5 Short Answer + 2 Essay

READ: curriculum/biology/cell-biology.md

ORCHESTRATION: Looping agent (generate questions iteratively until quality threshold met)

FOR EACH question type:
  1. Read curriculum content
  2. Generate question + answer + rubric
  3. Tag: topic, difficulty (1-5), bloom's level (Remember/Understand/Apply/Analyze)
  4. Check quality (Agent 2 validates)
  5. IF quality < 80% → regenerate (max 3 attempts)
  6. IF quality >= 80% → accept and continue

CONSTRAINTS:
- No duplicate questions (check against existing)
- Questions must reference specific curriculum concepts
- MCQ: 4 options, 1 correct
- Short Answer: 2-3 sentence expected answer
- Essay: Clear rubric (5 points breakdown)

OUTPUT:
- questions.json (structured format)
- Contains: question_id, type, question_text, options (MCQ), correct_answer, rubric, tags

QUALITY CRITERIA:
- Relevance: Does question test curriculum concept? (Yes/No)
- Clarity: Is question unambiguous? (Yes/No)
- Difficulty: Matches target level? (Yes/No)
- Grammar: No errors? (Yes/No)

Quality = (Relevance + Clarity + Difficulty + Grammar) / 4 * 100%
Accept if >= 80%"

Looping Execution:

Iteration 1: Generate Question 1
  → Send to Agent 2 (Validator)
  → Quality = 90% → ACCEPT

Iteration 2: Generate Question 2
  → Send to Agent 2 (Validator)
  → Quality = 65% (poor clarity) → REJECT
  → Regenerate with feedback: "Improve clarity - question is ambiguous"
  → Quality = 85% → ACCEPT

... (continue for all 17 questions)

Exit conditions:
- All 17 questions accepted (quality >= 80%), OR
- Max 3 regeneration attempts per question, OR
- Human intervention requested (if quality consistently low)

Time: 30 minutes (with looping iterations)

---

Agent 2: Validator (Quality Check)

Prompt:

"Validate exam question quality.

ORCHESTRATION: Validation agent called by Agent 1 (looping pattern)

INPUT: Single question (JSON)

VALIDATE:
1. Relevance: Check question against curriculum/biology/cell-biology.md
   - Does it test a concept from curriculum? (Yes/No)
   - Which concept? (name it)

2. Clarity: Analyze question text
   - Is wording clear and unambiguous? (Yes/No)
   - Any confusing phrasing? (list issues if any)

3. Difficulty: Estimate difficulty
   - Is it appropriate for Grade 10? (Yes/No)
   - Estimated difficulty: 1-5 (where 3 = medium)
   - Does it match target difficulty (medium)? (Yes/No)

4. Grammar: Check for errors
   - Any grammar/spelling errors? (Yes/No)
   - List errors if found

5. For MCQ: Check options
   - Are all 4 options plausible? (Yes/No)
   - Is correct answer actually correct? (Yes/No)
   - Are distractors reasonable? (Yes/No)

SCORING:
- Relevance: 25 points
- Clarity: 25 points
- Difficulty match: 25 points
- Grammar: 25 points
Total: 0-100

RETURN:
{
  "quality_score": 85,
  "passed": true,  // true if >= 80
  "feedback": {
    "relevance": "Tests mitosis phases - GOOD",
    "clarity": "Slightly ambiguous wording in option C",
    "difficulty": "Appropriate for Grade 10",
    "grammar": "No errors"
  },
  "action": "ACCEPT" // or "REVISE"
}"

Time: 2 minutes per question

---

Exit Conditions:

WHEN to stop looping:

1. Success: All questions meet quality threshold (>= 80%) 2. Max attempts: Question regenerated 3 times but still < 80% → flag for human review 3. Human intervention: Human manually reviews flagged questions and decides (accept/reject/edit)

---

Agent 3: Rubric Generator (Sequential)

Prompt:

"Generate grading rubrics for short answer and essay questions.

READ: questions.json (Agent 1 output - accepted questions only)

ORCHESTRATION: Sequential (runs AFTER Agent 1 complete)

FOR EACH short answer question:
  CREATE rubric:
  - 2 points: Correct concept identified
  - 1 point: Partial understanding
  - 0 points: Incorrect or missing

FOR EACH essay question:
  CREATE detailed rubric (5 points total):
  - 1 point: Introduction (clear thesis)
  - 2 points: Body (supporting arguments with evidence)
  - 1 point: Conclusion (summary + insights)
  - 1 point: Grammar and organization

OUTPUT: rubrics.json"

Time: 10 minutes

---

Agent 4: PDF Generator (Sequential)

Prompt:

"Generate formatted exam and answer key as PDFs.

READ:
- questions.json (all questions)
- rubrics.json (grading rubrics)

ORCHESTRATION: Sequential (runs AFTER Agents 1, 2, 3 complete)

GENERATE:
1. exam.pdf:
   - Header: School name, subject, date, student name field
   - Questions grouped by type (MCQ, Short Answer, Essay)
   - Clear numbering
   - Space for answers
   - Professional formatting

2. answer_key.pdf:
   - All correct answers
   - Rubrics for subjective questions
   - Point allocation
   - Marking guidance

CONSTRAINTS:
- Use LaTeX for formatting
- Professional layout (margins, fonts, spacing)
- Print-friendly (black and white)

OUTPUT:
- exams/biology-cell-biology-exam.pdf
- exams/biology-cell-biology-answer-key.pdf"

Time: 5 minutes

---

Error Handling (Retry Strategy)

What if AI model fails or times out?

Attempt 1: Call AI API to generate question
  → Timeout (30 seconds elapsed)

  RETRY (wait 5 seconds)

Attempt 2: Call AI API again
  → API rate limit exceeded (429 error)

  RETRY (wait 30 seconds - longer backoff)

Attempt 3: Call AI API again
  → Success! Question generated

IF all 3 attempts fail:
  FALLBACK: Use template-based question generation
  - Less sophisticated, but guarantees output
  - Flag questions as "template-generated" for human review

---

Total Time Breakdown

Manual (teacher creates questions): 2-3 hours

With AI orchestration: 45 minutes

Savings: 135 minutes (75% faster) + higher quality (validated)

---

Key Takeaways from Both Examples

MADUUKA (Inventory Sync)

Orchestration strategies used:

• ✅ Sequential (Requirements → Implementation → Testing → Review)
• ✅ Parallel (Database + API + Tests simultaneously)
• ✅ Human-in-the-Loop (3 approval gates)

Result: 75 minutes (vs 115 sequential) = 35% faster

BRIGHTSOMA (Exam Generation)

Orchestration strategies used:

• ✅ Looping (Generate questions until quality threshold met)
• ✅ Retry (Handle AI API failures gracefully)
• ✅ Sequential (Generator → Rubrics → PDF)

Result: 45 minutes (vs 180 manual) = 75% faster + higher quality

---

Practical Tips

When Orchestrating AI Agents:

1. Break work into focused agents: Each agent does ONE job well 2. Parallelize when possible: Database + API + Tests = 3x faster 3. Add quality loops: Don't accept poor output, regenerate 4. Include human gates: High-risk work needs human approval 5. Handle failures gracefully: Retry with backoff, have fallbacks 6. Provide clear context: Each agent gets spec, input files, orchestration info 7. Log everything: Agent interactions, decisions, outputs

Common Pitfalls:

❌ Over-orchestrating simple tasks: Sometimes 1 agent is enough ❌ Parallelizing dependent work: Causes race conditions and errors ❌ No quality validation: Accepting poor AI output ❌ Infinite loops: Always set max iterations and exit conditions ❌ No fallback plans: When AI fails, have degraded mode

---

Summary

Real-world AI orchestration delivers:

• 30-75% faster development (parallelization + automation)
• Higher quality output (validation loops, human gates)
• Better consistency (AI follows patterns reliably)
• Reduced errors (validation catches issues early)

Key principle: Right agent, right task, clear coordination, human oversight

---

See also:

• ../SKILL.md - Main AI-assisted development skill
• orchestration-strategies.md - The 5 orchestration strategies
• ai-patterns.md - AI-specific orchestration patterns
• ../../feature-planning/SKILL.md - Creating implementation plans
• ../../prompting-patterns-reference.md - Better AI prompts

Last Updated: 2026-02-07

ai-assisted-development Deep Dive

This file contains the extended guidance moved out of ../SKILL.md so the skill entrypoint stays under the repository size limit.

Included Sections

• When to Use This Skill
• Core Concepts (Quick Reference)
• The 5 Orchestration Strategies (Summary)
• The 3 AI Orchestration Patterns (Summary)
• Quick Reference: When to Use Which
• Real-World Examples (Summary)
• Practical Workflow: How to Apply This Skill
• Best Practices
• Integration with Other Skills
• Summary

When to Use This Skill

✅ USE when:

• Coordinating multiple AI agents on a single project
• Planning complex features with AI assistance
• Creating workflows that involve AI + human collaboration
• Setting up multi-agent development pipelines
• Optimizing AI-assisted development processes

❌ DON'T USE when:

• Single simple task with one AI agent (just use that agent directly)
• Manual development without AI assistance
• Basic prompting (use prompting-patterns-reference.md instead)

---

Core Concepts (Quick Reference)

1. AI Agent (Definition)

An AI agent is a specialized AI assistant that handles ONE category of work.

Examples:

• Planning Agent: Analyzes requirements, creates specs
• Coding Agent: Writes implementation code
• Testing Agent: Creates test cases
• Review Agent: Reviews code quality
• Documentation Agent: Writes documentation

Each agent has focused expertise and context.

2. Orchestration (for AI Development)

Orchestration = Coordinating multiple AI agents to work on a project together.

Example workflow:

Planning Agent: Create feature spec
    ↓ (spec output)
Coding Agent: Implement feature (uses spec as input)
    ↓ (code output)
Testing Agent: Create tests (uses code as input)
    ↓ (tests output)
Review Agent: Review everything (uses spec + code + tests)
    ↓
Human: Approve and deploy

3. Execution Strategies

• Sequential: One agent after another (most common)
• Parallel: Multiple agents working simultaneously (50-70% faster)
• Conditional: Different agents based on project type
• Looping: Iterate until quality threshold met
• Retry: Re-run agent if output unsatisfactory

---

The 5 Orchestration Strategies (Summary)

📖 See [orchestration-strategies.md](references/orchestration-strategies.md) for complete details with code examples.

Strategy 1: Sequential AI Workflow

Use when: Each AI agent needs previous agent's output

Pattern:

Agent 1 (Planning) → Spec
    ↓
Agent 2 (Coding) → Code
    ↓
Agent 3 (Testing) → Tests
    ↓
Agent 4 (Review) → Feedback

Example: Feature development pipeline (planning → coding → testing → review)

Time: 60 minutes (15 + 25 + 15 + 5)

---

Strategy 2: Parallel AI Execution

Use when: AI agents work on independent components

Pattern:

                ┌─→ Agent 2a: Backend ──┐
Agent 1 (Spec) ─┼─→ Agent 2b: Frontend ─┼─→ Agent 3 (Integration)
                └─→ Agent 2c: Docs ─────┘

Example: Full-stack feature (backend + frontend + docs simultaneously)

Time: 20 minutes parallel (vs 60 sequential) = 67% faster

---

Strategy 3: Conditional AI Routing

Use when: Different AI agents handle different project types

Pattern:

Analyze Project
  │
  ├─ IF (legacy) → Refactoring Agent
  ├─ ELIF (greenfield) → Architecture Agent
  ├─ ELIF (API) → Integration Agent
  └─ ELSE → Ask human

Example: Documentation generation based on project type

---

Strategy 4: Looping AI Iteration

Use when: AI agent needs to refine output until quality threshold met

Pattern:

┌──────────────────┐
│ Agent generates  │
└────────┬─────────┘
         │
         ▼
┌──────────────────┐
│ Quality >= 80%?  │◄──┐
│ YES → Done       │   │
│ NO → Refine      │───┘
└──────────────────┘
(max 3 iterations)

Example: Code generation with quality loop (syntax → style → tests)

---

Strategy 5: Retry with Fallback

Use when: AI agent might fail due to external dependencies

Pattern:

Attempt 1 → Success? YES → Done
            ↓ FAIL (wait 5s)
Attempt 2 → Success? YES → Done
            ↓ FAIL (wait 10s)
Attempt 3 → Success? YES → Done
            ↓ FAIL
Fallback → Degraded mode

Example: External API integration (fetch schema, retry on timeout, use cache if all fail)

---

The 3 AI Orchestration Patterns (Summary)

📖 See [ai-patterns.md](references/ai-patterns.md) for complete details with code examples.

Pattern 1: Agent Handoff (Pipeline)

Use case: One AI agent completes work, passes output to next AI agent

Flow:

Agent A → Output → Agent B → Output → Agent C → Done

Example: Requirements Agent → Specification Agent → Implementation Agent

Key principle: Each agent's output is next agent's input

---

Pattern 2: Fan-Out/Fan-In (Parallel + Combine)

Use case: Split work across multiple AI agents, then combine results

Flow:

                ┌─→ Agent A ──┐
Input (split) ──┼─→ Agent B ──┼─→ Combine → Output
                └─→ Agent C ──┘

Example: Multi-component documentation (database + API + UI docs in parallel, then combine)

Speedup: 50-70% faster than sequential

---

Pattern 3: Human-in-the-Loop (Gated Approval)

Use case: AI agents generate work, human approves before continuing

Flow:

Agent 1 → Output → [HUMAN REVIEW] → Approved? YES → Agent 2
                                                 ↓ NO
                                              Revise

Example: Spec → [Review] → Code → [Review] → Tests → [Review] → Deploy

Benefits: Safety, quality control, compliance, learning

---

Quick Reference: When to Use Which

---

Real-World Examples (Summary)

📖 See [practical-examples.md](references/practical-examples.md) for complete detailed walkthroughs.

Example 1: MADUUKA - Franchise Inventory Sync

Project: Multi-tenant franchise inventory management

Orchestration used:

• Sequential (Requirements → Implementation → Testing → Review)
• Parallel (Database + API + Tests simultaneously)
• Human-in-the-Loop (3 approval gates)

Agents: 1. Requirements Agent: Create spec (15 min) 2. Database Agent: Schema + models (20 min) ─┐ 3. API Agent: Endpoints + validation (20 min) ├─→ Parallel 4. Testing Agent: Tests (20 min) ─────────────┘ 5. Integration Agent: Run tests (10 min) 6. Review Agent: Quality check (15 min)

Result: 75 minutes (vs 115 sequential) = 35% faster

---

Example 2: BRIGHTSOMA - AI Exam Generation

Project: AI-powered exam question generator

Orchestration used:

• Looping (Generate questions until quality >= 80%)
• Retry (Handle AI API failures)
• Sequential (Generator → Rubrics → PDF)

Agents: 1. Question Generator: 17 questions with quality loops (30 min) 2. Validator: Check quality (embedded in loop) 3. Rubric Generator: Grading rubrics (10 min) 4. PDF Generator: Formatted exam + answer key (5 min)

Result: 45 minutes (vs 180 manual) = 75% faster + higher quality

---

Practical Workflow: How to Apply This Skill

Step 1: Analyze Your Task

Questions to ask:

• How many components does this feature have?
• Can any work be done in parallel?
• Are there external dependencies (APIs, databases)?
• Is this high-risk (needs human approval)?
• What's the quality threshold?

Step 2: Choose Orchestration Strategies

Based on analysis:

• Sequential dependencies? → Use Sequential strategy
• Independent components? → Use Parallel strategy
• Different project types? → Use Conditional strategy
• Quality threshold? → Use Looping strategy
• External APIs? → Use Retry strategy

Combine multiple strategies for complex projects.

Step 3: Design Agent Workflow

Define agents:

• What does each agent do? (ONE job each)
• What input does each need?
• What output does each produce?
• What's the execution order?

Example:

Agent 1: Planning Agent
  Input: User requirements
  Output: docs/specs/feature-spec.md
  Execution: Sequential (first)

Agent 2a: Backend Agent
  Input: docs/specs/feature-spec.md
  Output: Backend code
  Execution: Parallel with 2b and 2c

Agent 2b: Frontend Agent
  Input: docs/specs/feature-spec.md
  Output: Frontend code
  Execution: Parallel with 2a and 2c

Agent 2c: Testing Agent
  Input: docs/specs/feature-spec.md
  Output: Test files
  Execution: Parallel with 2a and 2b

Agent 3: Integration Agent
  Input: Backend + Frontend + Tests
  Output: Integrated feature
  Execution: Sequential (after 2a, 2b, 2c)

Step 4: Write Clear Prompts

Use prompting patterns (see prompting-patterns-reference.md):

"[TASK]

FILE TO READ: [input file from previous agent]

CONTEXT: [Why this is needed, what it builds on]

ORCHESTRATION: [Sequential/Parallel/Conditional/Looping/Retry]
[Dependencies or parallel info]

CONSTRAINTS:
- [Technical constraint 1]
- [Limit 2]
- [Standard 3]

OUTPUT: [Expected output files/format]"

Step 5: Add Human Gates (if needed)

For high-risk work:

Agent → Output → [HUMAN REVIEW] → Approved? → Next agent

What to check:

• Security implications
• Business logic correctness
• Compliance requirements
• Performance concerns

Step 6: Execute and Monitor

Track:

• Which agent is running
• What output was produced
• Quality metrics (if looping)
• Time spent per agent
• Any failures or retries

Log everything for debugging and optimization.

---

Best Practices

DO:

✅ Break work into focused agents - Each agent does ONE job well ✅ Parallelize when possible - 50-70% faster execution ✅ Add quality loops - Don't accept poor output ✅ Include human gates - High-risk work needs approval ✅ Handle failures gracefully - Retry with backoff, have fallbacks ✅ Provide clear context - Each agent gets spec, input files, orchestration info ✅ Log everything - Agent interactions, decisions, outputs ✅ Combine strategies - Use multiple for complex projects

DON'T:

❌ Don't over-orchestrate simple tasks - Sometimes 1 agent is enough ❌ Don't parallelize dependent work - Causes race conditions ❌ Don't skip quality validation - AI output needs verification ❌ Don't forget exit conditions - Loops must end ❌ Don't assume AI is perfect - Plan for failures ❌ Don't skip human review - Critical features need oversight

---

Integration with Other Skills

• feature-planning: Use AI agents to execute implementation plans
• prompting-patterns-reference: Better prompts = better agent output
• orchestration-patterns-reference: General orchestration concepts
• custom-sub-agents: Create specialized AI agents

---

Summary

AI-assisted development orchestration delivers:

• 30-75% faster development (parallelization + automation)
• Higher quality output (validation loops, human gates)
• Better consistency (AI follows patterns reliably)
• Reduced errors (validation catches issues early)

Key concepts:

• Break work into focused agents (ONE job each)
• Use 5 orchestration strategies (Sequential, Parallel, Conditional, Looping, Retry)
• Apply 3 AI patterns (Agent Handoff, Fan-Out/Fan-In, Human-in-the-Loop)
• Combine strategies for complex projects
• Always include quality validation and human oversight

Next steps: 1. 📖 Read orchestration-strategies.md for detailed strategy examples 2. 📖 Read ai-patterns.md for AI-specific patterns 3. 📖 Read practical-examples.md for real MADUUKA and BRIGHTSOMA walkthroughs 4. Apply to your own projects!

---

Related Skills:

• feature-planning/ - Create implementation plans that AI agents can execute
• prompting-patterns-reference.md - Better prompts for better AI output
• orchestration-patterns-reference.md - General orchestration concepts
• custom-sub-agents/ - Create specialized AI agents

Last Updated: 2026-02-07 Line Count: ~490 lines (compliant with doc-standards.md)