# BMAD JavaScript Full-Stack Expansion Pack - Complete Technical Guide ## Table of Contents 1. [Overview](#overview) 2. [Expansion Pack Architecture](#expansion-pack-architecture) 3. [Config.yaml - The Brain](#configyaml---the-brain) 4. [Agents - The Workers](#agents---the-workers) 5. [Agent Teams - Orchestrated Collaboration](#agent-teams---orchestrated-collaboration) 6. [Workflows - Execution Blueprints](#workflows---execution-blueprints) 7. [Tasks - Repeatable Procedures](#tasks---repeatable-procedures) 8. [Checklists - Quality Gates](#checklists---quality-gates) 9. [Templates - Document Scaffolds](#templates---document-scaffolds) 10. [Data Folder - Knowledge Base](#data-folder---knowledge-base) 11. [Parallel Development](#parallel-development) 12. [Complete Execution Flow](#complete-execution-flow) 13. [Real-World Examples](#real-world-examples) --- ## Overview The **bmad-javascript-fullstack** expansion pack extends BMAD-METHOD with specialized capabilities for modern JavaScript/TypeScript full-stack development. It provides a complete ecosystem of agents, workflows, checklists, and knowledge for building React/Node.js applications. ### What is BMAD-METHOD? BMAD (Business Model-Agile Development) METHOD is an AI-powered software development framework that uses specialized AI agents to guide development workflows from requirements to deployment. ### What is an Expansion Pack? An expansion pack extends BMAD core functionality with: - **Specialized Agents** - Domain-specific AI assistants - **Workflows** - Guided multi-step processes - **Templates** - Document scaffolds - **Checklists** - Quality validation - **Knowledge Base** - Best practices and guidelines ```mermaid graph TB subgraph "BMAD Core System" CORE[BMAD Core Engine] CORE_AGENTS[Core Agents: Analyst, PM, Scrum Master, etc.] end subgraph "JavaScript Expansion Pack" CONFIG[config.yaml] AGENTS[5 Specialized Agents] TEAMS[3 Agent Teams] WORKFLOWS[6 Workflows] TASKS[6 Task Templates] CHECKLISTS[8 Checklists] TEMPLATES[2 Templates] DATA[6 Knowledge Docs] end CORE -->|Loads| CONFIG CONFIG -->|Registers| AGENTS CONFIG -->|Defines| TEAMS AGENTS -->|Use| WORKFLOWS WORKFLOWS -->|Execute| TASKS TASKS -->|Validate with| CHECKLISTS AGENTS -->|Reference| DATA AGENTS -->|Fill out| TEMPLATES style CONFIG fill:#ff6b6b style AGENTS fill:#4ecdc4 style WORKFLOWS fill:#45b7d1 style DATA fill:#96ceb4 ``` --- ## Expansion Pack Architecture ### Directory Structure ``` bmad-javascript-fullstack/ ├── config.yaml # Expansion pack configuration ├── agents/ # AI agent definitions (5) │ ├── js-solution-architect.md │ ├── react-developer.md │ ├── node-backend-developer.md │ ├── api-developer.md │ └── typescript-expert.md ├── agent-teams/ # Team bundles (3) │ ├── fullstack-team.yaml │ ├── frontend-team.yaml │ └── backend-team.yaml ├── workflows/ # Process workflows (6) │ ├── fullstack-greenfield.yaml │ ├── feature-development.yaml │ ├── frontend-app-development.yaml │ ├── backend-api-development.yaml │ ├── mvp-rapid-prototype.yaml │ └── migration-to-typescript.yaml ├── tasks/ # Reusable tasks (6) │ ├── create-development-story.md │ ├── create-architecture-doc.md │ ├── create-api-spec.md │ ├── setup-project.md │ ├── code-review.md │ └── performance-optimization.md ├── checklists/ # Quality checklists (8) │ ├── architecture-review-checklist.md │ ├── frontend-checklist.md │ ├── backend-checklist.md │ ├── api-design-checklist.md │ ├── security-checklist.md │ ├── performance-checklist.md │ ├── deployment-readiness-checklist.md │ └── story-dod-checklist.md ├── templates/ # Document templates (2) │ ├── prd/ │ │ └── fullstack-javascript-prd.md │ └── stories/ │ └── javascript-development-story.md ├── data/ # Knowledge base (6) │ ├── development-guidelines.md │ ├── architecture-patterns.md │ ├── best-practices.md │ ├── technology-stack-guide.md │ ├── security-guidelines.md │ └── deployment-strategies.md └── DOCUMENTATION/ # User documentation ``` ### Component Relationships ```mermaid graph LR CONFIG[config.yaml] -->|Registers| AGENTS[Agents] CONFIG -->|Defines| TEAMS[Agent Teams] TEAMS -->|Include| AGENTS TEAMS -->|Reference| WORKFLOWS WORKFLOWS -->|Execute| TASKS WORKFLOWS -->|Use| CHECKLISTS AGENTS -->|Reference| DATA AGENTS -->|Create| DOCS[Documents] TASKS -->|Guide| AGENTS CHECKLISTS -->|Validate| DOCS TEMPLATES -->|Scaffold| DOCS DATA -->|Inform| AGENTS style CONFIG fill:#ff6b6b,color:#fff style AGENTS fill:#4ecdc4,color:#fff style TEAMS fill:#f7b731,color:#fff style WORKFLOWS fill:#5f27cd,color:#fff ``` --- ## Config.yaml - The Brain The `config.yaml` is the **entry point** for the expansion pack. It tells BMAD Core what this pack contains and how to integrate it. ### Structure ```yaml # Expansion pack metadata name: bmad-javascript-fullstack version: 1.0.1 short-title: JavaScript Full-Stack Dev Pack description: >- Comprehensive expansion pack for modern JavaScript/TypeScript full-stack development. Specialized agents for React, Node.js, API design, and TypeScript expertise. Complete workflows from architecture to deployment. author: BMAD Community slashPrefix: bmadJSFullStack ``` ### Key Fields Explained | Field | Purpose | Example | |-------|---------|---------| | `name` | Unique identifier for the pack | `bmad-javascript-fullstack` | | `version` | Semantic version | `1.0.1` | | `short-title` | Display name in UI | `JavaScript Full-Stack Dev Pack` | | `description` | What this pack provides | Multi-line description | | `author` | Creator/maintainer | `BMAD Community` | | `slashPrefix` | Command prefix for agents | `bmadJSFullStack` | ### How BMAD Uses config.yaml ```mermaid sequenceDiagram participant User participant BMAD Core participant Config participant Agents participant Workflows User->>BMAD Core: Install expansion pack BMAD Core->>Config: Read config.yaml Config-->>BMAD Core: Pack metadata BMAD Core->>Agents: Discover agents/ folder BMAD Core->>Workflows: Discover workflows/ folder BMAD Core->>BMAD Core: Register all components BMAD Core-->>User: Pack ready to use ``` ### What Gets Registered When BMAD loads the expansion pack via `config.yaml`: 1. **Agents** - All `.md` files in `agents/` folder 2. **Agent Teams** - All `.yaml` files in `agent-teams/` folder 3. **Workflows** - All `.yaml` files in `workflows/` folder 4. **Templates** - All files in `templates/` folder 5. **Checklists** - All files in `checklists/` folder 6. **Tasks** - All files in `tasks/` folder 7. **Data** - All files in `data/` folder as reference material --- ## Agents - The Workers Agents are **specialized AI assistants** that handle specific types of work. Each agent has expertise in a domain. ### Agent Definition Structure Agents are defined in Markdown files with YAML frontmatter: ```markdown --- name: react-developer icon: ⚛️ expertise: - React 18+ development - Next.js 14+ App Router - State management - Performance optimization technologies: - React - Next.js - TypeScript - Tailwind CSS --- # React Developer Agent ## Role Frontend development specialist... ## Expertise - React hooks and patterns - Component architecture - ... ## When to Use - Building UI components - ... ``` ### The 5 Agents in This Pack ```mermaid graph TB subgraph "JavaScript Expansion Pack Agents" ARCH[js-solution-architect
🏗️ Architecture & Design] REACT[react-developer
⚛️ Frontend Development] NODE[node-backend-developer
🟢 Backend Development] API[api-developer
🌐 API Design] TS[typescript-expert
📘 Type Safety] end ARCH -->|Designs for| REACT ARCH -->|Designs for| NODE ARCH -->|Defines| API TS -->|Helps| REACT TS -->|Helps| NODE TS -->|Helps| API REACT -->|Calls| API NODE -->|Implements| API style ARCH fill:#ff6b6b,color:#fff style REACT fill:#4ecdc4,color:#fff style NODE fill:#95e1d3,color:#000 style API fill:#f38181,color:#fff style TS fill:#546de5,color:#fff ``` #### 1. JS Solution Architect **Purpose:** High-level architecture and technology decisions **Responsibilities:** - System architecture design - Technology stack selection - Database schema design - Scalability planning - Performance architecture - Cloud infrastructure decisions **When to Use:** - Starting a new project - Major architectural changes - Technology evaluation - System design reviews **Example Interaction:** ``` User: I need to build a real-time collaboration platform with 10k users. What architecture should I use? Agent: I recommend a microservices architecture with: - Frontend: Next.js 14 with React Server Components - Backend: NestJS with TypeScript - Database: PostgreSQL for relational data, Redis for sessions - Real-time: WebSocket with Socket.io - Deployment: Docker containers on AWS ECS [Detailed architecture document follows...] ``` #### 2. React Developer **Purpose:** Frontend development with React **Responsibilities:** - Component development - State management - UI/UX implementation - Performance optimization - Accessibility - Testing **When to Use:** - Building UI components - State management decisions - Frontend architecture - Performance issues #### 3. Node Backend Developer **Purpose:** Server-side development **Responsibilities:** - API implementation - Database operations - Authentication/authorization - Background jobs - WebSocket/real-time - Error handling **When to Use:** - API implementation - Database design - Authentication systems - Background processing #### 4. API Developer **Purpose:** API design and contracts **Responsibilities:** - API contract design - RESTful/GraphQL/tRPC design - OpenAPI documentation - Versioning strategies - Rate limiting - API security **When to Use:** - Designing API contracts - API documentation - Versioning decisions - API best practices #### 5. TypeScript Expert **Purpose:** Advanced TypeScript and type safety **Responsibilities:** - Complex type definitions - Generics and utility types - JavaScript to TypeScript migration - Type system architecture - Configuration optimization **When to Use:** - Complex type problems - JS to TS migration - Type system design - Advanced TypeScript patterns ### How to Use Agents #### In Web UI (Chat Interface) ``` *react-developer I need to build a data table component with sorting, filtering, and pagination. ``` #### In IDE (VS Code Extension) ``` @react-developer Build a sortable data table with these features... ``` #### In API/CLI ```bash bmad-method invoke --agent react-developer --input "Build data table..." ``` --- ## Agent Teams - Orchestrated Collaboration Agent teams are **pre-configured bundles** that include multiple agents and workflows for specific scenarios. ### Team Structure (YAML) ```yaml # bundle: name: JavaScript Full-Stack Team icon: 🚀 description: Complete team for full-stack development agents: - analyst # From BMAD Core - bmad-orchestrator # From BMAD Core - js-solution-architect # From this pack - react-developer # From this pack - node-backend-developer # From this pack - api-developer # From this pack - typescript-expert # From this pack workflows: - fullstack-greenfield.yaml - feature-development.yaml - mvp-rapid-prototype.yaml ``` ### The 3 Teams in This Pack ```mermaid graph TB subgraph "Full-Stack Team 🚀" FS1[analyst] FS2[bmad-orchestrator] FS3[js-solution-architect] FS4[react-developer] FS5[node-backend-developer] FS6[api-developer] FS7[typescript-expert] end subgraph "Frontend Team ⚛️" FE1[analyst] FE2[bmad-orchestrator] FE3[js-solution-architect] FE4[react-developer] FE5[typescript-expert] end subgraph "Backend Team 🟢" BE1[analyst] BE2[bmad-orchestrator] BE3[js-solution-architect] BE4[node-backend-developer] BE5[api-developer] BE6[typescript-expert] end style FS1 fill:#dfe4ea style FE1 fill:#dfe4ea style BE1 fill:#dfe4ea ``` ### What Agent Teams Do 1. **Bundle Related Agents** - Group agents that work together 2. **Include Relevant Workflows** - Attach workflows for the team 3. **Simplify Selection** - Load entire team instead of individual agents 4. **Define Collaboration Patterns** - Show how agents work together ### How Teams Enable Collaboration ```mermaid sequenceDiagram participant User participant Analyst participant Architect participant React Dev participant Node Dev participant API Dev User->>Analyst: I need a user authentication system Analyst->>Architect: Requirements gathered Architect->>API Dev: Design auth API contract API Dev->>React Dev: API contract ready API Dev->>Node Dev: API contract ready React Dev-->>User: Login UI implemented Node Dev-->>User: Auth API implemented ``` ### Using Teams ``` *fullstack-team I need to build a task management app with real-time collaboration. ``` The team orchestrator will: 1. Route requirements to **analyst** 2. Send to **js-solution-architect** for architecture 3. Distribute work to **react-developer** and **node-backend-developer** 4. Use **api-developer** for API contracts 5. Leverage **typescript-expert** for type safety --- ## Workflows - Execution Blueprints Workflows are **step-by-step guides** that orchestrate agents through complex processes. ### Workflow Structure (YAML) ```yaml # workflow: id: fullstack-greenfield name: Full-Stack JavaScript - Greenfield Project description: Complete workflow for building a new full-stack app type: greenfield project_types: - web-application - saas-platform full_sequence: - agent: analyst creates: requirements-analysis.md notes: "Gather requirements. SAVE to docs/requirements/" - agent: js-solution-architect creates: technology-stack-decision.md requires: requirements-analysis.md notes: "Select tech stack. SAVE to docs/architecture/" - agent: js-solution-architect creates: system-architecture.md requires: - requirements-analysis.md - technology-stack-decision.md notes: "Design system architecture" - agent: js-solution-architect validates: architecture_completeness uses: architecture-review-checklist notes: "Validate architecture" ``` ### Workflow Components ```mermaid graph TD WF[Workflow Definition] WF --> META[Metadata] WF --> SEQ[Sequence Steps] WF --> GUIDE[Guidance] WF --> DIAGRAM[Flow Diagram] META --> ID[ID] META --> NAME[Name] META --> DESC[Description] META --> TYPE[Type] SEQ --> STEP1[Step 1: Agent + Action] SEQ --> STEP2[Step 2: Agent + Action] SEQ --> STEP3[Step 3: Agent + Action] GUIDE --> WHEN[When to Use] GUIDE --> BEST[Best Practices] GUIDE --> HANDOFF[Handoff Prompts] style WF fill:#5f27cd,color:#fff style SEQ fill:#00d2d3,color:#fff style GUIDE fill:#ff9ff3,color:#000 ``` ### The 6 Workflows #### 1. Fullstack Greenfield Workflow **Purpose:** Build a new full-stack app from scratch **Steps:** 1. Requirements analysis (analyst) 2. Tech stack selection (js-solution-architect) 3. System architecture design (js-solution-architect) 4. Architecture validation (js-solution-architect + checklist) 5. Project initialization 6. Story development begins **Flow Diagram:** ```mermaid graph TD A[Start: New Project] --> B{Scope?} B -->|Full App| C[Requirements Analysis] B -->|MVP| D[MVP Requirements] C --> E[Tech Stack Selection] E --> F[System Architecture] F --> G[Validate Architecture] G --> H{Issues?} H -->|Yes| F H -->|No| I[Initialize Project] I --> J[Story Development] D --> K[MVP Architecture] K --> L[Rapid Implementation] style J fill:#90EE90 style L fill:#90EE90 ``` #### 2. Feature Development Workflow **Purpose:** Add features to existing apps **Steps:** 1. Feature requirements (analyst) 2. Technical impact assessment (js-solution-architect) 3. Technical specification (relevant developer agent) 4. Story breakdown (scrum-master) 5. Implementation begins #### 3. Frontend App Development **Purpose:** Frontend-only projects **Steps:** 1. Requirements (analyst) 2. UI/UX design review 3. Component architecture (react-developer) 4. Implementation stories #### 4. Backend API Development **Purpose:** Backend/API-only projects **Steps:** 1. Requirements (analyst) 2. API contract design (api-developer) 3. Implementation specification (node-backend-developer) 4. Database design 5. Implementation stories #### 5. MVP Rapid Prototype **Purpose:** Quick MVP/proof-of-concept **Steps:** 1. Core feature identification 2. Minimal architecture 3. Rapid implementation 4. Skip detailed documentation #### 6. Migration to TypeScript **Purpose:** Convert JavaScript projects to TypeScript **Steps:** 1. Codebase analysis (typescript-expert) 2. Migration strategy 3. Incremental conversion plan 4. Type definition creation 5. Validation ### Workflow Execution Flow ```mermaid sequenceDiagram participant User participant BMAD participant Workflow participant Agent1 participant Agent2 participant Checklist participant Docs User->>BMAD: Start workflow: fullstack-greenfield BMAD->>Workflow: Load workflow definition Workflow->>Agent1: Execute step 1 (analyst) Agent1->>Docs: Create requirements-analysis.md Agent1-->>Workflow: Step 1 complete Workflow->>Agent2: Execute step 2 (architect) Agent2->>Docs: Read requirements-analysis.md Agent2->>Docs: Create system-architecture.md Agent2-->>Workflow: Step 2 complete Workflow->>Agent2: Execute step 3 (validate) Agent2->>Checklist: Use architecture-review-checklist Checklist-->>Agent2: Validation results Agent2-->>Workflow: Step 3 complete Workflow-->>User: Workflow complete, ready for implementation ``` ### How Workflows Work 1. **User Invokes Workflow** - Via command or UI 2. **BMAD Loads Definition** - Reads YAML file 3. **Sequential Execution** - Each step runs in order 4. **Agent Handoffs** - Output of one step becomes input to next 5. **Validation Gates** - Checklists validate outputs 6. **Document Creation** - Agents create artifacts at each step 7. **Workflow Completion** - All steps done, user proceeds to implementation ### Workflow vs Manual Agent Use | Aspect | Manual | Workflow | |--------|--------|----------| | **Process** | Ad-hoc | Structured | | **Handoffs** | Manual | Automatic | | **Validation** | Optional | Built-in | | **Documentation** | User's responsibility | Guided | | **Learning Curve** | Steeper | Easier | | **Flexibility** | High | Medium | | **Consistency** | Variable | High | --- ## Tasks - Repeatable Procedures Tasks are **reusable procedures** that can be invoked by agents or workflows. They're like functions in code. ### Task Structure (Markdown) ```markdown # # Create Development Story Task ## Purpose Create detailed, actionable development stories for JavaScript/TypeScript full-stack features that enable developers to implement without additional design decisions. ## When to Use - Breaking down epics into implementable stories - Converting architecture documents into development tasks - Preparing work for sprint planning ## Prerequisites - Completed architecture document - PRD or feature requirements - Epic definition this story belongs to ## Process ### 1. Story Identification **Review Context:** - Understand the epic's overall goal - Review architecture document sections - Identify specific feature to implement ### 2. Story Scoping **Single Responsibility:** - Focus on one specific feature or component - Ensure story is completable in 1-3 days ### 3. Template Execution Use `templates/stories/javascript-development-story.md` template ### 4. Story Validation Execute `checklists/story-dod-checklist.md` against completed story ## Success Criteria - [ ] Developer can start implementation immediately - [ ] No additional design decisions required - [ ] All technical questions answered ``` ### The 6 Tasks ```mermaid graph TB subgraph "Task Categories" DOC[Documentation Tasks] DEV[Development Tasks] QA[Quality Tasks] end DOC --> T1[create-development-story] DOC --> T2[create-architecture-doc] DOC --> T3[create-api-spec] DEV --> T4[setup-project] QA --> T5[code-review] QA --> T6[performance-optimization] style DOC fill:#ffeaa7,color:#000 style DEV fill:#74b9ff,color:#000 style QA fill:#a29bfe,color:#fff ``` #### Task Details | Task | Purpose | Used By | Output | |------|---------|---------|--------| | **create-development-story** | Generate implementation stories | Scrum Master, Agents | Story document | | **create-architecture-doc** | Document system design | Solution Architect | Architecture doc | | **create-api-spec** | Define API contracts | API Developer | OpenAPI spec | | **setup-project** | Initialize project structure | Developer | Project skeleton | | **code-review** | Review code quality | Developer, QA | Review report | | **performance-optimization** | Analyze and improve performance | Developer | Optimization plan | ### How Tasks Are Used #### In Workflows ```yaml - agent: scrum-master creates: feature-stories.md uses: create-development-story task notes: Break feature into implementable stories ``` #### Directly by Agents ``` *scrum-master Use the create-development-story task to break down the user authentication feature into implementable stories. ``` #### Manual Invocation ``` Task: create-development-story Input: User authentication feature from architecture doc ``` ### Task Execution Flow ```mermaid sequenceDiagram participant Agent participant Task participant Template participant Checklist participant Output Agent->>Task: Invoke create-development-story Task->>Task: Read Prerequisites Task->>Task: Execute Process Steps Task->>Template: Use story template Template-->>Task: Scaffolded document Task->>Checklist: Validate with story-dod-checklist Checklist-->>Task: Validation results Task->>Output: Create story document Output-->>Agent: Task complete ``` --- ## Checklists - Quality Gates Checklists are **quality validation tools** that ensure outputs meet standards. ### Checklist Structure (Markdown) ```markdown # # Frontend Quality Checklist ## React/Next.js Component Quality ### Component Structure - [ ] Single Responsibility - Each component has one clear purpose - [ ] Proper TypeScript Types - Props interface defined with no `any` - [ ] Component Size - Under 300 lines - [ ] Named Exports - Prefer named exports ### React Best Practices - [ ] Hooks Usage - Hooks used correctly - [ ] useEffect Dependencies - All dependencies included - [ ] Memoization - useMemo/useCallback for expensive operations ## Performance - [ ] Code Splitting - Large components lazy loaded - [ ] Bundle Size - No unnecessary dependencies - [ ] Lighthouse Score - >90 on all metrics ## Security - [ ] XSS Prevention - User input sanitized - [ ] No Secrets - No API keys in frontend code **Quality Rating:** ⭐⭐⭐⭐⭐ **Ready for Production:** [ ] Yes [ ] No ``` ### The 8 Checklists ```mermaid graph TB CL[Quality Checklists] CL --> ARCH[Architecture Review] CL --> FE[Frontend Quality] CL --> BE[Backend Quality] CL --> API[API Design] CL --> SEC[Security] CL --> PERF[Performance] CL --> DEPLOY[Deployment Readiness] CL --> STORY[Story DoD] ARCH --> |Validates| ARCH_DOC[Architecture Docs] FE --> |Validates| FE_CODE[Frontend Code] BE --> |Validates| BE_CODE[Backend Code] API --> |Validates| API_SPEC[API Specifications] SEC --> |Validates| SEC_IMPL[Security Implementation] PERF --> |Validates| PERF_IMPL[Performance Targets] DEPLOY --> |Validates| DEPLOY_READY[Production Readiness] STORY --> |Validates| STORIES[User Stories] style CL fill:#e74c3c,color:#fff style ARCH fill:#3498db,color:#fff style FE fill:#2ecc71,color:#fff style BE fill:#f39c12,color:#fff ``` #### Checklist Categories | Checklist | Purpose | Used In | Validates | |-----------|---------|---------|-----------| | **architecture-review-checklist** | Validate architecture docs | Greenfield workflow | Completeness, feasibility, scalability | | **frontend-checklist** | Validate React/UI code | Code review, deployment | Component quality, accessibility, performance | | **backend-checklist** | Validate Node.js code | Code review, deployment | API quality, security, error handling | | **api-design-checklist** | Validate API contracts | API design phase | RESTful principles, versioning, docs | | **security-checklist** | Validate security measures | Pre-deployment | Authentication, encryption, input validation | | **performance-checklist** | Validate performance targets | Pre-deployment | Load times, API speed, bundle size | | **deployment-readiness-checklist** | Validate production readiness | Before deploy | Monitoring, backups, rollback plan | | **story-dod-checklist** | Validate story quality | Story creation | Completeness, clarity, testability | ### How Checklists Work #### In Workflows (Automatic) ```yaml - agent: js-solution-architect validates: architecture_completeness uses: architecture-review-checklist notes: "Validate architecture document" ``` #### In Tasks (Manual) ```markdown ### 4. Story Validation Execute `checklists/story-dod-checklist.md` against completed story ``` #### In Code Reviews ``` Reviewer: Running frontend-checklist against UserProfile component... ✅ Component Structure: PASS ✅ React Best Practices: PASS ❌ Performance: FAIL - Missing code splitting ✅ Accessibility: PASS ❌ Security: FAIL - XSS vulnerability in user input ``` ### Checklist Execution Flow ```mermaid flowchart TD A[Artifact Created] --> B[Apply Checklist] B --> C{All Items Pass?} C -->|Yes| D[Artifact Approved] C -->|No| E[Identify Issues] E --> F[Return to Agent] F --> G[Agent Fixes Issues] G --> H[Artifact Updated] H --> B style D fill:#90EE90 style E fill:#FFB6C1 style C fill:#FFD700 ``` --- ## Templates - Document Scaffolds Templates are **pre-structured documents** that agents fill out with project-specific information. ### Template Structure Templates are Markdown files with placeholder sections: ```markdown # [Project Name] - Product Requirements Document ## 1. Executive Summary **Product Name:** [Name] **Version:** [Version] **Date:** [Date] **Author:** [Author] ### Vision [Describe the product vision in 2-3 sentences] ### Goals 1. [Primary goal] 2. [Secondary goal] ## 2. Technology Stack ### Frontend - **Framework:** [React/Next.js/Vue] - **State Management:** [Redux/Zustand/React Query] - **Styling:** [Tailwind/CSS Modules/Styled Components] ### Backend - **Framework:** [Express/Fastify/NestJS] - **Database:** [PostgreSQL/MongoDB/MySQL] - **ORM:** [Prisma/TypeORM/Mongoose] ## 3. Features ### Core Features | Feature | Priority | Complexity | Status | |---------|----------|------------|--------| | [Feature 1] | High | Medium | Planned | ## 4. API Requirements ### Endpoints | Endpoint | Method | Purpose | Authentication | |----------|--------|---------|----------------| | `/api/v1/users` | GET | List users | Required | ``` ### The 2 Templates #### 1. Full-Stack JavaScript PRD Template **Purpose:** Document product requirements for JavaScript projects **Sections:** 1. Executive Summary 2. Technology Stack Recommendations 3. Architecture Overview 4. Feature Requirements 5. User Stories 6. API Requirements 7. Database Design 8. UI/UX Requirements 9. Non-Functional Requirements 10. Security Requirements 11. Performance Requirements 12. Testing Requirements 13. Deployment Strategy 14. Timeline & Milestones 15. Appendices **Used By:** - Product Manager - Solution Architect - Analyst **When:** - Project kickoff - Feature planning - Architecture phase #### 2. JavaScript Development Story Template **Purpose:** Define implementation tasks for developers **Sections:** 1. Story Header (ID, Epic, Sprint, Status, Priority, Effort) 2. User Story (As a / I want / So that) 3. Background & Context 4. Acceptance Criteria (Functional, Technical, Performance, Security) 5. Technical Specification - Frontend Implementation - Backend Implementation - API Contract - Database Changes - TypeScript Types 6. File Changes 7. Implementation Tasks (ordered) 8. Testing Requirements 9. Dependencies 10. Definition of Done 11. Notes & Considerations **Used By:** - Scrum Master - Developers - QA **When:** - Sprint planning - Feature breakdown - Task assignment ### How Templates Work ```mermaid sequenceDiagram participant Agent participant Template participant Context participant Output Agent->>Template: Load template file Template-->>Agent: Template structure Agent->>Context: Read project context Context-->>Agent: Project details Agent->>Agent: Fill template with context Agent->>Output: Save filled template Output-->>Agent: Document created ``` ### Template Usage Example **User Request:** ``` *pm Create a PRD for a task management SaaS application using the fullstack-javascript-prd template. ``` **Agent Process:** 1. Loads `templates/prd/fullstack-javascript-prd.md` 2. Reads project context from previous conversations 3. Fills in each section with relevant information 4. Applies best practices from `data/` folder 5. Validates completeness 6. Outputs filled PRD **Result:** ```markdown # TaskFlow - Product Requirements Document ## 1. Executive Summary **Product Name:** TaskFlow **Version:** 1.0.0 **Date:** 2024-10-01 **Author:** Product Team ### Vision TaskFlow is a modern task management platform that enables teams to collaborate effectively on projects with real-time updates and intuitive workflows. ### Goals 1. Provide seamless real-time collaboration for distributed teams 2. Simplify project management with intuitive UI 3. Scale to 10,000+ users in first year ## 2. Technology Stack ### Frontend - **Framework:** Next.js 14+ (App Router) - **State Management:** Zustand + React Query - **Styling:** Tailwind CSS - **Real-time:** Socket.io Client ### Backend - **Framework:** NestJS with TypeScript - **Database:** PostgreSQL 14+ - **ORM:** Prisma - **Real-time:** Socket.io Server - **Caching:** Redis [... continues with all sections filled ...] ``` --- ## Data Folder - Knowledge Base The `data/` folder contains **reference material** that agents use to provide informed recommendations. ### Purpose The data folder is a **knowledge repository** containing: - Best practices - Architecture patterns - Technology guides - Security guidelines - Deployment strategies - Development standards ### The 6 Knowledge Documents ```mermaid graph TB DATA[Data Folder - Knowledge Base] DATA --> DEV[development-guidelines.md] DATA --> ARCH[architecture-patterns.md] DATA --> BEST[best-practices.md] DATA --> TECH[technology-stack-guide.md] DATA --> SEC[security-guidelines.md] DATA --> DEPLOY[deployment-strategies.md] AGENTS[All Agents] AGENTS -.->|Reference| DEV AGENTS -.->|Reference| ARCH AGENTS -.->|Reference| BEST AGENTS -.->|Reference| TECH AGENTS -.->|Reference| SEC AGENTS -.->|Reference| DEPLOY style DATA fill:#96ceb4,color:#000 style AGENTS fill:#4ecdc4,color:#fff ``` #### 1. development-guidelines.md **Content:** - Code organization standards - Naming conventions - File structure - Git workflow - Code review process - Documentation standards **Used By:** All developer agents **Impact:** Ensures consistent code style and structure #### 2. architecture-patterns.md **Content:** - Monolithic architecture - Microservices patterns - JAMstack architecture - Serverless patterns - Event-driven architecture - CQRS and Event Sourcing **Used By:** js-solution-architect **Impact:** Informed architecture decisions #### 3. best-practices.md **Content:** - Frontend best practices (React, state, performance, a11y) - Backend best practices (API, security, database, errors) - Testing strategies - DevOps practices - Code quality standards **Used By:** All agents **Impact:** High-quality, maintainable code #### 4. technology-stack-guide.md **Content:** - React vs Vue vs Svelte comparison - Express vs Fastify vs NestJS - PostgreSQL vs MongoDB vs MySQL - State management options - Testing frameworks - Deployment platforms **Used By:** js-solution-architect, all developers **Impact:** Informed technology choices #### 5. security-guidelines.md **Content:** - OWASP Top 10 mitigations - Authentication patterns (JWT, OAuth, Sessions) - Authorization (RBAC, ABAC) - Input validation - SQL injection prevention - XSS and CSRF protection - Security headers - Secrets management **Used By:** All developer agents, api-developer **Impact:** Secure applications #### 6. deployment-strategies.md **Content:** - Blue-green deployment - Canary releases - Rolling updates - Docker containerization - Kubernetes orchestration - CI/CD pipelines - Monitoring and logging - Backup strategies **Used By:** All agents during deployment planning **Impact:** Reliable deployments ### How Agents Use Data ```mermaid sequenceDiagram participant User participant Agent participant Data participant Response User->>Agent: What's the best state management for my app? Agent->>Data: Read best-practices.md Data-->>Agent: State management section Agent->>Data: Read technology-stack-guide.md Data-->>Agent: State library comparison Agent->>Agent: Analyze user context Agent->>Response: Formulate recommendation Response-->>User: "For your use case, I recommend Zustand because..." ``` ### Data vs Agent Knowledge | Source | Purpose | Content | Updates | |--------|---------|---------|---------| | **Agent Knowledge** | General AI knowledge | Broad programming concepts | Model training | | **Data Folder** | Specialized context | Specific patterns for this stack | Expansion pack updates | | **User Context** | Project-specific | Current project details | Per conversation | **Combined Result:** Agent uses all three sources to provide relevant, accurate, contextual advice. ### Example: Agent Using Data **User Question:** ``` *js-solution-architect Should I use PostgreSQL or MongoDB for a social media application with complex relationships and analytics? ``` **Agent Process:** 1. Reads `data/technology-stack-guide.md` - database comparison section 2. Reads `data/architecture-patterns.md` - social media architecture 3. Reads `data/best-practices.md` - database best practices 4. Analyzes user's requirements (complex relationships, analytics) 5. Formulates recommendation **Agent Response:** ``` Based on your requirements and industry best practices: **Recommendation: PostgreSQL** **Reasoning:** 1. Complex Relationships: Social media has many-to-many relationships (users, friends, posts, comments, likes). PostgreSQL excels at relational data. 2. Analytics: PostgreSQL has powerful aggregation functions and window functions for analytics queries. 3. ACID Compliance: Social interactions require transactional integrity. 4. JSON Support: PostgreSQL can also store unstructured data via JSONB when needed. [Source: technology-stack-guide.md, Section: Database Selection] **Implementation:** - Use Prisma ORM for type-safe database access - Add indexes on foreign keys and frequently queried fields - Use PostgreSQL full-text search for user/content search - Consider read replicas for analytics queries [Source: best-practices.md, Section: Database Best Practices] ``` --- ## Parallel Development Can BMAD and this expansion pack support parallel development? **Yes, absolutely!** ### Parallel Development Strategies #### 1. Multi-Agent Parallel Work ```mermaid graph LR subgraph "Sprint 1 - Parallel Development" STORY1[Story: User Auth UI] STORY2[Story: Auth API] STORY3[Story: User Profile UI] STORY4[Story: Profile API] end REACT[react-developer] --> STORY1 REACT --> STORY3 NODE[node-backend-developer] --> STORY2 NODE --> STORY4 STORY1 -.->|Uses API from| STORY2 STORY3 -.->|Uses API from| STORY4 style REACT fill:#4ecdc4,color:#fff style NODE fill:#95e1d3,color:#000 ``` **How It Works:** - **Frontend Developer** works on UI stories using `react-developer` agent - **Backend Developer** works on API stories using `node-backend-developer` agent - Both work simultaneously on different stories - API contracts defined upfront ensure compatibility #### 2. Feature Team Parallelization ```mermaid graph TB subgraph "Team A: Authentication Feature" A_FE[Frontend: Login UI] A_BE[Backend: Auth API] end subgraph "Team B: Dashboard Feature" B_FE[Frontend: Dashboard UI] B_BE[Backend: Dashboard API] end subgraph "Team C: Settings Feature" C_FE[Frontend: Settings UI] C_BE[Backend: Settings API] end style A_FE fill:#4ecdc4 style A_BE fill:#95e1d3 style B_FE fill:#4ecdc4 style B_BE fill:#95e1d3 style C_FE fill:#4ecdc4 style C_BE fill:#95e1d3 ``` **How It Works:** - Multiple feature teams work on independent features - Each team uses the full-stack agent team - Minimal dependencies between features - Coordinated through architecture document and API contracts #### 3. Workflow Parallel Execution ```mermaid sequenceDiagram participant PM as Product Manager participant A1 as Analyst participant A2 as Solution Architect participant Dev1 as React Developer participant Dev2 as Node Developer participant QA as QA Engineer PM->>A1: Feature Requirements (parallel) PM->>A1: User Research (parallel) par Requirements + Research A1->>A2: Requirements ready A1->>A2: Research insights end A2->>A2: Architecture Design par Frontend + Backend Implementation A2->>Dev1: Frontend specs A2->>Dev2: Backend specs Dev1->>Dev1: Implement UI Dev2->>Dev2: Implement API end par Testing Dev1->>QA: Frontend complete Dev2->>QA: Backend complete end QA->>PM: Feature complete ``` ### Enabling Parallel Development #### 1. Clear API Contracts (Critical!) The **api-developer** agent creates contracts upfront: ```typescript // API Contract: User Authentication // Created by: api-developer agent // Date: 2024-10-01 interface AuthAPI { // Login POST /api/v1/auth/login Request: { email: string; password: string } Response: { token: string; user: User } // Register POST /api/v1/auth/register Request: { email: string; password: string; name: string } Response: { token: string; user: User } } ``` With this contract: - **Frontend team** can implement UI immediately (mock API) - **Backend team** can implement API independently - Both teams work in parallel, guaranteed compatibility #### 2. Independent Stories Stories created with `create-development-story` task are designed for parallelization: ``` ✅ Story JS-001: Login UI Component - Frontend only - No backend dependencies (uses mock API) - Can implement immediately - Assigned to: React Developer ✅ Story JS-002: Authentication API - Backend only - No frontend dependencies - Can implement immediately - Assigned to: Node Developer ✅ Story JS-003: Integrate Login UI with Auth API - Frontend + Backend - Depends on: JS-001, JS-002 - Assigned to: Full-Stack Developer ``` Stories JS-001 and JS-002 can be done **in parallel**! #### 3. Database Migrations The **node-backend-developer** agent creates migration files that can be run independently: ``` migrations/ 001_create_users_table.sql 002_create_posts_table.sql 003_create_comments_table.sql ``` Different developers can work on different migrations in parallel. #### 4. Component Isolation The **react-developer** agent structures components for parallel development: ``` src/ features/ auth/ components/ # Auth team works here hooks/ services/ dashboard/ components/ # Dashboard team works here hooks/ services/ profile/ components/ # Profile team works here hooks/ services/ ``` Each feature folder is independent, allowing parallel work. ### Parallel Development Workflow Example **Scenario:** Building a task management app with 3 developers ```mermaid gantt title Parallel Development Timeline dateFormat YYYY-MM-DD section Architecture Requirements Analysis :a1, 2024-10-01, 1d Architecture Design :a2, after a1, 1d section Frontend (Dev1) Task List UI :f1, after a2, 2d Task Form UI :f2, after f1, 2d Dashboard UI :f3, after f1, 2d section Backend (Dev2) Task API :b1, after a2, 2d User API :b2, after a2, 2d Auth API :b3, after a2, 2d section Real-time (Dev3) WebSocket Setup :r1, after a2, 2d Real-time Sync :r2, after r1, 2d section Integration Integration Testing :i1, after f3, 1d ``` **Day 1-2: Architecture** - Solution Architect agent designs system - API contracts defined - Stories created **Day 3-4: Parallel Implementation (3 developers)** - Dev1 uses `react-developer` for Task List UI - Dev2 uses `node-backend-developer` for Task API - Dev3 uses `node-backend-developer` for WebSocket **Day 5-6: Parallel Implementation (continued)** - Dev1 uses `react-developer` for Task Form + Dashboard (parallel) - Dev2 uses `node-backend-developer` for User API + Auth API (parallel) - Dev3 uses `node-backend-developer` for Real-time Sync **Day 7: Integration** - All developers integrate and test together **Result:** 7 days with parallel work vs 13 days sequential! ### Coordination Mechanisms ```mermaid graph TB subgraph "Coordination Layer" ARCH[Architecture Document] API[API Contracts] TYPES[Shared TypeScript Types] STORIES[Story Dependencies] end subgraph "Dev Team" DEV1[Developer 1
Frontend] DEV2[Developer 2
Backend] DEV3[Developer 3
Real-time] end ARCH -->|Guides| DEV1 ARCH -->|Guides| DEV2 ARCH -->|Guides| DEV3 API -->|Defines interface| DEV1 API -->|Defines interface| DEV2 TYPES -->|Shared types| DEV1 TYPES -->|Shared types| DEV2 TYPES -->|Shared types| DEV3 STORIES -->|Prevents conflicts| DEV1 STORIES -->|Prevents conflicts| DEV2 STORIES -->|Prevents conflicts| DEV3 style ARCH fill:#ff6b6b,color:#fff style API fill:#4ecdc4,color:#fff style TYPES fill:#45b7d1,color:#fff ``` ### Best Practices for Parallel Development 1. **Define API Contracts First** - Use `api-developer` before splitting work 2. **Use Shared TypeScript Types** - One source of truth for types 3. **Feature Flags** - Deploy incomplete features hidden behind flags 4. **Regular Integration** - Integrate at least daily to catch conflicts early 5. **Story Dependencies** - Clearly mark which stories block others 6. **Communication** - Daily standup to coordinate 7. **Mock APIs** - Frontend can use mock APIs while backend is in progress --- ## Complete Execution Flow Let's walk through a **complete end-to-end example** of building a new application. ### Scenario: Building a Blog Platform **Requirements:** - User authentication - Create/edit/delete blog posts - Comment system - User profiles - SEO-friendly URLs ### Phase 1: Architecture (Days 1-3) ```mermaid sequenceDiagram participant User participant Analyst participant Architect participant API Dev participant Docs User->>Analyst: I want to build a blog platform Analyst->>Analyst: Gather requirements Analyst->>Docs: Create requirements-analysis.md Analyst->>Architect: Requirements ready Architect->>Architect: Select tech stack Architect->>Docs: Create technology-stack-decision.md Architect->>Architect: Design system architecture Architect->>Docs: Create system-architecture.md Architect->>Architect: Validate with architecture-review-checklist Architect->>User: Architecture complete ✅ Architect->>API Dev: Design API contracts API Dev->>Docs: Create api-specification.md ``` **Outputs:** 1. `requirements-analysis.md` - 1,200 lines detailing all requirements 2. `technology-stack-decision.md` - Selected Next.js, NestJS, PostgreSQL 3. `system-architecture.md` - Complete architecture with diagrams 4. `api-specification.md` - OpenAPI spec for all endpoints **Time:** 3 days (mostly thinking and design) ### Phase 2: Story Creation (Day 4) ```mermaid sequenceDiagram participant PM participant Scrum Master participant Task participant Template participant Stories PM->>Scrum Master: Break down architecture into stories Scrum Master->>Task: Use create-development-story task Task->>Template: Load javascript-development-story.md loop For each feature Scrum Master->>Template: Fill template for feature Template-->>Stories: Create story document end Scrum Master->>Stories: Validate with story-dod-checklist Scrum Master->>PM: 15 stories created ✅ ``` **Outputs:** 15 implementation stories: - `BLOG-001`: Project setup and configuration - `BLOG-002`: Database schema and migrations - `BLOG-003`: User authentication API - `BLOG-004`: Login/Register UI - `BLOG-005`: Post API (CRUD) - `BLOG-006`: Post list UI - `BLOG-007`: Post detail UI - `BLOG-008`: Post editor UI - `BLOG-009`: Comment API - `BLOG-010`: Comment UI - `BLOG-011`: User profile API - `BLOG-012`: User profile UI - `BLOG-013`: SEO optimization - `BLOG-014`: Testing suite - `BLOG-015`: Deployment pipeline **Time:** 1 day ### Phase 3: Sprint 1 - Foundation (Days 5-10) ```mermaid gantt title Sprint 1 - Foundation dateFormat YYYY-MM-DD section Setup Project Setup :s1, 2024-10-05, 1d section Backend Database Schema :b1, after s1, 1d Auth API :b2, after b1, 2d section Frontend App Structure :f1, after s1, 1d Login/Register UI :f2, after f1, 2d section Testing Auth Tests :t1, after b2, 1d ``` **Developer 1 (Backend) - Uses `node-backend-developer` agent** **Day 5: BLOG-001 - Project Setup** ```bash # Developer interaction with agent *node-backend-developer Story: BLOG-001 Task: Set up NestJS project with TypeScript, Prisma, and PostgreSQL. [Agent provides complete setup instructions] ``` Agent creates: - NestJS project structure - `prisma/schema.prisma` - `.env.example` - `docker-compose.yml` for PostgreSQL - `README.md` with setup instructions **Day 6: BLOG-002 - Database Schema** ```bash *node-backend-developer Story: BLOG-002 Task: Create Prisma schema for User, Post, Comment models. [Agent creates schema] ``` Agent creates: ```prisma model User { id String @id @default(cuid()) email String @unique password String name String posts Post[] comments Comment[] createdAt DateTime @default(now()) } model Post { id String @id @default(cuid()) title String slug String @unique content String author User @relation(...) comments Comment[] createdAt DateTime @default(now()) } model Comment { id String @id @default(cuid()) content String post Post @relation(...) author User @relation(...) createdAt DateTime @default(now()) } ``` **Days 7-8: BLOG-003 - Auth API** ```bash *node-backend-developer Story: BLOG-003 Task: Implement authentication API with JWT. [Agent implements auth module] ``` Agent creates: - `src/auth/auth.controller.ts` - `src/auth/auth.service.ts` - `src/auth/jwt.strategy.ts` - `src/auth/dto/login.dto.ts` - `src/auth/dto/register.dto.ts` - Tests **Developer 2 (Frontend) - Uses `react-developer` agent** **Day 5: BLOG-001 - App Structure** ```bash *react-developer Story: BLOG-001 Task: Set up Next.js 14 project with TypeScript and Tailwind. [Agent provides setup] ``` Agent creates: - Next.js project with App Router - TypeScript configuration - Tailwind CSS setup - Folder structure (`components/`, `app/`, `lib/`) **Days 6-7: BLOG-004 - Login/Register UI** ```bash *react-developer Story: BLOG-004 Task: Create login and register pages with forms. [Agent implements auth UI] ``` Agent creates: ```typescript // app/auth/login/page.tsx export default function LoginPage() { const [email, setEmail] = useState('') const [password, setPassword] = useState('') const loginMutation = useMutation({ mutationFn: (credentials) => authService.login(credentials), onSuccess: (data) => { // Handle successful login } }) return (
{/* Form fields */}
) } ``` **End of Sprint 1:** - ✅ Foundation complete - ✅ Authentication working - ✅ Both developers worked in parallel ### Phase 4: Sprint 2 - Core Features (Days 11-18) **Parallel Development:** **Backend (Developer 1):** - Days 11-13: BLOG-005 - Post API (CRUD) - Days 14-15: BLOG-009 - Comment API - Days 16-17: BLOG-011 - User Profile API **Frontend (Developer 2):** - Days 11-12: BLOG-006 - Post List UI - Days 13-14: BLOG-007 - Post Detail UI - Days 15-16: BLOG-008 - Post Editor UI - Day 17: BLOG-010 - Comment UI **Integration (Both):** - Day 18: Integration testing ### Phase 5: Polish & Deploy (Days 19-21) **Developer 1:** - Day 19: BLOG-013 - SEO optimization - Day 20: BLOG-014 - Testing suite completion **Developer 2:** - Day 19: UI polish and accessibility - Day 20: Performance optimization **Both:** - Day 21: BLOG-015 - Deployment pipeline setup ### Complete Flow Visualization ```mermaid flowchart TB START([User: I want to build a blog platform]) subgraph "Phase 1: Architecture (Days 1-3)" WF1[Invoke: fullstack-greenfield workflow] A1[analyst: requirements-analysis.md] A2[js-solution-architect: tech-stack-decision.md] A3[js-solution-architect: system-architecture.md] A4[api-developer: api-specification.md] end subgraph "Phase 2: Planning (Day 4)" SM[scrum-master: Create 15 stories] TASK[Use: create-development-story task] TPL[Use: javascript-development-story template] CHK[Validate: story-dod-checklist] end subgraph "Phase 3-4: Development (Days 5-18)" DEV1[node-backend-developer
Backend stories] DEV2[react-developer
Frontend stories] CHK1[Validate: backend-checklist] CHK2[Validate: frontend-checklist] end subgraph "Phase 5: Deploy (Days 19-21)" OPT[Performance optimization] TEST[Complete testing] DEPLOY[Deploy to production] CHK3[Validate: deployment-readiness-checklist] end END([Blog Platform Live! 🎉]) START --> WF1 WF1 --> A1 --> A2 --> A3 --> A4 A4 --> SM SM --> TASK --> TPL --> CHK CHK --> DEV1 CHK --> DEV2 DEV1 --> CHK1 --> OPT DEV2 --> CHK2 --> OPT OPT --> TEST --> DEPLOY --> CHK3 --> END style START fill:#e8f5e9 style END fill:#c8e6c9 style WF1 fill:#5f27cd,color:#fff style DEV1 fill:#95e1d3 style DEV2 fill:#4ecdc4,color:#fff ``` ### Final Deliverables **Documentation:** - `requirements-analysis.md` (1,200 lines) - `technology-stack-decision.md` (300 lines) - `system-architecture.md` (2,500 lines) - `api-specification.md` (OpenAPI, 800 lines) - 15 implementation stories (avg 400 lines each = 6,000 lines) **Code:** - Backend: ~5,000 lines - Frontend: ~4,000 lines - Tests: ~3,000 lines - **Total:** ~12,000 lines of production code **Timeline:** - **21 days** with 2 developers working in parallel - Would be **35+ days** with sequential work - **40% time savings** from parallel development! --- ## Real-World Examples ### Example 1: Adding a Feature to Existing App **Scenario:** Add "dark mode" to existing blog platform #### Step 1: Feature Requirements (1 hour) ```bash *analyst I want to add dark mode to our blog platform. Users should be able to toggle between light and dark themes, and their preference should persist. ``` **Output:** `feature-requirements.md` #### Step 2: Technical Impact (30 minutes) ```bash *js-solution-architect Review the feature requirements and assess technical impact on our existing Next.js + Tailwind application. ``` **Output:** Impact assessment - Frontend changes: Theme context, toggle component, CSS updates - Backend changes: User preference storage (new column) - No API breaking changes #### Step 3: Create Story (1 hour) ```bash *scrum-master Use the create-development-story task to create an implementation story for dark mode feature. ``` **Output:** `BLOG-DM-001` story with: - Frontend: Theme provider, toggle component, CSS variables - Backend: Add `theme` column to User model - API: PATCH `/api/v1/users/me` to update theme preference - Testing: Theme switching, persistence, SSR compatibility #### Step 4: Implementation (1 day) ```bash # Frontend developer *react-developer Story: BLOG-DM-001 Implement dark mode toggle and theme provider. # Backend developer (parallel) *node-backend-developer Story: BLOG-DM-001 Add theme column to User model and update API. ``` **Result:** Dark mode complete in **1.5 days** (vs 3 days without BMAD) ### Example 2: TypeScript Migration **Scenario:** Migrate existing JavaScript codebase to TypeScript #### Step 1: Codebase Analysis ```bash *typescript-expert Analyze our JavaScript codebase and create a TypeScript migration strategy. Codebase details: - React frontend (CRA, 50 components) - Express backend (20 routes, 15 services) - No types currently ``` **Output:** Migration strategy document - Phase 1: Infrastructure (tsconfig, tooling) - Phase 2: Shared types and interfaces - Phase 3: Incremental file conversion - Phase 4: Strict mode enablement #### Step 2: Create Migration Stories ```bash *scrum-master Use the create-development-story task to create migration stories following the TypeScript expert's strategy. ``` **Output:** 12 migration stories - `TS-001`: TypeScript setup - `TS-002`: Shared type definitions - `TS-003-010`: Convert files (8 stories, parallel) - `TS-011`: Enable strict mode - `TS-012`: Fix strict mode issues #### Step 3: Parallel Migration (2 weeks) ```bash # Developer 1 *typescript-expert Stories: TS-003, TS-004, TS-005 # Developer 2 *typescript-expert Stories: TS-006, TS-007, TS-008 # Developer 3 *typescript-expert Stories: TS-009, TS-010 ``` **Result:** Full TypeScript migration in **2 weeks** with 3 developers ### Example 3: Performance Optimization **Scenario:** Blog platform is slow, needs optimization #### Step 1: Performance Analysis ```bash *js-solution-architect Our blog platform has performance issues: - Lighthouse score: 65 - LCP: 4.5s - Large bundle size: 850KB Analyze and create optimization plan. ``` **Output:** Optimization strategy 1. Frontend: Code splitting, image optimization, lazy loading 2. Backend: Database query optimization, caching, CDN 3. Metrics: Set up monitoring #### Step 2: Execute Performance Task ```bash *react-developer Use the performance-optimization task to optimize the frontend. Apply the performance-checklist. ``` **Agent actions:** 1. Analyzes bundle with webpack-bundle-analyzer 2. Implements code splitting for routes 3. Adds next/image for images 4. Lazy loads heavy components 5. Implements React.memo for expensive components 6. Validates with performance-checklist **Result:** - Lighthouse score: 65 → 94 - LCP: 4.5s → 2.1s - Bundle size: 850KB → 320KB --- ## Summary: How It All Works Together ```mermaid graph TB subgraph "User Interaction Layer" USER[Developer] end subgraph "BMAD Core" CORE[BMAD Engine] UI[Web UI / IDE Extension] end subgraph "Expansion Pack" CONFIG[config.yaml] subgraph "Execution" AGENTS[5 Specialized Agents] TEAMS[3 Agent Teams] WORKFLOWS[6 Workflows] end subgraph "Guidance" TASKS[6 Tasks] CHECKLISTS[8 Checklists] TEMPLATES[2 Templates] end subgraph "Knowledge" DATA[6 Reference Docs] end end subgraph "Outputs" DOCS[Documentation] CODE[Code] SPECS[Specifications] end USER -->|Requests| UI UI -->|Invokes| CORE CORE -->|Loads| CONFIG CONFIG -->|Registers| AGENTS CONFIG -->|Defines| TEAMS USER -->|Starts| WORKFLOWS WORKFLOWS -->|Execute via| AGENTS WORKFLOWS -->|Use| TASKS AGENTS -->|Follow| TASKS AGENTS -->|Fill| TEMPLATES AGENTS -->|Reference| DATA TASKS -->|Validate with| CHECKLISTS TEMPLATES -->|Validated by| CHECKLISTS AGENTS -->|Create| DOCS AGENTS -->|Generate| CODE AGENTS -->|Write| SPECS style USER fill:#e8f5e9 style CONFIG fill:#ff6b6b,color:#fff style AGENTS fill:#4ecdc4,color:#fff style WORKFLOWS fill:#5f27cd,color:#fff style DATA fill:#96ceb4 style DOCS fill:#fff9c4 style CODE fill:#c8e6c9 ``` ### The Complete Picture 1. **config.yaml** tells BMAD what this pack contains 2. **Agents** are specialized workers with domain expertise 3. **Agent Teams** bundle agents that work well together 4. **Workflows** provide step-by-step processes for common scenarios 5. **Tasks** are reusable procedures agents follow 6. **Checklists** validate quality at each step 7. **Templates** provide document structure 8. **Data** folder provides knowledge and best practices ### Key Principles ✅ **Modular** - Each component has a single purpose ✅ **Composable** - Components work together seamlessly ✅ **Reusable** - Tasks, checklists, templates used across workflows ✅ **Validated** - Quality gates at every step ✅ **Parallel** - Designed for concurrent development ✅ **Documented** - Everything is self-documenting ✅ **Extensible** - Easy to add new agents, workflows, etc. ### Benefits 🚀 **Speed** - 40% faster development with parallel work 🎯 **Quality** - Built-in validation and best practices 📚 **Consistency** - Templates and standards ensure uniformity 🧠 **Knowledge** - Data folder provides expert guidance 🤝 **Collaboration** - Clear handoffs and communication 📈 **Scalability** - Works for solo devs or large teams --- ## Conclusion The **bmad-javascript-fullstack** expansion pack is a **complete ecosystem** for modern JavaScript development. It combines: - **Specialized AI agents** that understand React, Node.js, TypeScript, and APIs - **Orchestrated workflows** that guide complex processes - **Quality gates** that ensure production-ready output - **Knowledge base** with industry best practices - **Parallel development** support for team efficiency Whether you're building a greenfield app, adding features, migrating to TypeScript, or optimizing performance, this expansion pack provides the structure, guidance, and automation to deliver high-quality software faster. --- **Version:** 1.0.1 **Last Updated:** 2024-10-01 **Maintained By:** BMAD Community