60 KiB

Raw Blame History

JavaScript Full-Stack Expansion Pack — User Guide

This guide explains how to effectively use the JavaScript Full-Stack Expansion Pack with the BMad Method for building modern JavaScript/TypeScript applications.

Overview

The JavaScript Full-Stack Expansion Pack provides specialized agents, workflows, and templates for:

Frontend Development: React 18+, Next.js 14, modern state management
Backend Development: Node.js, Express, Fastify, NestJS
API Design: REST, GraphQL, tRPC with versioning and documentation
Type Safety: TypeScript strict mode, advanced patterns, migration
Full-Stack Integration: Coordinated frontend/backend development

The JavaScript Full-Stack Workflow

Planning Phase: Greenfield Projects

For new JavaScript/TypeScript projects, follow this specialized planning workflow:

graph TD
    A["Start: New JS Project"] --> B{Optional: Analyst Research}
    B -->|Yes| C["Analyst: Brainstorming & Research"]
    B -->|No| G{Project Brief Available?}
    C --> C2["Analyst: Competitor Analysis"]
    C2 --> D["Analyst: Create Project Brief"]
    D --> G
    G -->|Yes| E["PM: Create PRD (JS Template)"]
    G -->|No| E2["PM: Interactive PRD Creation"]
    E --> F["PRD with JS-Specific Requirements"]
    E2 --> F

    F --> F2{UX Required?}
    F2 -->|Yes| F3["UX Expert: Create Frontend Spec"]
    F2 -->|No| H["JS Solution Architect: Tech Stack Selection"]
    F3 --> H

    H --> H2["JS Solution Architect: Database Schema Design"]
    H2 --> H3["JS Solution Architect: API Contract Definition"]
    H3 --> H4["JS Solution Architect: System Architecture"]

    H4 --> TS{TypeScript Migration?}
    TS -->|Existing JS Codebase| TS2["TypeScript Expert: Migration Strategy"]
    TS -->|New Project| I
    TS2 --> I["Architect: Complete Architecture Document"]

    I --> Q{Early Test Strategy?}
    Q -->|Yes| R["QA: Risk Assessment + Test Strategy"]
    Q -->|No| V
    R --> V["PO: Master Checklist Validation"]

    V --> J{Documents Aligned?}
    J -->|Yes| K["Planning Complete"]
    J -->|No| L["PO: Update Epics & Stories"]
    L --> M["Update PRD/Architecture"]
    M --> V

    K --> N["📁 Switch to IDE"]
    N --> O["PO: Shard Documents"]
    O --> P["Ready for Development"]

    style A fill:#f5f5f5,color:#000
    style B fill:#e3f2fd,color:#000
    style C fill:#e8f5e9,color:#000
    style C2 fill:#e8f5e9,color:#000
    style D fill:#e8f5e9,color:#000
    style E fill:#fff3e0,color:#000
    style E2 fill:#fff3e0,color:#000
    style F fill:#fff3e0,color:#000
    style F2 fill:#e3f2fd,color:#000
    style F3 fill:#e1f5fe,color:#000
    style G fill:#e3f2fd,color:#000
    style H fill:#f3e5f5,color:#000
    style H2 fill:#f3e5f5,color:#000
    style H3 fill:#f3e5f5,color:#000
    style H4 fill:#f3e5f5,color:#000
    style TS fill:#e3f2fd,color:#000
    style TS2 fill:#f3e5f5,color:#000
    style I fill:#f3e5f5,color:#000
    style Q fill:#e3f2fd,color:#000
    style R fill:#ffd54f,color:#000
    style V fill:#f9ab00,color:#fff
    style J fill:#e3f2fd,color:#000
    style K fill:#34a853,color:#fff
    style L fill:#f9ab00,color:#fff
    style M fill:#fff3e0,color:#000
    style N fill:#1a73e8,color:#fff
    style O fill:#f9ab00,color:#fff
    style P fill:#34a853,color:#fff

Planning Artifacts (JavaScript Projects)

PRD                    → docs/prd.md (uses fullstack-javascript-prd.md template)
Architecture           → docs/architecture.md
Tech Stack Decision    → docs/architecture/tech-stack-decision.md
Database Schema        → docs/architecture/database-schema.md
API Specification      → docs/architecture/api-specification.md
Frontend Architecture  → docs/architecture/frontend-architecture.md
Backend Architecture   → docs/architecture/backend-architecture.md
TypeScript Config      → docs/architecture/typescript-configuration.md
Sharded Epics          → docs/epics/
Sharded Stories        → docs/stories/
QA Assessments         → docs/qa/assessments/
QA Gates               → docs/qa/gates/

Development Phase: Full-Stack Implementation

Once planning is complete, follow this development workflow with JavaScript-specific considerations:

graph TD
    A["Development Phase Start"] --> B["SM: Review Previous Story Notes"]
    B --> B2["SM: Draft Story from Epic + Architecture"]
    B2 --> ST{Story Type?}

    ST -->|Full-Stack Feature| ST1["Include Frontend + Backend + API Tasks"]
    ST -->|Frontend Only| ST2["Include React/Next.js Tasks"]
    ST -->|Backend Only| ST3["Include Node.js/API Tasks"]
    ST -->|TypeScript Migration| ST4["Include Migration Tasks"]

    ST1 --> S
    ST2 --> S
    ST3 --> S
    ST4 --> S

    S{High-Risk Story?}
    S -->|Yes| T["QA: *risk + *design"]
    S -->|No| B3
    T --> U["Test Strategy Created"]
    U --> B3{PO: Validate Story?}

    B3 -->|Yes| B4["PO: Validate Against Architecture"]
    B3 -->|Skip| C
    B4 --> C{User Approval}

    C -->|Approved| D["Dev: Select Appropriate Agent(s)"]
    C -->|Needs Changes| B2

    D --> D2{Implementation Type?}
    D2 -->|Frontend| D3["React Developer: Implement Components"]
    D2 -->|Backend| D4["Node Backend Developer: Implement Services"]
    D2 -->|API| D5["API Developer: Implement Endpoints"]
    D2 -->|Types| D6["TypeScript Expert: Define Types"]
    D2 -->|Full-Stack| D7["Coordinate Multiple Agents"]

    D3 --> E
    D4 --> E
    D5 --> E
    D6 --> E
    D7 --> E

    E["Dev: Implementation + Tests"]
    E --> E2["Frontend: Component Tests + E2E"]
    E2 --> E3["Backend: Unit Tests + Integration Tests"]
    E3 --> E4["API: Contract Tests + Documentation"]
    E4 --> E5["TypeScript: Type Checking"]

    E5 --> V{Mid-Dev QA Check?}
    V -->|Yes| W["QA: *trace or *nfr"]
    V -->|No| F
    W --> X["Dev: Address Gaps"]
    X --> F

    F["Dev: Run All Validations"]
    F --> F2["✓ TypeScript: tsc --noEmit"]
    F2 --> F3["✓ Linting: ESLint"]
    F3 --> F4["✓ Tests: Unit + Integration + E2E"]
    F4 --> F5["✓ Build: Frontend + Backend"]
    F5 --> F6["✓ Checklists: Frontend/Backend/API"]

    F6 --> G["Dev: Mark Ready for Review + Notes"]
    G --> H{User Verification}

    H -->|Request QA Review| I["QA: Full Test Architecture Review"]
    H -->|Approve Without QA| M
    I --> J["QA: Requirements Tracing + Refactoring"]
    J --> L{QA Decision}

    L -->|Needs Dev Work| D
    L -->|Approved| M
    H -->|Needs Fixes| D

    M["CRITICAL: Verify Tests + Linting Pass"]
    M --> M2["CRITICAL: Test on Dev Environment"]
    M2 --> N["CRITICAL: COMMIT CHANGES!"]

    N --> Y{Gate Update?}
    Y -->|Yes| Z["QA: *gate to Update Status"]
    Y -->|No| K
    Z --> K["Mark Story Complete"]
    K --> K2["Update Story Status in Epic"]
    K2 --> B

    style A fill:#f5f5f5,color:#000
    style B fill:#e8f5e9,color:#000
    style B2 fill:#e8f5e9,color:#000
    style ST fill:#e3f2fd,color:#000
    style ST1 fill:#bbdefb,color:#000
    style ST2 fill:#c8e6c9,color:#000
    style ST3 fill:#fff9c4,color:#000
    style ST4 fill:#f8bbd0,color:#000
    style S fill:#e3f2fd,color:#000
    style T fill:#ffd54f,color:#000
    style U fill:#ffd54f,color:#000
    style B3 fill:#e3f2fd,color:#000
    style B4 fill:#fce4ec,color:#000
    style C fill:#e3f2fd,color:#000
    style D fill:#e3f2fd,color:#000
    style D2 fill:#e3f2fd,color:#000
    style D3 fill:#c8e6c9,color:#000
    style D4 fill:#fff9c4,color:#000
    style D5 fill:#ffecb3,color:#000
    style D6 fill:#f8bbd0,color:#000
    style D7 fill:#bbdefb,color:#000
    style E fill:#e3f2fd,color:#000
    style E2 fill:#c8e6c9,color:#000
    style E3 fill:#fff9c4,color:#000
    style E4 fill:#ffecb3,color:#000
    style E5 fill:#f8bbd0,color:#000
    style V fill:#e3f2fd,color:#000
    style W fill:#ffd54f,color:#000
    style X fill:#e3f2fd,color:#000
    style F fill:#e3f2fd,color:#000
    style F2 fill:#e1f5fe,color:#000
    style F3 fill:#e1f5fe,color:#000
    style F4 fill:#e1f5fe,color:#000
    style F5 fill:#e1f5fe,color:#000
    style F6 fill:#e1f5fe,color:#000
    style G fill:#e3f2fd,color:#000
    style H fill:#e3f2fd,color:#000
    style I fill:#f9ab00,color:#fff
    style J fill:#ffd54f,color:#000
    style K fill:#34a853,color:#fff
    style K2 fill:#34a853,color:#fff
    style L fill:#e3f2fd,color:#000
    style M fill:#ff5722,color:#fff
    style M2 fill:#ff5722,color:#fff
    style N fill:#d32f2f,color:#fff
    style Y fill:#e3f2fd,color:#000
    style Z fill:#ffd54f,color:#000

Feature Development Workflow

For adding features to existing JavaScript applications:

graph TD
    A["New Feature Request"] --> B["Analyst: Gather Requirements"]
    B --> C["PM: Document Feature Requirements"]
    C --> D["JS Solution Architect: Assess Impact"]

    D --> D2{Impact Analysis}
    D2 -->|Frontend Changes| D3["Identify Affected Components"]
    D2 -->|Backend Changes| D4["Identify Affected Services"]
    D2 -->|API Changes| D5["API Versioning Strategy"]
    D2 -->|Database Changes| D6["Schema Migration Plan"]

    D3 --> E
    D4 --> E
    D5 --> E
    D6 --> E

    E["Create Technical Specification"]
    E --> E2["Define TypeScript Interfaces"]
    E2 --> E3["Document API Changes"]
    E3 --> E4["Plan Test Strategy"]

    E4 --> F["SM: Create Feature Stories"]
    F --> F2{Story Priority}

    F2 -->|P0: Critical| G["Implement Immediately"]
    F2 -->|P1: Important| H["Schedule in Sprint"]
    F2 -->|P2: Nice-to-Have| I["Backlog"]

    G --> J["Development Cycle"]
    H --> J
    I --> K["End"]

    J --> J2["Frontend: React Developer"]
    J2 --> J3["Backend: Node Backend Developer"]
    J3 --> J4["API: API Developer"]
    J4 --> J5["Types: TypeScript Expert"]

    J5 --> L["Integration Testing"]
    L --> M["Deploy to Staging"]
    M --> N["QA Validation"]
    N --> O{Tests Pass?}

    O -->|Yes| P["Deploy to Production"]
    O -->|No| J

    P --> Q["Monitor Metrics"]
    Q --> K

    style A fill:#f5f5f5,color:#000
    style B fill:#e8f5e9,color:#000
    style C fill:#fff3e0,color:#000
    style D fill:#f3e5f5,color:#000
    style D2 fill:#e3f2fd,color:#000
    style D3 fill:#c8e6c9,color:#000
    style D4 fill:#fff9c4,color:#000
    style D5 fill:#ffecb3,color:#000
    style D6 fill:#f8bbd0,color:#000
    style E fill:#e3f2fd,color:#000
    style E2 fill:#f8bbd0,color:#000
    style E3 fill:#ffecb3,color:#000
    style E4 fill:#ffd54f,color:#000
    style F fill:#e8f5e9,color:#000
    style F2 fill:#e3f2fd,color:#000
    style G fill:#ff5722,color:#fff
    style H fill:#ff9800,color:#fff
    style I fill:#9e9e9e,color:#fff
    style J fill:#e3f2fd,color:#000
    style J2 fill:#c8e6c9,color:#000
    style J3 fill:#fff9c4,color:#000
    style J4 fill:#ffecb3,color:#000
    style J5 fill:#f8bbd0,color:#000
    style L fill:#e3f2fd,color:#000
    style M fill:#bbdefb,color:#000
    style N fill:#ffd54f,color:#000
    style O fill:#e3f2fd,color:#000
    style P fill:#34a853,color:#fff
    style Q fill:#1a73e8,color:#fff
    style K fill:#34a853,color:#fff

TypeScript Migration Workflow

For migrating existing JavaScript codebases to TypeScript:

graph TD
    A["Start: JS Codebase"] --> B["TypeScript Expert: Assess Codebase"]
    B --> B2["Estimate Effort & Complexity"]
    B2 --> C["Create Migration Strategy"]

    C --> D["Phase 1: Setup TypeScript"]
    D --> D2["Configure tsconfig.json (allowJs: true)"]
    D2 --> D3["Install @types packages"]
    D3 --> D4["Add Type Definitions"]

    D4 --> E["Phase 2: Incremental Conversion"]
    E --> E2{File Selection Strategy}

    E2 -->|Bottom-Up| E3["Convert Utilities First"]
    E2 -->|Top-Down| E4["Convert Entry Points First"]
    E2 -->|Risk-Based| E5["Convert Critical Paths First"]

    E3 --> F
    E4 --> F
    E5 --> F

    F["Convert Files in Batches (5-10 files)"]
    F --> F2["Run Tests After Each Batch"]
    F2 --> F3{Tests Pass?}

    F3 -->|Yes| G["Commit Changes"]
    F3 -->|No| F4["Fix Issues"]
    F4 --> F2

    G --> H{More Files?}
    H -->|Yes| F
    H -->|No| I["Phase 3: Enable Strict Mode"]

    I --> I2["Enable noImplicitAny"]
    I2 --> I3["Fix Errors"]
    I3 --> I4["Enable strictNullChecks"]
    I4 --> I5["Fix Errors"]
    I5 --> I6["Enable All Strict Flags"]
    I6 --> I7["Fix Remaining Errors"]

    I7 --> J["Phase 4: Refinement"]
    J --> J2["Replace 'any' with Proper Types"]
    J2 --> J3["Add Generics Where Appropriate"]
    J3 --> J4["Document Complex Types"]

    J4 --> K["Migration Complete"]
    K --> L["Update Documentation"]
    L --> M["Train Team on TypeScript"]
    M --> N["Establish TypeScript Standards"]

    style A fill:#f5f5f5,color:#000
    style B fill:#f8bbd0,color:#000
    style B2 fill:#f8bbd0,color:#000
    style C fill:#f3e5f5,color:#000
    style D fill:#e1f5fe,color:#000
    style D2 fill:#e1f5fe,color:#000
    style D3 fill:#e1f5fe,color:#000
    style D4 fill:#e1f5fe,color:#000
    style E fill:#fff3e0,color:#000
    style E2 fill:#e3f2fd,color:#000
    style E3 fill:#c8e6c9,color:#000
    style E4 fill:#fff9c4,color:#000
    style E5 fill:#ffecb3,color:#000
    style F fill:#e3f2fd,color:#000
    style F2 fill:#ffd54f,color:#000
    style F3 fill:#e3f2fd,color:#000
    style F4 fill:#ff5722,color:#fff
    style G fill:#34a853,color:#fff
    style H fill:#e3f2fd,color:#000
    style I fill:#fff3e0,color:#000
    style I2 fill:#ffecb3,color:#000
    style I3 fill:#e3f2fd,color:#000
    style I4 fill:#ffecb3,color:#000
    style I5 fill:#e3f2fd,color:#000
    style I6 fill:#ffecb3,color:#000
    style I7 fill:#e3f2fd,color:#000
    style J fill:#c8e6c9,color:#000
    style J2 fill:#c8e6c9,color:#000
    style J3 fill:#c8e6c9,color:#000
    style J4 fill:#c8e6c9,color:#000
    style K fill:#34a853,color:#fff
    style L fill:#1a73e8,color:#fff
    style M fill:#1a73e8,color:#fff
    style N fill:#34a853,color:#fff

Specialized Agents

JS Solution Architect

When to Use: Architecture design, tech stack selection, system design

Key Responsibilities:

Technology stack selection (Next.js vs Vite, Express vs NestJS, etc.)
Architecture pattern selection (Monolith, Microservices, JAMstack, Serverless)
Database design (SQL vs NoSQL, schema design)
API contract definition (REST vs GraphQL vs tRPC)
Performance and scalability planning
Security architecture

Example Usage:

@js-solution-architect I need to build a SaaS application with:
- React frontend with real-time updates
- Node.js backend
- PostgreSQL database
- 10,000 expected users
- Multi-tenant architecture

Please recommend the tech stack and create the architecture.

Key Outputs:

docs/architecture/tech-stack-decision.md
docs/architecture/system-architecture.md
docs/architecture/database-schema.md
docs/architecture/api-specification.md

React Developer

When to Use: Frontend implementation, React components, state management

Key Responsibilities:

Component implementation (React 18+, Next.js 14)
State management (React Query, Zustand, Redux)
Routing (file-based or React Router)
Styling (Tailwind CSS, CSS Modules)
Performance optimization (code splitting, lazy loading)
Accessibility (WCAG compliance)

Example Usage:

@react-developer Implement a user dashboard with:
- User profile card
- Activity feed with infinite scroll
- Real-time notifications
- Dark mode support
- Fully responsive
- Accessible (WCAG AA)

Use React Query for data fetching and Tailwind for styling.

Validation Checklist:

Uses checklists/frontend-checklist.md
TypeScript types for all props
Component tests with React Testing Library
Accessibility tests
Performance checks (bundle size, re-renders)

Node Backend Developer

When to Use: Backend services, business logic, database operations

Key Responsibilities:

Express/Fastify/NestJS implementation
Database integration (Prisma, TypeORM)
Authentication & authorization (JWT, OAuth)
Background jobs (Bull, BullMQ)
Caching strategies (Redis)
Error handling and logging

Example Usage:

@node-backend-developer Implement user authentication service:
- Email/password registration
- JWT access tokens (15 min expiry)
- Refresh token strategy
- Password reset flow
- Rate limiting (5 attempts per 15 min)
- Bcrypt password hashing

Use Express with Prisma and PostgreSQL.

Validation Checklist:

Uses checklists/backend-checklist.md
Input validation (Zod schemas)
Unit tests for business logic
Integration tests for API endpoints
Security checks (SQL injection, XSS prevention)

API Developer

When to Use: API design, endpoint implementation, documentation

Key Responsibilities:

RESTful API design (resource-based URLs, proper HTTP methods)
GraphQL schema and resolvers
tRPC for type-safe APIs
API versioning strategies
Rate limiting and throttling
OpenAPI/Swagger documentation

Example Usage:

@api-developer Design the REST API for a blog platform:
- User management (CRUD)
- Post management (with drafts, publishing)
- Comments (nested, moderation)
- Tags and categories
- Search functionality
- Pagination (cursor-based)

Include OpenAPI specification and example requests.

Validation Checklist:

Uses checklists/api-design-checklist.md
RESTful conventions followed
Proper HTTP status codes
Pagination implemented
Rate limiting configured
API documentation complete

TypeScript Expert

When to Use: Type definitions, advanced patterns, migration

Key Responsibilities:

TypeScript configuration (strict mode)
Advanced type patterns (generics, mapped types, conditional types)
Type inference and narrowing
JavaScript to TypeScript migration
Shared types between frontend/backend
Type-safe API client design

Example Usage:

@typescript-expert Create type-safe API client:
- Define all request/response types
- Implement generic fetch wrapper
- Type-safe query parameters
- Discriminated unions for API responses
- Error types with proper narrowing

No 'any' types allowed, full type safety end-to-end.

Validation:

tsc --noEmit passes with no errors
No any types (use unknown if needed)
Proper type guards for runtime checks
Comprehensive interfaces for all DTOs

Agent Teams

Full-Stack Team

Use When: Building complete applications from scratch

Team Composition:

Analyst (core BMAD)
BMad-Orchestrator (core BMAD)
JS Solution Architect
React Developer
Node Backend Developer
API Developer
TypeScript Expert

Workflows:

fullstack-greenfield.yaml
feature-development.yaml
mvp-rapid-prototype.yaml

Frontend Team

Use When: Frontend-only or frontend-heavy projects

Team Composition:

Analyst (core BMAD)
BMad-Orchestrator (core BMAD)
JS Solution Architect
React Developer
TypeScript Expert

Workflows:

frontend-app-development.yaml
feature-development.yaml

Backend Team

Use When: API services, backend systems, microservices

Team Composition:

Analyst (core BMAD)
BMad-Orchestrator (core BMAD)
JS Solution Architect
Node Backend Developer
API Developer
TypeScript Expert

Workflows:

backend-api-development.yaml
feature-development.yaml

Quality Checklists

The expansion pack includes comprehensive quality checklists for each phase:

Architecture Phase

architecture-review-checklist.md: Validates architecture completeness
- Frontend architecture (framework, state, routing, styling)
- Backend architecture (framework, API, auth, middleware)
- Database design (schema, indexes, migrations)
- API design (versioning, pagination, rate limiting)
- Non-functional requirements (performance, security, scalability)

Development Phase

frontend-checklist.md: React/Next.js code quality
- Component structure and TypeScript types
- React best practices (hooks, memoization, error boundaries)
- State management
- Performance (code splitting, bundle size, Core Web Vitals)
- Accessibility (WCAG compliance)
backend-checklist.md: Node.js backend quality
- API endpoint quality (RESTful design, status codes)
- Authentication & authorization
- Database operations (ORM usage, transactions, indexes)
- Error handling
- Security (Helmet.js, input validation, rate limiting)
api-design-checklist.md: API quality standards
- REST API design (resource naming, HTTP methods)
- Request/response format
- Authentication strategy
- Error handling
- Documentation (OpenAPI/Swagger)
security-checklist.md: Security validation
- Authentication (password hashing, token management)
- Authorization (RBAC, resource-level permissions)
- Input validation (frontend and backend)
- SQL injection prevention
- XSS and CSRF protection
- OWASP Top 10 coverage
performance-checklist.md: Performance optimization
- Frontend performance (Core Web Vitals, bundle size)
- Backend performance (API response time, database queries)
- Caching strategy
- Network optimization (CDN, compression, HTTP/2)

Deployment Phase

deployment-readiness-checklist.md: Production readiness
- Code quality (tests pass, no TypeScript errors)
- Environment configuration
- Database migrations tested
- Security headers configured
- Performance targets met
- Monitoring and logging configured
story-dod-checklist.md: Definition of Done
- Requirements met
- Code quality (TypeScript, linting)
- Testing (unit, integration, E2E)
- Frontend-specific (responsive, accessible)
- Backend-specific (validation, error handling)
- Security and documentation

Task Guides

Detailed step-by-step guides for common tasks:

`create-development-story.md`

Story identification and scoping
Using the JavaScript story template
Full-stack coordination (frontend + backend + API)
TypeScript interface definitions
Testing requirements
Validation process

`create-architecture-doc.md`

Architecture document structure
Technology stack selection
Database schema design
API contract definition
Non-functional requirements
Development standards

`create-api-spec.md`

API specification structure
Endpoint documentation template
TypeScript DTO definitions
OpenAPI/Swagger generation
Best practices

`setup-project.md`

Monorepo setup (Turborepo)
TypeScript configuration
Linting and formatting (ESLint, Prettier)
Database setup (Prisma)
Testing frameworks (Vitest, Jest, Playwright)
CI/CD pipeline

`code-review.md`

Code review checklist
TypeScript quality checks
React best practices
Backend security checks
Performance considerations
Git hygiene

`performance-optimization.md`

Performance measurement
Frontend optimization (bundle, images, caching)
Backend optimization (database, Redis, background jobs)
Network optimization
Monitoring setup

Reference Materials

`development-guidelines.md`

TypeScript standards (strict mode, naming conventions)
React best practices (hooks, memoization)
Backend patterns (error handling, validation)
Code organization
Testing standards

`architecture-patterns.md`

Monolithic Full-Stack
JAMstack with Serverless
Microservices
Backend for Frontend (BFF)
Event-Driven Architecture
Decision matrix and migration paths

`best-practices.md`

General principles
Frontend best practices
Backend best practices
Testing strategy
DevOps and deployment
Common anti-patterns to avoid

`technology-stack-guide.md`

Decision framework
Recommended stacks by use case (MVP, SaaS, E-commerce, etc.)
Technology comparison tables
Decision trees for framework/database selection

`security-guidelines.md`

Authentication (password hashing, JWT)
Input validation (Zod schemas)
SQL injection prevention
XSS and CSRF protection
CORS configuration
Rate limiting
Secrets management
OWASP Top 10 checklist

`deployment-strategies.md`

Deployment patterns (Rolling, Blue-Green, Canary)
Platform-specific deployment (Vercel, Railway, AWS)
CI/CD setup (GitHub Actions)
Database migrations
Environment management
Rollback strategies
Health checks and monitoring

Best Practices

Planning Phase

Start with Tech Stack Selection: Let JS Solution Architect evaluate options
Define API Contracts Early: Enables parallel frontend/backend development
Consider TypeScript from Day One: Easier than migration later
Plan for Testing: Include test strategy in architecture
Document NFRs: Performance, security, scalability requirements

Development Phase

Use Appropriate Agent: Match agent to task (React Dev for components, API Dev for endpoints)
Coordinate Full-Stack Features: Define TypeScript interfaces shared between frontend/backend
Test at Multiple Levels: Unit tests (logic), integration tests (APIs), E2E tests (user flows)
Run Checklists: Use quality checklists before marking stories complete
Commit Often: Save work after each story completion

Code Quality

TypeScript Strict Mode: Enable all strict flags
No any Types: Use proper types or unknown
Lint and Format: ESLint + Prettier configured
Test Coverage: >80% for frontend, >85% for backend
Security First: Validate all inputs, sanitize outputs

Performance

Monitor Metrics: Track Core Web Vitals, API response times
Optimize Bundle Size: Code splitting, lazy loading
Database Indexes: Add indexes on frequently queried fields
Caching Strategy: Use Redis for frequently accessed data
CDN for Static Assets: Serve assets from edge locations

Deployment

CI/CD Pipeline: Automate tests and deployment
Environment Variables: Never commit secrets
Database Migrations: Test on staging first
Health Checks: Implement /health endpoint
Monitor Post-Deployment: Watch for 24 hours after launch

Common Workflows

MVP Rapid Prototype Workflow

For time-constrained projects (1-2 weeks), use the streamlined MVP workflow:

graph TD
    A["Start: MVP Concept"] --> B["Day 1: Planning (4 hours)"]
    B --> B2["Analyst: Quick Requirements (1 hour)"]
    B2 --> B3["PM: Lean PRD (1 hour)"]
    B3 --> B4["JS Architect: Minimal Architecture (2 hours)"]

    B4 --> C["Day 2-3: Setup + Core Features"]
    C --> C2["Dev: Project Setup (2 hours)"]
    C2 --> C3["Node Dev: Auth + DB (4 hours)"]
    C3 --> C4["React Dev: Core UI (6 hours)"]
    C4 --> C5["API Dev: Basic Endpoints (4 hours)"]

    C5 --> D["Day 4-5: Features + Integration"]
    D --> D2["React Dev: Feature Components (8 hours)"]
    D2 --> D3["Node Dev: Business Logic (6 hours)"]
    D3 --> D4["Integration + Basic Tests (2 hours)"]

    D4 --> E["Day 6-7: Polish + Deploy"]
    E --> E2["Dev: Bug Fixes (4 hours)"]
    E2 --> E3["Dev: Essential Tests (2 hours)"]
    E3 --> E4["Dev: Deploy to Staging (1 hour)"]
    E4 --> E5["QA: Quick Validation (2 hours)"]
    E5 --> E6["Dev: Deploy to Production (1 hour)"]

    E6 --> F["MVP Complete"]

    style A fill:#f5f5f5,color:#000
    style B fill:#fff3e0,color:#000
    style B2 fill:#e8f5e9,color:#000
    style B3 fill:#fff3e0,color:#000
    style B4 fill:#f3e5f5,color:#000
    style C fill:#e3f2fd,color:#000
    style C2 fill:#e1f5fe,color:#000
    style C3 fill:#fff9c4,color:#000
    style C4 fill:#c8e6c9,color:#000
    style C5 fill:#ffecb3,color:#000
    style D fill:#e3f2fd,color:#000
    style D2 fill:#c8e6c9,color:#000
    style D3 fill:#fff9c4,color:#000
    style D4 fill:#ffd54f,color:#000
    style E fill:#e3f2fd,color:#000
    style E2 fill:#e3f2fd,color:#000
    style E3 fill:#ffd54f,color:#000
    style E4 fill:#bbdefb,color:#000
    style E5 fill:#ffd54f,color:#000
    style E6 fill:#34a853,color:#fff
    style F fill:#34a853,color:#fff

Key MVP Principles:

Time-boxing: Strict 2-hour max per planning phase
Minimal Documentation: PRD + lean architecture only
Essential Features Only: Core user flow, no nice-to-haves
Basic Testing: Critical paths only
Fast Deployment: Vercel/Railway for instant deploy

Step-by-Step MVP Commands (For Beginners)

Here's exactly what to type and run for a simple MVP project. Example: Building a basic Todo App MVP

Day 1: Planning (Morning - 4 hours)

Step 1: Define Your Idea (1 hour)

# In Web UI, prompt the Analyst:
@analyst I want to build a simple Todo app MVP with:
- User can add, edit, delete todos
- Mark todos as complete
- Simple login (email/password)
- Mobile responsive
- Deploy in 1 week

Please create a brief project outline.

Step 2: Create PRD (1 hour)

# After analyst completes, prompt PM:
@pm Create a minimal PRD for this Todo app MVP focusing on:
- Core features only (add, edit, delete, complete todos)
- User authentication
- Simple UI
- 1-week timeline

Step 3: Architecture Design (2 hours)

# Switch to IDE, prompt JS Solution Architect:
@js-solution-architect Design minimal architecture for Todo MVP:
- Frontend: Next.js with App Router
- Backend: Next.js API routes
- Database: PostgreSQL with Prisma
- Auth: NextAuth.js
- Deployment: Vercel

Create tech stack document and simple database schema.

Day 2: Project Setup (Morning - 2 hours)

Step 1: Initialize Project

# In your terminal, create the project:
npx create-next-app@latest todo-mvp --typescript --tailwind --app

# Navigate into project:
cd todo-mvp

# Install dependencies:
npm install prisma @prisma/client next-auth bcryptjs
npm install -D @types/bcryptjs

Step 2: Setup Database

# Initialize Prisma:
npx prisma init

# In IDE, prompt:
@typescript-expert Create Prisma schema for Todo app with:
- User model (id, email, password, name)
- Todo model (id, title, completed, userId, createdAt)

Update prisma/schema.prisma file.

# After schema is created, run migration:
npx prisma migrate dev --name init
npx prisma generate

Step 3: Configure Environment

# Create .env.local file:
@dev Create .env.local with:
- DATABASE_URL
- NEXTAUTH_SECRET
- NEXTAUTH_URL

Generate secure secret with: openssl rand -base64 32

Day 2-3: Authentication (Afternoon - 4 hours)

Step 1: Setup NextAuth

# In IDE, prompt:
@node-backend-developer Setup NextAuth.js with:
- Credentials provider (email/password)
- JWT strategy
- Bcrypt password hashing
- Session handling

Create app/api/auth/[...nextauth]/route.ts

Step 2: Create Auth API

# Prompt API Developer:
@api-developer Create registration endpoint at /api/auth/register:
- Validate email and password
- Hash password with bcrypt
- Create user in database
- Return success/error

Step 3: Create Login UI

# Prompt React Developer:
@react-developer Create authentication pages:
- app/login/page.tsx (email/password form)
- app/register/page.tsx (registration form)
- Use Tailwind CSS
- Form validation
- Loading states

Day 3: Todo Backend (Afternoon - 4 hours)

Step 1: Create Todo API Endpoints

# Prompt API Developer:
@api-developer Create Todo CRUD API endpoints:
- GET /api/todos (list all user todos)
- POST /api/todos (create todo)
- PATCH /api/todos/[id] (update todo)
- DELETE /api/todos/[id] (delete todo)

All endpoints require authentication.

Step 2: Test API Endpoints

# In terminal, test with curl or use Postman:
# (After implementing endpoints)

# Login to get session
curl -X POST http://localhost:3000/api/auth/callback/credentials \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password123"}'

# Test creating a todo
curl -X POST http://localhost:3000/api/todos \
  -H "Content-Type: application/json" \
  -d '{"title":"Test Todo"}'

Day 3-4: Todo Frontend (Evening/Morning - 6 hours)

Step 1: Create Todo Components

# Prompt React Developer:
@react-developer Create Todo UI components:
- TodoList component (displays all todos)
- TodoItem component (single todo with edit/delete)
- AddTodoForm component (input + add button)
- Use Tailwind CSS for styling
- Mobile responsive

Step 2: Add State Management

# Prompt React Developer:
@react-developer Add state management:
- Use React hooks (useState, useEffect)
- Fetch todos on page load
- Optimistic UI updates
- Error handling

Step 3: Create Main Todo Page

# Prompt React Developer:
@react-developer Create main todo page at app/dashboard/page.tsx:
- Protected route (requires login)
- Display TodoList component
- Add AddTodoForm at top
- Logout button

Day 4-5: Polish & Features (8 hours)

Step 1: Add Todo Completion

# Prompt:
@react-developer Add toggle completion feature:
- Click checkbox to mark todo complete
- Strikethrough completed todos
- Update database via PATCH /api/todos/[id]

Step 2: Add Edit Functionality

# Prompt:
@react-developer Add inline edit for todos:
- Double-click to edit
- Save on Enter or blur
- Cancel on Escape

Step 3: Improve UI/UX

# Prompt:
@react-developer Polish the UI:
- Add loading spinners
- Empty state (no todos message)
- Success/error toasts
- Smooth animations
- Better mobile layout

Day 5: Testing (Afternoon - 2 hours)

Step 1: Manual Testing Checklist

# Test in browser:
□ Register new user
□ Login with credentials
□ Add 5 different todos
□ Mark 2 todos as complete
□ Edit a todo title
□ Delete a todo
□ Logout and login again
□ Verify todos persist
□ Test on mobile screen size

Step 2: Fix Critical Bugs

# If you find bugs, prompt:
@dev Fix bug: [describe the issue]

# Example:
@dev Fix bug: Todos not persisting after refresh.
Check if API is returning correct user todos.

Day 6: Deployment (Morning - 1 hour)

Step 1: Prepare for Deployment

# In terminal, verify build works:
npm run build

# Check for TypeScript errors:
npx tsc --noEmit

# Run Prisma generate:
npx prisma generate

Step 2: Setup Database (Production)

# Option A: Vercel Postgres
# - Go to vercel.com
# - Create new Postgres database
# - Copy DATABASE_URL

# Option B: Supabase
# - Go to supabase.com
# - Create project
# - Copy connection string

Step 3: Deploy to Vercel

# Install Vercel CLI:
npm i -g vercel

# Login to Vercel:
vercel login

# Deploy:
vercel

# Follow prompts:
# - Link to project: Yes
# - Project name: todo-mvp
# - Framework: Next.js

# Set environment variables in Vercel dashboard:
# - DATABASE_URL
# - NEXTAUTH_SECRET
# - NEXTAUTH_URL (https://your-app.vercel.app)

# Run migration on production database:
npx prisma migrate deploy

Day 6: Staging Validation (Afternoon - 2 hours)

Step 1: Test Production App

# Open your deployed URL: https://todo-mvp.vercel.app

# Test complete flow:
□ Register new user
□ Login
□ Add todos
□ Edit todos
□ Complete todos
□ Delete todos
□ Logout/Login
□ Test on mobile device

Step 2: Monitor for Issues

# Check Vercel logs:
# - Go to Vercel dashboard
# - Click on your project
# - Go to "Logs" tab
# - Watch for errors

# Check database connections:
# - Verify todos are saving to production DB

Day 7: Final Polish & Launch (2 hours)

Step 1: Add Final Touches

# Prompt:
@react-developer Add finishing touches:
- Update page title and meta tags
- Add favicon
- Improve loading states
- Add basic error boundaries

Step 2: Production Deploy

# In terminal, commit all changes:
git add .
git commit -m "feat: MVP complete - todo app with auth"
git push origin main

# Vercel auto-deploys from main branch
# Wait for deployment to complete

# Visit production URL and verify everything works

Step 3: Share Your MVP!

# Your MVP is live! 🎉
# Share the URL: https://todo-mvp.vercel.app

# Next steps (post-MVP):
# - Gather user feedback
# - Monitor usage
# - Plan v2 features

Complete Command Reference (Copy-Paste Ready)

Here's a complete script you can follow:

# === DAY 1: SETUP ===
npx create-next-app@latest todo-mvp --typescript --tailwind --app
cd todo-mvp
npm install prisma @prisma/client next-auth bcryptjs zod
npm install -D @types/bcryptjs
npx prisma init

# === DAY 2: DATABASE ===
# (After updating schema.prisma)
npx prisma migrate dev --name init
npx prisma generate

# === DAY 3-5: DEVELOPMENT ===
# Use IDE agents to build features
# Test locally:
npm run dev
# Open: http://localhost:3000

# === DAY 6: TESTING ===
npm run build
npx tsc --noEmit
npm test # if you added tests

# === DAY 7: DEPLOY ===
vercel login
vercel --prod
npx prisma migrate deploy

# === DONE! ===

What You'll Have After 7 Days

✅ Working Todo App with authentication ✅ Live URL (e.g., todo-mvp.vercel.app) ✅ User registration & login ✅ Full CRUD for todos ✅ Mobile responsive design ✅ Production database ✅ Deployed & running

Total Lines of Code: ~800-1000 lines Total Time: 35-40 hours (1 week) Cost: $0 (free tier Vercel + Supabase)

Complete Full-Stack Feature Workflow

Detailed step-by-step workflow for implementing a full-stack feature:

graph TD
    A["Feature Request"] --> B["Step 1: Requirements"]
    B --> B2["Analyst: Interview Stakeholders"]
    B2 --> B3["Analyst: Document User Stories"]
    B3 --> B4["PM: Add to PRD"]

    B4 --> C["Step 2: Technical Planning"]
    C --> C2["JS Architect: Impact Analysis"]
    C2 --> C3{Requires New Architecture?}
    C3 -->|Yes| C4["JS Architect: Design New Components"]
    C3 -->|No| D
    C4 --> D

    D["Step 3: Type Definitions"]
    D --> D2["TypeScript Expert: Define DTOs"]
    D2 --> D3["TypeScript Expert: Frontend Types"]
    D3 --> D4["TypeScript Expert: Backend Types"]
    D4 --> D5["TypeScript Expert: API Types"]

    D5 --> E["Step 4: API Contract"]
    E --> E2["API Dev: Define Endpoints"]
    E2 --> E3["API Dev: Document Request/Response"]
    E3 --> E4["API Dev: Create OpenAPI Spec"]

    E4 --> F["Step 5: Database Changes"]
    F --> F2{Schema Changes?}
    F2 -->|Yes| F3["Node Dev: Create Migration"]
    F2 -->|No| G
    F3 --> F4["Node Dev: Test Migration"]
    F4 --> G

    G["Step 6: Backend Implementation"]
    G --> G2["Node Dev: Service Layer"]
    G2 --> G3["Node Dev: Unit Tests"]
    G3 --> G4["API Dev: Endpoint Implementation"]
    G4 --> G5["API Dev: Integration Tests"]

    G5 --> H["Step 7: Frontend Implementation"]
    H --> H2["React Dev: Component Structure"]
    H2 --> H3["React Dev: State Management"]
    H3 --> H4["React Dev: API Integration"]
    H4 --> H5["React Dev: Component Tests"]

    H5 --> I["Step 8: Integration"]
    I --> I2["Dev: E2E Tests"]
    I2 --> I3["Dev: Manual Testing"]
    I3 --> I4{Issues Found?}
    I4 -->|Yes| I5["Dev: Fix Issues"]
    I4 -->|No| J
    I5 --> I2

    J["Step 9: Quality Validation"]
    J --> J2["Dev: Frontend Checklist"]
    J2 --> J3["Dev: Backend Checklist"]
    J3 --> J4["Dev: API Checklist"]
    J4 --> J5["Dev: Security Checklist"]

    J5 --> K["Step 10: Review"]
    K --> K2["QA: Test Architecture Review"]
    K2 --> K3{QA Approval?}
    K3 -->|Yes| L
    K3 -->|No| M["Dev: Address Feedback"]
    M --> I2

    L["Step 11: Deployment"]
    L --> L2["Dev: Deploy to Staging"]
    L2 --> L3["QA: Staging Validation"]
    L3 --> L4{Ready for Prod?}
    L4 -->|Yes| L5["Dev: Production Deploy"]
    L4 -->|No| M

    L5 --> N["Step 12: Monitoring"]
    N --> N2["Dev: Watch Error Logs"]
    N2 --> N3["Dev: Monitor Performance"]
    N3 --> N4["Dev: Track User Metrics"]

    N4 --> O["Feature Complete"]

    style A fill:#f5f5f5,color:#000
    style B fill:#e8f5e9,color:#000
    style C fill:#f3e5f5,color:#000
    style D fill:#f8bbd0,color:#000
    style E fill:#ffecb3,color:#000
    style F fill:#fff9c4,color:#000
    style G fill:#fff9c4,color:#000
    style H fill:#c8e6c9,color:#000
    style I fill:#e3f2fd,color:#000
    style J fill:#ffd54f,color:#000
    style K fill:#f9ab00,color:#fff
    style L fill:#bbdefb,color:#000
    style M fill:#ff5722,color:#fff
    style N fill:#1a73e8,color:#fff
    style O fill:#34a853,color:#fff

Technology Stack Selection Workflow

Decision tree for choosing the right technology stack:

graph TD
    A["New Project"] --> B{Project Type?}

    B -->|Web App| C{Frontend Complexity?}
    B -->|API Service| D{API Type?}
    B -->|Mobile App| E["React Native + Backend"]

    C -->|Simple| C2["Next.js (App Router)"]
    C -->|Complex| C3["React + Vite"]

    C2 --> F{Backend Needs?}
    C3 --> F

    F -->|None| F2["Next.js API Routes"]
    F -->|Simple| F3["Express"]
    F -->|Complex| F4["NestJS"]

    D -->|REST| D2["Express + OpenAPI"]
    D -->|GraphQL| D3["Apollo Server"]
    D -->|Type-Safe| D4["tRPC"]

    F2 --> G{Database?}
    F3 --> G
    F4 --> G
    D2 --> G
    D3 --> G
    D4 --> G
    E --> G

    G -->|Relational| G2["PostgreSQL + Prisma"]
    G -->|Document| G3["MongoDB + Mongoose"]
    G -->|Key-Value| G4["Redis"]

    G2 --> H{State Management?}
    G3 --> H
    G4 --> H

    H -->|Server State| H2["React Query"]
    H -->|Client State| H3{Complexity?}

    H3 -->|Simple| H4["Zustand"]
    H3 -->|Complex| H5["Redux Toolkit"]

    H2 --> I{Authentication?}
    H4 --> I
    H5 --> I

    I -->|Simple| I2["NextAuth.js"]
    I -->|Custom| I3["JWT + Refresh Tokens"]
    I -->|Enterprise| I4["Auth0/Clerk"]

    I2 --> J["Tech Stack Complete"]
    I3 --> J
    I4 --> J

    style A fill:#f5f5f5,color:#000
    style B fill:#e3f2fd,color:#000
    style C fill:#e3f2fd,color:#000
    style C2 fill:#c8e6c9,color:#000
    style C3 fill:#c8e6c9,color:#000
    style D fill:#e3f2fd,color:#000
    style D2 fill:#ffecb3,color:#000
    style D3 fill:#ffecb3,color:#000
    style D4 fill:#ffecb3,color:#000
    style E fill:#f8bbd0,color:#000
    style F fill:#e3f2fd,color:#000
    style F2 fill:#fff9c4,color:#000
    style F3 fill:#fff9c4,color:#000
    style F4 fill:#fff9c4,color:#000
    style G fill:#e3f2fd,color:#000
    style G2 fill:#e1f5fe,color:#000
    style G3 fill:#e1f5fe,color:#000
    style G4 fill:#e1f5fe,color:#000
    style H fill:#e3f2fd,color:#000
    style H2 fill:#f3e5f5,color:#000
    style H3 fill:#e3f2fd,color:#000
    style H4 fill:#f3e5f5,color:#000
    style H5 fill:#f3e5f5,color:#000
    style I fill:#e3f2fd,color:#000
    style I2 fill:#fff3e0,color:#000
    style I3 fill:#fff3e0,color:#000
    style I4 fill:#fff3e0,color:#000
    style J fill:#34a853,color:#fff

Detailed Example Workflows

Example 1: Building a SaaS Application (12-Week Timeline)

Project: Task management SaaS with teams, projects, and real-time collaboration

Week 1-2: Planning & Architecture

Day 1-2: Requirements Gathering

# Web UI
@analyst Create project brief for team task management SaaS
# Output: docs/project-brief.md

@analyst Research competitors (Asana, Linear, Monday.com)
# Output: docs/research/competitor-analysis.md

@pm Create comprehensive PRD from project brief
# Output: docs/prd.md

Day 3-5: Technical Architecture

# Web UI
@js-solution-architect Design architecture for:
- 5,000 teams (50,000 users)
- Real-time collaboration
- Multi-tenant database
- PostgreSQL + Redis
- Next.js 14 + NestJS backend

# Outputs:
# - docs/architecture/tech-stack-decision.md
# - docs/architecture/system-architecture.md
# - docs/architecture/database-schema.md
# - docs/architecture/api-specification.md

@typescript-expert Define core TypeScript types
# Output: docs/architecture/typescript-types.md

Day 6-7: Validation & Planning

@po Run master checklist validation
@po Shard documents into epics and stories
# Output: docs/epics/ and docs/stories/

Week 3-4: Project Setup & Authentication

Day 8: Project Initialization

# IDE
@dev Initialize monorepo with Turborepo
# Creates: apps/web, apps/api, packages/shared-types

@typescript-expert Configure strict TypeScript
# Creates: tsconfig.json, tsconfig.base.json

@dev Setup Prisma with PostgreSQL
# Creates: packages/database/

Day 9-11: Authentication System

# IDE
@sm Draft authentication story
# Output: docs/stories/auth-001-user-authentication.md

@typescript-expert Define auth types
# Creates: packages/shared-types/src/auth.ts

@node-backend-developer Implement JWT authentication
# Creates:
# - apps/api/src/auth/auth.service.ts
# - apps/api/src/auth/auth.controller.ts
# - apps/api/src/auth/strategies/jwt.strategy.ts

@api-developer Document auth endpoints
# Updates: docs/architecture/api-specification.md

@react-developer Create login/register components
# Creates:
# - apps/web/src/components/auth/LoginForm.tsx
# - apps/web/src/components/auth/RegisterForm.tsx

@dev Run frontend and backend checklists
@dev Commit: "feat: implement user authentication system"

Day 12-14: Team Management

@sm Draft team management story
@node-backend-developer Implement team CRUD
@react-developer Create team UI
@dev Run integration tests
@dev Commit: "feat: add team management"

Week 5-6: Core Task Management

Day 15-18: Task CRUD

@sm Draft task management story

@node-backend-developer Implement task service:
- Create, read, update, delete tasks
- Task assignments
- Due dates and priorities
- Task comments

@api-developer Create REST endpoints:
- POST /api/tasks
- GET /api/tasks/:id
- PATCH /api/tasks/:id
- DELETE /api/tasks/:id
- POST /api/tasks/:id/comments

@react-developer Implement task components:
- TaskList component
- TaskCard component
- TaskForm component
- TaskDetail component

@dev Run all tests
@dev Commit: "feat: implement core task management"

Day 19-21: Project Organization

@sm Draft project organization story
@node-backend-developer Implement projects and boards
@react-developer Create project views
@dev Integration tests
@dev Commit: "feat: add project organization"

Week 7-8: Real-Time Features

Day 22-25: WebSocket Integration

@js-solution-architect Design real-time architecture
# Updates: docs/architecture/realtime-architecture.md

@node-backend-developer Implement Socket.io server:
- WebSocket connection handling
- Room management (team/project rooms)
- Event broadcasting

@react-developer Implement WebSocket client:
- Connection management
- Event listeners
- Real-time UI updates

@dev Test real-time collaboration
@dev Commit: "feat: add real-time collaboration"

Day 26-28: Live Updates

@react-developer Implement real-time features:
- Live task updates
- Online user presence
- Typing indicators
- Instant notifications

@dev Performance testing
@dev Commit: "feat: implement live updates"

Week 9-10: Advanced Features

Day 29-32: File Uploads

@js-solution-architect Design file storage strategy (S3)
@node-backend-developer Implement file upload service
@react-developer Create file upload UI
@dev Test file uploads
@dev Commit: "feat: add file attachments"

Day 33-35: Search & Filters

@node-backend-developer Implement full-text search
@react-developer Create advanced filters UI
@dev Test search performance
@dev Commit: "feat: implement search and filters"

Week 11: Testing & Optimization

Day 36-38: Comprehensive Testing

@qa Create comprehensive test plan
@dev Write E2E tests with Playwright
@dev Performance testing
@dev Fix identified issues

Day 39-42: Performance Optimization

@react-developer Optimize bundle size:
- Code splitting
- Lazy loading
- Tree shaking

@node-backend-developer Optimize database:
- Add indexes
- Query optimization
- Redis caching

@dev Monitor Core Web Vitals
@dev Commit: "perf: optimize application performance"

Week 12: Deployment & Launch

Day 43-45: Deployment Setup

@dev Setup CI/CD with GitHub Actions
@dev Configure Vercel for frontend
@dev Configure Railway for backend
@dev Setup monitoring (Sentry, LogRocket)

Day 46-47: Staging Testing

@qa Full staging validation
@dev Fix staging issues
@dev Run deployment readiness checklist

Day 48: Production Launch

@dev Deploy to production
@dev Monitor for 24 hours
@dev Track error rates and performance

Example 2: Adding Real-Time Notifications Feature (4-Day Implementation)

Context: Existing SaaS application needs real-time notification system

Day 1: Planning & Architecture

Morning: Requirements

# Web UI
@analyst Document notification requirements:
- Task assignments
- Comments and mentions
- Project updates
- Team invitations

# Output: docs/features/notifications-requirements.md

@js-solution-architect Assess technical impact:
- WebSocket vs Server-Sent Events
- Database schema changes
- Caching strategy
- Performance impact

# Output: docs/features/notifications-architecture.md

Afternoon: Type Definitions & API Design

# IDE
@typescript-expert Define notification types
# Creates: packages/shared-types/src/notifications.ts

// packages/shared-types/src/notifications.ts
export enum NotificationType {
  TASK_ASSIGNED = 'TASK_ASSIGNED',
  TASK_COMMENT = 'TASK_COMMENT',
  MENTION = 'MENTION',
  PROJECT_UPDATE = 'PROJECT_UPDATE',
  TEAM_INVITATION = 'TEAM_INVITATION',
}

export interface Notification {
  id: string;
  userId: string;
  type: NotificationType;
  title: string;
  message: string;
  data: Record<string, any>;
  read: boolean;
  createdAt: Date;
}

export interface NotificationPreferences {
  emailNotifications: boolean;
  pushNotifications: boolean;
  notificationTypes: NotificationType[];
}

@api-developer Define notification endpoints
# Updates: docs/architecture/api-specification.md

Day 2: Backend Implementation

Morning: Database & Service Layer

# IDE
@node-backend-developer Create Prisma migration

# packages/database/prisma/migrations/
npx prisma migrate dev --name add_notifications

@node-backend-developer Implement notification service
# Creates:
# - apps/api/src/notifications/notification.service.ts
# - apps/api/src/notifications/notification.controller.ts
# - apps/api/src/notifications/notification.gateway.ts

Afternoon: WebSocket Integration

@node-backend-developer Implement WebSocket gateway:
- Connect/disconnect handlers
- Room management
- Event broadcasting
- Authentication

# Updates: apps/api/src/notifications/notification.gateway.ts

@node-backend-developer Write unit tests
# Creates: apps/api/src/notifications/__tests__/

@dev Run backend checklist
@dev Commit: "feat(api): implement notification backend"

Day 3: Frontend Implementation

Morning: Notification Components

# IDE
@react-developer Create notification components
# Creates:
# - apps/web/src/components/notifications/NotificationBell.tsx
# - apps/web/src/components/notifications/NotificationList.tsx
# - apps/web/src/components/notifications/NotificationItem.tsx
# - apps/web/src/components/notifications/NotificationPreferences.tsx

// Example component structure
export function NotificationBell() {
  const { notifications, unreadCount } = useNotifications();

  return (
    <Popover>
      <PopoverTrigger>
        <Button variant="ghost" size="icon">
          <Bell className="h-5 w-5" />
          {unreadCount > 0 && (
            <Badge className="absolute -top-1 -right-1">
              {unreadCount}
            </Badge>
          )}
        </Button>
      </PopoverTrigger>
      <PopoverContent>
        <NotificationList notifications={notifications} />
      </PopoverContent>
    </Popover>
  );
}

Afternoon: WebSocket Client & State Management

@react-developer Implement WebSocket client hook
# Creates: apps/web/src/hooks/useNotifications.ts

@react-developer Integrate React Query for state
# Updates: apps/web/src/lib/api/notifications.ts

@dev Write component tests
# Creates: apps/web/src/components/notifications/__tests__/

@dev Run frontend checklist
@dev Commit: "feat(web): implement notification UI"

Day 4: Integration, Testing & Deployment

Morning: Integration Testing

@dev Write E2E tests
# Creates: apps/web/e2e/notifications.spec.ts

@dev Manual testing:
- Create task → verify assignment notification
- Add comment → verify comment notification
- Mention user → verify mention notification
- Test real-time delivery
- Test notification preferences

@dev Fix any issues found

Afternoon: Quality & Deployment

@qa *review notification feature

@dev Run all checklists:
- Frontend checklist
- Backend checklist
- Security checklist
- Performance checklist

@dev Deploy to staging
@qa Staging validation
@dev Deploy to production
@dev Monitor for issues

@dev Commit: "feat: complete real-time notifications feature"

Example 3: Migrating JavaScript to TypeScript (12-Week Migration)

Context: Large JavaScript codebase (500+ files) migrating to TypeScript

Week 1-2: Assessment & Planning

Week 1: Codebase Analysis

# Web UI
@typescript-expert Assess codebase:
- Count files (JavaScript vs TypeScript)
- Identify complex areas
- List external dependencies
- Estimate effort

# Output: docs/migration/assessment.md

@typescript-expert Create migration strategy:
- Phase breakdown
- File prioritization (bottom-up approach)
- Risk mitigation
- Timeline

# Output: docs/migration/strategy.md

Week 2: Environment Setup

# IDE
@typescript-expert Configure TypeScript
# Creates: tsconfig.json

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "lib": ["ES2020", "DOM"],
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "strict": false,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules"]
}

@typescript-expert Install @types packages
npm install -D @types/react @types/node @types/express

@dev Setup ESLint for TypeScript
# Updates: .eslintrc.js

@dev Commit: "chore: setup TypeScript environment"

Week 3-5: Phase 1 - Utilities & Helpers (Bottom-Up)

Week 3: Core Utilities

@typescript-expert Convert utility files (Batch 1: 20 files)
# Converts:
# - src/utils/date.js → src/utils/date.ts
# - src/utils/string.js → src/utils/string.ts
# - src/utils/validation.js → src/utils/validation.ts
# - src/utils/format.js → src/utils/format.ts

@dev Run tests after each file
npm test

@dev Commit: "refactor: convert core utilities to TypeScript"

Week 4: Data Models & Types

@typescript-expert Define shared types
# Creates: src/types/

@typescript-expert Convert model files (Batch 2: 25 files)
# Converts:
# - src/models/*.js → src/models/*.ts

@dev Run tests
@dev Commit: "refactor: convert data models to TypeScript"

Week 5: Service Layer

@typescript-expert Convert service files (Batch 3: 30 files)
# Converts:
# - src/services/auth.js → src/services/auth.ts
# - src/services/user.js → src/services/user.ts
# - src/services/task.js → src/services/task.ts

@dev Integration tests
@dev Commit: "refactor: convert service layer to TypeScript"

Week 6-8: Phase 2 - Components & API

Week 6: React Components (Batch 4: 50 files)

@typescript-expert Convert utility components first
@react-developer Update component props to TypeScript

// Before (JavaScript)
export function Button({ children, onClick, variant }) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
}

// After (TypeScript)
interface ButtonProps {
  children: React.ReactNode;
  onClick?: () => void;
  variant?: 'primary' | 'secondary' | 'danger';
}

export function Button({
  children,
  onClick,
  variant = 'primary'
}: ButtonProps) {
  return (
    <button className={`btn btn-${variant}`} onClick={onClick}>
      {children}
    </button>
  );
}

@dev Test each component
@dev Commit: "refactor: convert utility components to TypeScript"

Week 7: Complex Components (Batch 5: 40 files)

@typescript-expert Convert feature components
@react-developer Add proper type inference for hooks
@dev Component tests
@dev Commit: "refactor: convert feature components to TypeScript"

Week 8: API Layer (Batch 6: 35 files)

@api-developer Convert API routes and controllers
@typescript-expert Define request/response types
@dev API tests
@dev Commit: "refactor: convert API layer to TypeScript"

Week 9-10: Phase 3 - Enable Strict Mode

Week 9: Enable noImplicitAny

# IDE
@typescript-expert Update tsconfig.json

{
  "compilerOptions": {
    "noImplicitAny": true
  }
}

@typescript-expert Fix implicit any errors (100+ errors)
# Systematically add types to all parameters and variables

@dev Run tests continuously
@dev Commit: "refactor: enable noImplicitAny and fix errors"

Week 10: Enable strictNullChecks

@typescript-expert Update tsconfig.json

{
  "compilerOptions": {
    "strictNullChecks": true
  }
}

@typescript-expert Fix null/undefined errors (200+ errors)
# Add proper null checks and optional chaining

@dev Run tests
@dev Commit: "refactor: enable strictNullChecks and fix errors"

Week 11: Phase 4 - Full Strict Mode

Enable All Strict Flags

@typescript-expert Update tsconfig.json to full strict mode

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "strictFunctionTypes": true,
    "strictBindCallApply": true,
    "strictPropertyInitialization": true,
    "noImplicitThis": true,
    "alwaysStrict": true
  }
}

@typescript-expert Fix remaining strict errors (150+ errors)
@dev Run full test suite
@dev Commit: "refactor: enable full strict mode"

Week 12: Refinement & Documentation

Replace 'any' Types

@typescript-expert Find all 'any' types:
npm run find-any-types  # Custom script

@typescript-expert Replace with proper types:
- Use generics where appropriate
- Create specific interfaces
- Use 'unknown' for truly unknown types
- Add type guards for runtime checks

@dev Commit: "refactor: eliminate 'any' types"

Add Generics & Advanced Types

@typescript-expert Improve type safety:
- Add generics to reusable functions
- Use conditional types where appropriate
- Implement type guards
- Add discriminated unions

@dev Commit: "refactor: add advanced TypeScript patterns"

Documentation & Training

@typescript-expert Document TypeScript standards
# Creates: docs/typescript-standards.md

@typescript-expert Create migration retrospective
# Creates: docs/migration/retrospective.md

@dev Update team documentation
@dev Commit: "docs: complete TypeScript migration documentation"

Final Validation

# Verify TypeScript compilation
tsc --noEmit

# Run all tests
npm test

# Check bundle size impact
npm run build && npm run analyze

# Performance testing
npm run test:perf

# Deploy to staging for final validation
@dev Deploy to staging
@qa Full regression testing
@dev Deploy to production

@dev Commit: "chore: complete TypeScript migration 🎉"

Integration with Core BMAD

This expansion pack integrates seamlessly with core BMAD agents:

Analyst: Gathers requirements for JavaScript projects
PM: Uses JavaScript-specific PRD template
Architect: Collaborates with JS Solution Architect
Scrum Master: Creates stories using JavaScript story template
Dev: Executes using specialized JavaScript agents
QA: Tests with JavaScript testing frameworks
PO: Validates using JavaScript-specific checklists

Getting Help

Expansion Pack Issues: Check DOCUMENTATION/ folder
Core BMAD Help: Reference main user guide
Community: Join BMAD Discord
Examples: See data/ folder for reference implementations

Quick Reference

Agent Selection

Architecture/Tech Stack → @js-solution-architect
React Components → @react-developer
Backend Services → @node-backend-developer
API Endpoints → @api-developer
TypeScript Types → @typescript-expert

Quality Gates

Architecture → architecture-review-checklist.md
Frontend Code → frontend-checklist.md
Backend Code → backend-checklist.md
API Design → api-design-checklist.md
Security → security-checklist.md
Performance → performance-checklist.md
Deployment → deployment-readiness-checklist.md

Common Commands

# Planning
@js-solution-architect Design architecture for {project}
@typescript-expert Create type definitions for {feature}

# Development
@react-developer Implement {component}
@node-backend-developer Implement {service}
@api-developer Create {endpoint}

# Quality
@dev Run all validations
@qa *review {story}

# Deployment
@dev Deploy to staging
@dev Monitor production metrics

Conclusion

The JavaScript Full-Stack Expansion Pack enhances BMAD Method with specialized expertise for modern JavaScript/TypeScript development. Use the appropriate agents for each task, follow the quality checklists, and leverage the comprehensive reference materials to build high-quality full-stack applications efficiently.

Remember: This expansion pack works best when integrated with core BMAD workflows. Use it as a specialized toolkit while following the overall BMAD methodology for planning, development, and quality assurance.

60 KiB Raw Blame History

JavaScript Full-Stack Expansion Pack — User Guide

Overview

The JavaScript Full-Stack Workflow

Planning Phase: Greenfield Projects

Planning Artifacts (JavaScript Projects)

Development Phase: Full-Stack Implementation

Feature Development Workflow

TypeScript Migration Workflow

Specialized Agents

JS Solution Architect

React Developer

Node Backend Developer

API Developer

TypeScript Expert

Agent Teams

Full-Stack Team

Frontend Team

Backend Team

Quality Checklists

Architecture Phase

Development Phase

Deployment Phase

Task Guides

create-development-story.md

create-architecture-doc.md

create-api-spec.md

setup-project.md

code-review.md

performance-optimization.md

Reference Materials

development-guidelines.md

architecture-patterns.md

best-practices.md

technology-stack-guide.md

security-guidelines.md

deployment-strategies.md

Best Practices

Planning Phase

Development Phase

Code Quality

Performance

Deployment

Common Workflows

MVP Rapid Prototype Workflow

Step-by-Step MVP Commands (For Beginners)

Day 1: Planning (Morning - 4 hours)

Day 2: Project Setup (Morning - 2 hours)

Day 2-3: Authentication (Afternoon - 4 hours)

Day 3: Todo Backend (Afternoon - 4 hours)

Day 3-4: Todo Frontend (Evening/Morning - 6 hours)

Day 4-5: Polish & Features (8 hours)

Day 5: Testing (Afternoon - 2 hours)

Day 6: Deployment (Morning - 1 hour)

Day 6: Staging Validation (Afternoon - 2 hours)

Day 7: Final Polish & Launch (2 hours)

Complete Command Reference (Copy-Paste Ready)

What You'll Have After 7 Days

Complete Full-Stack Feature Workflow

Technology Stack Selection Workflow

Detailed Example Workflows

Example 1: Building a SaaS Application (12-Week Timeline)

Week 1-2: Planning & Architecture

Week 3-4: Project Setup & Authentication

Week 5-6: Core Task Management

Week 7-8: Real-Time Features

Week 9-10: Advanced Features

Week 11: Testing & Optimization

Week 12: Deployment & Launch

Example 2: Adding Real-Time Notifications Feature (4-Day Implementation)

Day 1: Planning & Architecture

Day 2: Backend Implementation

Day 3: Frontend Implementation

Day 4: Integration, Testing & Deployment

Example 3: Migrating JavaScript to TypeScript (12-Week Migration)

Week 1-2: Assessment & Planning

Week 3-5: Phase 1 - Utilities & Helpers (Bottom-Up)

Week 6-8: Phase 2 - Components & API

Week 9-10: Phase 3 - Enable Strict Mode

Week 11: Phase 4 - Full Strict Mode

60 KiB

Raw Blame History

`create-development-story.md`

`create-architecture-doc.md`

`create-api-spec.md`

`setup-project.md`

`code-review.md`

`performance-optimization.md`

`development-guidelines.md`

`architecture-patterns.md`

`best-practices.md`

`technology-stack-guide.md`

`security-guidelines.md`

`deployment-strategies.md`