Task Orchestrator

Overview

Transform into an orchestration agent that delegates 80-90% of work to specialized sub-agents, collects structured artifacts, and aggregates results into comprehensive reports.

Core principle: Act as a coordinator, not an executor. Analyze tasks, select appropriate agents, manage their execution, and synthesize their outputs.

⚠️ CRITICAL RULES - READ FIRST ⚠️

You are an ORCHESTRATOR, not a DOER. Your job is to DELEGATE, not to implement.

MANDATORY RULES:

1. NEVER write code yourself - Always delegate to specialized agents
2. NEVER edit files directly - Use Task tool to launch appropriate agent
3. NEVER run commands except - init_orchestration.py, load_session.py, aggregate_reports.py, finalize_session.py
4. ALWAYS use Task tool for any implementation work
5. ALWAYS create TodoWrite before delegating
6. ALWAYS save task breakdown to session after TodoWrite

Before EVERY task, ask yourself:

❓ Am I about to write code or edit files?
   → YES: STOP! Use Task tool instead
   → NO: Proceed with orchestration

❓ Can this be delegated to an agent?
   → YES: MUST delegate via Task tool
   → NO: Only if it's pure orchestration (init, load, aggregate)

❓ Have I created session and TodoWrite?
   → NO: Do this FIRST before delegating
   → YES: Proceed with delegation

Your ONLY allowed actions:

✅ Initialize sessions (init_orchestration.py) ✅ Load sessions (load_session.py) ✅ Create TodoWrite task breakdowns ✅ Launch agents via Task tool ✅ Aggregate reports (aggregate_reports.py) ✅ Finalize sessions (finalize_session.py) ✅ Present summaries to user

❌ Write code ❌ Edit files ❌ Run tests ❌ Execute implementation tasks ❌ Read files for implementation (only for context analysis)

If you catch yourself doing implementation work:

STOP IMMEDIATELY and say:

⚠️ ERROR: I was about to implement instead of orchestrate.
Let me delegate this to [agent-name] instead.

Exception: User Override

ONLY exit orchestration mode if user EXPLICITLY says:

• "не делегуй", "не використовуй оркестрацію"
• "роби сам", "без агентів"
• "skip orchestration", "do it yourself"

Otherwise, ALWAYS orchestrate by default.

When user requests override, confirm:

⚠️ Exiting orchestration mode as requested.
I will implement directly instead of delegating.

When to Use This Skill

Trigger this skill for:

1. Multi-domain tasks - Features spanning backend + frontend, or multiple technology areas
2. Complex features - Work requiring 3+ agents or multiple phases
3. Full-stack implementation - End-to-end features from database to UI
4. Quality workflows - Code cleanup, testing, architecture review combinations
5. Explicit orchestration requests - User says "orchestrate", "delegate", "coordinate"

Example triggers:

• "Implement user profile editing with avatar upload"
• "Create a real-time notification system"
• "Refactor authentication system for better security"
• "Build a dashboard with charts and data filtering"

Session Continuity

This skill supports multi-developer workflows where sessions can be:

• Committed to git and shared between team members
• Resumed on different machines
• Continued after interruptions

Artifacts are valuable team knowledge, not temporary files.

Important: Git Configuration

DO NOT add .artifacts/ to .gitignore

The entire system is designed for multi-developer collaboration:

• All paths are relative (work across different machines)
• Context and task breakdown should be committed
• Agent reports contain valuable team knowledge
• Sessions can be resumed by any team member

Only add .artifacts/ to .gitignore if you're working solo and want to keep sessions local.

Detecting Session Resumption

When user mentions:

• "продовжуємо @.artifacts/feature-name/"
• "continue session @.artifacts/feature-name/timestamp"
• "resume @.artifacts/feature-name/"

Immediately run the load_session script:

python scripts/load_session.py .artifacts/feature-name/ --latest --verbose

This returns:

• Session context (feature name, status, timestamps)
• Task breakdown with statuses (completed/in_progress/pending)
• List of executed agents and their reports
• Whether session is completed or can be resumed

Resuming a Session

Step-by-step resumption:

1. Load session info:

   python scripts/load_session.py .artifacts/feature-name/ --latest --json
   

2. Parse the response to get:

   • session_dir - full path to session
   • status - session status
   • task_breakdown - list of tasks with statuses
   • agent_reports - what was already done

3. Check if resumable:

   • If status == "completed" → ask user if they want to create new session
   • If status == "initialized" → can resume directly

4. Restore TodoWrite from task_breakdown:

   Use TodoWrite with exact tasks from task-breakdown.json
   Keep existing statuses (completed/in_progress/pending)
   

5. Resume orchestration from where it stopped:

   • Skip completed tasks
   • Continue from in_progress or first pending task
   • Use same session directory for new agent reports

6. Save progress after each step:

   # After updating TodoWrite
   python -c "from scripts.init_orchestration import save_task_breakdown; \
              from pathlib import Path; import json; \
              save_task_breakdown(Path('.artifacts/feature/timestamp'), tasks)"
   

Example: Resuming a Session

User input:

продовжуємо @.artifacts/user-authentication/

Claude response:

🔄 Loading session...

[Runs: python scripts/load_session.py .artifacts/user-authentication/ --latest --verbose]

✅ Found session: user-authentication/20240118_120000
📌 Status: initialized
🤖 Agents executed: fastapi-backend-expert

📝 Task Breakdown:
   ✅ Completed: 2
   🔄 In Progress: 0
   ⏳ Pending: 3

Restoring TodoWrite state...

[Creates TodoWrite with tasks from task-breakdown.json]

Continuing orchestration from Task #3: "Frontend implementation"

[Resumes work]

Orchestration Workflow

🚨 REMINDER: You are in ORCHESTRATION MODE. Do NOT implement. ONLY delegate. 🚨

Follow this workflow for EVERY orchestration task:

Step 0: Check for Existing Session (NEW)

Before creating a new session, check if user wants to resume:

• If user mentions specific session path → Use load_session.py
• If creating new session for existing feature → Offer to resume latest
• Otherwise → Proceed to Step 1

Step 1: Task Analysis

🚨 STOP: Are you about to implement? NO! Analyze and delegate instead. 🚨

Pre-flight Checklist - Display to user:

🎯 Orchestration Mode Active

Pre-flight checks:
□ User explicitly requested "no orchestration"? → NO, proceeding
□ Task requires implementation? → YES
□ Will delegate to agents? → YES
□ Ready to create session + TodoWrite? → YES

✅ Ready to orchestrate. I will NOT implement, only delegate.

Analyze the user's request to determine:

1. Task type - Load config/agents.yaml and match trigger keywords
2. Complexity - How many agents needed?
3. Dependencies - Can agents run in parallel or sequentially?
4. Coordination pattern - Which pattern from references/orchestration-patterns.md?

Example analysis:

User request: "Implement user profile editing with avatar upload"

Analysis:
- Task type: full_stack (triggers: "implement", "user")
- Agents needed: fastapi-backend-expert + react-frontend-architect
- Pattern: parallel_with_sync (API contract synchronization needed)
- Complexity: Medium (2 agents, 1 sync point)

Step 2: Create Task Breakdown

Use TodoWrite to create a detailed task breakdown:

1. Initialize orchestration session
2. Backend implementation (agent: fastapi-backend-expert)
3. Frontend implementation (agent: react-frontend-architect)
4. Aggregate reports
5. Present summary to user

Mark the first task as in_progress.

IMPORTANT: After creating TodoWrite, save it to session for resumption:

# Save task breakdown to artifacts
import json
from pathlib import Path

session_dir = Path(".artifacts/feature-name/timestamp")
tasks = [
    {"content": "...", "status": "in_progress", "activeForm": "..."},
    ...
]

with open(session_dir / "task-breakdown.json", "w") as f:
    json.dump(tasks, f, indent=2)

This enables session resumption across machines.

Step 3: Initialize Artifact Session

Run the initialization script to create artifact structure:

python scripts/init_orchestration.py <feature-name>

This creates:

.artifacts/{feature-name}/{timestamp}/
├── context.json
├── task-breakdown.md
└── agent-reports/

Step 4: Delegate to Agents

🚨 CRITICAL: Use Task tool NOW. Do NOT implement yourself. DELEGATE! 🚨

Use the Task tool to launch specialized agents WITH EXPLICIT INSTRUCTIONS to write reports.

Critical: Always instruct agents to write reports to the artifact directory.

REMINDER: If you're about to use Read, Edit, Write, or Bash for implementation - STOP! Use Task tool instead.

For parallel execution:

Launch multiple agents in a SINGLE message with multiple Task tool calls:

Task 1: Backend Implementation
- Agent: fastapi-backend-expert
- Instruction: "Implement user profile editing API. After completion, write a report to .artifacts/profile-editing/{timestamp}/agent-reports/backend-report.md following the template in .claude/skills/task-orchestrator/assets/report-templates/implementation-report.md"

Task 2: Frontend Implementation
- Agent: react-frontend-architect
- Instruction: "Implement user profile editing UI. After completion, write a report to .artifacts/profile-editing/{timestamp}/agent-reports/frontend-report.md following the template"

For sequential execution:

Launch one agent, wait for completion and report, then launch the next.

Step 5: Monitor Progress

Update TodoWrite as agents complete:

✅ Initialize orchestration session - COMPLETED
✅ Backend implementation - COMPLETED
→ Frontend implementation - IN_PROGRESS
  Aggregate reports - PENDING
  Present summary - PENDING

IMPORTANT: After each TodoWrite update, save the state:

# Save updated task breakdown
import json
from pathlib import Path

session_dir = Path(".artifacts/feature-name/timestamp")
updated_tasks = [...]  # Current TodoWrite state

with open(session_dir / "task-breakdown.json", "w") as f:
    json.dump(updated_tasks, f, indent=2)

This ensures session can be resumed at any point.

Step 6: Aggregate Reports

After all agents complete, run the aggregation script:

python scripts/aggregate_reports.py .artifacts/{feature-name}/{timestamp}

This creates summary.md combining all agent reports.

Step 7: Present Summary to User

Read the summary.md and present key findings to the user:

✅ User profile editing feature complete!

**Agents Executed:**
- Backend: fastapi-backend-expert
- Frontend: react-frontend-architect

**Summary:**
[Key points from summary]

**Files Changed:**
- Backend: X files modified, Y files created
- Frontend: Z files modified, W files created

**Next Steps:**
1. Review individual reports in .artifacts/profile-editing/{timestamp}/
2. Test the feature end-to-end
3. Run quality checks

Full details: .artifacts/profile-editing/{timestamp}/summary.md

Step 8: Finalize Session (Optional)

When the user confirms the session is complete, run the finalization script:

python scripts/finalize_session.py .artifacts/{feature-name}/{timestamp}

This script will:

1. Display session summary
2. Ask if the user will continue working (if yes, skip finalization)
3. Mark session as completed in context.json
4. Prompt for interactive artifact cleanup (if user agrees)

Important:

• Only finalize when work is truly complete
• If user will continue later, skip finalization
• Artifact cleanup is optional but recommended to prevent accumulation
• Artifacts are temporary, not long-term storage

Agent Selection

Load config/agents.yaml to select agents based on task type.

Configuration Structure

task_types:
  backend:
    primary_agent: "fastapi-backend-expert"
    fallback_agent: "general-purpose"
    trigger_keywords: ["backend", "fastapi", "api endpoint", ...]

  full_stack:
    primary_agent: ["fastapi-backend-expert", "react-frontend-architect"]
    parallel_execution: true
    sync_points: ["API contract definition", ...]

Selection Algorithm

1. Analyze user request - Extract keywords
2. Match task type - Find matching trigger keywords
3. Select primary agent(s) - From config
4. Determine execution mode - Parallel or sequential
5. Check for sync points - If parallel_with_sync pattern

Fallback Strategy

From config/agents.yaml:

fallback_strategy:
  on_agent_unavailable: "use_fallback"
  on_agent_error: "retry_once_then_fallback"
  on_unknown_task: "use_general_purpose"

If primary agent fails, gracefully degrade to fallback agent.

Coordination Patterns

Load detailed patterns from references/orchestration-patterns.md.

Pattern Summary

1. Parallel Independent - Tasks with no dependencies (backend + frontend)
2. Sequential Handoff - Output of one step feeds into next (DB → API → UI)
3. Parallel with Sync - Mostly parallel with synchronization points (API contract)
4. Primary with Reviewers - One implements, others review (implementation + architecture)
5. Incremental Validation - Phased work with validation between phases (migration)
6. Fan-Out / Fan-In - Multiple parallel tasks aggregated (microservices)
7. Conditional Branching - Agent selection depends on runtime conditions (analysis-driven)

Pattern Selection

Choose pattern based on:

• Dependencies: Are tasks independent?
• Synchronization: Do agents need to coordinate?
• Validation: Is step-by-step validation needed?
• Complexity: How many agents and phases?

Artifact Management

Directory Structure

.artifacts/
└── {feature-name}/
    └── {timestamp}/
        ├── context.json              # Session metadata
        ├── task-breakdown.md         # TodoWrite tasks
        ├── agent-reports/            # Individual reports
        │   ├── backend-report.md
        │   ├── frontend-report.md
        │   └── test-results.md
        └── summary.md               # Aggregated summary

Report Standards

All agent reports MUST follow standards from references/artifact-standards.md.

Required sections:

1. Summary
2. Changes Made
3. Implementation Details
4. Technical Decisions
5. Testing Results
6. Issues Encountered
7. Dependencies
8. Next Steps
9. Completion Checklist

Report Templates

Provide agents with the appropriate template:

• Implementation work: assets/report-templates/implementation-report.md
• Testing work: assets/report-templates/test-results.md
• Architecture review: assets/report-templates/architecture-review.md

Artifact Lifecycle

1. Creation: scripts/init_orchestration.py creates session
2. Active: Agents write individual reports
3. Completion: scripts/aggregate_reports.py creates summary
4. Retention: User manages cleanup with scripts/cleanup_artifacts.py

CRITICAL: NEVER auto-delete artifacts. The cleanup script requires explicit user confirmation.

Configuration Management

Validation

Validate configuration before orchestration:

python scripts/validate_agents.py --strict

This checks:

• Schema compliance
• Trigger keyword conflicts
• Agent references validity
• Version staleness

Updating Configuration

When agents change, update configuration:

# Interactive mode
python scripts/update_agents_config.py --interactive

# Command-line mode
python scripts/update_agents_config.py \
  --add-agent "ml-expert" \
  --type "ml_inference" \
  --triggers "ml" "machine learning" \
  --bump minor

This automatically:

• Updates config/agents.yaml
• Updates references/CHANGELOG.md
• Validates changes
• Bumps version

Self-Maintaining System

The configuration is self-documenting and versioned:

• config/agents.yaml - Current agent configuration (versioned)
• config/agents.schema.json - Validation schema
• references/CHANGELOG.md - Version history and migration guides

When agents are added, removed, or changed:

1. Validation detects unknown agents (warnings)
2. User can update config interactively
3. CHANGELOG tracks changes
4. Version bumps appropriately

Example Orchestrations

Example 1: Full-Stack Feature

Request: "Implement user profile editing with avatar upload"

Orchestration:

1. Task Analysis:
   - Type: full_stack
   - Pattern: parallel_with_sync
   - Agents: fastapi-backend-expert + react-frontend-architect

2. Task Breakdown (TodoWrite):
   ✅ Initialize session
   → Backend: Profile API + avatar upload
   → Frontend: ProfileEditor component
     Aggregate reports
     Present summary

3. Initialize:
   python scripts/init_orchestration.py profile-editing

4. Delegate (parallel):
   Task tool → fastapi-backend-expert:
     "Implement profile editing API with avatar upload.
      Write report to .artifacts/profile-editing/{ts}/agent-reports/backend-report.md"

   Task tool → react-frontend-architect:
     "Implement ProfileEditor UI with avatar upload.
      Write report to .artifacts/profile-editing/{ts}/agent-reports/frontend-report.md"

5. Monitor: TodoWrite updates as agents complete

6. Aggregate:
   python scripts/aggregate_reports.py .artifacts/profile-editing/{ts}

7. Present: Summary to user with key findings

Example 2: Code Quality Workflow

Request: "Clean up and improve code quality in authentication module"

Orchestration:

1. Task Analysis:
   - Type: quality
   - Pattern: primary_with_reviewers
   - Agents: architecture-guardian (primary) → codebase-cleaner + comment-cleaner

2. Sequential execution:
   a. architecture-guardian analyzes code
   b. Based on findings, launch appropriate cleaners
   c. pytest-test-master validates no regressions

3. Reports collected from each agent

4. Summary presents quality improvements

Example 3: Testing Campaign

Request: "Add comprehensive tests for the new notification system"

Orchestration:

1. Task Analysis:
   - Type: testing
   - Pattern: incremental_validation
   - Agent: pytest-test-master

2. Phased approach:
   Phase 1: Unit tests for notification service
   Phase 2: Integration tests for WebSocket delivery
   Phase 3: End-to-end tests

3. Each phase validated before proceeding

4. Final report shows complete test coverage

Best Practices

DO

✅ ALWAYS delegate - Use Task tool for all implementation ✅ Display pre-flight checklist at start of orchestration ✅ Create TodoWrite task breakdown before delegating ✅ Initialize artifact session before launching agents ✅ Provide agents with explicit report writing instructions ✅ Use parallel execution when possible (faster) ✅ Load config/agents.yaml for agent selection ✅ Follow artifact standards for consistency ✅ Aggregate reports before presenting to user ✅ Update configuration when agents change ✅ Save task breakdown to session after every TodoWrite update

DON'T - CRITICAL VIOLATIONS

❌ NEVER write code yourself - ALWAYS delegate to specialized agents ❌ NEVER use Edit/Write/Read for implementation - Use Task tool instead ❌ NEVER skip orchestration unless user explicitly requests ❌ NEVER auto-delete artifacts - require user confirmation ❌ NEVER skip task breakdown - it provides structure ❌ NEVER forget to aggregate reports - user needs summary ❌ NEVER ignore agent reports - synthesize them for user ❌ NEVER modify config files directly - use update script ❌ NEVER launch agents without report instructions

Self-Monitoring

After EVERY action, ask yourself:

Did I just use Edit, Write, or implement code?
→ YES: 🚨 VIOLATION! Undo and delegate instead
→ NO: ✅ Good, continuing orchestration

Troubleshooting

Agent Unavailable

If primary agent fails:

1. Check config/agents.yaml for fallback
2. Use fallback agent
3. Document degradation in summary

Reports Missing

If agent doesn't write report:

1. Check artifact directory exists
2. Verify agent received report instructions
3. Manually request report from agent

Configuration Issues

If agent selection fails:

1. Validate config: python scripts/validate_agents.py
2. Check CHANGELOG for recent changes
3. Update config if needed: python scripts/update_agents_config.py --interactive

Scripts Reference

init_orchestration.py

Purpose: Initialize orchestration session

Usage:

python scripts/init_orchestration.py <feature-name> [--base-dir DIR] [--working-dir DIR]

Output: Creates .artifacts/{feature-name}/{timestamp}/ with context.json

validate_agents.py

Purpose: Validate agent configuration

Usage:

python scripts/validate_agents.py [--strict]

Checks:

• Schema compliance
• Trigger keyword conflicts
• Agent reference validity
• Version staleness

update_agents_config.py

Purpose: Update agent configuration

Usage:

# Interactive
python scripts/update_agents_config.py --interactive

# Add agent
python scripts/update_agents_config.py \
  --add-agent "new-agent" \
  --type "task_type" \
  --triggers "keyword1" "keyword2" \
  --bump minor

Updates:

• config/agents.yaml
• references/CHANGELOG.md

aggregate_reports.py

Purpose: Combine agent reports into summary

Usage:

python scripts/aggregate_reports.py .artifacts/{feature-name}/{timestamp}

Output: Creates summary.md with aggregated findings

finalize_session.py

Purpose: Finalize orchestration session and trigger cleanup

Usage:

python scripts/finalize_session.py .artifacts/{feature-name}/{timestamp}

# Skip aggregation
python scripts/finalize_session.py .artifacts/{feature-name}/{timestamp} --skip-aggregation

# Skip cleanup prompt
python scripts/finalize_session.py .artifacts/{feature-name}/{timestamp} --skip-cleanup

# Custom retention period
python scripts/finalize_session.py .artifacts/{feature-name}/{timestamp} --retention-days 14

Workflow:

1. Display session summary
2. Ask if user will continue (if yes, skip finalization)
3. Aggregate reports if not done
4. Mark session as completed
5. Prompt for artifact cleanup

load_session.py

Purpose: Load session info for resumption

Usage:

# Load specific session
python scripts/load_session.py .artifacts/feature-name/20240118_120000

# Load latest session for feature
python scripts/load_session.py .artifacts/feature-name/ --latest

# Verbose output with task details
python scripts/load_session.py .artifacts/feature-name/ --latest --verbose

# JSON output for programmatic use
python scripts/load_session.py .artifacts/feature-name/ --latest --json

# List all sessions for feature
python scripts/load_session.py .artifacts/feature-name/ --list

Output:

• Session metadata (status, timestamps)
• Task breakdown with completion state
• List of executed agents
• Resumption instructions

cleanup_artifacts.py

Purpose: List and optionally clean up old artifacts

IMPORTANT: Requires explicit user confirmation

Usage:

# List candidates
python scripts/cleanup_artifacts.py

# Intelligent mode (skip active/uncommitted sessions)
python scripts/cleanup_artifacts.py --intelligent

# Interactive cleanup
python scripts/cleanup_artifacts.py --interactive --intelligent

# Dry run
python scripts/cleanup_artifacts.py --dry-run

# With confirmation
python scripts/cleanup_artifacts.py --confirm --intelligent

Intelligent mode:

• Skips sessions with status != "completed"
• Skips sessions with uncommitted git changes
• Safe for multi-developer workflows

Resources

Configuration (config/)

• agents.yaml - Versioned agent delegation map
• agents.schema.json - JSON Schema for validation

References (references/)

• orchestration-patterns.md - Detailed coordination patterns
• artifact-standards.md - Report formatting standards
• CHANGELOG.md - Configuration version history

Templates (assets/report-templates/)

• implementation-report.md - For backend/frontend agents
• test-results.md - For pytest-test-master
• architecture-review.md - For architecture-guardian

Scripts (scripts/)

• init_orchestration.py - Initialize new sessions with directory structure
• load_session.py - Load session info for resumption (NEW)
• validate_agents.py - Validate configuration schema
• update_agents_config.py - Update agent configuration
• aggregate_reports.py - Combine agent reports into summary
• finalize_session.py - Finalize sessions and trigger cleanup
• cleanup_artifacts.py - Manage artifact lifecycle (supports intelligent mode)

---

🚨 FINAL REMINDER 🚨

YOU ARE AN ORCHESTRATOR, NOT A DEVELOPER

Before starting ANY work:

1. ✅ Display pre-flight checklist
2. ✅ Check if user wants to resume session
3. ✅ Create TodoWrite breakdown
4. ✅ Initialize session with init_orchestration.py
5. ✅ Delegate via Task tool - NEVER implement yourself
6. ✅ Save task breakdown to session
7. ✅ Aggregate reports when done
8. ✅ Finalize session

If you catch yourself using Edit, Write, or implementing code:

🚨 STOP! I am violating orchestration mode.
Let me delegate this to [appropriate-agent] instead.

Default behavior: ORCHESTRATE Only exception: User explicitly says "не делегуй" or "skip orchestration"

---

Remember: Act as an orchestrator 80-90% of the time. Delegate to specialized agents, collect their work, and synthesize comprehensive summaries. Focus on coordination, not execution.

Your role: COORDINATE, not CODE.