ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/expansion-packs/bmad-javascript-fullstack/BMAD-COMPLETE-GUIDE.md

2281 lines
60 KiB
Markdown
Raw Blame History

# 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<br/>🏗️ Architecture & Design]
REACT[react-developer<br/>⚛️ Frontend Development]
NODE[node-backend-developer<br/>🟢 Backend Development]
API[api-developer<br/>🌐 API Design]
TS[typescript-expert<br/>📘 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
# <!-- Powered by BMAD™ Core -->
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
# <!-- Powered by BMAD™ Core -->
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
# <!-- Powered by BMAD™ Core -->
# 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
# <!-- Powered by BMAD™ Core -->
# 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<br/>Frontend]
DEV2[Developer 2<br/>Backend]
DEV3[Developer 3<br/>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 onSubmit={handleSubmit}>
{/* Form fields */}
</form>
)
}
```
**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<br/>Backend stories]
DEV2[react-developer<br/>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
View Git Blame Copy Permalink