/orchestrated-execution

name: orchestrated-execution
description: 4-phase execution loop for work units - IMPLEMENT, VALIDATE, ADVERSARIAL REVIEW, COMMIT
auto_activate: false
triggers:
  - "orchestrated execution"
  - "4-phase loop"
  - "adversarial review"

Orchestrated Execution Skill

**Core principle**: Trust nothing. Verify everything. Review adversarially.

This skill defines a generalized 4-phase execution loop that any orchestrator can invoke when implementing work units. It replaces linear "implement then review" flows with a rigorous cycle that independently validates results and adversarially reviews against a written spec contract.

---

Coordination Mode Note

This skill is mode-agnostic — the 4-phase execution loop works identically in both Task Mode and Team Mode. The differences:

• **Phase 1 (IMPLEMENT)**: In Team Mode, the coding subagent may be a persistent teammate (retains context across work units). In Task Mode, it's a fresh `Task()` per work unit.
• **Phase 3 (ADVERSARIAL REVIEW)**: ALWAYS a fresh `Task()` instance in BOTH modes. Never a teammate, never resumed.
• **All quality gates**: Unchanged regardless of mode.

See `./guides/agent-coordination.md` for full mode detection and coordination details.

---

Plan Review Gate

After drafting an implementation plan (Step 1: Plan Validation), submit it to the **Plan Review Gate** before presenting to the user. The gate spawns 3 adversarial reviewers (Feasibility, Completeness, Scope & Alignment) — all must PASS. See `skills/plan-review-gate/SKILL.md` for details.

---

When to Use This Skill

• **Complex tasks** decomposed into multiple work units
• **Tasks with a written spec** containing Definition of Done (DoD) items
• **Multi-agent orchestration** where subagents produce work that needs verification
• **High-stakes changes** where self-reported "it works" is insufficient

**Do NOT use for**: Single-file bug fixes, copy changes, or tasks without a spec.

---

1. Plan Validation (Pre-Flight Checklist)

Before submitting a plan to the Design Review Gate, the orchestrator MUST verify every item on this checklist. This prevents expensive design review cycles on fundamentally broken plans.

> **Note**: The `Plan` subagent type cannot write files (it has read-only access by design). If you spawn an Architect as a Plan subagent, it will return the plan as text in its response. The orchestrator must write the plan to `PLAN.md` itself.

Architecture Checklist

• [ ] Every data access goes through a service layer (no direct DB calls from routes/handlers)
• [ ] Each work unit has a single responsibility (max ~5 files created/modified)
• [ ] Error handling strategy specified (typed error hierarchy, how errors cross layer boundaries)
• [ ] No hard-coded configuration — environment variables for all external service config

Dependency Graph Checklist

• [ ] Each WU's dependencies are minimal (only depends on what it actually imports/uses)
• [ ] No unnecessary serialization — WUs that CAN be parallel ARE marked parallel
• [ ] No circular dependencies
• [ ] Integration WUs exist to wire components into the app shell (not just built in isolation)

API Contract Checklist

If the plan includes HTTP endpoints or WebSocket protocols, verify:

• [ ] Every HTTP endpoint specifies: method, path, request schema, all response status codes, error response shapes
• [ ] WebSocket message types fully specified (client-to-server AND server-to-client message type tables)
• [ ] Protocol concerns documented: heartbeat, reconnection, acknowledgment strategy
• [ ] Response codes are explicit (not "returns the todo" but "returns 201 with the created todo")

Security Checklist

• [ ] Trust boundaries identified (which inputs are untrusted?)
• [ ] Input validation specified for every endpoint/handler (schema, max size)
• [ ] Rate limiting specified for expensive operations (AI API calls, file uploads)
• [ ] Authentication/authorization requirements documented
• [ ] Secrets management documented (.env pattern, .gitignore verification)

UI/UX Checklist

If the plan includes a user interface:

• [ ] User flows documented with trigger, steps, and visible outcome (see UI-FLOWS.md template)
• [ ] Text-based wireframes for each screen showing layout and interactive elements
• [ ] Empty states, loading states, and error states defined for each view
• [ ] Integration work units explicitly created to wire components into the app shell
• [ ] Component hierarchy documented (what renders what, where)

External Dependencies Checklist

• [ ] All external services identified (APIs, SDKs, third-party services)
• [ ] Required credentials/config documented (env var names, how to obtain)
• [ ] Human checkpoint planned BEFORE work units that depend on external services
• [ ] Graceful degradation specified for when credentials are missing
• [ ] `.env.example` includes all required env vars

Completeness Checklist

• [ ] All human checkpoints from the spec are included
• [ ] All features from the spec have at least one work unit
• [ ] Tooling is consistent (one package manager, matching config files across WUs)
• [ ] No WU exceeds ~5 files or ~3 distinct concerns
• [ ] WUs that are too large are split with explicit dependencies between parts

**If any checklist item fails, fix the plan BEFORE submitting to Design Review Gate.**

Required Plan Sections

Every plan submitted for Design Review MUST include these sections:

1. **Work Unit Decomposition** — WU list with DoD items, file scopes, dependencies 2. **API Contract** (if applicable) — structured endpoint/protocol specs:

   ### POST /api/todos
   - **Request Body**: `{ title: string }` (required, 1-500 chars, trimmed)
   - **Success**: `201 Created` -> `{ id, title, completed, createdAt, updatedAt }`
   - **Errors**: `400` (validation) / `500` (internal)

3. **Security Considerations** — trust boundaries, input validation table, rate limiting table, secrets management 4. **User Fl