# Orchestrator

> Master Orchestrator — the intelligent execution engine for full-lifecycle product delivery across all 5 TaskPilot domains (PM, PE, SDE, QAE, UX). Orchestrates 55+ skills across 9 phases: Discovery, Validation, Planning, Design, Architecture, Build, Quality, Launch, Feedback. Use this whenever you need to build a complete feature or product from idea to launch with cross-domain coordination. Use WHENEVER you hear: build a feature, ship a product, implement a system, launch an initiative, run a full project lifecycle, need quality gates, require cross-team coordination, anything involving multiple domains.

- Skill: `cortexark/orchestrator` (Agent Skill, multi-file: 5 files)
- Install (CLI): `npx skillmds@latest add cortexark/orchestrator`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cortexark/orchestrator/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: cortexark (https://skillmd.com/u/cortexark)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/cortexark/orchestrator

---


# Master Orchestrator Engine

**Status**: Ready to orchestrate ANY feature request

## Overview

The Master Orchestrator is the intelligent execution engine that:

1. **Analyzes ANY feature request** — not hardcoded for specific products
2. **Intelligently reviews all skills in all role levels, analyzes what the product needs, and builds the skill list** — picks only the skills needed from 55+, based on feature analysis
3. **Orchestrates 9-phase SDLC** — Discovery → Validation → Planning → Design → Architecture → Build → Quality → Launch → Feedback
4. **Executes autonomously** — I am the team: run skills, write code, test, find bugs, fix bugs, document
5. **Maintains user control** — 4 decision gates where user reviews and approves before proceeding
6. **Tracks everything** — commits, PRs, bug lifecycle, quality metrics in organized folders

## Core Principles

- **Not hardwired**: Works for ANY feature type (auth, dashboard, API, mobile, etc.)
- **Observable**: Shows action plans before executing each skill
- **Traceable**: All outputs organized in `.project/skill_response_doc/` by phase eg: SDE feature PR,codereview, Feature completion status, system design, QA sign off and other report
- **User-gated**: Critical decisions at Phase 3, 4, 7, and before final commit
- **Autonomous execution**: I execute all skills sequentially, with mini-parallelism where possible
- **Real code delivery**: Actual files written to repo, real commits/PRs, real code reviews

---

## Project Detection (Runs Once on First Invocation)

Before Phase 1, the orchestrator MUST detect the project environment and save it for use by all subsequent phases and gates.

### Step 1: Language & Framework Detection

Scan the project root for these files to determine language, build, and test commands:

| Marker File | Language | Build Command | Test Command | Coverage Flag |
|-------------|----------|---------------|--------------|---------------|
| Package.swift | Swift | `swift build` | `swift test` | `--enable-code-coverage` |
| package.json | Node/TS | `npm run build` | `npx jest --coverage` or `npm test` | `--coverage` |
| requirements.txt / pyproject.toml | Python | `python -m py_compile` | `pytest --cov=src/` | `--cov` |
| go.mod | Go | `go build ./...` | `go test -cover ./...` | `-cover` |
| Cargo.toml | Rust | `cargo build` | `cargo test` | `cargo tarpaulin` |
| build.gradle | Kotlin/Java | `./gradlew build` | `./gradlew test` | `jacocoTestReport` |
| pom.xml | Java | `mvn compile` | `mvn test` | `jacoco:report` |
| Makefile | Any | `make build` | `make test` | (check Makefile) |

If multiple markers exist, use the primary one (e.g., Package.swift over Makefile for Swift projects).

### Step 2: Save Detection Results

Write to `.project/environment.json`:

```json
{
  "language": "swift",
  "framework": "SwiftUI",
  "build_command": "swift build",
  "test_command": "swift test --enable-code-coverage",
  "source_extensions": [".swift"],
  "stub_scan_extensions": ["--include='*.swift'"],
  "detected_at": "2026-03-05T10:00:00Z",
  "detected_from": "Package.swift"
}
```

### Step 3: Use in Gates 6A-6D

All Phase 6 gates read commands from `.project/environment.json` instead of hardcoded values:
- **Gate 6A**: Run `build_command` → check exit code
- **Gate 6B**: Run stub scan grep with `stub_scan_extensions`
- **Gate 6C**: Run `test_command` → parse coverage output
- **Gate 6D**: Run `build_command` after combining all parallel agents' code

If `.project/environment.json` does not exist when Gate 6A is reached, BLOCK and run Project Detection first.

---

## Feature Analysis: 5 Dimensions

Before selecting skills, the orchestrator analyzes the feature across 5 key dimensions:

### 1. **Domain** — Who leads this feature?
- **PM-driven**: Product decisions, market gaps, user needs
- **SDE-driven**: Architecture, technical infrastructure, performance
- **UX-driven**: User interface, interaction, accessibility
- **PE-driven**: Strategic alignment, tech debt, organizational impact
- **QAE-driven**: Quality critical paths, security, compliance

Example: OAuth2 = **PM (product decision) + SDE (technical implementation)**

### 2. **Complexity** — How complicated is it?
- **Simple**: Single feature, low risk, <1 week
- **Medium**: New capability, some architecture, 1-4 weeks
- **High**: Platform rebuild, major refactor, 4-12 weeks
- **Critical**: Core infrastructure, security-sensitive, >12 weeks

Example: OAuth2 = **Medium-High** (new auth system, security-sensitive)

### 3. **Risk Level** — What could go wrong?
- **Low**: Isolated change, can rollback easily
- **Medium**: Affects multiple systems, needs testing
- **High**: Authentication, payment, data handling
- **Critical**: Infrastructure, production data, compliance

Example: OAuth2 = **High** (authentication is critical path)

### 4. **Scope** — How many skills needed?
- **Small**: 1-3 skills
- **Medium**: 4-8 skills
- **Large**: 9-15 skills
- **Massive**: 16+ skills

Example: OAuth2 = **8-13 skills**

### 5. **Team Capacity** — How many people?
- **1 person**: Sequential execution, mini-parallelism
- **2-3 people**: Some parallelism
- **5+ people**: Heavy parallelism

Example: OAuth2 with 1 person = **4-5 weeks sequential**

---

## 9-Phase SDLC Model

### Phase 1: DISCOVERY
**Goal**: Understand the problem, user needs, competitive landscape

**Skills**: pm:customer-research, pm:research-agent, pm:buyer-psychology, pe:org-health
**Outputs**: .pm/research/, .pm/competitors/, .pe/org/

---

### Phase 2: VALIDATION
**Goal**: Validate assumptions, test feasibility, align on strategy

**Skills**: pm:discovery-validator, pm:experiment-designer, pe:tech-strategy, ux:design-system
**Outputs**: .pm/experiments/, .pe/strategy/, .ux/design-systems/

---

### Phase 3: PLANNING ⚠️ USER GATE 1
**Goal**: Create product spec, define success metrics, validate technical feasibility

**Skills**: pm:gap-analyst, pm:prioritization-engine, pm:prd-generator, pm:metrics-advisor, pe:architecture-reviewer
**Outputs**: .pm/gaps/, .pm/prds/, .pm/metrics/, .pe/architecture/
**Deliverables Tracked**:
- ✅ BRD Document (.pm/prds/)
- ✅ PM Document (gap analysis)
- ✅ Success Metrics Definition

**USER GATE 1**: Review BRD, metrics, tech strategy → Approve, Revise, or Reject

---

### Phase 4: DESIGN ⚠️ USER GATE 2
**Goal**: Design user interface, component library, accessibility

**Skills**: ux:design-system, ux:component-design, ux:visual-hierarchy, ux:typography, ux:color-system, ux:accessibility
**Outputs**: .ux/design-systems/, .ux/components/, .ux/colors/, .ux/typography/
**Deliverables Tracked**:
- ✅ Design Theme Files (.ux/design-systems/)
- ✅ Component Specs (all states)
- ✅ Accessibility Audit

**USER GATE 2**: Review design files, components, accessibility → Approve, Revise, or Reject

---

### Phase 5: ARCHITECTURE
**Goal**: Technical design, scalability assessment, dependency mapping

**Skills**: sde:requirements, sde:system-design, sde:architecture, pe:leverage-analyzer
**Outputs**: .sde/requirements/, .sde/designs/, .sde/architecture/, .pe/decisions/
**Deliverables Tracked**:
- ✅ System Design Document (.sde/designs/)
- ✅ Architecture Review (.sde/architecture/)
- ✅ Technical Feasibility Sign-off

---

### Phase 6: BUILD
**Goal**: Write code using TDD, maintain quality standards

**Skills**: sde:tdd, sde:code-craftsman, sde:code-review
**Execution**:
- Write actual code files to repo
- Create commits with meaningful messages
- Use code-review skill to review own code
- Track all PRs in code-delivery-log.md

**Outputs**: .sde/code/, .sde/tests/, .sde/reviews/, code in repo
**Deliverables Tracked**:
- ✅ Code Review (sde:code-review skill output)
- ✅ PR References (in code-delivery-log.md)
- ✅ Commit Hashes
- ✅ Test Coverage Report

---

### Phase 6 Completion Gate: MANDATORY BUILD VERIFICATION ⛔

**CRITICAL: ALL 4 gates below MUST pass before Phase 7 begins. These are hard blocks, not warnings. If ANY gate fails, Phase 6 remains IN PROGRESS.**

#### Gate 6A: Compilation Verification
Run the project's build command and verify zero errors:
- **Swift/Xcode:** `swift build 2>&1` or `xcodebuild build`
- **Node.js:** `npm run build` or `tsc --noEmit`
- **Python:** `python -m py_compile` on all source files
- **Go:** `go build ./...`

**PASS:** Build exits code 0, zero errors (warnings acceptable)
**FAIL:** BLOCK Phase 7. List all compilation errors. Route to sde:code-craftsman.

#### Gate 6B: TODO/Stub/Placeholder Detection
Scan ALL source files for incomplete implementations:
```bash
grep -rn 'TODO\|FIXME\|HACK\|STUB\|placeholder.*compilation\|placeholder.*accessor\|placeholder.*for.*actual\|fatalError.*not.implemented\|preconditionFailure\|NotImplementedError\|raise NotImplementedError\|throw new Error.*not implemented' --include='*.swift' --include='*.ts' --include='*.py' --include='*.go' --include='*.java' --include='*.kt' --include='*.js' --include='*.tsx' .
```

**Critical patterns (MUST have zero matches):**
| Pattern | Language | Indicates |
|---------|----------|-----------|
| `TODO`, `FIXME`, `HACK`, `STUB` | All | Incomplete work |
| `placeholder for compilation` | Swift/Kotlin | Empty accessor to satisfy compiler |
| `fatalError("not implemented")` | Swift | Crash-on-call stub |
| `NotImplementedError` | Python/Kotlin | Explicit not-implemented |
| `throw new Error("not implemented")` | TS/JS | Explicit not-implemented |
| Empty function body with only comment | All | Deferred real implementation |

**Exceptions (do NOT flag):** `fatalError` in `required init?(coder:)` (standard Swift pattern), `placeholder` in UI text strings, `// TODO: v2` with explicit tech debt documentation.

**PASS:** Zero critical pattern matches
**FAIL:** BLOCK Phase 7. List all stubs with file:line. Route to sde:code-craftsman.

#### Gate 6C: Test Coverage Verification
Run the test suite and measure coverage:
- **Swift:** `swift test --enable-code-coverage`
- **Node.js:** `npx jest --coverage`
- **Python:** `pytest --cov=src/`
- **Go:** `go test -cover ./...`

**PASS:** Coverage >= 80% AND zero test failures
**FAIL:** If coverage < 80%, route to sde:tdd. If tests fail, route to sde:debugging.

#### Gate 6D: Contract Integrity (Parallel Agents Only)
If Phase 6 used parallel agents, verify interfaces match:
1. Identify all protocols/interfaces produced by one agent and consumed by another
2. Compile the FULL project to verify no type mismatches at boundaries
3. Check no agent created duplicate/conflicting definitions

**PASS:** Full project compiles with all agents' code combined
**FAIL:** BLOCK Phase 7. Identify conflicting interfaces. Generate shared protocol file. Route affected agents to fix.

**Gate Enforcement:** Record results in `.project/skill_response_doc/phase-6-build/gate-results.md`. If ANY gate fails, orchestrator MUST NOT transition to Phase 7.

---

### Phase 7: QUALITY ⚠️ USER GATE 3
**Goal**: Comprehensive testing, security scanning, performance validation

**Skills**: qae:test-strategy, qae:test-automation, qae:api-testing, qae:security, qae:performance, qae:defect-management
**Outputs**: .qae/strategies/, .qae/automation/, .qae/security/, .qae/performance/, .qae/defects/
**Deliverables Tracked**:
- ✅ QA Sign-off Document
- ✅ Test Coverage Report (>80% required)
- ✅ Security Scan Results
- ✅ Performance Baseline
- ✅ Bug Report (all open/closed)
- ✅ Go/No-Go Decision

**Bug Lifecycle**:
- QAE finds bug → create bug-[id].md
- SDE fixes (Phase 6 loop) → commit with bug ref
- QAE validates → mark closed

**USER GATE 3**: Review QA report, test coverage, bugs, performance → Approve, Fix & Retest, or Reject

---

### Phase 8: LAUNCH
**Goal**: Deploy to production, setup monitoring and runbooks

**Skills**: qae:cicd-pipeline, pe:incident-reliability
**Outputs**: .qae/pipelines/, .pe/incidents/
**Deliverables Tracked**:
- ✅ CI/CD Pipeline Config
- ✅ Deployment Runbook

---

### Phase 9: FEEDBACK
**Goal**: Measure impact, assess tech debt, plan next iteration

**Skills**: pm:metrics-advisor, pm:pivot-analyzer, pe:technical-quality
**Outputs**: .pm/metrics/, .pm/analysis/, .pe/quality/
**Deliverables Tracked**:
- ✅ Post-Launch Metrics Report
- ✅ Tech Debt Assessment

---

## User Decision Gates

### Gate 1: After Phase 3 (BRD Review)
**Files for Review**: .project/skill_response_doc/phase-3-planning/
- pm-gap-analyst.md
- pm-prd-generator.md
- pm-metrics-advisor.md
- pe-architecture-reviewer.md

**User Decision**: ✅ APPROVE → Phase 4 | 🔄 REVISE | ❌ REJECT

---

### Gate 2: After Phase 4 (Design Review)
**Files for Review**: .project/skill_response_doc/phase-4-design/
- Component state matrices
- Color palette with WCAG ratios
- Typography system
- Accessibility audit
- Responsive breakpoints

**User Decision**: ✅ APPROVE → Phase 5 | 🔄 REVISE | ❌ REJECT

---

### Gate 3: After Phase 7 (QA Review)
**Files for Review**: .project/skill_response_doc/phase-7-quality/
- Test coverage report (>80% required)
- Security scan results
- Performance baseline
- Bug list (open, fixed, closed)
- Risk assessment

**User Decision**: ✅ APPROVE → Phase 8 | 🔄 FIX & RETEST | ❌ REJECT

---

### Gate 4: Before Git Commit (Final Review)
**Files for Review**: .project/skill_response_doc/ (entire)
- All skill outputs by phase
- code-delivery-log.md (all commits)
- bug-report.md (final status)
- final-product-summary.md

**User Decision**: ✅ APPROVE → COMMIT TO MAIN | 🔄 CHANGES | ❌ REJECT

---

## User Gate Interaction Protocol

When a user gate is reached, the orchestrator MUST follow this exact protocol:

### 1. Present Gate Summary
List all deliverables produced in the completed phase with their file paths:
```
Phase 3 Deliverables:
- .pm/prds/feature-name.md (PRD)
- .pm/gaps/analysis.md (Gap Analysis)
- .pm/metrics/north-star.md (Success Metrics)
```

### 2. Show Quality Gate Results
Display pass/fail for each gate criterion relevant to this phase:
```
Quality Gate Results:
✅ Customer evidence: 5 interviews conducted
✅ Success metrics: North star + 2 secondary defined
✅ Acceptance criteria: 8 testable criteria defined
❌ Competitive positioning: Only 2 competitors analyzed (need 3+)
```

### 3. Ask User via AskUserQuestion Tool
Present exactly 3 options using the AskUserQuestion tool:
- **Option 1: "Approve"** — Proceed to next phase
- **Option 2: "Revise"** — User specifies what to change, orchestrator loops back
- **Option 3: "Reject"** — Stop execution, save state

### 4. Handle Each Response

**On APPROVE**: Update `.project/status.md` to mark phase COMPLETE, proceed to next phase.

**On REVISE**:
1. Ask user what specifically needs to change
2. Loop back to the skill that produced the deliverable
3. Re-run with user's feedback incorporated
4. Present gate again after revision

**On REJECT**:
1. Save current state to `.project/status.md` with REJECTED status
2. Log rejection reason in `.project/orchestration-log.md`
3. Stop execution — user can resume later

---

## Quality Standards Per Role

High bar standards that each role MUST meet at decision gates and phase completion. These are non-negotiable quality criteria, not aspirational.

### Product Management High Bar

**Phase 3 (Planning) Gate Criteria:**
- ✅ **Customer Evidence** — 5+ customer interviews OR market research conducted, not assumptions
- ✅ **Competitive Positioning** — Specific gaps identified in 3+ competitors, not generic "we're better"
- ✅ **Success Metrics** — North star metric + 2-3 secondary metrics with clear success/failure thresholds
- ✅ **Acceptance Criteria** — 5-10 specific, testable acceptance criteria (what "done" means)
- ✅ **Priority Justification** — RICE score shows this outweighs other backlog items, not just "we should build it"
- ❌ **Reject if**: No customer interviews, metrics are vanity metrics, acceptance criteria are vague ("users can X"), priority score missing

**Deliverables Quality Checklist:**
- BRD includes: Problem statement, user personas, JTBD, competitive context, target metrics
- PRD includes: Feature description, user flows, edge cases, success criteria, rollback plan
- Metrics are: Measurable, actionable, easy to track (avoid "customer satisfaction")

### Senior SDE High Bar

**Phase 5 (Architecture) Gate Criteria:**
- ✅ **Scalability Analysis** — System design shows QPS estimates, storage requirements, bandwidth calculations
- ✅ **Trade-off Clarity** — Architecture states what you gain AND lose (e.g., "faster reads, slower writes")
- ✅ **SOLID Compliance** — Design avoids Single Responsibility, Open/Closed, Liskov, Interface Segregation violations
- ✅ **Dependency Mapping** — All external service dependencies identified with failure modes
- ✅ **Feasibility Sign-off** — PE or tech lead has reviewed design and confirmed it's buildable
- ❌ **Reject if**: No estimation (you don't know if it scales), trade-offs missing, circular dependencies exist, tech debt not acknowledged

**Phase 6 (Build) Gate Criteria:**
- ✅ **TDD Process** — Every feature starts with failing test, passes test, then refactors
- ✅ **Test Coverage** — Minimum 80% code coverage (measured, not estimated)
- ✅ **Code Review Issues** — Zero critical/high severity issues (SOLID violations, security bugs, performance problems)
- ✅ **Boy Scout Rule** — Every file touched is cleaner than found (no "while I'm here" tech debt additions)
- ✅ **Meaningful Commits** — Commit messages explain WHY, not just WHAT (atomic, descriptive)
- ❌ **Reject if**: Test coverage <80%, code review issues unresolved, Boy Scout rule violated, commits are too large to review

**Deliverables Quality Checklist (MANDATORY — enforced by Gate 6A-6D):**
- [GATE 6A] Code compiles without errors (verified by running build command)
- [GATE 6B] No TODO/FIXME/stub/placeholder code detected (verified by grep scan)
- [GATE 6C] Test coverage >= 80% with zero failures (verified by test runner)
- [GATE 6D] All parallel-agent interfaces compile together (verified by full build)
- Code review completed with zero critical issues
- PR includes test coverage report percentage
- Commits are logically grouped and well-described

### UX/Design High Bar

**Phase 4 (Design) Gate Criteria:**
- ✅ **Accessibility Compliance** — WCAG 2.2 AA on all components (not pending, not next sprint)
- ✅ **Component Completeness** — All states specified: default, hover, active, focus, disabled, loading, error, skeleton
- ✅ **Design Token System** — Colors, typography, spacing follow 3-tier design token model (reference → system → component)
- ✅ **Responsive Breakpoints** — Designs tested at mobile (375px), tablet (768px), desktop (1280px)
- ✅ **User Testing Evidence** — Prototypes tested with 3+ users, feedback incorporated
- ❌ **Reject if**: Accessibility not tested, states are missing, tokens are inconsistent, designs untested with users, breakpoints assumed

**Deliverables Quality Checklist:**
- Component state matrix shows all 8+ states with screenshots
- Color palette includes WCAG AA contrast ratios for text/background combinations
- Typography system includes line-height, letter-spacing, size scales with CSS values
- Accessibility audit completed and passed (keyboard nav, screen reader, ARIA)
- Responsive design tested at all breakpoints, not just desktop

### Quality Assurance High Bar

**Phase 7 (Quality) Gate Criteria:**
- ✅ **Test Coverage Baseline** — Minimum 80% code coverage achieved and documented
- ✅ **Security Scanning Passed** — OWASP Top 10 scan run, zero critical/high vulnerabilities
- ✅ **Performance Baseline** — Response times, load times, memory usage measured and documented
- ✅ **Defect Triage Complete** — All bugs severity/priority classified, critical/high bugs have fix commits
- ✅ **Risk Assessment** — Known limitations documented (e.g., "scaling to 100k users untested")
- ❌ **Reject if**: Coverage <80%, security scan not run or has critical bugs, performance not measured, bugs untriaged, risk assessment missing

**Deliverables Quality Checklist:**
- Test coverage report shows coverage % and trend (improving, stable, declining)
- Security scan includes: OWASP checklist, specific vulnerabilities found (or none), remediation status
- Performance report includes: baseline metrics, load test results, capacity limits
- Bug report organized by severity: Critical (0 expected), High (<=3), Medium (<=10), Low (<=20)
- Risk assessment lists unknowns and assumptions (e.g., concurrent users, data volume, third-party reliability)

### Principal Engineering High Bar

**Phase 5 (Architecture) & Phase 9 (Feedback) Gate Criteria:**
- ✅ **Architecture Review Complete** — ADR written explaining decision, alternatives considered, trade-offs
- ✅ **Tech Debt Assessed** — Current tech debt inventory (known issues, accumulated shortcuts)
- ✅ **Scalability Assumptions Clear** — Future growth scenarios documented (2x, 10x, 100x users)
- ✅ **Migration/Integration Risks** — If integrating with existing systems, risks identified and mitigated
- ✅ **Org Impact Considered** — How this affects team (skills needed, hiring, training), not just code
- ❌ **Reject if**: No ADR, tech debt hidden/untracked, scalability assumptions unstated, migration risks ignored, org impact unaddressed

**Deliverables Quality Checklist:**
- ADR includes: Context, decision, consequences (good and bad)
- Tech debt inventory is specific (e.g., "JWT library outdated, SQLi risk in legacy queries", not "code is messy")
- Scalability document states limits (e.g., "scales to 50k concurrent, beyond that needs sharding")
- Migration risk register identifies: breaking changes, data migration requirements, rollback plan
- Org impact statement includes: team size needed, new skills required, estimated ramp-up time

---

## Skill Selection Rules by Feature Type examples

### Authentication System (OAuth2)
- **Phase 1**: pm:customer-research, pm:research-agent, pm:buyer-psychology
- **Phase 2**: pm:discovery-validator, pe:tech-strategy
- **Phase 3**: pm:gap-analyst, pm:prd-generator, pm:metrics-advisor
- **Phase 4**: SKIP (backend-heavy)
- **Phase 5**: sde:requirements, sde:system-design, sde:architecture
- **Phase 6**: sde:tdd, sde:code-craftsman, sde:code-review
- **Phase 7**: qae:test-strategy, qae:test-automation, qae:api-testing, qae:security, qae:performance
- **Phase 8-9**: qae:cicd-pipeline, pe:incident-reliability, pm:metrics-advisor

**TOTAL**: 13 skills | **TIME**: 3-4 weeks

### Dashboard/Analytics
- **Phase 1**: pm:customer-research, pm:research-agent
- **Phase 2**: pm:discovery-validator
- **Phase 3**: pm:prd-generator, pm:metrics-advisor
- **Phase 4**: ux:design-system, ux:component-design, ux:visual-hierarchy, ux:color-system, ux:accessibility
- **Phase 5**: sde:system-design, sde:architecture
- **Phase 6**: sde:tdd, sde:code-craftsman, sde:code-review
- **Phase 7**: qae:test-automation, qae:api-testing, qae:performance
- **Phase 8-9**: qae:cicd-pipeline, pm:metrics-advisor

**TOTAL**: 16 skills | **TIME**: 5-6 weeks

### Simple API Endpoint
- **Phase 1-2**: SKIP (internal)
- **Phase 3**: pm:prd-generator, sde:requirements
- **Phase 4**: SKIP (headless)
- **Phase 5**: sde:system-design, sde:architecture
- **Phase 6**: sde:tdd, sde:code-craftsman, sde:code-review
- **Phase 7**: qae:api-testing, qae:security
- **Phase 8-9**: qae:cicd-pipeline

**TOTAL**: 8 skills | **TIME**: 2-3 weeks

---

## Autonomous Execution Model

### How It Works

1. **User provides feature** → "Build OAuth2..."
2. **Orchestrator analyzes** → Feature analysis matrix, skill selection
3. **Orchestrator executes** (for each skill):
   - Create action plan (what skill WILL produce)
   - Execute skill
   - Collect output in skill_response_doc/phase-N/
   - Check quality gates
4. **After each phase** → Update orchestration-log.md, trigger user gates if needed
5. **Code execution** → Write actual code, create commits, track PRs
6. **Bug lifecycle** → QAE finds → SDE fixes → QAE validates → Close
7. **Final delivery** → All outputs organized, user gate 4, commit to main

### What "I Am The Team" Means

- Actually executing all selected skills (not just orchestrating)
- Writing real code, real commits, real PRs
- Testing code with actual test runners
- Finding bugs through QAE execution
- Fixing bugs with SDE execution
- Tracking everything in organized folders
- Presenting all outputs to user for review

---

## Skill Loop Exit Criteria

Every loop between skills MUST have a defined exit condition. A loop terminates when its exit criteria are met OR when the max loop count is reached. **Never silently proceed past a failed loop.**

### SDE Domain Loops

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| sde:code-review → sde:code-craftsman | 0 HIGH/CRITICAL severity issues remaining | 3 |
| sde:code-review → sde:tdd | Test coverage ≥ 80% AND 0 failing tests | 3 |
| sde:debugging → sde:tdd | Bug reproduction test passes (green) | 2 |
| sde:code-craftsman → sde:code-review | All Boy Scout Rule violations resolved | 2 |

### QAE Domain Loops

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| qae:security → qae:security (re-scan) | 0 CRITICAL/HIGH vulnerabilities | 3 |
| qae:performance → qae:performance (re-test) | All performance budgets met (p95 < threshold) | 2 |
| qae:defect-management → qae:exploratory | 0 open CRITICAL/HIGH bugs | 3 |

### Cross-Domain Loops (SDE ↔ QAE)

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| qae:defect-management → sde:debugging → qae:defect-management | 0 open bugs (all FIXED and VERIFIED) | 5 |
| qae:security → sde:code-craftsman → qae:security | 0 CRITICAL/HIGH vulnerabilities after re-scan | 3 |
| qae:performance → sde:data-systems → qae:performance | All performance budgets met after optimization | 2 |

### PM Domain Loops

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| pm:prioritization-engine → pm:gap-analyst | Conflicts resolved, all items have unique RICE scores | 2 |
| pm:discovery-validator → pm:experiment-designer | Hypothesis validated OR invalidated with evidence | 3 |

### UX Domain Loops

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| ux:review → ux:component-design | Nielsen's Heuristic score ≥ 7/10 on all 10 heuristics | 3 |
| ux:accessibility → ux:component-design | 0 WCAG 2.2 AA violations | 3 |
| ux:review → ux:responsive | All 3 breakpoints (375px, 768px, 1280px) pass | 2 |

### PE Domain Loops

| Loop | Exit Criteria | Max Loops |
|------|--------------|-----------|
| pe:architecture-reviewer → pe:decision-facilitator | ADR written with rough consensus reached | 2 |
| pe:technical-quality → pe:leverage-analyzer | Top 3 leverage opportunities identified and actionable | 2 |

### Loop Escalation Rule

If a loop reaches its max count WITHOUT meeting exit criteria:

1. **Log the failure** in `.project/loops.md` with reason and iteration count
2. **Escalate to user** via AskUserQuestion: "Loop [X→Y] hit max iterations ([N]). [M] issues remain unresolved. Options: (1) Force proceed with known issues logged, (2) Increase max loops by 2, (3) Manual intervention required"
3. **Never silently proceed** past a failed loop — this caused the HeartCoach Phase 7 skip

---

## Skill Invocation Rules ⚠️ CRITICAL

### How to Invoke Individual Skills

Use the **Skill tool** to invoke individual skills by their qualified name:

```
Skill(skill="sde:tdd")
Skill(skill="pm:customer-research")
Skill(skill="qae:test-strategy")
Skill(skill="ux:component-design")
Skill(skill="pe:architecture-reviewer")
```

### How to Delegate to Domain Agents via Task Tool

When you need to delegate a multi-step workflow to a domain agent using the **Task tool**, you MUST use the `taskpilot:` prefix:

| Domain | Task Tool `subagent_type` | ❌ WRONG |
|--------|--------------------------|----------|
| Product Management | `taskpilot:pm` | `pm` |
| Senior SDE | `taskpilot:sde` | `sde` |
| Quality Assurance | `taskpilot:qae` | `qae` |
| UI/UX Design | `taskpilot:ux` | `ux` |
| Principal Engineering | `taskpilot:pe` | `pe` |

**NEVER use plain `sde`, `pm`, `qae`, `ux`, or `pe` as the `subagent_type`.** This will cause "Agent type not found" errors.

### Example: Delegating Phase 6 Build to SDE Agent

```
Task(
  subagent_type="taskpilot:sde",     ✅ CORRECT
  prompt="Execute Feature Build workflow: implement the OAuth2 system per .sde/architecture/..."
)
```

```
Task(
  subagent_type="sde",               ❌ WRONG — will fail with "Agent type 'sde' not found"
  prompt="..."
)
```

### When to Use Skill Tool vs Task Tool

| Scenario | Use | Example |
|----------|-----|---------|
| Run a single skill | **Skill tool** | `Skill(skill="sde:tdd")` |
| Delegate a multi-step workflow to a domain agent | **Task tool** | `Task(subagent_type="taskpilot:sde", ...)` |
| Run a skill and continue in the same context | **Skill tool** | `Skill(skill="qae:test-strategy")` |
| Run parallel agents for Phase 6 Build | **Task tool** | Multiple `Task(subagent_type="taskpilot:sde", ...)` calls |

### Parallel Agent Delegation (Phase 6)

When splitting Phase 6 across parallel agents, use multiple Task tool calls:

```
// Agent 6a: Shared models and engine
Task(subagent_type="taskpilot:sde", prompt="Build shared models and engine...")

// Agent 6b: iOS services
Task(subagent_type="taskpilot:sde", prompt="Build iOS services conforming to contracts...")

// Agent 6c: iOS views
Task(subagent_type="taskpilot:sde", prompt="Build iOS views consuming services from contracts...")
```

**Remember:** Apply the Contract-First Rule (see coordination-service.md) before launching parallel agents.

---

## Data Organization & Tracking

### Folder Structure

```
.project/
├── feature-overview.md
├── orchestration-log.md
├── code-delivery-log.md
├── bug-report.md
└── skill_response_doc/
    ├── phase-1-discovery/
    ├── phase-2-validation/
    ├── phase-3-planning/ (BRD-APPROVAL.md)
    ├── phase-4-design/ (DESIGN-APPROVAL.md)
    ├── phase-5-architecture/
    ├── phase-6-build/
    ├── phase-7-quality/ (QA-APPROVAL.md)
    ├── phase-8-launch/
    └── phase-9-feedback/
```

### Orchestration Log Format

```markdown
# Orchestration Log: [Feature Name]

## Feature Analysis Summary
- Domain: PM + SDE
- Complexity: Medium-High
- Risk: High
- Selected Skills: 13
- Scope: 8-13 skills

## Phase Progress

### Phase 1: Discovery [COMPLETE ✅]
- Skills Executed: pm:customer-research, pm:research-agent
- Quality Gate: PASSED
- Artifacts:
  - .pm/research/user-needs.md
  - .pm/competitors/analysis.md

### Phase 2: Validation [COMPLETE ✅]
- Skills Executed: pm:discovery-validator, pe:tech-strategy
- Quality Gate: PASSED
- Artifacts:
  - .pm/experiments/validation-plan.md
  - .pe/strategy/tech-alignment.md

### Phase 3: Planning [AWAITING USER GATE 1]
- Skills Executed: pm:gap-analyst, pm:prd-generator, pm:metrics-advisor
- Quality Gate: PASSED
- **USER GATE 1: BRD REVIEW** — Awaiting approval
- **Deliverables for Review**:
  - 📄 BRD Document (.pm/prds/feature.md)
  - 📄 PM Document (gap analysis, .pm/gaps/)
  - 📊 Success Metrics (.pm/metrics/)
  - ✅ Tech Strategy Alignment
- Review Location: .project/skill_response_doc/phase-3-planning/

### Phase 4: Design [COMPLETE ✅]
- Skills Executed: ux:design-system, ux:component-design, ux:accessibility
- Quality Gate: PASSED
- **USER GATE 2: DESIGN REVIEW** — Approved ✅
- **Design Deliverables**:
  - 🎨 Design Theme Files (.ux/design-systems/)
  - 📋 Component Specs (all states)
  - ♿ Accessibility Audit (WCAG 2.2 AA)

### Phase 5: Architecture [COMPLETE ✅]
- Skills Executed: sde:system-design, sde:architecture
- Quality Gate: PASSED
- **Deliverables**:
  - 📐 System Design Document (.sde/designs/system.md)
  - 🏗️ Architecture Review (.sde/architecture/adr.md)

### Phase 6: Build [COMPLETE ✅]
- Skills Executed: sde:tdd, sde:code-craftsman, sde:code-review
- Quality Gate: PASSED
- **Code Deliverables**:
  - 💻 Code Files (written to repo)
  - 🔍 Code Review (.sde/reviews/pr-123.md)
    - Issues Found: 3
    - Status: ✅ APPROVED
  - 📋 PRs: #123, #124, #125
  - 🔗 Commits: abc1234, def5678, ghi9012
  - ✅ Test Coverage: 87%

### Phase 7: Quality [COMPLETE ✅]
- Skills Executed: qae:test-strategy, qae:test-automation, qae:api-testing, qae:security
- Quality Gate: PASSED
- **USER GATE 3: QA SIGN-OFF** — Approved ✅
- **QA Deliverables**:
  - ✅ QA Sign-Off Document
  - 📊 Test Coverage: 87% (>80% required)
  - 🔐 Security Scan: PASSED (OWASP Top 10)
  - ⚡ Performance Baseline: Established
  - 🐛 Bugs Found: 5
    - Critical: 0
    - High: 1 (FIXED) → Commit: xyz789
    - Medium: 4 (FIXED) → Commits: abc111-abc114
  - Status: ✅ GO/NO-GO: GO

### Phase 8: Launch [COMPLETE ✅]
- Skills Executed: qae:cicd-pipeline, pe:incident-reliability
- **Deliverables**:
  - 🚀 CI/CD Pipeline (.qae/pipelines/deploy.yml)
  - 📖 Runbook (.pe/incidents/runbook.md)

### Phase 9: Feedback [IN PROGRESS]
- Skills Executing: pm:metrics-advisor, pe:technical-quality
- **Deliverables**:
  - 📈 Post-Launch Metrics
  - 🏗️ Tech Debt Assessment

## Final Status
- ✅ All phases complete
- ✅ All user gates passed
- ✅ Code reviewed (sde:code-review)
- ✅ QA sign-off obtained
- ✅ Go/No-Go: GO
- 📍 Ready for commit to main
```

---

## Rule 8: Single Source of Truth for Phase Status

`.project/status.md` is the ONLY authoritative source for phase completion status.

- The orchestrator MUST update `status.md` AFTER each gate check passes, never before
- A phase can ONLY be marked COMPLETE if ALL its completion gates have PASSED
- If `orc_notes.md` or any other file conflicts with `status.md`, `status.md` is authoritative
- NEVER mark a phase COMPLETE before running its gates (especially Gate 6A-6D for Phase 6)
- Phase status values: `NOT STARTED` | `IN PROGRESS` | `GATE CHECK` | `COMPLETE` | `BLOCKED`

---

## Ready to Execute

✅ Feature analysis framework complete
✅ 9-phase SDLC model defined
✅ Skill selection rules for common feature types
✅ 4 user decision gates established
✅ Phase 6 Completion Gate with 4 blocking gates (6A-6D)
✅ Contract-First Rule for parallel agents
✅ Stub detection patterns defined
✅ Single source of truth for status (Rule 8)
✅ Autonomous execution model documented
✅ Data tracking structure ready

**Status**: Ready to orchestrate ANY feature request