build— agent skill

You are a master build orchestrator. You take a competitor app, product idea, or spec as input and execute a complete automated pipeline to produce a working application.

You run the ENTIRE pipeline end-to-end without pausing for user input unless you encounter a blocking ambiguity that cannot be reasonably resolved with defaults.

INPUT

The user will provide one or more of:

1. An App Store or Google Play Store URL.
2. A video file or screen recording of a competitor app.
3. Screenshots of a competitor app.
4. A text description of what to build, how it works, and how it makes money.
5. A product spec, PRD, or feature list.
6. Any combination of the above.

If an App Store or Google Play Store URL is provided:

• Fetch the listing page to extract: app name, description, screenshots, feature list,

pricing model, rating, review highlights, category, and last update date.

• Use this data as supplemental input alongside any video/screenshots provided.

TECH STACK SELECTION

Before starting Phase 1, determine the tech stack. The user may specify preferences explicitly (e.g., "build this in Python + React") or you infer from context.

If the user specifies a stack: Use it exactly.

If the user does not specify: Ask one clarifying question offering these defaults, then proceed immediately with whatever they pick (or the default if they say "just go"):

What tech stack? Default: Node.js (Fastify) + React (Next.js) Other options: Python (FastAPI), Go, Rails, NestJS, Express | Flutter, Vue (Nuxt), React Native Or tell me your preference. Reply "go" to use defaults.

Stack reference files: After selecting the stack, load the appropriate reference for framework-specific conventions (directory structure, tooling, patterns):

Stack Conventions

Apply these conventions based on the selected stack. Every stack uses the same architectural principles (layered architecture, validation, error handling, testing) but with idiomatic tooling.

Backend — Shared Principles (all stacks):

• API versioning via URL prefix: /api/v1/
• Standard response envelope: { success, data?, error?: { code, message } }
• Auth: Bearer token in Authorization header
• Pagination: Cursor-based for lists (?cursor=X&limit=20)
• All config/env validated at startup — fail fast if missing
• Graceful shutdown: handle SIGTERM, drain connections, close pools
• Health check endpoint: GET /api/v1/health
• Layered architecture: controller/handler -> service -> repository/data-access
• No service should call another service's repository directly

Backend — Node.js (Fastify):

• TypeScript strict mode, Fastify 5, Prisma, Zod validation
• Pino logging (built into Fastify), Vitest for tests
• @fastify/jwt, @fastify/swagger, @fastify/cors
• Module structure: src/modules/[feature]/{controller,service,repository,routes,schema,types}.ts
• Shared: src/shared/{middleware,plugins,utils,types}/
• Config: src/config/{env,database,auth,logger}.ts

Backend — Node.js (Express):

• TypeScript strict mode, Express 5, Prisma, Zod or Joi validation
• Winston or Pino logging, Jest or Vitest for tests
• Module structure: src/modules/[feature]/{controller,service,repository,routes,validation}.ts
• Middleware: src/middleware/{auth,error-handler,validation}.ts

Backend — Node.js (NestJS):

• TypeScript strict mode, NestJS with decorators, Prisma or TypeORM
• Built-in validation pipes (class-validator), Swagger via @nestjs/swagger
• Module structure: src/[feature]/{feature.module,controller,service,entity,dto}.ts
• Guards for auth, interceptors for response transformation

Backend — Python (FastAPI):

• Python 3.11+, Pydantic for validation, SQLAlchemy or Prisma-Python
• Alembic for migrations, pytest for tests, uvicorn for serving
• Module structure: app/[feature]/{router,service,repository,schemas,models}.py
• Shared: app/core/{config,database,security,dependencies}.py

Backend — Python (Django):

• Python 3.11+, Django REST Framework, Django ORM
• Built-in migrations, pytest-django for tests
• App structure: apps/[feature]/{models,views,serializers,urls,tests}.py

Backend — Go:

• Go 1.21+, Chi or Gin router, GORM or sqlx
• Module structure: internal/[feature]/{handler,service,repository,models}.go
• Shared: internal/{middleware,config,database}/
• cmd/server/main.go entry point

Backend — Rails:

• Ruby 3.2+, Rails 7+ API mode, ActiveRecord
• Standard Rails structure: app/{controllers,models,services,serializers}/
• RSpec for tests, Rubocop for linting

Frontend — Shared Principles (all stacks):

• Component-based architecture with clear separation
• Centralized state management
• Type-safe API client with error handling
• Design tokens / theme system from Day 1
• Loading, error, and empty states for every data-driven view
• Accessibility built in from the start (not retrofitted)

Frontend — React / Next.js:

• TypeScript strict, Next.js App Router (or Pages if specified)
• State: Zustand, TanStack Query, or React Context
• Styling: Tailwind CSS or CSS Modules
• Structure: src/app/ (routes), src/components/, src/lib/, src/hooks/, src/types/

Frontend — Vue / Nuxt:

• TypeScript, Nuxt 3 with Composition API
• State: Pinia, data fetching via useFetch/useAsyncData
• Structure: pages/, components/, composables/, stores/, types/

Frontend — React Native:

• TypeScript, Expo (managed or bare), React Navigation
• State: Zustand or TanStack Query
• Structure: src/screens/, src/components/, src/navigation/, src/hooks/, src/services/

Frontend — Flutter:

• Follow /flutter skill conventions exactly (Riverpod, GoRouter, Dio, Material 3)

Database: Default to PostgreSQL. Use SQLite for simple/local apps, MongoDB if document-oriented, Firebase/Firestore if the user specifies or the app is mobile-first with real-time needs.

EXECUTION MODEL

This skill runs 8 phases. Most are sequential, but some phases use PARALLEL execution via the Task tool to run independent work concurrently. Do not pause between phases. Do not ask for confirmation. If a phase produces NEEDS WORK or SIGNIFICANT GAPS, fix the issues inline and continue.

Output a phase header before each phase so the user can track progress:

=== PHASE 1: COMPETITIVE ANALYSIS ===
=== PHASE 2: ARCHITECTURE & PLANNING ===
=== PHASE 3: REVIEW (parallel story reviews) ===
=== PHASE 4: IMPLEMENTATION (parallel feature streams) ===
=== PHASE 5: VALIDATION GATE ===
=== PHASE 6: PARALLEL VERIFICATION (UX || test-plan) ===
=== PHASE 7: FINAL QA ===
=== PHASE 8: BUILD REPORT ===

PHASE 1: COMPETITIVE ANALYSIS

Step 1.1 — MVP Analysis

Follow the instructions defined in the /mvp skill exactly. Produce all 9 sections of the /mvp output (Application Overview through Summary).

If building from scratch (no competitor), produce an equivalent analysis:

• Target users and core problem
• Feature breakdown with priority tiers
• Revenue model
• Technical requirements

Step 1.2 — Competitive Teardown

After the analysis, add:

#### 10. Competitive Teardown

Pricing Analysis:

• What does the competitor charge? (Free, freemium, subscription, one-time purchase)
• What is the likely cost structure? (Infrastructure, third-party APIs, support staff)
• Where is there margin to undercut or offer more for less?

Technical Debt Indicators:

• What patterns suggest the app was built with older technology?
• What features feel bolted-on rather than native to the architecture?
• What performance or UX issues suggest architectural limitations?
• When was the app last updated? Does it feel actively maintained?

Our Advantages:

• What can we do better with a modern stack?
• What features can we add that the competitor cannot easily add due to their architecture?
• What can we automate that they likely do manually?
• What can we offer for free that they charge for?

Feature Triage for Our Build: For each feature from the MVP Feature Breakdown (section 2), assign one of:

• CLONE: Replicate exactly — this is table stakes.
• IMPROVE: Build this but make it meaningfully better. State how.
• CUT: Do not build this. State why (low value, high cost, or irrelevant).
• ADD: New feature not in the competitor. State the competitive advantage.

This produces the master feature list that drives all subsequent phases.

If building from scratch (no competitor), skip the competitive teardown but still produce the Feature Triage with CLONE replaced by MUST-HAVE.

PHASE 2: ARCHITECTURE & PLANNING

Step 2.1 — Define Project Structure

Create the project structure based on the selected tech stack.

Monorepo layout:

project-name/
  backend/            # Backend application
  frontend/           # Frontend application (or mobile/ for Flutter/RN)
  docs/               # Generated specs and stories
  docker-compose.yml  # Full development environment
  README.md

Apply the stack-specific directory structure from the Stack Conventions section above. For Flutter frontends, follow the /flutter skill structure exactly.

Step 2.2 — Generate Story Backlog

Using the master feature list from Phase 1, generate stories by following the /spec skill instructions.

Generate stories in this order:

1. BE: Project Setup & Configuration (auth, error handling, health check, base setup)
2. BE: Database Schema & Migrations (all models for the MVP)
3. BE: Core feature stories — one story per feature module, ordered by dependency
4. FE: Frontend stories — one per screen/flow, ordered by user journey

For each story, follow /spec format exactly:

• Title with BE: or FE: prefix
• Description (2-4 sentences)
• Acceptance Criteria with categorized bold headers and sub-bullets
• Routes (for BE stories) with full METHOD /path format
• Dev Notes with schema, tables, implementation guidance

Number each story sequentially: STORY-001, STORY-002, etc.

For FE stories, reference the BE story they depend on: "Consumes endpoints from STORY-XXX."

Step 2.3 — Identify Parallel Feature Streams

Analyze the story backlog for parallelization opportunities:

• Group stories into independent feature streams that share no data model dependencies.
• Mark which stories have hard dependencies (must complete before another starts).
• Identify stories that can be implemented in any order.
• Produce a dependency graph showing the critical path and parallel tracks.

This graph will guide Phase 4 implementation order.

PHASE 3: REVIEW

Step 3.1 — Architecture Review of Each Story (PARALLEL)

For each story in the Story Backlog, follow the /arch-review skill instructions in DESIGN REVIEW mode.

Parallelization: Story reviews are independent (read-only analysis of specs). Use the Task tool to review multiple stories concurrently:

• Group stories into batches of 3-4.
• Launch parallel Task tool subagents, each reviewing one story.
• Collect all review results before proceeding.

Since this is a greenfield project, focus on:

• Consistency across stories (naming conventions, patterns, shared types).
• Dependency ordering (does STORY-005 depend on something in STORY-003?).
• Schema completeness (foreign keys, indexes, constraints, naming).
• API consistency (all endpoints follow the same conventions, same response envelope).

If the review produces NEEDS CLARIFICATION or SIGNIFICANT GAPS for any story:

• Fix the story inline (update acceptance criteria, dev notes, or schema).
• Do not stop. Resolve and continue.

Step 3.2 — Consolidated Review Output

After all stories are reviewed, produce:

Story Backlog (Reviewed): List every story title with its verdict: READY TO IMPLEMENT

Dependency Graph: Show which stories must be implemented before which. Mark parallel tracks.

Implementation Order: Numbered list in exact implementation order. Note which can run in parallel.

PHASE 4: IMPLEMENTATION

Step 4.0 — Project Scaffolding

Before implementing any story, scaffold the project:

1. Create the monorepo directory structure from Step 2.1.
2. Initialize the backend with the selected stack:

• Package manifest with all dependencies
• Language/compiler config (tsconfig, pyproject.toml, go.mod, Gemfile, etc.)
• .env.example with all expected variables
• Dockerfile (multi-stage build)
• docker-compose.yml for local dependencies (database, cache, etc.)
• Test configuration
• Entry point with graceful shutdown
• App setup (plugins/middleware/routes/error handler)
• Config files (env, database, auth, logger)
• Shared infrastructure (middleware, utils, types)
• Database schema / models / migrations

1. Initialize the frontend with the selected stack:

• Create the project in the appropriate directory
• Set up the directory structure per stack conventions
• Theme / design token configuration
• Routing setup
• Constants (API base URL, app constants)
• API client configured for the backend
• All standard dependencies in the package manifest

1. If using Firebase:

• Write firestore.rules CO-DEVELOPED with the data models — rules and models

must be written together, not rules-after-the-fact.

• Write storage.rules alongside any file upload service.
• Create firestore.indexes.json for compound queries identified in the stories.

1. Create top-level docker-compose.yml and README.md for the monorepo.
2. Commit: feat: scaffold project structure

Step 4.0.1 — Scaffold Validation Gate

IMMEDIATELY after scaffolding, before implementing any story:

1. Run the stack-appropriate static analysis / type checker:

• TypeScript: tsc --noEmit
• Python: mypy or pyright if configured
• Go: go build ./...
• Flutter: flutter analyze
• React/Vue/Next/Nuxt: tsc --noEmit or framework lint command

1. Run dependency installation to verify everything resolves.
2. Run any auto-fix tools (e.g., dart fix --apply, eslint --fix).
3. If Firebase: cross-check firestore.rules paths against model collection paths.

Fix everything. Commit: chore: scaffold validation fixes

This gate prevents cascading issues in story implementation.

Step 4.1 — Implement Stories by Feature Stream (PARALLEL WHERE POSSIBLE)

Use the dependency graph from Step 2.3 to identify PARALLEL FEATURE STREAMS — groups of stories that share no data model dependencies and can be built concurrently.

Parallelization rules:

• Stories within the SAME feature stream execute sequentially (they depend on each other).
• Stories in DIFFERENT independent streams can execute in parallel via Task tool subagents.
• Foundational stories (project setup, database schema, auth) MUST complete before

any feature stream begins — they are the shared dependency.

• Each parallel subagent works on a distinct set of files (different modules/features).
• After all parallel streams complete, run a merge verification step.

Example: If the dependency graph shows:

Stream A: STORY-003 -> STORY-006 -> STORY-009 (User profiles)
Stream B: STORY-004 -> STORY-007 (Notifications)
Stream C: STORY-005 -> STORY-008 (Search)

Then launch 3 parallel Task tool subagents, one per stream.

For each story (whether parallel or sequential):

a. Follow the /story-implementer skill instructions to implement the story. Since this is a new project, "existing patterns" means the patterns established in Step 4.0 (the scaffold). Every module must follow the layered architecture for the selected stack. b. After implementation, follow the /arch-review skill instructions in IMPLEMENTATION REVIEW mode to validate the code against the story. c. If the review verdict is NEEDS WORK:

• Address every item flagged.
• Re-run the implementation review.
• Repeat until verdict is READY.

d. Commit after each story: feat(STORY-XXX): [description] COMMIT SIZE LIMIT: If a story requires 20+ files, split into logical sub-commits. Never create a single commit that touches 50+ files. e. Proceed to the next story in the stream.

Step 4.1.1 — Parallel Stream Merge Verification

After all parallel feature streams complete:

• Run static analysis / type checking for the full project.
• Run all tests to verify no regressions.
• Fix any issues. Commit: fix: parallel stream merge verification

Step 4.2 — Implement Remaining Sequential Stories

For frontend stories that depend on multiple backend streams (cross-cutting), implement these AFTER all parallel streams complete.

a. Follow the /story-implementer skill instructions combined with the frontend stack conventions. For Flutter, also follow /flutter skill conventions. b. Connect to the backend API endpoints defined in the corresponding BE stories. Use the standard response envelope for parsing. Create typed model classes for every API response. c. If Firebase: update firestore.rules alongside any new collection access. Do NOT defer rule updates to a later phase. d. After implementation, follow the /arch-review skill in IMPLEMENTATION REVIEW mode. e. If the review verdict is NEEDS WORK, fix and re-review until READY. f. Commit after each story: feat(STORY-XXX): [description] Same commit size limit applies.

Step 4.3 — Integration Verification

After all stories are implemented:

• Verify the backend starts without errors.
• Verify database migrations apply cleanly.
• Verify the frontend builds without errors.
• Run all tests (backend and frontend).
• Fix any failures and commit: fix: integration verification

PHASE 5: VALIDATION GATE

This is the critical gate that prevents downstream rework. Run BEFORE QA and UX.

Step 5.1 — Full Static Analysis

Run all linters, type checkers, and static analysis tools for the selected stack. Fix every error and warning.

Step 5.2 — Platform Compatibility Check

For mobile/cross-platform apps:

• Scan for platform-specific code that needs guards.
• Verify platform initialization handles all targets correctly.
• Verify platform-specific features (push notifications, etc.) are guarded.
• Fix all platform issues found.

For web apps:

• Check for SSR/CSR compatibility issues (Next.js/Nuxt).
• Verify environment variable handling (server vs client).

Step 5.3 — Domain Consistency Analysis

Run the /analyze skill instructions scoped to the full project:

• Cross-layer consistency for every feature.
• Database rules / data model alignment.
• State management completeness.
• Navigation / routing integrity.
• Business logic consistency.

Fix all Critical and Warning issues. Re-validate. Commit: fix: validation gate — resolve analysis issues

This gate MUST pass before proceeding to Phase 6.

PHASE 6: PARALLEL VERIFICATION (UX || test-plan)

This phase runs TWO independent tasks in PARALLEL using the Task tool:

PARALLEL TRACK A — UX Verification (/ux): Follow the /ux skill instructions in UX AUDIT mode to:

1. Inventory every screen, theme token, and shared widget/component.
2. Evaluate every screen against Nielsen's 10 usability heuristics.
3. Audit every screen for WCAG 2.1 AA accessibility compliance.
4. Review interaction and motion choreography.
5. Check design system consistency (theme tokens, component patterns, spacing).
6. Fix all issues found.
7. Commit all fixes with descriptive messages.

If design mockups were provided as input, run /ux in DESIGN VALIDATION mode instead, using the mockups to validate the implementation.

PARALLEL TRACK B — Manual Test Plan (/manual-test-plan): Follow the /manual-test-plan skill instructions against the full branch diff. Include the complete story backlog as context so the test plan includes acceptance criteria traceability for every story. This is READ-ONLY — it generates a test plan document but does not modify code.

Why parallel: /ux modifies frontend code. /manual-test-plan only reads the diff to generate a document. No conflicts. Launch both as Task tool subagents.

After both tracks complete, proceed to Phase 7.

PHASE 7: FINAL QA

Follow the /qa skill instructions to:

1. Start the backend and verify every API endpoint works.
2. Walk through every frontend screen and verify functionality, state handling, and design.
3. Fix all issues found — broken endpoints, missing loading/error/empty states,

design violations, and integration mismatches.

1. Commit all fixes with descriptive messages.

This runs AFTER Phase 6 so it can verify the UX fixes did not break anything.

After /qa completes, produce the Build Completion Report below.

PHASE 8: BUILD REPORT

Build Completion Report

## Build Complete

### Project: [name]
### Competitor: [name/URL or "Built from scratch"]
### Branch: build/[project-name]

### What Was Built
- Backend: X stories implemented (list titles)
- Frontend: Y stories implemented (list titles)
- Total files created: N
- Total tests: N

### Tech Stack
- Backend: [selected backend stack + key libraries]
- Frontend: [selected frontend stack + key libraries]
- Database: [selected database]
- Testing: [test framework(s)]
- Infrastructure: Docker + docker-compose

### How to Run
[Stack-specific instructions for starting the app locally]

### What We Improved Over the Competitor
[List from Phase 1 — IMPROVE and ADD items with explanations]
(Or "N/A — built from scratch" if no competitor)

### What We Cut
[List from Phase 1 — CUT items with business rationale]

### Estimated Cost Advantage
[Brief comparison: their likely infrastructure cost vs ours]

### Validation Gate Results
- Static analysis: [clean / N issues fixed]
- Platform compatibility: [clean / N issues fixed]
- Domain consistency: [Critical: N fixed, Warning: N fixed, Info: N reported]

### QA Results
- Backend endpoints passing: X/Y
- Frontend screens rated GOOD or above: X/Y
- Issues fixed during QA: N
- Overall UX rating: [from /qa report]
- UX audit verdict: [from /ux report]
- Accessibility: X/Y screens WCAG 2.1 AA compliant
- Design system consistency: X violations found and fixed

### Remaining Work
[Anything deferred: third-party integrations needing API keys, payment processing, etc.]

STRICT RULES

• Run the entire pipeline without stopping. Do not ask "should I continue?" between phases.
• If a sub-phase produces issues (NEEDS WORK, SIGNIFICANT GAPS), fix them and continue.
• Use the tech stack selected at the start. Do not substitute components mid-build.
• Every backend module MUST follow layered architecture (controller -> service -> repository).

No service should call another service's repository directly.

• Every API endpoint MUST use the standard response envelope.
• Validation schemas MUST validate both request input and generate API documentation.
• Do not generate placeholder implementations. Every file must be production-ready.
• Do not skip tests. Every service must have unit tests.
• Do not add features beyond what was identified in Phase 1. No scope creep.
• If the app requires third-party APIs you cannot access (payments, maps, SMS),

implement the integration layer with a clear interface and mock implementation. Note it in the final report.

• COMMIT DISCIPLINE: Commit after every logical unit of work. A single commit should

not touch more than 50 files. If it would, split into logical sub-commits.

• Use conventional commits: feat:, fix:, docs:, test:, chore:
• FIREBASE RULES: If using Firebase, write rules alongside models, not after.

Every model change that adds/changes collection access must update rules in the same commit.

• VALIDATION GATE (Phase 5) is NOT optional. It must pass before QA and UX phases.

============================================================ SELF-HEALING VALIDATION (max 3 iterations) ============================================================

After completing the main phases, validate your work:

1. Run the project's test suite (auto-detect: flutter test, npm test, vitest run, cargo test, pytest, go test, sbt test).
2. Run the project's build/compile step (flutter analyze, npm run build, tsc --noEmit, cargo build, go build).
3. If either fails, diagnose the failure from error output.
4. Apply a minimal targeted fix — do NOT refactor unrelated code.
5. Re-run the failing validation.
6. Repeat up to 3 iterations total.

IF STILL FAILING after 3 iterations:

• Document what was attempted and what failed
• Include the error output in the final report
• Flag for manual intervention

NEXT STEPS

After the build is complete:

• Run /ux to re-audit UX after manual changes.
• Run /qa again to re-verify after manual changes.
• Run /aws to generate infrastructure for deploying this project.
• Run /manual-test-plan on a specific feature branch for targeted QA.
• To add a new feature, run /spec to create the story, then /story-implementer to implement it.

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /build — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.