Team Leadership Skill

Spawn a Team Leader agent that orchestrates multiple sub-agents to achieve complex goals.

Philosophy

A team operates as follows:

Team Leader receives a high-level goal or requirement
Decomposes the goal into smaller, independent tasks
Creates tasks in docs/todo/pending/ with clear ownership
Selects personalities that match each task type
Spawns sub-agents using ogt-agent-spawn
Manages communication between team members (shared progress docs)
Monitors progress via task signals and .assigned_to_ markers
Resolves blockers by coordinating across the team
Verifies completion against acceptance criteria
Reports results to human with final status

The Team Leader acts as a project manager and technical orchestrator.

When to Use

Complex projects requiring multiple specialists
Work that can be parallelized across team members
Tasks requiring coordination (some depend on others)
Projects where communication between agents is critical
Large goals broken into smaller deliverables
Need for progress tracking and human oversight

Team Leader Personality

The Team Leader always adopts this personality:

You are a Team Leader. Your role:

1. **Understand the Goal** - Read the requirement fully
2. **Decompose Work** - Break into independent, parallel tasks
3. **Create Tasks** - Write task definitions in docs/todo/pending/
4. **Assign Specialists** - Choose personalities matching each task
5. **Spawn Sub-Agents** - Use ogt-agent-spawn with right backend mix
6. **Coordinate** - Manage dependencies and blockers
7. **Monitor** - Track progress via task signals
8. **Communicate** - Update humans on status and blockers
9. **Verify** - Ensure all tasks meet acceptance criteria
10. **Report** - Provide final results with complete accounting

Decision-making:
- Break large goals into 3-7 independent tasks
- Assign personalities based on task type
- Distribute work fairly across backends
- Escalate blockers to humans immediately
- Aim for parallel execution, not sequential

Communication: Professional, status-focused, transparent
Output: Task decomposition, progress reports, final results

Quick Start

Basic Team Operation

ogt-agent-team \
  --goal "Build user authentication system" \
  --team-size 3-5 \
  --deadline "2 days"

With Specific Requirements

ogt-agent-team \
  --goal "Refactor API from REST to GraphQL" \
  --requirements "docs/requirements.md" \
  --team-size 4 \
  --prioritize "architect,engineer,tester" \
  --reporting-interval "1h"

With Dependencies

ogt-agent-team \
  --goal "Build multi-tenant system" \
  --dependencies "docs/architecture.md" \
  --backend-weights "claude:40,gemini:35,opencode:25" \
  --human-reviews-between-phases true

Team Operation Flow

flowchart TD
    A["Team Goal<br/>Human Input"] --> B["Team Leader<br/>Analyzes Requirement"]
    B --> C["Decompose<br/>Create Task Breakdown"]
    C --> D["Create Tasks<br/>docs/todo/pending/"]
    D --> E["Assign Personalities<br/>& Backends"]
    E --> F["Spawn Sub-Agents<br/>ogt-agent-spawn"]
    F --> G["Parallel Execution<br/>Monitor Progress"]
    G --> H{Blockers?}
    H -->|Yes| I["Resolve<br/>Coordinate Team"]
    I --> G
    H -->|No| J["Verify Results<br/>Check Criteria"]
    J --> K{All Pass?}
    K -->|No| L["Create Issues<br/>Return to In Progress"]
    L --> G
    K -->|Yes| M["Move to Done/"]
    M --> N["Report Results<br/>to Human"]
    
    style A fill:#fef3c7
    style B fill:#fef3c7
    style G fill:#dbeafe
    style N fill:#d1fae5
    style H fill:#e0e7ff
    style K fill:#e0e7ff

Task Decomposition

Team Leader reads the goal and breaks it into tasks:

Goal Analysis

Read the goal/requirement and identify:

Scope — What's in vs out
Dependencies — Task ordering
Complexity — Effort levels
Specializations — What types of work

Task Creation

Create tasks in docs/todo/pending/{task_slug}/ with:

# Task: {Clear Title}

## Summary
One sentence about this task.

## Objectives
- Objective 1
- Objective 2

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Criterion 2

## Dependencies
- Depends on: docs/todo/pending/{other-task}
- OR: None

## Estimated Effort
{Size} ({hours} hours)

## Team Assignment
Personality: {architect|engineer|researcher|tester|educator}
Backend: {claude|gemini|opencode|copilot}

Personality Assignment Rules

Task Type	Best Personality	Reason
Design/Architecture	Architect	Holistic thinking
Implementation	Engineer	Pragmatism, ships code
Testing/Verification	Tester	Thoroughness
Investigation	Researcher	Detailed analysis
Documentation	Educator	Clear communication
Code Review	Architect	Critical analysis

Sub-Agent Management

Spawning Pattern

# Task 1: Research (needs deep analysis)
ogt-agent-spawn \
  --task "evaluate-db-options" \
  --personality researcher \
  --backend claude  # deep thinking

# Task 2: Architecture (needs design thinking)
ogt-agent-spawn \
  --task "design-auth-system" \
  --personality architect \
  --backend claude  # deep thinking

# Task 3: Implementation (needs fast execution)
ogt-agent-spawn \
  --task "implement-auth-service" \
  --personality engineer \
  --backend gemini  # fast execution

# Task 4: Testing (needs thoroughness)
ogt-agent-spawn \
  --task "test-auth-flow" \
  --personality tester \
  --backend claude  # thorough analysis

# Task 5: Documentation (needs clarity)
ogt-agent-spawn \
  --task "document-auth-api" \
  --personality educator \
  --backend gemini  # good examples

Load Balancing

Distribute across backends to balance cost/quality/speed:

Team of 6 sub-agents:
- 30% Claude (complex reasoning, code review)
- 40% Gemini (fast, bulk work)
- 20% OpenCode (templated generation)
- 10% Copilot (repository-aware)

Example team:
- Task 1: Claude (Architect)
- Task 2: Claude (Tester)
- Task 3: Gemini (Engineer)
- Task 4: Gemini (Engineer)
- Task 5: OpenCode (Engineer)
- Task 6: Copilot (Engineer)

Progress Tracking

Team Leader monitors tasks via signals and files:

Tracking Signals

Check these signals to understand task state:

# Find all tasks assigned to current team
find docs/todo -name ".assigned_to_*" | wc -l

# Find blocked tasks
find docs/todo/blocked -name ".blocked_reason" -exec cat {} \;

# Find ready for review
find docs/todo/review -name ".ready_for_review" | wc -l

# Find completed
find docs/todo/done -name ".verified" | wc -l

Progress File Format

Team Leader updates team_progress.md in project root:

# Team Progress Report

## Goal
Implement user authentication system

## Team Composition
- Task 1: evaluate-db-options (Researcher/Claude) - 40% complete
- Task 2: design-auth-system (Architect/Claude) - 80% complete
- Task 3: implement-auth-service (Engineer/Gemini) - Blocked
- Task 4: test-auth-flow (Tester/Claude) - Waiting on Task 3
- Task 5: document-auth-api (Educator/Gemini) - Not started

## Blockers
**Task 3: implement-auth-service**
- Blocked on: Task 2 design approval
- Details: Waiting for final architecture sign-off
- Expected resolution: 2 hours

## Time Tracking
- Total hours available: 16h
- Hours used: 6.5h
- Hours remaining: 9.5h

## Next Actions
1. Review Task 2 architecture
2. Unblock Task 3 once approved
3. Monitor Tasks 3, 4 for completion

## Completed Tasks
- None yet

Coordination Patterns

Sequential Dependency

When tasks depend on each other:

# Task A (must complete first)
ogt-agent-spawn --task task-a --priority high

# Wait for task-a to complete (check done/ directory)
# Then spawn Task B
ogt-agent-spawn --task task-b --depends-on task-a

Parallel Execution

When tasks are independent:

# Spawn all at once
ogt-agent-spawn --task task-1 &
ogt-agent-spawn --task task-2 &
ogt-agent-spawn --task task-3 &
wait  # Wait for all to complete

Blocking Resolver

When a task is blocked:

Identify blocker

cat docs/todo/blocked/{task}/.blocked_reason

Resolve blocker (might require human input)

# If blocker is another task, spawn it
ogt-agent-spawn --task {blocking-task} --priority critical

# If blocker is human decision, ask human
echo "Need decision on {thing}..."

Unblock task

# Remove blocking signals
rm docs/todo/blocked/{task}/.blocked
rm docs/todo/blocked/{task}/.blocked_reason

# Move back to pending
mv docs/todo/blocked/{task} docs/todo/pending/{task}

# Re-spawn agent
ogt-agent-spawn --task {task}

Verification & Reporting

Verification Process

After all sub-agents complete, Team Leader verifies:

# For each task, check acceptance criteria
for task in docs/todo/done/*/; do
  echo "=== $(basename $task) ==="
  grep "## Acceptance Criteria" "$task/task.md" -A 10
  
  # Check if .verified signal exists
  if [ -f "$task/.verified" ]; then
    echo "✅ Verified"
  else
    echo "❌ Not verified - move back to pending"
    mv "$task" docs/todo/pending/
  fi
done

Final Report

Team Leader returns comprehensive report:

{
  "goal": "Build user authentication system",
  "status": "completed",
  "started_at": "2026-02-06T20:15:00Z",
  "completed_at": "2026-02-06T23:45:00Z",
  "total_time_hours": 3.5,
  
  "tasks": {
    "total": 5,
    "completed": 5,
    "blocked": 0,
    "failed": 0
  },
  
  "team": {
    "sub_agents": 5,
    "personalities": ["architect", "engineer", "tester", "researcher", "educator"],
    "backends": {
      "claude": 2,
      "gemini": 2,
      "opencode": 1
    }
  },
  
  "results": {
    "files_created": 12,
    "files_modified": 8,
    "tests_passing": 24,
    "documentation_pages": 4,
    "pr_created": "https://github.com/org/repo/pull/456"
  },
  
  "blockers": "None - completed smoothly",
  
  "next_steps": "Review PR, merge to main, deploy to staging"
}

Communication with Team

Status Updates

Team Leader provides periodic updates to human:

🚀 Team Update - User Auth System
─────────────────────────────────

✅ Completed: 2/5 tasks
⏳ In Progress: 2/5 tasks
⏸️  Blocked: 0/5 tasks
⏱️  Time elapsed: 1.5h / 3.5h estimated

📊 Details:
  ✅ Task 1: evaluate-db-options (100%) - Researcher/Claude - Done
  ✅ Task 2: design-auth-system (100%) - Architect/Claude - Done
  ⏳ Task 3: implement-auth-service (45%) - Engineer/Gemini - In Progress
  ⏳ Task 4: test-auth-flow (0%) - Tester/Claude - Waiting
  ⏳ Task 5: document-auth-api (0%) - Educator/Gemini - Waiting

🔄 Next Actions:
  - Monitor Task 3 implementation (ETA 45min)
  - Task 4 ready to start once Task 3 moves to review
  - Task 5 has all context, can start anytime

❓ Blockers: None
💬 Communication: Team members updating progress.md every 30min

Human Escalation

For issues Team Leader cannot resolve:

🆘 Blocker Alert - User Auth System
─────────────────────────────────

❌ Task: implement-auth-service
   Blocked by: Architectural decision on JWT vs sessions
   
Architect (Task 2) recommends JWT but Engineer (Task 3) needs
confirmation before proceeding. Both are standby waiting for decision.

📋 Decision Needed:
  Q: Use JWT or session-based auth?
     - JWT: Stateless, scales better, more complex token mgmt
     - Sessions: Simpler, requires session store, scales horizontally
  
  Impact: Task 3 (8h) and Task 4 (4h) cannot progress without this

🔗 Architecture Recommendation: docs/todo/done/design-auth-system/implementation.md

⏰ Team is idle. Each hour costs equivalent to sub-agent time.

👤 Please decide and respond with: JWT or SESSIONS

Configuration

Team Size

# Small team (3-4 agents) - simple goals
ogt-agent-team --goal "Refactor UserComponent" --team-size 3

# Medium team (5-7 agents) - complex goals
ogt-agent-team --goal "Build auth system" --team-size 5

# Large team (8+) - enterprise goals
ogt-agent-team --goal "Microservices migration" --team-size 8

Reporting Interval

# Quick feedback (updates every 15 min)
ogt-agent-team --goal "..." --reporting-interval "15m"

# Standard (updates every hour)
ogt-agent-team --goal "..." --reporting-interval "1h"

# Minimal (updates on blocker or completion only)
ogt-agent-team --goal "..." --reporting-interval "on-change"

Backend Weighting

# Balanced (even distribution)
ogt-agent-team --goal "..." --backend-weights "equal"

# Quality-focused (prefer Claude)
ogt-agent-team --goal "..." --backend-weights "claude:50,gemini:30,opencode:20"

# Speed-focused (prefer Gemini)
ogt-agent-team --goal "..." --backend-weights "gemini:50,claude:30,opencode:20"

# Cost-focused (prefer OpenCode)
ogt-agent-team --goal "..." --backend-weights "opencode:50,gemini:30,claude:20"

Examples

Example 1: Feature Implementation

ogt-agent-team --goal "Implement dark mode toggle" --team-size 4

Team decomposition:

Architect - Design theme system architecture
Engineer - Implement theme provider and toggle
Tester - Write tests and edge case scenarios
Educator - Document theme API for other developers

Result: Complete feature with tests, docs, ready to merge

Example 2: API Migration

ogt-agent-team \
  --goal "Migrate REST API to GraphQL" \
  --requirements "docs/migration-plan.md" \
  --team-size 6

Team decomposition:

Researcher - Evaluate GraphQL libraries and best practices
Architect - Design new GraphQL schema and resolver structure
Engineer - Implement GraphQL resolvers and types
Engineer - Implement client-side GraphQL queries
Tester - Test API and client integration
Educator - Write GraphQL API documentation

Result: Fully migrated API with client code and documentation

Example 3: System Redesign

ogt-agent-team \
  --goal "Redesign authentication from password to OAuth" \
  --dependencies "docs/security-requirements.md" \
  --team-size 7 \
  --human-reviews-between-phases true

Team decomposition:

Researcher - Research OAuth providers and security practices
Architect - Design OAuth integration architecture
Engineer - Implement OAuth provider integration
Engineer - Implement client-side OAuth flow
Engineer - Implement token management service
Tester - Test OAuth flow and security edge cases
Educator - Document OAuth setup and usage

Result: Complete OAuth system with security audited and documented

Tips & Best Practices

Clear Requirements — Provide detailed goals, not vague ones
Size Teams Appropriately — 3-7 agents typically optimal
Monitor Blockers — Check progress every 1-2 hours
Escalate Early — Don't let teams spin on decisions
Verify Thoroughly — Check acceptance criteria, not just "done"
Document Decisions — Have Team Leader log why tasks were decomposed that way
Plan for Dependencies — Order tasks to enable parallelism
Review Before Shipping — Have human review final results

Troubleshooting

Team Gets Stuck

# Check for blockers
find docs/todo/blocked -name ".blocked_reason" -exec cat {} \;

# Check progress files
find docs/todo/in_progress -name "progress.md" -exec tail -20 {} \;

# If blocked for >30min, escalate to human

Task Keeps Failing

# Check task definition
cat docs/todo/pending/{task}/task.md

# Verify acceptance criteria are achievable
# If too vague, edit task.md with clearer criteria

# Switch to different personality/backend
ogt-agent-spawn --task {task} --personality {different} --backend {different}

Team Not Communicating

# Create shared progress doc if missing
touch team_progress.md

# Ensure all tasks have progress.md
for task in docs/todo/in_progress/*/; do
  if [ ! -f "$task/progress.md" ]; then
    cp docs/_templates/progress.md "$task/progress.md"
  fi
done

Team Slow

# Check which tasks are in_progress but idle
ls -lt docs/todo/in_progress/

# If not changing for >30min, may be stuck
# Check progress.md for last update time

# If truly stuck, move back to pending and re-spawn
mv docs/todo/in_progress/{task} docs/todo/pending/{task}
ogt-agent-spawn --task {task} --backend {different}