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:

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:

{
  "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:

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):

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

1. After each phase → Update orchestration-log.md, trigger user gates if needed
2. Code execution → Write actual code, create commits, track PRs
3. Bug lifecycle → QAE finds → SDE fixes → QAE validates → Close
4. 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

QAE Domain Loops

Cross-Domain Loops (SDE ↔ QAE)

PM Domain Loops

UX Domain Loops

PE Domain Loops

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:

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

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

# 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