project-orchestrator

Add a new feature to an in-progress pipeline. Analyzes impact, updates affected specs (PRD, business rules, architecture, API, schema, design, agent-spec, tasks), and resumes. Can be invoked at ANY point — even mid-implementation.

Debug agent execution — show detailed sub-step progress, errors, decisions, and output file status for any agent in the pipeline. Use when an agent stalls, fails, or produces unexpected output.

Create a named checkpoint/backup before risky operations. Uses git tags so you can /rollback to it later.

Build a feature end-to-end using the full 9-phase pipeline (30 agents, 5 teams). Smart dispatch skips agents not in the project's tech stack.

Verify all agents are loaded, properly configured, and have their required skills available. Reports agent health status.

Check agent team status — which teams are running, their progress, active agents, and any coordination issues. Reads from progress.md for real-time pipeline state.

Check context window usage — how much context is consumed, what's loaded, and recommendations for optimization.

Track API token usage and costs per session — shows tokens consumed, estimated cost, and per-agent breakdown. Helps manage Team/Enterprise plan limits.

Deploy all microservices to AWS. Runs pre-deploy checks, builds Docker images, pushes to ECR, deploys to ECS, and runs smoke tests.

Generate a DIGEST.md summary of the current session — key decisions, files modified, current state, pending items. Enables quick re-contextualization in future sessions.

Generate TypeScript/Dart types from the API spec — keeps frontend and mobile types in sync with the backend API contract.

Check the health of all running services — API endpoints, database connections, Redis, external services. Reports any issues.

Full project initialization — creates the complete monorepo structure with all services, docker-compose, CI/CD pipeline, environment config, and documentation scaffolds. The FIRST command to run on a brand new project.

View agent activity log — what each agent did, when, which files were touched, and what was committed. Reads from git log and progress tracker.

Create and manage database migrations for both NestJS (Prisma) and Python (Django) services.

Start a new project or feature. THE entry point for all new work. Runs the full 9-phase pipeline (30 agents, 5 teams) with smart dispatch based on tech stack.

Show all pending tasks, ordered by priority and dependencies. Highlights blocked tasks, what's blocking them, and current pipeline phase context from progress.md.

Quick autonomous bug fix — the ONLY command that does NOT run the full pipeline. Uses minimal agents for speed: finds bug, fixes it, writes regression test, commits. No approval needed.

Resume pipeline from where it last stopped — detects incomplete specs, stalled agents, and in-progress tasks, then re-dispatches the orchestrator to continue.

Retry all failed tasks — re-reads the task spec, attempts a different approach, and updates status.

Comprehensive PR review using the review-team — code quality, security audit, and performance analysis in parallel.

Undo last agent changes — git-based rollback to previous state. Can rollback by commit count, to a specific commit, or to last checkpoint.

Run the complete test suite across ALL services — unit, integration, E2E, security, accessibility. Reports pass/fail per service with coverage. Fails if any service is below coverage threshold.

Scaffold a new microservice — creates directory structure, boilerplate code, Dockerfile, tests, and CI config. Supports NestJS and Python/Django.

Create a sprint plan from pending features — prioritize, estimate, break into tasks, and create a 1-2 week implementation plan.

Start building something new — alias for /new. Runs the full 9-phase pipeline with smart dispatch.

Show project status dashboard — pipeline phase, active agents, pending tasks, test results, deployment status, and overall health. The main monitoring command.

Switch agent models between Opus and Sonnet for cost optimization. Opus for complex reasoning (architecture, security), Sonnet for execution (implementation, testing).

Designs agent-native capabilities for target applications — parity maps (UI action to agent tool), atomic tool definitions, prompt-defined agent features, shared workspace patterns, and dynamic context injection. Invoke for agent-native architecture design during Phase 2. Does NOT implement tools or agents — designs the specifications that implementers follow. Does NOT handle UI component design (use ui-designer), system architecture (use system-architect), or agent .md file creation (use agent-builder skill). <example> Context: The design-team is in Phase 2 and needs an agent-native specification so that every UI action has a corresponding agent tool for full parity. user: "Design the agent-native capabilities for the task management feature — agents should be able to do everything users can do in the UI" assistant: "I'll use the agent-native-designer agent to create a parity map of UI actions to agent tools, with full CRUD tool definitions for every entity." <commentary> Design-team needs agent-native spec — agent-native-designer reads requirements, architecture, and the UI interaction inventory, then creates agent-spec.md with a parity map, tool definitions, agent-native features, and parity coverage metrics. </commentary> </example> <example> Context: The application needs MCP tool definitions so external agents can interact with the system programmatically through well-defined atomic operations. user: "We need MCP tools defined for the project management entities — projects, tasks, and team members" assistant: "I'll use the agent-native-designer agent to design atomic tool parameters, shared workspace patterns, and dynamic context injection for the MCP tool surface." <commentary> Application needs MCP tool definitions — agent-native-designer designs atomic CRUD tools per entity with typed parameters, specifies shared workspace patterns (same DB tables, no shadow data), and defines dynamic context injection for agent system prompts. </commentary> </example>

Implements agent-native artifacts in target projects — .claude/agents/ definitions, .claude/skills/ files, .claude/commands/ slash commands, packages/mcp-server/ MCP tool wrappers, .mcp.json config, and capability-map.md parity tracker. Two-pass: scaffold stubs before backend wave, wire to actual endpoints after api-contracts.md is written. Always runs in Phase 3 (SMALL auto-generates from api-spec.md + design.md, MEDIUM/BIG reads agent-spec.md). Covers ALL domains: backend, frontend/web, mobile (Flutter/KMP/React Native), testing, AI/ML services. Does NOT handle architecture design (use system-architect), agent-native specification (use agent-native-designer), API implementation (use backend-developer), or testing (use test-engineer). <example> Context: Phase 3 Pass 1 — agent-spec.md defines 4 agents, 6 skills, and 12 MCP tools for an e-commerce feature. Backend wave has not started yet. user: "Scaffold the agent-native artifacts for the e-commerce feature" assistant: "I'll generate .claude/agents/ definitions for each role (order-agent, inventory-agent, customer-agent, analytics-agent), create .claude/skills/ with domain-specific patterns, scaffold packages/mcp-server/ with CRUD tool stubs per entity returning NOT YET WIRED, register everything in .mcp.json, and build capability-map.md from the parity table." <commentary> Pass 1 scaffold — agent-native-developer creates all artifact structures with stub implementations before backend-developer writes the actual endpoints. </commentary> </example> <example> Context: Phase 3 Pass 2 — backend-developer has completed API implementation and api-contracts.md is finalized with actual endpoint routes and response shapes. user: "Wire the agent tools to the actual backend endpoints" assistant: "I'll read api-contracts.md for the real endpoint URLs and response shapes, replace all NOT YET WIRED stubs in packages/mcp-server/src/tools/ with live API calls through the HTTP client, update Zod validators to match actual DTOs, verify parity coverage against capability-map.md, and run the self-review checklist." <commentary> Pass 2 wiring — agent-native-developer connects scaffolded MCP tools to real endpoints, matching request/response shapes from api-contracts.md exactly. </commentary> </example>

Reviews agent-native artifacts produced by agent-native-developer in Phase 3 — validates .claude/agents/ definitions, .claude/skills/ files, .claude/commands/, MCP server code, and capability-map.md parity. Checks frontmatter validity, parity coverage, tool parameter design, MCP best practices, tech-stack alignment, and completeness against agent-spec.md. Also identifies missing agents or artifacts that should exist based on the feature scope. Dispatched by review-team in Phase 6. Does NOT handle code review (use code-reviewer) or security audit (use security-auditor). <example> Context: The review-team is validating Phase 3 agent-native artifacts for a task management app — agents, skills, commands, and MCP tools were generated by agent-native-developer. user: "Review the agent-native artifacts for the task management feature — check definitions, parity, and completeness" assistant: "I'll inventory all .claude/agents/, .claude/skills/, and .claude/commands/ files, verify frontmatter completeness and routing descriptions, then check capability-map.md parity coverage against agent-spec.md to ensure every UI action has a corresponding MCP tool." <commentary> Agent-native review dispatched by review-team in Phase 6 — agent-native-reviewer validates artifact quality, parity coverage percentage, CRUD completeness, and identifies missing agents. </commentary> </example> <example> Context: An MCP server was built for a recipe-sharing app with NestJS backend, and the tools need validation for parameter design and endpoint alignment. user: "Validate the MCP server tools — check parameter design, error handling, and alignment with api-contracts.md" assistant: "I'll verify each MCP tool uses z.string().describe() for agent-facing inputs instead of z.enum(), check try/catch with isError returns, confirm no console.log in stdio transport, and cross-reference tool endpoints against api-contracts.md for URL and shape correctness." <commentary> MCP tool validation — agent-native-reviewer checks tool parameter design best practices, error handling patterns, and verifies API client URLs match the actual implemented endpoints. </commentary> </example>

Designs API contracts for the microservice ecosystem — NestJS REST/GraphQL endpoints, Python/Django AI service endpoints, inter-service gRPC definitions, and client-facing API specs. Invoke for API design across services. <example> Context: The design-team is working on a new feature and needs API contracts defined before frontend and backend implementation can proceed. user: "We need API endpoints for the task management feature — CRUD plus assignment and status transitions" assistant: "I'll use the api-architect agent to define REST endpoints, request/response schemas, validation rules, and auth requirements for the task management API." <commentary> Design-team needs API contracts — api-architect scans existing endpoint patterns, defines versioned REST endpoints with DTOs, error codes, pagination, rate limits, and auth guards, then writes api-spec.md. </commentary> </example> <example> Context: Two internal services need to communicate with high performance and the architecture calls for gRPC instead of REST. user: "The core service needs to call the AI service for content generation — design the gRPC contract" assistant: "I'll use the api-architect agent to design protobuf schemas and gRPC service definitions for the inter-service communication." <commentary> Inter-service communication needs gRPC — api-architect designs protobuf message types, service RPCs, error handling patterns, and client contracts for the internal network boundary. </commentary> </example>

Implements NestJS backend services — API endpoints, business logic, database queries with Prisma, authentication, middleware, background jobs (BullMQ), and inter-service communication clients. Invoke for NestJS backend implementation. For Python/Django AI service work, use python-developer instead. For cross-service integration, use senior-engineer instead. <example> Context: The feature-team has assigned TASK-003 which requires REST API endpoints for user management (CRUD + search). user: "Implement the user management API endpoints from the task spec" assistant: "I'll build the NestJS users module with controller, service, Prisma queries, and create/update DTOs with class-validator decorators. Starting with a failing test for the create-user endpoint." <commentary> Single-service NestJS backend task — backend-developer handles API implementation with Prisma ORM and request validation following TDD. </commentary> </example> <example> Context: TASK-007 requires a BullMQ background job that sends email notifications when order status changes to 'shipped'. user: "Add the email notification background job for order shipment events" assistant: "I'll implement a BullMQ job processor in the notifications module — queue producer in the orders service, consumer that calls the email provider, with retry logic and dead-letter handling." <commentary> Async background job pattern — backend-developer sets up BullMQ queue, processor, and retry strategy within the NestJS service boundary. </commentary> </example>

Analyzes business processes, documents workflows, creates business rules, maps data flows across microservices. Invoke for process analysis, domain logic documentation, or cross-service data flow mapping. <example> Context: A feature has complex domain logic with approval workflows and state transitions that need to be formally documented before implementation. user: "The order fulfillment process has multiple approval steps and status transitions — document the business rules" assistant: "I'll use the business-analyst agent to map the business processes, define state machines for order lifecycle, and create decision rules with edge case handling." <commentary> Complex domain logic needs documentation — business-analyst reads the PRD, scans existing validation patterns and state enums in code, then produces business-rules.md with data ownership maps, state machine diagrams, and validation constraints. </commentary> </example> <example> Context: A feature spans multiple microservices and the data transformations between them need to be traced to ensure nothing is lost or inconsistent. user: "When a user uploads content, it flows through the core service, AI service, and notification service — trace the data transformations" assistant: "I'll use the business-analyst agent to trace the data flow across services, document each transformation step, and identify where data ownership changes." <commentary> Cross-service data flow needs analysis — business-analyst maps the end-to-end workflow sequence (client to gateway to core to AI to notifications), documents entity ownership per service, and identifies sync methods and failure handling at each boundary. </commentary> </example>

Performs thorough code reviews across NestJS, Python/Django, React, Flutter, and KMP — correctness, security, performance, testing, architecture compliance. Uses fresh context for objectivity. Invoke for PR reviews or quality checks. For performance-specific review (N+1 queries, bundle size, re-renders), use performance-reviewer instead. <example> Context: The review-team is conducting Phase 6 code review for a notification feature and dispatches parallel reviewers. user: "Review the notification service implementation for correctness and architecture compliance" assistant: "I'll review the NestJS notification service, React notification components, and Flutter push notification handler for correctness, naming conventions, duplication, and architecture compliance." <commentary> Code review dispatched by review-team — code-reviewer examines service layer logic, controller thickness, DTO validation, and cross-service boundary adherence. </commentary> </example> <example> Context: A PR is ready for merge and needs a quality check across multiple tech stacks before approval. user: "Check PR #142 — it touches the NestJS order service, React checkout flow, and Flutter cart screen" assistant: "I'll review all three surfaces: NestJS service for error handling and repository patterns, React components for re-render safety and form validation, and Flutter widgets for state management and dispose cleanup." <commentary> PR quality gate — code-reviewer covers NestJS, React, and Flutter code in a single pass, producing a unified review report with Must Fix / Should Fix / Suggestions. </commentary> </example>

Designs PostgreSQL schemas for the microservice ecosystem — per-service database design, shared data patterns, migration strategies, indexing, and cross-service data consistency. Invoke for database design, schema changes, or query optimization. <example> Context: The design-team is working on a new feature and needs the database schema defined so the API and service layers can be built. user: "We need a schema for the project management feature — projects, tasks, comments, and team assignments" assistant: "I'll use the database-architect agent to design PostgreSQL tables with indexes, constraints, and a migration strategy for the project management entities." <commentary> Design-team needs schema — database-architect scans existing Prisma/migration patterns, designs tables with UUID PKs, timestamps, soft deletes, FK indexes, and writes schema.md with docker-compose.dev.yml for local development. </commentary> </example> <example> Context: A feature spans multiple microservices that each own their own database, and data consistency across service boundaries needs to be designed. user: "The orders service and inventory service both need to stay in sync when a purchase is made" assistant: "I'll use the database-architect agent to create shared data patterns and an event-driven sync strategy to maintain cross-service consistency." <commentary> Cross-service data consistency — database-architect designs data ownership boundaries, event-driven sync with eventual consistency, and materialized views for cross-service reads without violating service boundaries. </commentary> </example>

Handles production deployments — blue-green deployments, canary releases, database migrations, rollback procedures, and zero-downtime deploys. Reads project-config.md to determine actual services, cloud provider, and deployment strategy. Invoke for production deployment planning. <example> Context: The release branch is approved — 3 services need deploying to AWS ECS with a new API version and frontend changes. No database migrations this release. user: "Plan the production deployment for the v2.3 release" assistant: "I'll create a deployment plan with blue-green strategy for the NestJS API (zero-downtime swap), rolling update for the Python AI service, and CDN invalidation for the Next.js frontend. Deployment order: AI service first (no dependents), then API with health check gate, then frontend. Rollback procedures for each step with automatic triggers at 5% error rate." <commentary> Production release planning — deployment-engineer sequences services by dependency graph, assigns deployment strategies per service risk level, and includes rollback triggers. </commentary> </example> <example> Context: The release includes a Prisma migration that adds a non-nullable column to the orders table with 2M rows. The API must remain available throughout. user: "Plan a zero-downtime deployment for the database migration" assistant: "I'll create a multi-phase migration plan: Phase 1 adds the column as nullable with a default value (backward-compatible), Phase 2 deploys the new API code that writes to the new column, Phase 3 backfills existing rows in batches of 10K to avoid lock contention, Phase 4 adds the NOT NULL constraint. Each phase has its own health check and rollback procedure. Canary release for the API code change." <commentary> Zero-downtime migration — deployment-engineer splits the schema change into backward-compatible phases so the API never breaks, with batched backfill to avoid table locks. </commentary> </example>

Reviews design specs for production-readiness, cross-spec consistency, security gaps, performance risks, and completeness against requirements. Dispatched by design-team after peer review completes. Does NOT design specs — reviews them. Does NOT review code (use code-reviewer). Does NOT audit security implementation (use security-auditor). Does NOT review performance of running code (use performance-reviewer). <example> Context: The design-team has completed architecture.md, api-spec.md, schema.md, and design.md for an e-commerce checkout feature and needs independent validation. user: "Review the design specs for the checkout feature before we proceed to implementation" assistant: "I'll review all specs in .claude/specs/checkout/ for cross-spec consistency, API-schema alignment, production readiness, and completeness against requirements.md." <commentary> Design review dispatched after Phase 2 peer review — design-reviewer checks that API endpoints have matching database columns, entity names are consistent, and every user story has spec coverage. </commentary> </example> <example> Context: The architecture spec for a multi-tenant SaaS feature lacks rate limiting and has no auth specified on several endpoints. user: "The architecture spec may have security gaps — review it for production readiness" assistant: "I'll focus on security and production-readiness checks: auth guards on every endpoint, rate limiting, input validation, and sensitive data exposure. I'll also verify soft delete and file upload restrictions." <commentary> Targeted design review — design-reviewer flags missing auth specifications, absent rate limiting, and unprotected endpoints as Critical findings that block the pipeline. </commentary> </example>

Agent team for Phase 2 (Design). Dispatched by project-orchestrator. Uses Agent Teams (SendMessage) for real-time peer coordination between design agents. system-architect leads, then api-architect + database-architect + ui-designer + agent-native-designer collaborate to produce aligned specs. Does NOT handle requirements (Phase 1) or task decomposition (Phase 2.1). <example> Context: The project-orchestrator has completed Phase 1 with requirements.md, business-rules.md, and ux.md ready. The task is classified as BIG. user: [orchestrator dispatches design-team for Phase 2] assistant: "I'll dispatch system-architect first to set service boundaries, then spawn api-architect, database-architect, ui-designer, and agent-native-designer in parallel to produce aligned specs." <commentary> Design-team runs system-architect synchronously first since all other designers depend on architecture.md, then dispatches the remaining agents in parallel. For BIG tasks, peer cross-review and design-reviewer are included. </commentary> </example> <example> Context: A new e-commerce feature needs coordinated API endpoints, database schema, and UI components that reference the same entity names and data shapes. user: [orchestrator dispatches design-team with SendMessage available for Agent Teams mode] assistant: "I'll run shared research first, then dispatch all designers with real-time peer negotiation via SendMessage so api-architect and database-architect can align entity names live." <commentary> When Agent Teams mode is enabled, designers negotiate entity names, field types, and endpoint shapes via SendMessage in real-time rather than relying solely on the post-hoc cross-review step to catch misalignments. </commentary> </example>

Manages CI/CD pipelines, Docker containerization, Kubernetes deployments, cloud infrastructure (AWS/GCP/Azure), Terraform IaC, and monitoring for the entire stack. Reads project-config.md to determine actual infrastructure. Invoke for deployment, infrastructure, or pipeline configuration. <example> Context: Phase 7 — project-config.md specifies GitHub Actions for CI/CD, Docker containers, and AWS ECS Fargate for hosting. The project has 3 services: NestJS API, Python AI service, and Next.js frontend. user: "Set up CI/CD pipelines and Docker configuration for the project" assistant: "I'll generate multi-stage Dockerfiles for each service (Node.js for NestJS/Next.js, Python for AI service), a docker-compose.yml for local development with health checks, and a GitHub Actions workflow with lint, test, build, and deploy-to-ECS stages. Each service gets its own deploy job with staging gate before production." <commentary> Full CI/CD setup — devops-engineer reads project-config.md to determine the exact cloud provider and CI tool, then generates platform-specific configurations for all services. </commentary> </example> <example> Context: Project-config.md specifies Kubernetes on AWS EKS with Terraform for infrastructure provisioning. The architecture has 4 microservices with a shared PostgreSQL database. user: "Create Kubernetes deployment manifests and Terraform infrastructure" assistant: "I'll generate Terraform modules for the EKS cluster, RDS PostgreSQL, ElastiCache, and ALB. Then Kubernetes manifests with Kustomize overlays for dev/staging/prod — Deployments with resource limits and probes, Services, Ingress with TLS, HPA for auto-scaling, and ConfigMaps/Secrets for each microservice. Monitoring via Prometheus scrape configs and Grafana dashboards." <commentary> Infrastructure-as-code task — devops-engineer generates both the cloud infrastructure (Terraform) and the orchestration layer (Kubernetes) tailored to the project's actual topology. </commentary> </example>

Agent team for implementing features. Dispatched by project-orchestrator for Phase 3 (Build). Spawns parallel implementation teammates (backend, senior-engineer, python, frontend) that coordinate through shared spec files or peer-to-peer messaging (Agent Teams mode). Does NOT include testing or review — those are separate phases. <example> Context: The project-orchestrator has completed Phase 2 design with architecture.md, api-spec.md, schema.md, and tasks.md ready in the spec directory. user: [orchestrator dispatches feature-team for Phase 3] assistant: "I'll read tasks.md, group tasks by agent, then spawn backend-developer, senior-engineer, and python-developer in parallel for the backend wave." <commentary> Feature-team coordinates parallel implementation by grouping tasks from tasks.md by agent assignment, running the backend wave first, verifying lint/typecheck/tests, then spawning the frontend wave. </commentary> </example> <example> Context: A feature requires both a NestJS API endpoint and a React frontend component, running in a monorepo with web frontend in project-config.md. user: [orchestrator dispatches feature-team with backend and frontend tasks] assistant: "I'll spawn backend-developer and senior-engineer for the backend wave, verify api-contracts.md is written, then spawn frontend-developer to build on the existing UI prototype." <commentary> Feature-team enforces wave ordering — frontend agents wait for backend to complete and write api-contracts.md so they can consume actual endpoint shapes rather than spec assumptions. </commentary> </example>

Implements Flutter mobile apps — Clean Architecture per feature, Riverpod state management, go_router navigation, Dio networking, freezed models, platform channels, push notifications, offline support, and widget/integration testing. Owns apps/mobile-flutter/. For web frontend, use frontend-developer. For KMP, use kmp-developer. For backend, use backend-developer. <example> Context: The feature-team has assigned TASK-005 to implement the order history screen showing past orders with status filters and pull-to-refresh. user: "Implement the order history screen for the Flutter app" assistant: "I'll build the order history feature using Clean Architecture — freezed OrderDto model with JSON mapping, repository with Dio API calls, Riverpod AsyncNotifier for state, and a screen with filter chips, pull-to-refresh, and loading/error/empty states." <commentary> Standard mobile screen implementation — flutter-developer follows Clean Architecture layers (data/domain/presentation) with Riverpod for state and Dio for networking. </commentary> </example> <example> Context: TASK-009 requires offline-capable order viewing so users can access their recent orders without network connectivity. user: "Add offline support for the orders feature in the Flutter app" assistant: "I'll implement a local cache layer using Hive for order data, a sync manager that queues writes when offline and replays them on reconnection, a connectivity listener that toggles the offline indicator in the UI, and Riverpod providers that read from cache when the network is unavailable." <commentary> Offline-first mobile pattern — flutter-developer implements local persistence with Hive, background sync queue, and connectivity-aware Riverpod providers. </commentary> </example>

Implements React/Next.js web applications — App Router with server/client components, TanStack Query for server state, Zustand for client state, React Hook Form + Zod validation, Tailwind CSS styling, error boundaries, and testing with Vitest + testing-library. Owns apps/web/. For Flutter mobile, use flutter-developer. For KMP mobile, use kmp-developer. For backend, use backend-developer. <example> Context: The feature-team has assigned TASK-004 to build the analytics dashboard page showing order metrics, charts, and recent activity. user: "Build the analytics dashboard page from the design spec" assistant: "I'll implement the dashboard as a Next.js server component with TanStack Query hooks for order metrics and activity feed. Loading skeletons for each section, error boundary around the chart widget, and Tailwind responsive layout matching design.md breakpoints." <commentary> Data-heavy dashboard page — frontend-developer uses server components for initial data, TanStack Query for client-side refetching, and handles all UI states (loading, error, empty). </commentary> </example> <example> Context: TASK-006 requires a multi-step user registration form with email verification and password strength validation. user: "Create the user registration form with full validation" assistant: "I'll build a multi-step form using React Hook Form with Zod schemas derived from api-contracts.md. Client component for interactivity, server action for submission, inline field validation, and toast notifications for success/error states." <commentary> Form-heavy task — frontend-developer uses React Hook Form + Zod for validation, matching API contract shapes exactly, with proper error handling at every layer. </commentary> </example>

Implements Kotlin Multiplatform (KMP) mobile apps — shared business logic in commonMain, Compose Multiplatform UI, Ktor networking, SQLDelight persistence, Koin DI, coroutines/Flow state management, and expect/actual for platform-specific features. Owns apps/mobile-kmp/. For web frontend, use frontend-developer. For Flutter, use flutter-developer. For backend, use backend-developer. <example> Context: The feature-team has assigned TASK-004 to build the shared order management logic with API integration and local caching across Android and iOS. user: "Implement the shared order management module in commonMain" assistant: "I'll create the orders feature in commonMain — domain entity with use cases, Ktor API client for order endpoints, SQLDelight schema for local caching, Koin module for DI wiring, and a ViewModel exposing StateFlow for the UI layer. All shared tests in commonTest." <commentary> Shared business logic task — kmp-developer builds everything in commonMain so both Android and iOS get the same logic, networking, and persistence. </commentary> </example> <example> Context: TASK-008 requires camera-based barcode scanning that uses CameraX on Android and AVFoundation on iOS. user: "Add barcode scanning using platform-native camera APIs" assistant: "I'll define an expect class BarcodeScanner in commonMain with a suspend scan() function, then provide actual implementations — CameraX with ML Kit on Android in androidMain, and AVFoundation with Vision framework on iOS in iosMain. Koin will inject the platform-specific instance." <commentary> Platform-specific feature — kmp-developer uses the expect/actual pattern to abstract platform differences while keeping the shared API surface in commonMain. </commentary> </example>

Reviews code for performance issues across the stack — N+1 queries, unnecessary re-renders, missing indexes, bundle size, memory leaks, API latency, and AI service response times. Invoke when optimizing performance. Does NOT optimize code (use senior-engineer). Does NOT review security (use security-auditor). Does NOT review code quality or patterns (use code-reviewer). <example> Context: The review-team is running Phase 6 review for a dashboard feature and needs performance analysis across backend and frontend. user: "Analyze the dashboard feature for performance issues — it loads user activity, notifications, and analytics" assistant: "I'll check the NestJS endpoints for N+1 query patterns on the activity feed joins, verify indexes exist for the notification queries, and review the React dashboard for unnecessary re-renders and missing memoization." <commentary> Performance review dispatched by review-team — performance-reviewer examines database query patterns, missing indexes, and frontend rendering efficiency across the full stack. </commentary> </example> <example> Context: The /api/orders endpoint is responding in 800ms p95, well above the 200ms target, and the team needs to identify the bottleneck. user: "API latency on the orders endpoint is 4x our target — find the bottleneck" assistant: "I'll profile the orders endpoint: run EXPLAIN ANALYZE on the order queries to check for full table scans, inspect the service layer for synchronous blocking calls to the AI service, and check if caching is configured for frequently-read order status lookups." <commentary> Targeted performance investigation — performance-reviewer uses database profiling and service-layer analysis to pinpoint whether latency comes from missing indexes, sync blocking, or absent caching. </commentary> </example>

Agent team for Phase 1 (Planning). Dispatched by project-orchestrator. Manages product-manager, business-analyst, and ux-researcher sequentially to gather requirements with full user interaction. Includes cross-review and independent requirements-reviewer for quality. Does NOT handle design (Phase 2) or task decomposition (Phase 2.1). <example> Context: The project-orchestrator has completed Phase 0.5 (project-setup) and needs Phase 1 requirements for a BIG e-commerce feature. user: [orchestrator dispatches planning-team for Phase 1] assistant: "I'll run shared research first, then dispatch product-manager for requirements discovery, business-analyst for business rules, and ux-researcher for UX specs — all sequentially so each agent can ask the user questions directly." <commentary> Planning-team dispatches agents sequentially (not in background) so AskUserQuestion calls from each agent reach the user. After all three complete, planning-team performs cross-review and dispatches requirements-reviewer for independent validation. </commentary> </example> <example> Context: A SMALL bug fix needs only a quick PRD — no business rules or UX research needed. user: [orchestrator dispatches planning-team with task_size=SMALL] assistant: "SMALL task — I'll dispatch only product-manager for an abbreviated PRD with 2-3 questions. Skipping BA, UX, research, and review." <commentary> For SMALL tasks, planning-team skips shared research, BA, UX, cross-review, and requirements-reviewer. Only PM runs with abbreviated discovery. </commentary> </example>

Gathers requirements, writes PRDs, user stories with acceptance criteria, feature lists, and business rules. The starting point for every feature. Invoke when planning features, defining scope, writing specs, or creating product documentation. <example> Context: A new feature request has been submitted and needs requirements discovery before design can begin. user: "We need to add a notification system to the app" assistant: "I'll use the product-manager agent to gather requirements and write the PRD with user stories and acceptance criteria." <commentary> New feature needs requirements gathering — product-manager conducts adaptive discovery, writes a full PRD with numbered user stories, acceptance criteria, and produces feature_list.json. </commentary> </example> <example> Context: The user has a broad idea but the scope and boundaries are undefined, risking scope creep during design. user: "I want some kind of dashboard for managing team workflows" assistant: "I'll use the product-manager agent to conduct discovery, clarify the scope, and define clear feature boundaries before proceeding." <commentary> Scope is unclear — product-manager asks targeted questions using assumption-then-correct patterns, defines scope with opt-out framing, asks whether to scope as MVP or production-ready, and produces a PRD with a cut list of excluded features. </commentary> </example>

THE primary entry point for ALL new work. ALWAYS invoke this agent when the user wants to create, build, make, or develop anything. Runs the full 9-phase pipeline for every request. Within each phase, agents are conditionally dispatched based on project-config.md — agents whose tech stack is absent are skipped. Classifies tasks for approval gates (SMALL=auto, MEDIUM=quick approval, BIG=full gates). Trigger on: 'create an app', 'build', 'I want to make', 'new feature', 'develop', 'implement', or ANY request to create something. <example> Context: The user wants to build a new task management application from scratch. user: "Build me a task management app" assistant: "I'll use the project-orchestrator agent to run the full development pipeline." <commentary> New application request triggers the orchestrator which classifies it as BIG and runs all 9 phases with approval gates at requirements, design, tasks, and implementation. </commentary> </example> <example> Context: The user has an existing settings page and wants a minor UI addition. user: "Add a dark mode toggle to the settings page" assistant: "I'll classify this as a SMALL task and run a streamlined pipeline — fewer approval gates, lighter testing." <commentary> A small scoped change (1-3 files, single service) skips formal approval gates and uses phase transition questions only, with test depth limited to unit and integration tests on changed files. </commentary> </example>

Phase 0.5 agent — interviews the user about ALL infrastructure, tech stack, and setup decisions before any planning begins. Generates project-config.md that replaces static steering files. Covers: architecture type, tech stack, auth, CI/CD, testing, code quality, database, cloud, folder structure, linting, formatting, PR templates, and more. Every project gets its own tailored configuration. <example> Context: A new greenfield project is starting and no project-config.md exists yet. The orchestrator dispatches project-setup as Phase 0.5. user: [orchestrator dispatches project-setup for a new project] assistant: "I'll scan for existing project files first. Since this is greenfield, I'll ask about application type, scale, and offer preset configurations, then write project-config.md with all tech stack and infrastructure decisions." <commentary> Project-setup runs before any planning begins. It interviews the user through structured questions (app type, scale, preset vs custom), then generates project-config.md that all downstream agents read for tech stack decisions. Presets like Startup Lean or Enterprise Microservices provide smart defaults. </commentary> </example> <example> Context: An existing project has project-config.md but the user wants to switch from Jest to Vitest for unit testing. user: "Switch our testing framework from Jest to Vitest." assistant: "I'll read the current project-config.md, update the testing section to Vitest, adjust related configuration like coverage thresholds, and present the updated config for approval before writing." <commentary> Project-setup can regenerate or modify project-config.md for an existing project. It presents the full updated configuration for user approval before writing, ensuring downstream agents pick up the change on subsequent pipeline runs. </commentary> </example>

Implements Python/Django services — AI integration with Claude/OpenAI, Django REST Framework APIs, Celery async tasks, data processing pipelines, ML model serving, and testing with pytest. Invoke for Python backend work, AI features, or data processing. For NestJS backend work, use backend-developer instead. <example> Context: The feature-team has assigned TASK-006 to build an AI-powered product description generator that accepts a product title and attributes, then returns marketing copy. user: "Implement the AI product description endpoint in the Django service" assistant: "I'll create a DRF APIView at /api/ai/generate-description with a serializer for the request payload, call the Claude API with a structured system prompt for marketing copy, handle rate limits with exponential backoff, and return the generated text with token usage metadata. Pytest fixtures will mock the Anthropic client." <commentary> AI integration task — python-developer builds the Django endpoint with Claude API, proper error handling for provider failures, and serializer validation. </commentary> </example> <example> Context: TASK-010 requires an async pipeline that processes uploaded CSV files — validates rows, enriches data from an external API, and stores results in the database. user: "Build the async CSV processing pipeline with Celery" assistant: "I'll implement a Celery task chain: first task validates and parses the CSV rows, second task enriches each batch via the external API with retry on failure, third task bulk-inserts validated records into PostgreSQL. The upload endpoint returns a job ID, and a status endpoint polls the task state. Dead-letter queue for permanently failed rows." <commentary> Async data pipeline — python-developer uses Celery task chains with per-stage error handling, idempotent retries, and a status-polling API for the caller. </commentary> </example>

Owns ALL browser and mobile E2E testing — Playwright (web), Flutter integration tests (mobile), visual regression, cross-browser/cross-device validation. Dispatched by quality-team with scope assignments from test-plan.md. Does NOT write unit, integration, API E2E, or other test types — those are owned by test-engineer. <example> Context: The quality-team assigns browser E2E scope for the checkout flow in a React/Next.js web app, per test-plan.md. user: "Write Playwright E2E tests for the checkout flow — cover cart, payment, and order confirmation across browsers" assistant: "I'll create Playwright tests for the full checkout flow: add items to cart, enter shipping details, complete payment, and verify order confirmation. Tests will run across Chromium, Firefox, WebKit, and mobile viewports (Pixel 5 and iPhone 12) with screenshot capture on failure." <commentary> Browser E2E dispatched by quality-team — qa-automation writes Playwright tests covering the critical user path with cross-browser and mobile viewport validation using the project's playwright.config.ts. </commentary> </example> <example> Context: A Flutter mobile app for a recipe-sharing platform needs E2E coverage for the recipe creation and browsing flows, including visual regression baselines. user: "Create Flutter integration tests for recipe creation and browsing, with visual regression checks" assistant: "I'll write Flutter integration tests using IntegrationTestWidgetsFlutterBinding for the create-recipe flow (form fill, image upload, publish) and browse-recipe flow (search, filter, detail view). I'll add golden file comparisons for the recipe card and detail screen to catch visual regressions." <commentary> Mobile E2E dispatched by quality-team — qa-automation creates Flutter integration tests with pumpAndSettle for async flows and golden file baselines for visual regression detection. </commentary> </example>

Agent team for Phase 4 Testing. Coordinates test-engineer and qa-automation via Agent Teams. Creates test-plan.md, presents Gate 3.5 for user approval, dispatches agents in parallel, writes test-report.md with structured coverage data, and routes failures (test bugs internally, impl bugs through feature-team). Dispatched by project-orchestrator after Phase 3. <example> Context: Feature-team has completed Phase 3 implementation for a BIG task. The orchestrator dispatches quality-team with the list of implemented services and files. user: [orchestrator dispatches quality-team for Phase 4] assistant: "I'll run requirements traceability, create a test plan covering all levels, present Gate 3.5 for approval, then dispatch test-engineer and qa-automation in parallel." <commentary> Quality-team creates test-plan.md with depth scaled to task size, gets user approval at Gate 3.5, then dispatches both test agents in parallel. Failures are classified as implementation bugs, test bugs, environment issues, or flaky tests and routed accordingly. </commentary> </example> <example> Context: Phase 3 is complete for a MEDIUM task and the orchestrator needs a coverage report with structured failure data before proceeding to the Phase 5 security audit. user: [orchestrator dispatches quality-team with task_size=MEDIUM] assistant: "I'll create the test plan scoped to unit, integration, contract, and API E2E for test-engineer, plus E2E for affected flows only via qa-automation, then produce test-report.md with per-service coverage deltas." <commentary> For MEDIUM tasks, test depth is moderate — test-engineer runs unit through API E2E while qa-automation covers only affected browser flows. The resulting test-report.md includes structured coverage data the orchestrator uses to decide whether to proceed or trigger a Phase 4-to-3 feedback loop. </commentary> </example>

Reviews Phase 1 planning specs for completeness, cross-document consistency, and quality. Dispatched by planning-team after cross-review completes. Does NOT write requirements — reviews them. Does NOT review design specs (use design-reviewer). Does NOT review code (use code-reviewer). <example> Context: The planning-team has completed requirements.md, business-rules.md, and ux.md for a task management feature and needs independent validation. user: "Review the Phase 1 specs for the task management feature before we proceed to design" assistant: "I'll review all planning specs in .claude/specs/task-management/ for user story completeness, cross-document consistency, and scope boundary alignment against requirements.md." <commentary> Requirements review dispatched after planning-team cross-review — requirements-reviewer checks that every persona has stories, every business rule traces to a requirement, and every UX flow maps to a user story. </commentary> </example> <example> Context: The requirements spec for a payment feature has user stories without edge cases and business rules that reference entities not in the PRD. user: "The requirements spec may have gaps — review it for completeness" assistant: "I'll focus on user story completeness and cross-document consistency: every story needs acceptance criteria and edge cases, every business rule must trace to a requirement, and no scope creep from BA or UX." <commentary> Targeted requirements review — requirements-reviewer flags incomplete acceptance criteria and orphan business rules as Critical findings that block the pipeline. </commentary> </example>

Agent team for comprehensive code review. Spawns parallel reviewers for code quality, security, and performance that produce a combined report. <example> Context: The orchestrator has completed Phase 5 security audit with no critical findings. Phase 6 review is next for a BIG task with agent-native artifacts present. user: [orchestrator dispatches review-team for Phase 6] assistant: "I'll spawn code-reviewer, security-auditor (spot-check mode), performance-reviewer, static-analyzer, agent-native-reviewer, and spec-tracer all in parallel, then compile a combined review-report.md." <commentary> Review-team dispatches all applicable reviewers simultaneously since they are independent. For BIG tasks with agent-native artifacts, all 6 reviewer roles run. The security-auditor performs a focused spot-check of code changes only, not a full OWASP audit (that was Phase 5). </commentary> </example> <example> Context: A MEDIUM feature is ready for review. The orchestrator needs a combined report with severity-ranked findings and a spec traceability matrix before the feature can proceed to DevOps. user: [orchestrator dispatches review-team for Phase 6 with task_size=MEDIUM] assistant: "I'll spawn code-reviewer, security-auditor, performance-reviewer, static-analyzer, and spec-tracer in parallel, then merge all findings into review-report.md organized by severity with an approve/request-changes recommendation." <commentary> The combined report merges findings from all reviewers by severity (Critical, High, Medium, Low). Critical or High findings trigger a Phase 6-to-3 feedback loop where the orchestrator re-dispatches feature-team for surgical fixes. </commentary> </example>

Performs security audits across the entire stack — OWASP Top 10, STRIDE threat modeling, secrets scanning, dependency audit, and compliance checks. Produces structured security-audit.md with severity classification. Routes CRITICAL/HIGH findings through Phase 5→3 feedback loop. Invoke for Phase 5 (full audit) or Phase 6 (focused spot-check). <example> Context: Phase 4 tests have passed for a BIG-sized e-commerce feature with NestJS, React, and Flutter — the orchestrator dispatches Phase 5 full security audit. user: "Run the full Phase 5 security audit on the e-commerce feature" assistant: "I'll execute the full audit protocol: secrets-scanner first for committed credentials, dependency-audit across npm and pip ecosystems, OWASP Top 10 checks on all NestJS endpoints, STRIDE threat modeling on the payment flow, and compliance checks against PCI-DSS requirements from project-config.md." <commentary> Phase 5 full audit for a BIG task — security-auditor runs all 5 skills in order, writes security-audit.md with severity-classified findings, and returns results to the orchestrator. </commentary> </example> <example> Context: During the secrets-scanner step, a Stripe API key is found committed in the NestJS payment service configuration file. user: "A production secret was found in the codebase during the security audit" assistant: "STOP triggered — confirmed vendor-pattern secret (Stripe API key) in services/payment/src/config.ts. I'll write partial security-audit.md with Status: STOPPED, include the STOP finding as SEC-001 CRITICAL, and return immediately to the orchestrator for Phase 5 to 3 routing so the feature-team can remediate." <commentary> STOP policy activated — security-auditor halts the audit immediately on finding a committed production secret, preserves partial results, and signals the orchestrator to route back to Phase 3 for remediation. </commentary> </example>

Principal engineer who implements complex cross-service features, handles integration between NestJS and Python services, resolves architectural issues, and mentors other agents. The go-to for anything that spans multiple services. Invoke for complex features, cross-service integration, or architectural implementation. For single-service NestJS features (not cross-service), use backend-developer instead. <example> Context: The feature requires the NestJS core service to call the Python AI service for content moderation, with shared request/response types and circuit breaker fallback. user: "Implement the content moderation flow across NestJS and Python services" assistant: "I'll define the shared interface in the proto schema, implement the moderation endpoint in the Django AI service with Claude API, build the NestJS HTTP client with circuit breaker and 30s timeout, add structured logging for cross-service tracing, and write integration tests that exercise both services end-to-end." <commentary> Cross-service integration — senior-engineer owns the full flow spanning NestJS and Python, including shared types, error handling, and retry logic that no single-service agent covers. </commentary> </example> <example> Context: During Phase 3, backend-developer flagged that the planned event-driven architecture conflicts with the synchronous API contract defined in api-spec.md. user: "The event-driven approach conflicts with the sync API contract — resolve this" assistant: "I'll analyze both the api-spec.md contract and the architecture.md event flow, determine whether to adapt the API to async (webhook callbacks) or keep sync with internal events, update the affected specs, and notify backend-developer and frontend-developer of the revised contract." <commentary> Architectural conflict resolution — senior-engineer has the cross-cutting authority to resolve design disagreements and update specs that affect multiple agents. </commentary> </example>

Runs tool-based static analysis for code quality — duplication detection (jscpd), complexity metrics (Semgrep/ESLint/Ruff/Detekt), dead code detection (knip/vulture/deadcode), and code smells. Dispatched by review-team as a parallel reviewer in Phase 6. Produces advisory findings (not blocking). <example> Context: The review-team is running Phase 6 review for a payments feature and dispatches static analysis alongside LLM-based code review. user: "Run static analysis on the payments feature codebase — NestJS backend and React frontend" assistant: "I'll run jscpd for duplication detection, Semgrep maintainability and best-practices rulesets, ESLint complexity checks, and knip for dead code across both the NestJS service and React app." <commentary> Static analysis dispatched by review-team in Phase 6 — static-analyzer runs tool-based checks in parallel with code-reviewer's LLM-based review, producing advisory metrics for the combined report. </commentary> </example> <example> Context: A large codebase has grown over several sprints and the team suspects accumulated complexity and unused exports. user: "Audit the codebase for complexity hotspots and dead code" assistant: "I'll run Semgrep C901 complexity rules to find functions with excessive branching, knip to detect unused exports and imports, and jscpd to surface copy-paste blocks. All findings are advisory — they won't block the pipeline." <commentary> Complexity and dead code audit — static-analyzer identifies maintenance risks through deterministic tooling, reporting cyclomatic complexity scores and unused symbol counts. </commentary> </example>

Designs microservice architecture — service boundaries, communication patterns (REST/gRPC), data flow, infrastructure topology, and ADRs. Specializes in NestJS + Python microservices on AWS. Invoke for architecture decisions, service design, or infrastructure planning. <example> Context: A new project has been scoped by the product-manager and needs architecture design before implementation can begin. user: "Build a multi-tenant SaaS platform with a NestJS backend and React frontend" assistant: "I'll use the system-architect agent to define service boundaries, communication patterns, and infrastructure topology based on project-config.md." <commentary> New project needs architecture — system-architect reads project-config.md, proposes 2-3 architectural approaches, designs service boundaries and data flow, and writes architecture.md with ADRs and Mermaid diagrams. </commentary> </example> <example> Context: A feature requires processing that doesn't fit in the existing core service and needs its own microservice with defined integration points. user: "We need a dedicated AI inference service that the core backend calls via gRPC" assistant: "I'll use the system-architect agent to create an ADR for the new service and design the integration points with the existing architecture." <commentary> Feature requires a new microservice — system-architect creates an ADR documenting the decision, designs gRPC contracts and service communication patterns, and updates the architecture diagram. </commentary> </example>

Reads design specs and decomposes them into ordered, dependency-aware implementation tasks. Produces tasks.md with TASK-NNN format. Dispatched by orchestrator in Phase 2.1. <example> Context: Phase 2 (Design) is complete and all design specs have been approved. The orchestrator dispatches Phase 2.1 to produce implementation tasks. user: "Design is approved — break it down into implementation tasks" assistant: "I'll use the task-decomposer agent to read all design specs and produce an ordered tasks.md with TASK-NNN items, dependency graph, and agent assignments." <commentary> Design specs approved — task-decomposer reads requirements.md, architecture.md, api-spec.md, schema.md, design.md, and agent-spec.md, then produces tasks.md with phased TASK-NNN items, effort estimates, risk levels, and verification commands. </commentary> </example> <example> Context: A large feature spans multiple services and needs granular task decomposition so parallel agent teams can work without blocking each other. user: "This feature touches backend, frontend, and mobile — break it into small enough tasks for parallel development" assistant: "I'll use the task-decomposer agent to break the work into granular TASK-NNN items with effort estimates, agent assignments, and a validated dependency DAG for parallel execution." <commentary> Large feature needs granular tasks — task-decomposer decomposes across foundation, data, service, API, UI, and integration layers, assigns each task to the correct agent from the ownership matrix, and validates the dependency graph has no cycles. </commentary> </example>

Autonomous task execution engine — reads tasks from tasks.md, implements each in dependency order, runs verification, creates atomic commits, and tracks progress. The workhorse for batch implementation. Invoke to execute a pre-approved set of tasks without interaction. <example> Context: Tasks.md has been approved with 8 tasks — 3 backend (NestJS), 3 frontend (Next.js), 2 shared utilities — with a dependency graph showing backend tasks must complete first. user: "Execute the approved tasks from tasks.md" assistant: "I'll work through tasks in dependency order: first the 3 NestJS backend tasks (using nestjs-patterns), then the 2 shared utilities, then the 3 Next.js frontend tasks (using react-patterns). Each task gets TDD implementation, verification, and an atomic commit. I'll mark each complete in tasks.md as I go." <commentary> Ordered batch execution — task-executor respects the dependency graph, detects service type per task path, and creates one commit per completed task. </commentary> </example> <example> Context: Tasks.md contains 5 independent refactoring tasks across the codebase — no dependencies between them, all pre-approved. user: "Work through the refactoring tasks autonomously" assistant: "I'll execute all 5 tasks sequentially — for each one I'll read the task description, implement the refactor, run the verification command, commit if passing, retry once with a different approach if failing, then move to the next. Progress tracked in tasks.md after each task." <commentary> Independent batch — task-executor processes each task autonomously with built-in retry logic, no user interaction needed between tasks. </commentary> </example>

Writes project documentation — API references, architecture guides, README, runbooks, changelogs, and developer onboarding guides. Reads project-config.md to adapt docs structure to the actual tech stack. Invoke for any documentation task. <example> Context: Phase 8 documentation is needed for a food delivery app built with NestJS, React, and Flutter — all prior phase specs and audit reports are available. user: "Generate project documentation for the food delivery feature — API reference, architecture guide, and README" assistant: "I'll read project-config.md and all phase outputs first, then generate docs/API.md from api-contracts.md, docs/ARCHITECTURE.md from architecture.md, and docs/README.md with quick-start instructions for the NestJS + React + Flutter stack." <commentary> Phase 8 documentation generation — technical-writer reads all spec files to produce accurate docs, then runs a completeness check to verify every endpoint and environment variable is documented. </commentary> </example> <example> Context: A new real-time chat feature was added to an existing Django + React project and developers need a setup and deployment runbook. user: "Create a developer onboarding guide and deployment runbook for the chat feature" assistant: "I'll read project-config.md for the Django + React stack, then create docs/DEVELOPMENT.md with local setup steps including WebSocket configuration, and docs/DEPLOYMENT.md incorporating the deployment order and rollback procedures from deployment-plan.md." <commentary> Targeted documentation — technical-writer adapts the runbook to Django's manage.py commands, Redis for WebSocket channels, and React's dev server, pulling deployment details from Phase 7 outputs. </commentary> </example>

Writes comprehensive tests across unit, integration, contract, API E2E, security, UAT, accessibility, and performance levels. Dispatched by quality-team with scope assignments from test-plan.md. Does NOT write browser E2E (Playwright) or mobile E2E (Flutter integration) — those are owned by qa-automation. <example> Context: The quality-team assigns unit and integration test scope for the user authentication service in a NestJS backend, per test-plan.md. user: "Write unit and integration tests for the auth service — cover login, registration, and token refresh" assistant: "I'll write Jest unit tests for AuthService covering happy path login, invalid credentials, expired tokens, and edge cases like rate-limited accounts. Then I'll add integration tests using Supertest with a test database for the full POST /auth/login and POST /auth/refresh request lifecycle." <commentary> Test-engineer dispatched by quality-team with scoped assignment — writes unit tests mocking dependencies and integration tests with real database, targeting 80% coverage per project-config.md thresholds. </commentary> </example> <example> Context: A microservices project needs contract tests between the API gateway and core service, plus API E2E tests for the order endpoints. user: "Create contract tests for gateway-to-core and API E2E tests for the order CRUD endpoints" assistant: "I'll create Pact consumer tests in the API gateway verifying the /orders contract with the core service, then write API E2E tests using Supertest that exercise the full create, read, update, delete lifecycle for orders with schema validation on every response." <commentary> Contract and API E2E testing — test-engineer creates Pact consumer-driven contracts for cross-service boundaries and end-to-end API tests validating response shapes against the defined schemas. </commentary> </example>

Creates UI component specifications, design systems, responsive layouts for React/Next.js web and Flutter/KMP mobile. Invoke for component design, design system creation, or visual specifications. <example> Context: The design-team is working on a new feature and needs UI component specifications and responsive layouts before frontend implementation can begin. user: "We need the UI designed for an analytics dashboard with charts, filters, and data tables" assistant: "I'll use the ui-designer agent to create responsive layouts with design tokens, component hierarchy, and an interaction inventory for the dashboard screens." <commentary> Design-team needs component specs — ui-designer asks design preferences, creates design.md with shared tokens, responsive breakpoints, component states, dark mode support, and builds a Next.js prototype for review. </commentary> </example> <example> Context: The project targets both web and mobile platforms and needs a unified design system so components look consistent across React and Flutter. user: "We need a shared design system that works across our React web app and Flutter mobile app" assistant: "I'll use the ui-designer agent to define shared design primitives — colors, spacing, typography tokens — with platform-specific mappings for React (Tailwind) and Flutter (ThemeData)." <commentary> Mobile and web need a consistent design system — ui-designer defines shared tokens with a platform mapping table, designs platform-adaptive components (Material on Android, Cupertino on iOS, custom on web), and creates the /design-system page. </commentary> </example>

Creates user personas, journey maps, information architecture, wireframes, and UI specifications for web (React) and mobile (Flutter/KMP). Invoke for UX planning and design. <example> Context: A new feature has been scoped by the product-manager and needs user flow design before UI components can be specified. user: "We need the user experience designed for the onboarding flow — signup through first project creation" assistant: "I'll use the ux-researcher agent to create personas, journey maps, and information architecture for the onboarding experience." <commentary> New feature needs user flow design — ux-researcher reads the PRD, scans existing UI patterns, creates personas and journey maps, defines wireframe layouts with responsive breakpoints, and documents accessibility requirements. </commentary> </example> <example> Context: An existing feature has poor conversion rates and users are dropping off, indicating usability problems that need diagnosis. user: "Users keep abandoning the checkout flow after the payment step — figure out why and fix the UX" assistant: "I'll use the ux-researcher agent to map the current pain points in the checkout flow and propose wireframe improvements with better error handling and clearer feedback." <commentary> Existing feature has usability issues — ux-researcher traces the current user journey, identifies friction points and missing states (loading, error, empty), and produces updated wireframes with improved flow and accessibility. </commentary> </example>

Validate WCAG 2.1 AA/AAA compliance — ARIA labels, keyboard navigation, color contrast, screen reader support, focus management, and semantic HTML. Use when the user mentions "accessibility", "WCAG", "a11y", "screen reader", "keyboard navigation", or needs to make their app accessible to all users.

Build Claude Code agents — .md agent definitions, frontmatter configuration, tool selection, model routing, subagent dispatch, and multi-agent coordination. Use when creating or modifying agents, configuring agent teams, or designing orchestration flows.

Agent-native architecture design methodology — parity mapping (UI action to agent tool), atomic tool definitions, prompt-defined features, shared workspace patterns, and dynamic context injection. Use when designing agent-native capabilities for a target application during Phase 2 of the pipeline.

Sub-phase progress tracking protocol for all agents. Enables debugging pipeline execution by writing structured status files at every step transition. Injected into every agent to provide observability into internal workflows.

Generate CLAUDE.md, settings.json, hooks, subagents, commands, and MCP config. Auto-detects tech stack from project files. Use when setting up or managing the development workspace and tooling.

Integrate LLM APIs — prompt engineering, streaming, function calling, token management, cost optimization, fallback strategies. Supports Claude, OpenAI, Gemini. Use when building AI features, agents, integrations, or automation workflows.

Set up privacy-first application analytics for web (React/Next.js) and mobile (Flutter) with PostHog, event tracking architecture, consent management, and server-side tracking from NestJS.

Design and generate API specifications — REST endpoints, GraphQL schemas, request/response formats, authentication, error codes, rate limiting, pagination, and versioning. Outputs in OpenAPI/Swagger YAML or Markdown. Use when the user says "design the API", "create API spec", "REST endpoints", "GraphQL schema", "API documentation", or needs to define the contract between frontend and backend.

Generate API documentation from code — endpoint descriptions, request/response examples, auth guides, SDK samples. Supports OpenAPI/Swagger output. Use when the user says "API documentation", "generate docs from code", "Swagger docs", "OpenAPI spec", "document endpoints", or needs to create API reference docs.

Implement REST/GraphQL APIs with validation, error handling, pagination, auth middleware, rate limiting, and consistent response formats. Use when the user mentions "Build the API", "Implement endpoint", or related tasks.

Generate and run API test suites — endpoint validation, auth flows, error scenarios, rate limit testing, and schema validation. Use when the user says "test the API", "API test suite", "validate endpoints", or needs to verify API behavior against its specification.

Deploy applications to AWS, GCP, or Azure — covers Lambda, ECS, Cloud Run, GKE, Azure Container Apps, AKS, CDK/Terraform, and PaaS platforms (Vercel, Railway, Render). Use when deploying to any cloud provider, configuring cloud resources, or setting up infrastructure.

Auto-generate changelogs from git commits using conventional commit format. Groups by Added/Changed/Fixed/Security. Use when the user says "generate changelog", "CHANGELOG.md", "release notes from commits", "what changed", or needs to create a changelog for a release.

Generate CI/CD pipelines — GitHub Actions, GitLab CI, Jenkins. Build, test, lint, deploy stages with environment variables and secrets management. Use when the user says "set up CI/CD", "GitHub Actions", "pipeline", "automated deployment", or needs continuous integration.

Enforce code documentation standards — JSDoc/TSDoc, Google-style docstrings, KDoc, dartdoc, godoc. Public APIs always documented, private only when complex, no trivial comments. TODO/FIXME must reference tickets. Use when implementing features or reviewing code for documentation quality.

Perform thorough code review — logic errors, naming quality, duplication, complexity, test coverage, performance, and security. Uses a fresh context for objectivity. Use when the user says "review this code", "PR review", "code quality check", or needs a second pair of eyes on implementation.

Review and simplify code — extract reusable utilities, reduce duplication, improve naming, simplify logic, and enhance readability. Use when the user says "simplify", "clean up", "refactor", "reduce complexity", "code smell", or after implementation to improve code quality.

Research and compare competing products, features, pricing, and market positioning to inform product decisions. Use when the user asks about competitors, market research, competitive landscape, feature comparison, or needs to understand what alternatives exist.

Validate compliance with GDPR, CCPA, HIPAA, PCI-DSS, SOC2. Check data handling, consent flows, audit logging, and data retention. Use when the user mentions regulatory compliance or needs to ensure their application meets legal requirements.

Build ETL/ELT pipelines — extraction from APIs, transformation with Pydantic models, loading to PostgreSQL, batch processing with Django management commands, streaming with async generators, data validation, checkpointing, and idempotent operations. Use when working with data ingestion, processing, or batch jobs.

Build charts, dashboards, and data-driven UI in React/Next.js using Recharts, Chart.js, or D3. Covers responsive sizing, accessibility, real-time updates, loading states, and error handling.

Design database schemas — ER diagrams, table definitions with constraints, indexes, relationships, migration strategies, seed data, and query optimization. Supports PostgreSQL, MySQL, SQLite, MongoDB. Use when the user says "design the database", "create schema", "data model", "ER diagram", "database migration", "table structure", or needs to define how data is stored and related.

Optimize database queries — EXPLAIN analysis, index recommendations, query rewriting, connection pooling, N+1 detection. Supports PostgreSQL with TypeORM/Prisma and Django ORM. Use when the user says "slow query", "optimize queries", "EXPLAIN ANALYZE", "N+1 problem", "database performance", "index recommendations", or needs to tune database performance.

Scan dependencies for vulnerabilities, outdated packages, license conflicts, and supply chain risks. Use when the user says "audit dependencies", "check vulnerabilities", "update packages", "npm audit", "supply chain security".

Create component libraries, design tokens, theme systems, and shared UI primitives for consistent cross-app design. Use when building a design system, component library, theme configuration, or shared UI kit for React, Vue, Flutter, or any framework.

Create optimized Dockerfiles, multi-stage builds, docker-compose configs, health checks, and container security. Use when the user says "Dockerize", "Docker compose", "container", "Dockerfile", or needs to containerize their application.

Configure development environments -- Docker Compose, environment variables, database setup, language toolchains (Node.js, Python, Flutter), IDE config, and pre-commit hooks. Use when setting up or managing the development workspace and tooling.

Implement consistent error handling: custom error classes, boundaries, retry logic, graceful degradation. Use when the user mentions "Handle errors", "Error strategy", or related tasks.

Provide story point and time estimates for features and tasks using complexity analysis, historical patterns, and risk assessment. Use when the user asks "how long will this take", "estimate this feature", "story points", "effort estimation", or needs to plan sprints and timelines.

Build Flutter applications with clean architecture, BLoC/Riverpod state management, responsive layouts, platform-adaptive widgets, and testing. Use when building Flutter apps, creating widgets, managing state, handling navigation, or implementing platform-specific features. Trigger on "Flutter", "Dart", "Flutter widget", "BLoC", "Riverpod", "Flutter app".

Create distinctive frontend interfaces when DELEGATED by the frontend-developer or ui-designer agents. Provides design systems, component architecture, responsive layouts, animations, and accessibility patterns. Do NOT invoke directly for new application requests — those go through project-orchestrator first.

Scaffold and configure project structures, boilerplate code, and initial setup when DELEGATED by the project-orchestrator agent. Do NOT invoke this skill directly for new application requests — those should go through the project-orchestrator agent first. Only triggers when explicitly called by an agent, not from user prompts like "build an app" or "create a project".

Manage Git operations -- branching strategies, conventional commits, PR workflow, rebase, conflict resolution, and feature branch lifecycle. Use when setting up or managing the development workspace and tooling.

Generate Kubernetes manifests — deployments, services, ingress, HPA, ConfigMaps, secrets, and Helm charts. Use when the user mentions "Kubernetes", "K8s", "Helm", "deployment manifest", or needs to deploy to a Kubernetes cluster.

Build Kotlin Multiplatform (KMP) applications — shared business logic across Android, iOS, desktop, and web. Covers project structure, expect/actual declarations, Ktor networking, SQLDelight database, Koin DI, and Compose Multiplatform UI. Use when building KMP apps, sharing code between platforms, or implementing cross-platform features. Trigger on "KMP", "Kotlin Multiplatform", "Compose Multiplatform", "shared module", "expect actual".

Set up and run performance/load testing — concurrent users, response time benchmarks, stress testing, and bottleneck identification using k6, Artillery, or Apache Bench. Use when the user says "load test", "performance benchmark", "stress test", "how many users can this handle".

Build MCP (Model Context Protocol) servers for Claude Code. Covers server structure (tools, resources, prompts), transport types (stdio, SSE), tool parameter design, error handling, testing, and TypeScript examples using @modelcontextprotocol/sdk.

Handle framework migrations (JS→TS, REST→GraphQL), database migrations, and version upgrades with safe rollback strategies. Use when the user mentions "Migrate to TypeScript", "Upgrade framework", or related tasks.

Configure observability — structured logging, metrics (Prometheus/CloudWatch), tracing (OpenTelemetry), alerting, and dashboards. Use when the user says "set up monitoring", "add logging", "observability", "alerting", or needs to track application health in production.

Manage the project monorepo structure with npm workspaces or Turborepo. Covers shared dependencies, cross-package types, build ordering, selective CI/CD, Docker builds, and package naming conventions.

Implement NestJS best practices — module architecture, dependency injection, guards, pipes, interceptors, exception filters, DTOs with class-validator, TypeORM/Prisma integration, and testing patterns. Use when building NestJS applications, creating modules, implementing middleware, or following NestJS conventions. Trigger on "NestJS", "Nest.js", "NestJS module", "NestJS guard", "NestJS service".

Profile and optimize: bundle size, lazy loading, query optimization, caching, memory leak detection. Use when the user mentions "Optimize performance", "Speed up", or related tasks.

Just-in-time phase instruction loader for the project-orchestrator. Reads focused ~40-line phase files instead of holding the entire 1094-line prompt in active attention. Each phase file contains preconditions, expected outputs, content validation, dispatch instructions, and conditional logic.

Provide accurate information about the product being built — its features, architecture, user flows, and business logic. Use this skill as a template for creating product-specific knowledge bases that agents reference during development. Trigger when agents need to understand "how does our product work", "what does this feature do", or need domain context.

Generate complete project requirement documents — PRD, user stories, feature lists, acceptance criteria, design specs, API specifications, database schemas, task breakdowns, and test plans. Use this skill whenever the user wants to create project documentation, write a PRD, define features, create user stories, spec out an application, plan a feature, create a design document, break down tasks for implementation, or prepare any specification document. Also trigger for "spec-driven development", "SDD", "requirements document", "feature spec", "product spec", "application spec", "write user stories", "acceptance criteria", "task breakdown", "implementation plan", "design doc".

Implement Python/Django best practices — project structure, Django REST Framework APIs, Celery async tasks, model patterns, serializers, viewsets, testing with pytest, and AI/ML service patterns. Used by python-developer and backend-developer agents for Python service implementation. Do NOT invoke directly — agents load this skill automatically.

Implement React best practices when DELEGATED by the frontend-developer or senior-engineer agents — hooks patterns, server components, state management, error boundaries, performance optimization. Not a standalone entry point for building applications.

Create comprehensive README.md — project description, installation, usage, API reference, contributing guide, license. Use when the user says "create README", "write README", "project README", "document setup instructions", or needs a README.md for their repository.

Manage releases — semantic versioning, changelog generation, release notes, git tags, and rollback procedures. Use when the user says "create release", "version bump", "changelog", "release notes", or needs to ship a new version.

Detect accidentally committed secrets — API keys, passwords, tokens, private keys, database URLs in code and config. Use when the user says "scan for secrets", "check for leaked keys", "secrets audit", or before any public repository push.

Review code for security vulnerabilities — OWASP Top 10, injection attacks, broken auth, XSS, CSRF, secrets in code, insecure dependencies. Outputs severity-rated report. Use when the user says "security review", "check vulnerabilities", "OWASP audit", "security scan", or before deploying to production.

Enforce the Spec-Driven Development workflow — Requirements→Design→Tasks→Implementation with phase gates and review checkpoints. Use when the user wants structured development instead of vibe coding, needs to plan a complex feature before building, or mentions "spec-driven", "SDD", "plan before code", "structured development", or "phase gates".

Model entity state transitions, guard conditions, side effects, and generate implementation code. Use when designing order flows, auth states, approval workflows, or any entity with distinct states and transition rules. Trigger on "state machine", "workflow states", "order flow", "status transitions".

Run tool-based static analysis for code quality — duplication detection (jscpd), complexity metrics (Semgrep/ESLint/Ruff/Detekt), dead code detection (knip/vulture/deadcode), and code smells (Semgrep best-practices). Use when the user says "code quality", "check duplication", "complexity analysis", "dead code", "static analysis".

Generate persistent project context files — product.md, tech.md, structure.md — that guide every coding session. Use when setting up a new project, creating project context, or when the user mentions "steering documents", "project context", "product vision", or "tech stack documentation".

Design system architecture — microservices vs monolith decisions, layer diagrams, module boundaries, data flow, infrastructure topology, and Mermaid diagrams. Use when the user asks to "design the architecture", "system design", "how should I structure this", "architect this app", "microservices or monolith", or needs to make high-level technical decisions before coding.

Break features into ordered, dependency-aware implementation tasks with verification commands, file lists, effort estimates, and commit messages. Use when the user says "break this into tasks", "create implementation plan", "task breakdown", "decompose this feature", or needs to convert a design into actionable coding steps.

Enforce strict Test-Driven Development — Red-Green-Refactor cycle. Write failing tests first, implement minimal code to pass, then refactor. Use when the user says "write tests first", "TDD", "test-driven", "red green refactor", or when building features that require high reliability. This skill prevents the agent from skipping to implementation.

Write clear technical documentation — guides, tutorials, architecture docs, and runbooks with proper structure and examples. Use when the user says "write a guide", "architecture doc", "ADR", "runbook", "deployment guide", "tutorial", or needs long-form technical documentation beyond a README.

Write Terraform infrastructure-as-code — modules, providers, state management, workspaces, and security. Use when the user mentions "Terraform", "IaC", "infrastructure as code", "cloud provisioning", or needs to manage cloud resources declaratively.

Write comprehensive unit and integration tests — happy path, edge cases, error scenarios, security tests. Ensures minimum 80% coverage. Use when the user says "write tests", "add coverage", "test this", or after implementing features. Works with Jest, Vitest, Pytest, JUnit, and all major frameworks.

Perform STRIDE threat modeling — Spoofing, Tampering, Repudiation, Information Disclosure, DoS, Elevation of Privilege. Use when the user says "threat model", "STRIDE analysis", "security assessment", or needs to identify threats before building security controls.

Create UI wireframes, screen layouts, navigation flows, and component specifications using ASCII art, Mermaid diagrams, and structured markdown. Use when the user needs wireframes, mockups, screen layouts, navigation maps, or UI specifications before building the frontend.

Generate numbered user stories in "As a / I want / So that" format with bullet-point acceptance criteria, priorities, dependencies, edge cases, and technical notes. Use when the user asks to "write user stories", "create acceptance criteria", "define features", "story mapping", or needs to convert vague requirements into structured, testable stories.

Capture and compare UI screenshots before/after changes to detect unintended visual differences. Use when the user mentions "visual regression", "screenshot testing", "UI diff", "visual comparison", or needs to ensure UI changes don't break existing pages.

Audit web application quality — Core Web Vitals (LCP, FID, CLS), Lighthouse scores, performance optimization, accessibility compliance, SEO, and best practices. Use when the user mentions "performance audit", "Lighthouse", "Core Web Vitals", "LCP", "page speed", "web quality", or needs to improve web app metrics.

Test web applications using Playwright — E2E tests, UI verification, visual regression, accessibility checks, and cross-browser testing. Use when the user needs "E2E tests", "browser testing", "Playwright", "UI testing", "visual regression", or wants to verify web app behavior.

Automate CI/CD pipelines and async workflows — GitHub Actions for lint/test/build/deploy, Celery tasks for async processing, event-driven patterns with RabbitMQ/SQS, scheduled jobs with Celery Beat. Use when building pipelines, automating deployments, or creating background job systems.

4 hooks across 2 events