Project Orchestrator

Overview

When to Use

• Starting a new project from scratch (greenfield)
• Adding a major feature that changes architecture, data flow, or integrations
• Unsure which skills to invoke and in what order
• Starting work on a project type you haven't classified before

• Small bug fixes, typos, minor UI tweaks — just do the work
• Pure research or exploration — use Explore agent directly
• Single-file changes with clear requirements — use TDD directly
• You already know exactly which single skill applies (e.g., just need

  /security-audit

  )

How It Works

1. Classify — Ask what you're building, determine project type
2. Route — Select the phases that apply
3. Execute — Walk through each phase sequentially
4. Handoff — Each phase produces a doc artifact; later phases build on earlier ones

docs/plans/

Phase 0: Project Classification

• Mobile/Web: "Does it have a backend?" — if yes, add full-stack phases
• Any type: "Does it integrate with external services?" — if yes, add resilience phase
• Any type: "Will this be deployed to cloud infrastructure you manage?" — if yes, add infrastructure phase
• Any type: "Is this a new project or adding to an existing system?" — if existing, add system assessment phase

Route Table

Compile Your Phase Plan

1. Review the route table for your project type
2. For each "o" phase, check the sub-classification answers to determine if it's active
3. Write out the numbered list of active phases (e.g., "Active phases: 0.5, 1, 2, 3, 4, 7, 10, 11, 12, 13, 15")
4. Present the phase plan to the user for confirmation before starting

Phase 0.5: Existing System Assessment

Purpose

Process

1. Map the current architecture:
   • Read README, docs/, and any existing design docs
   • Identify the tech stack, key dependencies, and deployment model
   • Map the data model (schemas, migrations, key entities)
   • Identify the main entry points and request flows
2. Identify constraints and boundaries:
   • What patterns and conventions does the codebase follow?
   • What are the existing API contracts that must not break?
   • What tech debt or known issues exist? (check issues, TODOs, CHANGELOG)
   • What dependencies are pinned or constrained?
3. Assess the test and CI situation:
   • What test coverage exists? What's tested vs untested?
   • What CI/CD pipeline exists? What checks run on PR?
   • How are deployments done today?
4. Summarize the integration surface:
   • What external services are already integrated?
   • What internal APIs exist that the new feature could reuse?
   • Where are the seams — natural places to extend without rewriting?

Deliverable

## Existing System Assessment

### Architecture Summary
- Stack: [Languages, frameworks, infrastructure]
- Key Components: [List with one-line descriptions]
- Data Model: [Key entities and relationships]

### Constraints
- Must Not Break: [Existing APIs, contracts, behaviors]
- Tech Debt: [Known issues that affect the new work]
- Conventions: [Patterns the new code must follow]

### Integration Surface
- Reusable: [Existing APIs/components the new feature can leverage]
- Seams: [Natural extension points]

### Test & CI Status
- Coverage: [What's tested, what's not]
- Pipeline: [What runs on PR/merge/deploy]

Phase 1: Brainstorming

/brainstorming

docs/plans/YYYY-MM-DD-<topic>-design.md

Phase 2: Domain Modeling

Questions to Ask

1. Bounded Contexts: What are the distinct areas of the business domain?
   • Each context has its own ubiquitous language, models, and rules
   • Example (AiSyst): Ordering, Menu Management, Voice Interaction, Billing
   • Example (RCM): Detection, Review, Training, Fleet Management, Telemetry
2. Aggregates: Within each context, what are the consistency boundaries?
   • An aggregate is a cluster of entities that must be consistent together
   • What invariants must hold within each aggregate?
   • Example: An "Order" aggregate — items can't be empty, total must match items, status transitions are valid
3. Domain Events: What important things happen that other contexts care about?
   • Events cross context boundaries; commands stay within them
   • Example: "DetectionCreated" -> triggers Review context; "ReviewCompleted" -> triggers Training context
4. Context Map: How do bounded contexts communicate?
   • Shared kernel, customer-supplier, conformist, anti-corruption layer?
   • Where are the translation layers needed?

Deliverable

## Domain Model

### Bounded Contexts
- **[Context Name]**: [Purpose, key entities, invariants]

### Aggregates
- **[Aggregate Name]**: [Root entity, child entities, invariants]

### Domain Events
- [EventName]: [Source context] -> [Target context(s)]

### Context Map
[How contexts relate and communicate]

Phase 3: System Design + Security-by-Design

/ddia-design

docs/plans/YYYY-MM-DD-<topic>-system-design.md

Security-by-Design Injection Points

/ddia-design

/ddia-design

• What access control model per table/collection? (RLS, RBAC, ABAC)
• Which fields contain PII? Encryption at rest strategy?
• What are the access patterns per role? (admin sees all, user sees own)
• Audit logging: which mutations need an audit trail?

• What auth mechanism at each boundary? (JWT, API key, mTLS, webhook signature)
• How are secrets managed? (Environment vars, Vault, Secrets Manager)
• Transport security per channel? (TLS, mTLS for service-to-service)
• Which data crosses trust boundaries? What validation is needed at each?

• What is the threat model? (STRIDE per component)
• Input validation strategy per boundary? (Zod schemas, parameterized queries)
• Rate limiting per endpoint tier? (public vs authenticated vs internal)
• What happens if a credential is compromised? Rotation and revocation plan?

Accessibility-by-Design Injection Point (Web, Mobile, Desktop)

• What WCAG level are you targeting? (A, AA, AAA — AA is the standard for most products)
• Color contrast: do all text/background combinations meet the target ratio? (4.5:1 for AA normal text, 3:1 for large text)
• Keyboard navigation: can every interactive element be reached and operated without a mouse?
• Screen reader strategy: what semantic HTML / ARIA roles are needed? What's the heading hierarchy?
• Motion: do animations respect

  prefers-reduced-motion

  ? Are there alternatives for motion-dependent interactions?
• Touch targets: are all interactive elements at least 44x44pt (iOS) / 48x48dp (Android)?

Deliverable

Phase 4: Resilience Patterns

Questions to Ask

1. Failure Mode: What happens when this dependency is unavailable?
   • Timeout? Error response? Silent data loss?
   • How long can you tolerate the outage?
2. Circuit Breaker: Should you fail fast after N failures?
   • What's the threshold? (e.g., 5 failures in 30 seconds)
   • What's the half-open recovery strategy?
3. Timeout Budget: What's the maximum wait time?
   • For voice agents: total turn budget (STT + LLM + TTS must complete before silence)
   • For web: p95 response time target per endpoint
4. Retry Policy: Is the operation safe to retry?
   • Idempotent? -> Retry with exponential backoff
   • Non-idempotent? -> Fail and surface to user
   • Maximum retries before circuit opens?
5. Bulkhead: Does failure in one integration affect others?
   • Separate thread pools / connection pools per dependency?
   • Can a slow Stripe response block voice ordering?
6. Graceful Degradation: What's the reduced-functionality mode?
   • POS down -> queue orders for later sync?
   • GPS unavailable -> save detection without coordinates?
   • Cache down -> serve from DB (slower but functional)?

Deliverable

## Resilience Patterns

| Dependency | Failure Mode | Circuit Breaker | Timeout | Retry | Degradation |
|-----------|-------------|----------------|---------|-------|-------------|
| [Service] | [What breaks] | [Threshold] | [ms] | [Policy] | [Fallback] |

Phase 5: ML Pipeline Design

docs/plans/YYYY-MM-DD-<topic>-ml-pipeline.md

Questions to Ask

1. What is the training data source? (labeled images, sensor data, logs)
2. How is data labeled? (manual, semi-automated, active learning)
3. What is the labeling quality control process?
4. Data versioning strategy? (DVC, S3 versioning, git-lfs)
5. Class imbalance — what's the distribution? Augmentation strategy?
6. Train/val/test split strategy? (random, temporal, geographic)

Deliverable

## ML Pipeline Design

### Data Pipeline
- Source: [Where training data comes from]
- Labeling: [Process, QC, tooling]
- Versioning: [Strategy]
- Splits: [Train/val/test ratios and strategy]

### Model Lifecycle
- Architecture: [Model, why chosen]
- Experiment Tracking: [Tool/process]
- Versioning: [Scheme]
- Export: [Format, size budget]

### Deployment
- Delivery: [OTA/manual, canary %]
- Rollback: [Trigger and process]

### Monitoring
- Health Metrics: [What to track]
- Drift Detection: [Method and thresholds]
- Retraining Trigger: [Conditions]
- Feedback Loop Latency: [Time from detection to retrained model deployed]

Phase 6: Edge Architecture Design

Questions to Ask

1. What hardware? (CPU, GPU, RAM, storage, connectivity)
2. Power source? (battery, vehicle power, mains)
3. Physical environment? (temperature range, vibration, dust, moisture)
4. What sensors? (cameras, GPS, accelerometer, etc.)

Deliverable

## Edge Architecture

### Device Profile
- Hardware: [Specs]
- Constraints: [Power, connectivity, environment]
- Sensors: [List with interfaces]

### Offline Strategy
- Queue: [Technology, max size, overflow policy]
- Sync: [Strategy, priority]
- Max Offline Duration: [Hours/days]

### Resource Budget
| Resource | Budget | Allocation |
|----------|--------|------------|
| CPU/GPU | 100% | Inference %, Upload %, Other % |
| RAM | [Size] | Model %, Queue %, OS % |
| Storage | [Size] | Models %, Queue %, Logs % |
| Bandwidth | [Daily] | Detections %, Telemetry %, Updates % |

### Fleet Management
- Fleet Size: [Current -> Projected]
- Provisioning: [Workflow]
- OTA Updates: [Strategy, rollout %]
- Health Monitoring: [Metrics, intervals, alerts]

Phase 7: API Specification

Process

1. List all endpoints/contracts:
   • REST endpoints (method, path)
   • Event schemas (SQS messages, EventBridge events)
   • Webhook contracts (incoming from third parties)
   • Device protocols (MQTT topics, IoT shadow schemas)
   • Tool interfaces (voice agent tools, function calling schemas)
2. For each endpoint, define:
   • Auth requirement (JWT, API key, service role, webhook signature, mTLS)
   • Request schema (with types, required/optional, validation rules)
   • Response schema (success + error shapes)
   • Rate limiting tier (public, authenticated, internal, service-to-service)
   • Idempotency (safe to retry? idempotency key?)
3. Error format standard:
   • Agree on ONE error shape across all APIs
   • Include: status code, error code, human message, details object

Deliverable

## API Specification

### Error Format
{ status, code, message, details }

### Endpoints

#### [Boundary Name]
| Method | Path | Auth | Rate Limit | Idempotent |
|--------|------|------|------------|------------|
| POST | /api/example | JWT | 100/min | Yes (key) |

**Request:** { ... }
**Response:** { ... }
**Errors:** 400 (validation), 401 (auth), 429 (rate limit)

Phase 8: Voice Agent Prompt Design

/voice-agent-prompt

Phase 9: Infrastructure Design

Questions to Ask

1. IaC Tool & Module Structure:
   • What IaC tool? (Terraform, Pulumi, CDK, CloudFormation)
   • Module boundaries — which resources belong together?
   • Shared vs environment-specific modules?
2. State Management:
   • Remote state backend? (S3, Terraform Cloud, Azure Blob)
   • State locking mechanism?
   • State file per environment or per module?
3. Environment Strategy:
   • How many environments? (dev, staging, prod)
   • How do changes promote? (manual apply, CI/CD pipeline, GitOps)
   • Blast radius of a bad apply — what's the worst case?
4. CI/CD Pipeline:
   • Plan on PR, apply on merge?
   • Who approves infrastructure changes?
   • Rollback strategy for infrastructure?
5. IaC Testing:
   • Static analysis? (tfsec, Checkov, OPA)
   • Plan validation? (terraform plan diff review)
   • Integration tests? (test environment that mirrors prod)
6. Secrets Management:
   • Where do secrets live? (Vault, Secrets Manager, SSM Parameter Store)
   • Rotation schedule?
   • Emergency revocation process?
7. Cost Estimation:
   • What's the compute cost per unit of work? (per API call, per inference, per voice minute)
   • What are the third-party API costs at projected volume? (Twilio per-minute, Deepgram per-hour, Stripe per-transaction, S3 per-GB)
   • What's the storage growth projection? (GB/month now, in 6 months, in 2 years)
   • What's the monthly burn at current scale? At 10x scale?
   • Where are the cost cliffs? (Aurora serverless scaling tiers, Lambda invocation thresholds, data transfer costs)
   • Is there a cost ceiling / budget constraint?
   • What's the cost-per-user or cost-per-unit-of-value? (Does the unit economics work?)

Deliverable

## Infrastructure Design

### IaC Structure
- Tool: [Terraform/Pulumi/etc.]
- Modules: [List with responsibilities]
- State: [Backend, locking, per-environment strategy]

### Environment Promotion
- Environments: [List]
- Promotion Flow: [PR -> plan -> review -> apply]
- Rollback: [Strategy]

### Secrets
- Store: [Tool]
- Rotation: [Schedule]
- Emergency Revocation: [Process]

### Cost Estimation
| Resource | Unit Cost | Current Volume | Monthly Cost | At 10x |
|----------|-----------|----------------|-------------|--------|
| [Compute] | [$/unit] | [units/month] | [$] | [$] |
| [Storage] | [$/GB] | [GB] | [$] | [$] |
| [Third-party API] | [$/call] | [calls/month] | [$] | [$] |
| **Total** | | | **[$]** | **[$]** |

Cost Ceiling: [Budget constraint if any]
Cost-per-User: [$/user/month at projected scale]

Phase 10: Implementation Planning

/writing-plans

Testing Strategy Addition

docs/plans/YYYY-MM-DD-<topic>-plan.md

Phase 11: Implementation

• Subagent-driven (current session): Invoke

  /subagent-driven-development

• Parallel session (separate): Invoke

  /executing-plans

  in a new session

Phase 12: Security Validation

/security-audit

/web-app-security-audit

• Device certificates: valid, unique per device, rotation scheduled
• MQTT topic security: devices can only publish to their own topics
• Firmware integrity: signed updates, verified on device
• Physical security: what credentials are on the device if someone steals it?

Phase 13: Observability Design

Questions to Ask

1. Structured Logging:
   • What logging format? (JSON, structured key-value)
   • What fields on every log line? (timestamp, service, request_id, user_id, trace_id)
   • Correlation IDs — how do you trace a request across services?
2. Distributed Tracing:
   • What spans exist? (one per service hop in the request path)
   • What tool? (X-Ray, Jaeger, OpenTelemetry)
   • What sampling rate? (100% in staging, 10% in prod, 100% for errors)
3. Metrics:
   • RED metrics per service: Rate, Errors, Duration
   • Business metrics: orders/hour, detections/day, review latency
   • Infrastructure metrics: CPU, memory, queue depth, cache hit rate
   • Use percentiles (p50, p95, p99), not averages
4. Alerting:
   • What's worth waking someone up for? (data loss, service down, security breach)
   • What can wait until morning? (elevated error rate, slow responses, queue backlog)
   • Alert fatigue prevention — fewer, better alerts
5. Dashboards:
   • One dashboard per bounded context
   • Top-level "system health" dashboard
   • On-call runbook linked from each alert

Deliverable

## Observability

### Logging
- Format: [JSON/structured]
- Required Fields: [timestamp, service, request_id, trace_id, ...]
- Correlation: [How trace IDs propagate]

### Tracing
- Tool: [X-Ray/Jaeger/OTEL]
- Spans: [List of spans in critical path]
- Sampling: [Rate per environment]

### Metrics
| Metric | Type | Alert Threshold |
|--------|------|----------------|
| [name] | [RED/business/infra] | [threshold] |

### Alerting
| Alert | Severity | Action |
|-------|----------|--------|
| [What] | [Page/Warning/Info] | [Runbook link] |

Phase 14: ML Validation

Validation Checklist

1. Model Performance:
   • Precision, recall, F1 on held-out test set
   • Performance per class (not just aggregate)
   • Performance on edge cases (night, rain, dust, unusual angles)
   • Latency on target hardware (not just dev machine)
2. Data Quality:
   • Label consistency audit (sample and re-label, measure agreement)
   • Data leakage check (training data contaminating test set)
   • Distribution shift check (training data vs production data)
3. Robustness:
   • Adversarial inputs (unusual lighting, occlusion, camera artifacts)
   • Out-of-distribution detection (does the model know when it doesn't know?)
   • Confidence calibration (does 90% confidence mean 90% accuracy?)
4. Fairness & Bias:
   • Performance across operating conditions (time of day, weather, road type)
   • False positive/negative rates across conditions
   • Are some environments systematically underrepresented?
5. Operational Readiness:
   • Model loads correctly on target hardware
   • Inference fits within resource budget (Phase 6)
   • Offline queue handles expected volume
   • Monitoring pipeline captures metrics correctly

Deliverable

## ML Validation Report

### Performance
| Metric | Overall | Class A | Class B | Edge Cases |
|--------|---------|---------|---------|------------|
| Precision | | | | |
| Recall | | | | |
| F1 | | | | |
| Latency (ms) | | | | |

### Data Quality
- Label Agreement: [%]
- Leakage Check: [Pass/Fail]
- Distribution Shift: [Within/Outside tolerance]

### Robustness
- Adversarial: [Results]
- OOD Detection: [Method, threshold]
- Calibration: [ECE score]

### Go/No-Go Decision
[Ready / Needs retraining / Needs more data]

Phase 15: Polish & Review

/design-code-review

/apple-craftsman

/mobile-ios-design

/ux-usability-review

/ui-polish-review

/ux-usability-review

/ui-polish-review

/ux-usability-review

/ux-usability-review

/ui-polish-review

/ux-usability-review

/code-simplifier

Resumption Protocol

1. Check

   docs/plans/

   for existing artifacts
2. Read each doc to understand decisions already made
3. Determine which phase produced the last artifact
4. Resume from the next phase

*-design.md

*-system-design.md

*-ml-pipeline.md

*-plan.md

Anti-Patterns

Book References