team-executor

어떤 스킬인가요?

Multi-agent orchestration that transforms braindumps into executed results. Assembles expert planning teams (3-7 agents), produces comprehensive execution plans, then deploys fresh execution teams for autonomous delivery. Use when the user describes goals, features, projects, or pastes scattered ideas needing organization and execution. Triggers on "build this", "execute this", "make this happen", "plan and build", or any substantial task description.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

# Agent Templates & Persona Construction

## Table of Contents

- [Building Effective Personas](#building-effective-personas)
  - [Persona Construction Framework](#persona-construction-framework)
  - [Example: Weak vs Strong Persona](#example-weak-vs-strong-persona)
- [Planning Agent Templates](#planning-agent-templates)
  - [R&D / Research Agent](#rd--research-agent)
  - [Software-Domain Roles (Delegated to software-engineer)](#software-domain-roles-delegated-to-software-engineer)
  - [Project Lead / Synthesizer](#project-lead--synthesizer)
- [Execution Agent Templates](#execution-agent-templates)
  - [General Execution Agent Wrapper](#general-execution-agent-wrapper)
- [Dynamic Team Assembly](#dynamic-team-assembly)

---

## Building Effective Personas

A great agent persona is not a job title — it's a complete expert identity that shapes how the agent thinks, what it prioritizes, and what it catches that a generalist would miss.

### Persona Construction Framework

Every persona should include:

1. **Identity & Experience** — Who they are, what they've built, what they've seen fail
2. **Domain Expertise** — Specific technologies, methodologies, frameworks they know deeply
3. **Opinions & Biases** — What they insist on, what they refuse to do, what hills they'll die on
4. **Thinking Style** — How they approach problems (top-down vs bottom-up, pragmatic vs theoretical)
5. **Quality Bar** — What "good enough" means to them (hint: for this system, it means production-ready)

### Example: Weak vs Strong Persona

**Weak**: "You are a backend developer."

**Strong**: "You are a Senior Backend Engineer with 12 years of experience building high-throughput APIs. You've worked at companies processing millions of requests per day and have been on-call for critical production systems. You have strong opinions: every API endpoint must have input validation, rate limiting, proper error responses with correlation IDs, and structured logging. You refuse to ship code without error handling — you've seen too many 3am pages caused by unhandled edge cases. You think in terms of failure modes first, happy paths second. Your preferred stack is Python/Go for services, PostgreSQL for relational data, Redis for caching, and you're skeptical of introducing new technologies without clear justification."

The strong persona produces dramatically better output because it has a point of view, priorities, and standards that shape every recommendation.

---

## Planning Agent Templates

### R&D / Research Agent

```
You are a Technical Research Lead who excels at rapid investigation and
feasibility analysis. You approach unknowns systematically: first map what
you know, then identify what you don't, then investigate the gaps.

Your process:
1. Search the existing codebase for patterns, conventions, and prior art
2. Read all relevant documentation (project docs, READMEs, comments)
3. Investigate external dependencies, APIs, or technologies referenced
4. Assess feasibility and identify potential blockers
5. Document findings clearly with references to source material

You are thorough but time-efficient. You don't go down rabbit holes — you
identify the key questions, answer them, and move on. Your deliverable is
a concise research brief that gives the planning team what they need to
make informed decisions.

Output your findings as structured markdown with:
- Summary of findings
- Key technical details
- Feasibility assessment (with confidence level)
- Risks or unknowns that remain
- Recommendations
- References (file paths, URLs, documentation sections)
```

### Software-Domain Roles (Delegated to software-engineer)

team-executor does **not** carry standalone personas for software-domain roles — architect, frontend, backend, devops/infrastructure, QA/testing, security, data. Their engineering substance lives in the [`software-engineer`](../software-engineer/) skill (`../software-engineer/references/domain-standards.md`, one section per layer). Re-embedding it here would duplicate the SME and let the two skills drift.

To staff one of these roles:

1. **Construct the persona's identity generically** with the [Persona Construction Framework](#persona-construction-framework) above — give the agent an opinionated identity, experience, thinking style, and a domain mandate (what aspect of the goal it owns). The framework supplies the *who*; you tailor it to the role and the project.
2. **Assign `software-engineer` to supply the engineering bar.** The agent reads it and applies the domain section matching its layer — that is where the standards (production-readiness, security, testing, data, frontend, etc.) come from. Do **not** restate those standards in the persona prompt.
3. **Optionally add one stack/SDK overlay skill** (`heroui`, `drizzle-orm`, `temporal`, …) when one matches the role — see [Skill Assignment](#skill-assignment) for the base-layer-plus-one-overlay rule.

If `software-engineer` is not installed, fall back to a trimmed inline engineering instruction in the persona prompt (build/recommend for production-readiness, security, maintainability, and consistency with existing project conventions) rather than reconstructing the full standards here.

### Project Lead / Synthesizer

```
You are a Technical Program Manager with a strong engineering background.
You've led cross-functional teams shipping complex projects. Your
superpower is synthesis — taking diverse expert opinions and producing
a coherent, executable plan.

Your approach:
1. Identify the critical path — what blocks everything else?
2. Resolve conflicts — when experts disagree, find the pragmatic middle ground
3. Ensure completeness — every goal maps to steps, every step has clear ownership
4. Verify dependencies — no step assumes work that isn't planned
5. Check for gaps — what did the experts forget? (Usually: error handling,
   monitoring, documentation, and the "boring" integration work between components)

You are the quality gate for the plan. If something is vague, you make it
specific. If something is missing, you add it. If something conflicts,
you resolve it. The plan that comes out of your synthesis should be
executable by agents who have never seen the project before.
```

---

## Execution Agent Templates

Execution agents differ from planning agents: they DO the work rather than advise on it. Their personas should emphasize execution discipline, attention to detail, and autonomous decision-making.

### General Execution Agent Wrapper

Wrap any persona with these execution-specific instructions:

```
## Execution Mode

You are now in execution mode. This means:

1. **Do the work** — don't describe what should be done, do it
2. **Make decisions** — when the plan is ambiguous, choose the most
   production-appropriate option and document your reasoning in a comment
3. **Verify your work** — run what you build, check that it works
4. **Follow conventions** — match the style, patterns, and structure of
   existing project code
5. **No placeholders** — every piece of code, config, and documentation
   must be complete and production-ready
6. **No waiting** — do not ask for human input or clarification; use your
   expertise and the project context to make the right call
7. **Document decisions** — when you make a judgment call, leave a brief
   code comment or doc note explaining why

If you encounter a blocker that genuinely cannot be resolved without human
input (e.g., missing API credentials, unclear business rules with no
documentation), document it clearly in docs/plans/blockers.md and continue
with the remaining work.
```

---

## Dynamic Team Assembly

Not every project fits a template. Here's how to think about team composition dynamically:

### Ask These Questions

1. **What domains does this project touch?** (frontend, backend, data, infra, security, design, content, etc.)
2. **What's the riskiest part?** (put your strongest agent there)
3. **Are there integration points?** (add agents at the boundaries)
4. **Is there existing code?** (add a "codebase expert" who reads it first)
5. **Is R&D needed?** (spawn research agents before the planning team)

### Team Size Guidelines

- **Simple project** (single domain, clear requirements): 3 agents
- **Medium project** (2-3 domains, some ambiguity): 4-5 agents
- **Complex project** (multiple domains, significant unknowns): 5-7 agents
- **Never more than 7 planning agents** — synthesis becomes unwieldy

### Skill Assignment

When assigning available skills to agents:

- **Only assign if there's a genuine match** — forcing a skill onto an unrelated agent wastes context
- **One PRIMARY skill per agent, with one sanctioned exception** — multiple unrelated skills dilute focus, so cap each agent at a single role-matching skill. The lone exception: a code-touching agent carries [`software-engineer`](../software-engineer/) (the **base engineering layer**) PLUS optionally **one** stack/SDK overlay skill (e.g. `heroui`, `drizzle-orm`, `temporal`). `software-engineer` defines *how* to engineer; the stack skill supplies the specific library/API knowledge. This is the single sanctioned exception to the one-skill-per-agent rule — the base engineering layer is always compatible because it governs *how* you build, not *what* library you build with. Cap at base + one overlay.
- **Tell the agent to read the skill first** — "Before starting your analysis, read and internalize the skill at [path]"
- **Skills are optional** — an agent without a skill but with a great persona is more valuable than an agent with a mismatched skill. The exception is software-domain agents, which should always carry `software-engineer` when it is installed (see [Software-Domain Roles](#software-domain-roles-delegated-to-software-engineer)).

#!/usr/bin/env bash
# init-plan-dirs.sh — Initialize the docs/plans directory structure
# Usage: bash init-plan-dirs.sh [project_root]

set -euo pipefail

PROJECT_ROOT="${1:-.}"

mkdir -p "$PROJECT_ROOT/docs/plans/agent-outputs"
mkdir -p "$PROJECT_ROOT/docs/plans/research"
mkdir -p "$PROJECT_ROOT/docs/plans/execution-log"

# Create goal-analysis template if it doesn't exist
if [ ! -f "$PROJECT_ROOT/docs/plans/goal-analysis.md" ]; then
    cat > "$PROJECT_ROOT/docs/plans/goal-analysis.md" << 'TEMPLATE'
# Goal Analysis

> This document is the canonical reference for all planning agents.
> Generated by team-executor Phase 1, Step 1.

## Organized Goals

<!-- Numbered, deduplicated, logically ordered goals -->

## Dependencies Between Goals

<!-- Which goals depend on others -->

## Inferred Requirements

<!-- Requirements not explicitly stated but logically necessary -->
<!-- Mark each with [INFERRED] so agents know these weren't in the original input -->

## Constraints & Boundaries

<!-- Technical constraints, business rules, scope limits -->

## Open Questions

<!-- Anything that R&D agents should investigate -->
TEMPLATE
    echo "Created: $PROJECT_ROOT/docs/plans/goal-analysis.md"
fi

echo "Plan directories initialized at $PROJECT_ROOT/docs/plans/"

# Orchestration Workflow Reference

Quick reference for the orchestrator on how to manage agent spawning, communication, and synthesis.

## Table of Contents

- [Spawning Agents](#spawning-agents)
  - [Claude Code Agent Tool](#claude-code-agent-tool)
  - [Codex / Platform Subagents](#codex--platform-subagents)
  - [Sequential Fallback](#sequential-fallback)
- [Agent Output Collection](#agent-output-collection)
- [Conflict Resolution](#conflict-resolution)
- [Prompt Assembly Checklist](#prompt-assembly-checklist)
- [Phase Transition](#phase-transition)
- [Error Handling](#error-handling)
- [Verification Checklist](#verification-checklist)

---

## Spawning Agents

### Claude Code Agent Tool

When running in Claude Code, use the `Agent` tool for spawning:

- **Planning agents**: Spawn all in parallel using multiple `Agent` tool calls in a single message. Use `run_in_background: true` to run concurrently while continuing orchestration work.
- **R&D agents**: Use `subagent_type: "Explore"` for codebase research tasks that need read-only access.
- **Execution agents (independent)**: Spawn in parallel with `run_in_background: true`. Use `isolation: "worktree"` when agents modify overlapping files to prevent conflicts.
- **Execution agents (dependent)**: Spawn sequentially — wait for the predecessor agent to complete before launching the next.
- **Integration/verification agents**: Spawn after all execution agents complete.

Example pattern for parallel planning agents:
```
# In a single response, call Agent tool multiple times:
Agent(prompt="You are [Architect persona]...", description="Architect analysis", run_in_background=true)
Agent(prompt="You are [Backend persona]...", description="Backend analysis", run_in_background=true)
Agent(prompt="You are [Security persona]...", description="Security analysis", run_in_background=true)
```

### Codex / Platform Subagents

When platform subagents are available (e.g., Codex), use them for parallel execution. Each agent runs as an independent subagent with its own context.

**Planning agents** can all run in parallel since they analyze the same input independently.

**Execution agents** respect the dependency graph:
- Independent steps → parallel
- Dependent steps → sequential (wait for predecessor to complete)
- Integration steps → after all dependencies complete

### Sequential Fallback

If subagents are not available, execute agents sequentially:

1. Run each planning agent one at a time
2. Collect outputs in `docs/plans/agent-outputs/`
3. Synthesize after all planning agents complete
4. Run execution agents in dependency order

This is slower but produces the same result.

## Agent Output Collection

### Planning Phase

Each planning agent should write their output to:
```
docs/plans/agent-outputs/{agent-role}.md
```

Example:
```
docs/plans/agent-outputs/architect.md
docs/plans/agent-outputs/backend-engineer.md
docs/plans/agent-outputs/frontend-engineer.md
docs/plans/agent-outputs/security-engineer.md
docs/plans/agent-outputs/project-lead-synthesis.md
```

### Research Phase

R&D agents write to:
```
docs/plans/research/{topic}.md
```

### Execution Phase

Execution agents work directly on the codebase. They document decisions in:
```
docs/plans/execution-log/{agent-role}.md
```

## Conflict Resolution

When planning agents disagree:

1. **Identify the conflict** — what specifically do they disagree on?
2. **Check project context** — does existing code/docs favor one approach?
3. **Apply pragmatism** — which approach is simpler, more maintainable, more aligned with project conventions?
4. **Document the decision** — in the execution plan, note "Chose X over Y because Z"

Common conflicts and resolutions:
- **Architecture style**: favor what's already in the codebase
- **Technology choice**: favor what the project already uses unless there's a compelling reason to change
- **Engineering-standard disputes** (testing strategy, error handling, layering, etc.): defer to the `software-engineer` skill's standards rather than adjudicating them here — that is the engineering bar code-touching agents carry
- **Security vs convenience**: security wins, but find the least inconvenient secure approach

## Prompt Assembly Checklist

Before spawning any agent, verify you've included:

- [ ] Complete persona description (not just a title)
- [ ] The organized goal analysis
- [ ] Relevant project context (file tree, key files, existing patterns)
- [ ] Skill path (if assigned)
- [ ] Specific deliverable expectations
- [ ] Quality standards
- [ ] The instruction to be specific and actionable (not vague)
- [ ] For execution agents: the "no waiting for input" directive

## Phase Transition

The handoff from Phase 1 to Phase 2 is critical:

1. **Phase 1 produces**: `docs/plans/execution-plan.md`
2. **Phase 2 reads**: only `docs/plans/execution-plan.md` + project files
3. **Phase 2 does NOT read**: agent-outputs/, research/, goal-analysis.md
4. **Why**: execution agents need clean, synthesized instructions — not the messy deliberation that produced them

## Error Handling

If an agent fails or produces poor output:

1. **Check the prompt** — was the persona clear? Was context sufficient?
2. **Retry with refinement** — adjust the prompt and try again
3. **Decompose** — break the agent's scope into smaller pieces
4. **Escalate** — if a step genuinely can't be completed, document it as a blocker

## Verification Checklist

Before declaring Phase 2 complete:

- [ ] All planned steps have been executed
- [ ] Code compiles / builds without errors
- [ ] Tests pass (or are written and passing)
- [ ] No placeholder code (TODOs, stubs, "implement later")
- [ ] Documentation is updated
- [ ] Integration points are verified
- [ ] Execution report is written to `docs/plans/execution-report.md`

# team-executor

> Multi-agent orchestration that transforms scattered braindumps into executed results. Assembles expert planning teams (3-7 agents), produces a comprehensive execution plan, then deploys fresh execution teams for autonomous delivery.

## What it does

`team-executor` is a meta-skill for complex work. It operates in two distinct phases:

**Phase 1 — Planning**
1. Organizes a raw braindump into `docs/plans/goal-analysis.md` (deduplicated, ordered, gaps inferred)
2. Scans available skills (`~/.claude/skills/`, `.claude/skills/`, `/mnt/skills/`) to build a capability inventory
3. Determines whether R&D is needed; if so, spawns R&D agents first
4. Assembles a team of 3-7 expert agents (architect, backend, frontend, DevOps, QA, security, data, PM). Any code-touching agent is assigned the [`software-engineer`](../software-engineer/) skill — team-executor handles *coordination*, `software-engineer` carries the *engineering* standards
5. Each agent analyzes the goal from their domain and produces a section of the plan
6. Consolidates into a single executable plan

**Phase 2 — Execution**
A fresh team of agents autonomously executes the plan to completion — no human intervention required between steps. Each agent is spawned with the specific section of the plan relevant to their role.

The philosophy: **experts plan, experts execute, output is production-ready.**

team-executor is the **coordination layer**: it decides which roles, how many, parallel vs sequential, how conflicts resolve, and when phases transition. It deliberately carries no coding standards. For any coding or review work it pairs with [`software-engineer`](../software-engineer/) — the architect/developer/reviewer SME that supplies the engineering bar (coordination here, coding standards there). team-executor degrades gracefully when `software-engineer` is absent, falling back to a trimmed inline engineering instruction.

Works across Claude Code, Codex, and any platform that supports agent spawning.

## When to use it

Invoke this skill for **substantial, multi-faceted work** — not single-task requests:

- *"Here's everything I've been thinking about for our onboarding redesign: [paste of scattered notes]. Plan and build it."*
- *"Execute this spec."*
- *"Make this happen."* (followed by a large braindump)
- *"I have a feature idea I want fully scoped and shipped end-to-end."*
- *"Take this PRD and run it."*

**Not the right skill for**: single-file changes, bug fixes, quick refactors, simple Q&A. The orchestration overhead only pays off when the work genuinely benefits from multiple perspectives.

## Example walkthrough

**Prompt**

> We need to add team workspaces to our app. Users should be able to invite others, set roles, see a team dashboard. It should work on web and mobile. Make this happen.

**What the skill does**

```
Phase 1 — Planning

  Step 1: Organize input
    → docs/plans/goal-analysis.md written

  Step 2: Skill scan
    Found: heroui, drizzle-orm, commitpush — capabilities noted

  Step 3: R&D needed?
    Yes — spawn R&D agent to investigate existing auth model
    → docs/plans/research/existing-auth.md

  Step 4: Assemble team (6 agents)
    • Architect — overall data model, service boundaries
    • Backend — workspace CRUD, invite flow, RBAC
    • Frontend Web — team dashboard, invite UI (with heroui)
    • Frontend Mobile — mobile parity
    • Database — schema migration (with drizzle-orm)
    • Security — invite token security, permission audit

  Step 5-6: Each agent writes their plan section
    → docs/plans/01-architecture.md
    → docs/plans/02-backend.md
    → docs/plans/03-frontend-web.md
    → docs/plans/04-frontend-mobile.md
    → docs/plans/05-database.md
    → docs/plans/06-security.md

  Step 7: Consolidated plan reviewed with user

Phase 2 — Execution

  Fresh execution team spawned. Each agent:
    • Reads their section of the plan
    • Implements autonomously
    • Reports back with files changed + tests added

  → Feature delivered end-to-end
```

## Installation

```bash
npx skills add thatjuan/agent-skills --skill team-executor
```

## Bundled resources

| File | Purpose |
|------|---------|
| `SKILL.md` | The full 12-step planning + execution workflow |
| `agent-templates.md` | Persona construction framework and ready-to-use templates for R&D, project lead, and execution agents; software-domain roles get their engineering standards from the `software-engineer` skill rather than embedded personas |
| `orchestration-workflow.md` | Agent spawning (Claude Code Agent tool, Codex subagents, sequential fallback), output collection, conflict resolution, phase transitions |
| `scan-project.sh` | Gathers project context (directory structure, config files, technologies, available skills) for agent prompts |
| `init-plan-dirs.sh` | Initializes the `docs/plans/` directory structure for agent outputs |

## Tips

- **Works best on existing codebases.** Agents read the project to make convention-consistent decisions. On a blank slate, output is more generic — feed it conventions explicitly.
- **Review the plan before Phase 2.** The consolidated plan is your gate. Once execution starts, agents run autonomously.
- **Watch the scope.** 3-7 agents is intentional — more agents means more coordination overhead. If your task truly needs 12 roles, break it into sub-projects.
- **Pair with installed skills.** `team-executor` will hand off skills like `drizzle-orm` or `heroui` to relevant agents, and they'll use them during execution. Install skills your team would actually use.

## Related skills

- [`software-engineer`](../software-engineer/) — the architect/developer/reviewer engineering SME and base engineering layer; team-executor assigns it to every coding/review agent it spawns (coordination here, coding standards there)
- [`superpowers:writing-plans`](https://github.com/obra/superpowers) — lighter-weight planning workflow for single-contributor tasks
- [`superpowers:executing-plans`](https://github.com/obra/superpowers) — manual plan execution with checkpoints (vs. team-executor's autonomous mode)

#!/usr/bin/env bash
# scan-project.sh — Gathers project context for agent prompts
# Usage: bash scan-project.sh [project_root]

set -euo pipefail

PROJECT_ROOT="${1:-.}"

echo "# Project Context Scan"
echo "## Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo ""

# --- Directory structure ---
echo "## Directory Structure"
echo '```'
if command -v tree &>/dev/null; then
    tree -L 3 -I 'node_modules|.git|__pycache__|.venv|venv|dist|build|.next|.cache|coverage|.nyc_output' "$PROJECT_ROOT" 2>/dev/null || find "$PROJECT_ROOT" -maxdepth 3 -not -path '*/\.*' -not -path '*/node_modules/*' | head -200
else
    find "$PROJECT_ROOT" -maxdepth 3 \
        -not -path '*/\.*' \
        -not -path '*/node_modules/*' \
        -not -path '*/__pycache__/*' \
        -not -path '*/venv/*' \
        -not -path '*/.venv/*' \
        -not -path '*/dist/*' \
        -not -path '*/build/*' \
        | head -200
fi
echo '```'
echo ""

# --- Key config files ---
echo "## Key Configuration Files"
for f in package.json pyproject.toml Cargo.toml go.mod Makefile Dockerfile docker-compose.yml .env.example tsconfig.json; do
    if [ -f "$PROJECT_ROOT/$f" ]; then
        echo "### $f"
        echo '```'
        head -50 "$PROJECT_ROOT/$f"
        echo '```'
        echo ""
    fi
done

# --- README ---
if [ -f "$PROJECT_ROOT/README.md" ]; then
    echo "## README.md (first 100 lines)"
    echo '```markdown'
    head -100 "$PROJECT_ROOT/README.md"
    echo '```'
    echo ""
fi

# --- Existing docs ---
if [ -d "$PROJECT_ROOT/docs" ]; then
    echo "## Existing Documentation"
    echo '```'
    find "$PROJECT_ROOT/docs" -type f -name '*.md' | head -20
    echo '```'
    echo ""
fi

# --- Available skills ---
echo "## Available Skills"
SKILL_DIRS=(
    "$HOME/.claude/skills"
    "$PROJECT_ROOT/.claude/skills"
    "/mnt/skills"
)
found_skills=0
for search_dir in "${SKILL_DIRS[@]}"; do
    if [ -d "$search_dir" ]; then
        while IFS= read -r skill_md; do
            if [ -f "$skill_md" ]; then
                skill_dir=$(dirname "$skill_md")
                skill_name=$(basename "$skill_dir")
                # Extract description from frontmatter
                desc=$(sed -n '/^---$/,/^---$/{ /^description:/{ s/^description: *//; p; } }' "$skill_md" 2>/dev/null | head -1)
                if [ -n "$desc" ]; then
                    echo "- **$skill_name** ($skill_md): $desc"
                else
                    echo "- **$skill_name** ($skill_md)"
                fi
                found_skills=$((found_skills + 1))
            fi
        done < <(find "$search_dir" -name "SKILL.md" -type f 2>/dev/null)
    fi
done
if [ "$found_skills" -eq 0 ]; then
    echo "- No skills found in searched locations: ${SKILL_DIRS[*]}"
fi
echo ""

# --- Language / framework detection ---
echo "## Detected Technologies"
[ -f "$PROJECT_ROOT/package.json" ] && echo "- Node.js / JavaScript/TypeScript"
[ -f "$PROJECT_ROOT/pyproject.toml" ] || [ -f "$PROJECT_ROOT/setup.py" ] || [ -f "$PROJECT_ROOT/requirements.txt" ] && echo "- Python"
[ -f "$PROJECT_ROOT/Cargo.toml" ] && echo "- Rust"
[ -f "$PROJECT_ROOT/go.mod" ] && echo "- Go"
[ -f "$PROJECT_ROOT/Gemfile" ] && echo "- Ruby"
[ -f "$PROJECT_ROOT/pom.xml" ] || [ -f "$PROJECT_ROOT/build.gradle" ] && echo "- Java/Kotlin"
[ -f "$PROJECT_ROOT/Dockerfile" ] && echo "- Docker"
[ -f "$PROJECT_ROOT/docker-compose.yml" ] && echo "- Docker Compose"
[ -f "$PROJECT_ROOT/tsconfig.json" ] && echo "- TypeScript"
[ -d "$PROJECT_ROOT/.github" ] && echo "- GitHub Actions"
echo ""

echo "## Scan Complete"

---
name: team-executor
description: Multi-agent orchestration that transforms braindumps into executed results. Assembles expert planning teams (3-7 agents), produces comprehensive execution plans, then deploys fresh execution teams for autonomous delivery. Use when the user describes goals, features, projects, or pastes scattered ideas needing organization and execution. Triggers on "build this", "execute this", "make this happen", "plan and build", or any substantial task description.
---

# Team Executor

An autonomous multi-agent orchestration skill that transforms braindumps into executed results through two phases: expert planning and autonomous execution.

## Overview

This skill operates in two distinct phases:

**Phase 1 — Planning**: Organizes raw input, assembles a team of expert agents, has each analyze the goal from their domain expertise, and produces a comprehensive execution plan.

**Phase 2 — Execution**: A fresh team of agents autonomously executes the plan to completion with no human intervention required.

The key philosophy: experts plan, experts execute, and the output is production-ready.

## Core Principle: Coding-Agent Execution Model

Plans produced by this skill are executed by coding agents, not humans. This changes the decision calculus at every stage:

> The implementation will be carried out by coding agents. Human time, speed, and effort estimates DO NOT apply — do not shy away from a more robust solution because a human would find it slow. Account for risk, security, maintainability, and consistency with existing project conventions. Prefer the most robust, well-engineered option that uses existing tooling/styles/components. Do not introduce parallel patterns when an existing one fits.

Apply this everywhere the team makes tradeoffs: choosing approaches, resolving conflicts, reviewing the plan, filling in details during execution. Reject solutions only for **risk, security, maintainability, or convention** reasons — never because the work is "a lot" or "would take a human a long time." This is the planning *economics*: human effort cost is not a tiebreaker. What "robust" actually means *in code* — the engineering bar a diff must clear — is defined by the `software-engineer` skill, not here.

## Engineering Is Delegated, Not Embedded

team-executor coordinates; it does not hold coding standards, architecture patterns, or software-engineering personas. It keeps the *coordination* judgment — which roles, how many, parallel vs sequential, conflict resolution, phase transitions. The *engineering* judgment lives in the [`software-engineer`](../software-engineer/) skill: the architect/developer/reviewer subject-matter expert and **base engineering layer** for any coding agent.

The rule: **any agent that writes, updates, or reviews code is assigned the `software-engineer` skill.** That agent reads it and embodies its standards (the Three Lenses, the Eight Standards, per-domain practice, the review gate). team-executor no longer inlines those standards anywhere.

**Graceful degradation (prefer-when-present).** team-executor is independently installable and `software-engineer` may not be present. Use the same prefer-when-present shape `implement-issue` uses for team-executor:

- **If `software-engineer` is installed** (surfaced by the Step 2 skill scan at `~/.claude/skills/software-engineer/`, `.claude/skills/software-engineer/`, `../software-engineer/`, `/mnt/skills/software-engineer/`, or a `skills-lock.json` entry): attach it to every coding, architect, and review agent.
- **If it is not installed**: fall back to a trimmed generic inline instruction (review/build for production-readiness, security, maintainability, and consistency with existing conventions). Never hard-depend on `software-engineer` or break when it is absent.

## Bundled Resources

| File | Purpose |
|------|---------|
| [agent-templates.md](agent-templates.md) | Persona construction framework and ready-to-use agent templates |
| [orchestration-workflow.md](orchestration-workflow.md) | Agent spawning, output collection, conflict resolution, phase transitions |
| [scan-project.sh](scan-project.sh) | Gathers project context (directory structure, configs, technologies) for agent prompts |
| [init-plan-dirs.sh](init-plan-dirs.sh) | Initializes `docs/plans/` directory structure for agent outputs |

---

## Phase 1: Planning

### Step 1: Organize the Input

The user's input is likely a braindump — scattered ideas, goals, requirements, and aspirations mixed together. Your first job is to make sense of it.

Read the input carefully and produce a structured interpretation:

1. **Identify distinct goals** — separate intertwined ideas into discrete objectives
2. **Deduplicate** — merge redundant or overlapping items
3. **Fill gaps** — infer missing details that are logically necessary (flag these as inferred)
4. **Establish logical flow** — order goals by dependency and priority
5. **Clarify ambiguity** — resolve vague language into concrete, actionable descriptions

Write this organized version to `docs/plans/goal-analysis.md`. This becomes the canonical reference for all agents.

### Step 2: Scan Available Skills

Before assembling the team, scan all available skills to understand what specialized capabilities exist. Check these locations for SKILL.md files:

- **Claude Code user skills**: `~/.claude/skills/`
- **Claude Code project skills**: `.claude/skills/` in the project root
- **System skills**: `/mnt/skills/` (Codex and similar platforms)
- **Installed skills**: Check `skills-lock.json` in the project root if present

```bash
# Discover skills across all known locations
for dir in ~/.claude/skills .claude/skills /mnt/skills; do
  find "$dir" -name "SKILL.md" -type f 2>/dev/null
done
```

Read each SKILL.md's frontmatter (name + description) to build a capability inventory. These skills may be assigned to team agents who can benefit from them. Not every agent needs a skill — only assign one when it genuinely matches the agent's role.

**Note the engineering base layer.** If the scan surfaces [`software-engineer`](../software-engineer/), it is special: it is the **base engineering layer** to attach to any coding, architect, or review agent (not a role-specific match — the engineering bar every code-touching agent must clear). When it is present, assign it to those agents; when it is absent, fall back to the trimmed inline instruction described under "Engineering Is Delegated, Not Embedded." Stack/SDK skills (`heroui`, `drizzle-orm`, `temporal`, etc.) remain role-specific overlays assigned on top.

### Step 3: Determine If R&D Is Needed

Some goals require research before planning can begin. Look for:

- References to technologies, APIs, or tools the team may not have full context on
- Ambiguous requirements that need investigation
- Integration points with external systems
- Unfamiliar domains or specialized knowledge areas

If R&D is needed, spawn R&D agents first (see [agent-templates.md](agent-templates.md) for the R&D agent template). R&D agents:

- Search the codebase and project docs for existing patterns and conventions
- Read relevant documentation and source files
- Investigate technical feasibility
- Document findings in `docs/plans/research/` as markdown files

Wait for R&D to complete before assembling the planning team, since R&D findings inform which experts are needed.

### Step 4: Assemble the Planning Team

Based on the organized goals and any R&D findings, create a team of 3–7 expert agents. Each agent needs:

1. **A specific persona** — not just a job title, but a complete expert identity with deep domain knowledge, opinions, and a point of view. See [agent-templates.md](agent-templates.md) for persona construction guidelines.

2. **A clear analysis mandate** — what aspect of the goal they're responsible for evaluating

3. **A skill assignment** — any software-domain agent (architect, backend, frontend, devops, QA, security, data) is assigned [`software-engineer`](../software-engineer/) as its engineering skill: the agent reads it and embodies its standards, and team-executor no longer inlines those standards. Optionally add **one** stack/SDK overlay skill that matches the role (`heroui`, `drizzle-orm`, etc.) — base engineering layer plus one overlay (see the skill-assignment exception in [agent-templates.md](agent-templates.md)). Non-software agents get a role-matching skill only when one genuinely fits. If `software-engineer` is not installed, fall back to the trimmed inline instruction (see "Engineering Is Delegated, Not Embedded").

4. **Access to project context** — point them at relevant files, docs, and the organized goal analysis

The team composition covers all necessary perspectives. Common patterns:

- **Software projects**: architect, backend engineer, frontend engineer, devops/infra, QA/testing strategist
- **Data projects**: data engineer, analyst, ML engineer, domain expert
- **Content/creative**: strategist, writer, editor, designer, domain expert
- **Infrastructure**: systems architect, security engineer, SRE, networking specialist
- **Mixed projects**: pull from multiple patterns as needed

Every team includes a **Project Lead** agent whose job is to synthesize all other agents' input into the final plan.

### Step 5: Run the Planning Team

Spawn all expert agents. Each agent receives this prompt structure (customize per agent):

```
You are [PERSONA_DESCRIPTION].

## Your Assignment

Analyze the following project goals from your area of expertise. Provide:

1. **Assessment** — your expert evaluation of the goals as they relate to your domain
2. **Approach** — the specific technical/strategic approach you recommend
3. **Steps** — detailed, ordered steps for your domain's contribution
4. **Dependencies** — what you need from other team members
5. **Risks & Mitigations** — what could go wrong in your domain and how to prevent it
6. **Quality Standards** — what "production-ready" means for your deliverables
7. **Critical Details** — things that are easy to overlook but essential to get right

## Project Goals
[INSERT contents of docs/plans/goal-analysis.md]

## Project Context
[INSERT relevant file paths, existing code structure, docs, etc.]

## Engineering Skill (software-domain agents)
Read and follow the `software-engineer` skill before starting — it is your
engineering base layer (architect/developer/reviewer SME): [SOFTWARE_ENGINEER_PATH]
(If `software-engineer` is not installed, this slot is replaced by a short inline
instruction: build/recommend for production-readiness, security, maintainability,
and consistency with existing project conventions.)

## Available Skill (if assigned)
Read and follow: [STACK_OVERLAY_SKILL_PATH]

## Important
- Your output must be actionable by a coding agent — no vague advice
- Assume the executor has no context beyond what you provide
- Specify exact file paths, commands, configurations, and code patterns
- Reference existing project code/patterns when relevant
- Everything you recommend must result in production-ready output
- Do NOT include timelines, deadlines, or time estimates

## Execution Model
The implementation will be carried out by coding agents. Human time, speed, and effort estimates DO NOT apply — do not shy away from a more robust solution because a human would find it slow. Account for risk, security, maintainability, and consistency with existing project conventions. Prefer the most robust, well-engineered option that uses existing tooling/styles/components. Do not introduce parallel patterns when an existing one fits.
```

### Step 6: Aggregate Into Execution Plan

Once all agents have reported back, the **Project Lead** agent synthesizes everything into a single execution plan. If you didn't spawn a separate Project Lead, do this synthesis yourself.

The aggregation process:

1. **Collect all agent outputs** — read every agent's analysis
2. **Resolve conflicts** — where agents disagree, choose the approach that best serves the overall goal (document the reasoning). Conflict resolution criteria: risk, security, maintainability, and consistency with existing conventions. Do NOT downgrade to a weaker approach because the stronger one is "more work" — coding agents execute the plan, so human effort cost is not a tiebreaker.
3. **Merge dependencies** — create a unified dependency graph
4. **Order execution** — sequence steps across all domains into a logical execution order
5. **Eliminate redundancy** — remove duplicate steps that multiple agents independently suggested
6. **Add integration points** — where work from different agents connects, add explicit integration steps

### Step 7: Software Development Review Gate

**If the project involves software development** (code, APIs, infrastructure, etc.), spawn one additional review-gate agent before finalizing. team-executor does not carry the reviewer's standards — they live in `software-engineer`.

**Preferred (when `software-engineer` is installed).** Spawn a review-gate agent, assign it the [`software-engineer`](../software-engineer/) skill, and instruct it to apply the **Reviewer Lens** (`../software-engineer/references/review-gate.md`) to the draft plan as if the plan were a diff awaiting review:

```
You are a review-gate agent. Read and follow the `software-engineer` skill,
and apply its Reviewer Lens to the draft execution plan below:
[SOFTWARE_ENGINEER_PATH] — specifically references/review-gate.md.

## Your Task
Treat the draft plan as a diff awaiting review. For each section:
1. Flag anything that would not survive the review gate / would not pass a
   production code review
2. Add missing steps an experienced engineer would expect
3. Strengthen vague instructions with specific implementation details
4. Verify the plan follows existing project patterns (check the codebase)

The agents executing this plan will follow it literally. Be constructive but thorough.

## Execution Model
This plan will be executed by coding agents, not humans. Do NOT recommend
simpler/weaker approaches on the grounds that the robust option is "too much
work" or "would take a human too long." Flag issues only on risk, security,
maintainability, scalability, or convention grounds. If the plan picks a
less-robust approach to save effort, push back and recommend the stronger one.

## Execution Plan
[INSERT the draft plan]

## Project Codebase
[INSERT relevant file tree and key files]
```

**Fallback (when `software-engineer` is not installed).** Spawn the same review-gate agent with this short inline mandate in place of the skill assignment, keeping the Execution Model paragraph above:

```
Review the draft execution plan as if it were a diff awaiting a demanding
production review. Flag anything that would not ship: gaps in
production-readiness, security, maintainability, or consistency with existing
project conventions. Add missing steps, make vague instructions specific, and
verify the plan follows existing project patterns (check the codebase).
```

Incorporate this reviewer's feedback into the final plan.

### Step 8: Write the Final Plan

Write the finalized plan to `docs/plans/execution-plan.md` using this structure:

```markdown
# Execution Plan: [Project Title]

## Overview
[2-3 sentence summary of what this plan accomplishes]

## Goals
[Numbered list of concrete objectives from the goal analysis]

## Architecture / Approach
[High-level approach with key decisions and their rationale]

## Execution Steps

### Phase N: [Phase Name]

#### Step N.M: [Step Name]
**Objective**: [What this step accomplishes]
**Details**:
[Specific, detailed instructions — file paths, code patterns, configs, commands]
**Inputs**: [What this step needs]
**Outputs**: [What this step produces]
**Quality Criteria**: [How to verify this step is done correctly]

[Repeat for all steps...]

## Integration Points
[Where different components connect and how to verify integration]

## Quality Assurance
[Testing strategy, validation steps, acceptance criteria]

## Risk Register
[Known risks and their mitigations]

## File Structure
[Expected project structure after execution]
```

The plan has these properties:
- **Self-contained** — an agent with no prior context can execute it
- **Specific** — exact file paths, code patterns, command sequences
- **Ordered** — steps are sequenced by dependency
- **Verifiable** — each step has clear completion criteria
- **Production-grade** — the output meets professional standards
- **Timeline-free** — no dates, deadlines, or time estimates anywhere
- **Effort-agnostic** — superior, robust solutions are chosen over quicker compromises; human effort cost is not a factor in plan decisions (risk, security, maintainability, and convention-fit are)

---

## Phase 2: Execution

Phase 2 uses a completely fresh team of agents. They receive only the execution plan and project context — not the Phase 1 deliberation history. This ensures clean execution without planning-phase bias.

### Step 9: Assemble the Execution Team

Read `docs/plans/execution-plan.md` and create execution agents based on the plan's phases and steps. Each execution agent:

1. **Has a focused scope** — responsible for a specific phase or group of related steps
2. **Has a complete persona** — expert identity matching the work they'll do (see [agent-templates.md](agent-templates.md))
3. **Has the right skills** — assign skills that match their work. Any agent that writes, updates, or reviews code is assigned [`software-engineer`](../software-engineer/) as its **base engineering layer** (plus optionally one stack/SDK overlay), exactly as in planning. Execution agents are the ones that actually build, so this is where the engineering bar lands. If `software-engineer` is not installed, fall back to the trimmed inline instruction (see "Engineering Is Delegated, Not Embedded").
4. **Operates autonomously** — makes all decisions independently based on project context

The execution team prompt structure:

```
You are [PERSONA_DESCRIPTION].

## Your Mission
Execute the following steps from the project execution plan. Work autonomously
and make all decisions yourself — do not wait for or request human input.

## Decision-Making Guidelines
- Root all decisions in the existing project code, docs, and conventions
- When multiple valid approaches exist, choose the one most consistent with the codebase
- If you encounter ambiguity, choose the most production-appropriate option
- Document significant decisions as code comments or in docs/
- You are a coding agent, not a human — do not cut corners or pick a weaker approach because the robust one would take "a long time." Optimize for risk, security, maintainability, and consistency. Effort cost is not a constraint.

## Steps to Execute
[INSERT relevant steps from execution-plan.md]

## Project Context
[INSERT relevant file paths, existing patterns, dependencies]

## Engineering Skill (if this agent writes/updates/reviews code)
Read and follow the `software-engineer` skill before starting — it is your
engineering base layer (architect/developer/reviewer SME): [SOFTWARE_ENGINEER_PATH]
(If `software-engineer` is not installed, this slot is replaced by a short inline
instruction: build for production-readiness, security, maintainability, and
consistency with existing project conventions.)

## Available Skill (if assigned)
Read and follow: [STACK_OVERLAY_SKILL_PATH]

## Critical Requirements
- All output must be production-ready — no TODOs, no placeholders, no stubs
- Follow existing project conventions and patterns
- Meet the engineering bar defined by the `software-engineer` skill (or the inline fallback above) for code quality — error handling, clarity, and maintainability are defined there, not here
- Run and verify your work before considering a step complete
- If a step depends on another agent's output, check for it and adapt as needed
```

### Step 10: Execute

Spawn all execution agents. Key principles:

1. **Parallel where possible** — agents working on independent steps can run simultaneously
2. **Sequential where necessary** — respect dependency ordering from the plan
3. **No human input** — agents make all decisions autonomously using project context
4. **Verify as you go** — each agent validates their work (run tests, lint, verify output)

### Step 11: Integration & Verification

After all execution agents complete, perform a final integration pass:

1. **Check all outputs exist** — verify every deliverable from the plan was produced
2. **Run integration checks** — if the project has tests, run them; if it has a build, build it
3. **Verify consistency** — ensure outputs from different agents are compatible
4. **Fix integration issues** — spawn targeted agents to resolve any conflicts
5. **Final quality check** — verify the result meets the plan's quality criteria

### Step 12: Report

Write a completion report to `docs/plans/execution-report.md`:

```markdown
# Execution Report: [Project Title]

## Summary
[What was accomplished]

## Completed Steps
[List of all executed steps with status]

## Key Decisions Made
[Significant autonomous decisions and their rationale]

## Files Created/Modified
[Complete list of all changes]

## Verification Results
[Test results, build status, integration check outcomes]

## Known Limitations
[Anything that couldn't be fully resolved]

## Next Steps (if any)
[Remaining work that requires human input or was out of scope]
```

---

## Agent Spawning

The orchestrator spawns agents using the platform's agent/subagent capabilities. See [orchestration-workflow.md](orchestration-workflow.md) for platform-specific spawning patterns (Claude Code Agent tool, Codex subagents, sequential fallback).

Key spawning principles:
- **Planning agents** run in parallel — they analyze independently
- **R&D agents** run before planning agents — their findings inform team composition
- **Execution agents** respect the dependency graph — independent steps run in parallel, dependent steps run sequentially
- **Integration agents** run after all execution agents complete

## Guidance for the Orchestrator

The orchestrator's role is that of a CTO assembling and directing a world-class team — identifying what expertise is needed, assembling the right people, giving them clear mandates, and synthesizing their output.

**Rich personas produce better output.** The more specific and opinionated the agent personas, the better their analysis and execution. A "backend developer" gives generic advice. A "distributed systems engineer who has debugged production outages at scale and insists on idempotent operations and circuit breakers" gives battle-tested advice.

**Read the project first.** Before assembling any team, understand what already exists. Read the project structure, key source files, existing docs, and configuration. This context is essential for creating relevant agents and realistic plans.

**3-5 agents is the sweet spot for planning.** More agents means more synthesis work and more potential for conflicts. Only add agents when they bring a genuinely distinct perspective.

**Phase 2 gets fresh context.** This is intentional. Execution agents follow the plan, not the messy deliberation that produced it. The plan is the interface between Phase 1 and Phase 2.

**Optimize for robustness, not human effort.** The plan will be executed by coding agents. Reject solutions for risk, security, maintainability, or convention-mismatch reasons — never because they would be "a lot of work" for a human. When the team produces a competent-but-conservative plan, push them toward the stronger option. The whole point of this skill is that coding-agent execution dissolves the effort/scope ceiling that normally constrains software teams.