# CLAUDE.md - BMAD v6 Project Memory

## Project Identity
**Project Name**: [Your Project Name]
**Tech Stack**: Node.js 20+, Express, TypeScript, PostgreSQL, Jest
**Status**: Active Development
**Last Updated**: 2026-01-11

---

## 🎯 BMAD Agents & Their Roles (Never Deviate)

### Phase 1: Planning (Agentic Planning)
These agents create the **PRD** and **Architecture** documents:

- **Analyst Agent** (`/analyst`)
  - INPUT: User brief, business goals
  - OUTPUT: `docs/prd.md` (complete product requirements)
  - Role: Deep requirements analysis, user stories gathering

- **PM Agent** (`/pm`)
  - INPUT: PRD from Analyst
  - OUTPUT: Epic backlog + prioritized stories
  - Role: Refine PRD, create backlog for SM

- **Architect Agent** (`/architect`)
  - INPUT: PRD + tech preferences
  - OUTPUT: `docs/architecture.md` (system design, ADRs, constraints)
  - Role: Technical decisions, architecture patterns, tech stack alignment

### Phase 2: Development (Context-Engineered Development)
These agents consume Story Files (created by SM):

- **Scrum Master Agent** (`/sm`)
  - INPUT: Backlog from PM + Architecture from Architect
  - OUTPUT: `docs/stories/X.Y.story-name.md` (implementation-ready)
  - **CRITICAL**: SM embeds **full context** into each story:
    - Architecture Decision References (ADRs)
    - Acceptance Criteria (exact, testable)
    - Implementation Guidance
    - Dependencies & testing requirements
  - Role: Create stories that Dev agent can execute with **zero ambiguity**

- **Dev Agent** (`/dev`)
  - INPUT: A single Story File + referenced Architecture
  - OUTPUT: Code implementation + tests + PR
  - **CRITICAL**: Dev agent should ONLY read:
    1. The current story file (reference with `@docs/stories/X.Y.story-name.md`)
    2. Architecture from `docs/architecture.md` (or specific ADR)
    3. Tech Stack patterns from `/src` code
  - Role: Execute, don't invent

- **QA Agent** (`/qa`)
  - INPUT: Dev's implementation + story file
  - OUTPUT: Validation checklist, defect list or verification
  - Role: Validate against acceptance criteria

---

## 📂 Context Locations (Where Each Agent Reads/Writes)

### Agent Reads
| Agent | Reads From | Purpose |
|-------|-----------|---------|
| Analyst | Business brief (input by you) | Understand requirements |
| PM | Analyst's PRD | Create backlog |
| Architect | PRD + tech preferences | Design system |
| SM | Backlog + Architecture + code patterns | Create story specs |
| Dev | Story file + Architecture refs | Implement feature |
| QA | Story file + Dev output | Validate |

### Agent Writes
| Agent | Writes To | Format |
|-------|-----------|--------|
| Analyst | `docs/prd.md` | Markdown |
| PM | Backlog (in chat or `docs/epics.md`) | Markdown |
| Architect | `docs/architecture.md` | Markdown (with ADR sections) |
| SM | `docs/stories/X.Y.description.md` | Markdown (detailed specs) |
| Dev | `src/`, `tests/` | Code + Test files |
| QA | Validation in chat + update story status | Markdown checklist |

---

## 🏗️ Architecture Constraints (MUST NOT BREAK)

**These are decided once, NEVER change mid-project without team review:**

### API Design Pattern
- Gateway Pattern: Single entry point (`/api`)
- Routes: RESTful `/api/v1/[resource]/[action]`
- Authentication: JWT at Gateway level (not per-route)
- Error responses: Standardized JSON with `code`, `message`, `details`

### Database Layer
- ORM: Prisma (never raw SQL)
- Migrations: One per feature, committed to git
- Schema: Timestamps (`createdAt`, `updatedAt`) on all tables
- Transactions: Always wrap multi-step operations

### Async Processing
- Queue Library: Bull
- Message Broker: Redis
- Pattern: Email sends, notifications, heavy computation → queued
- Retry policy: 3 attempts, exponential backoff

### Authentication & Security
- Password hashing: bcrypt (library: bcryptjs)
- JWT signing key: Stored in `.env`, never in code
- CORS: Whitelist explicit domains
- Rate limiting: 100 req/minute per IP

### Testing
- Framework: Jest
- Coverage minimum: 80%
- Tests near code: `*.test.ts` in same folder as source
- Test data: Use fixtures in `tests/fixtures/`

### Code Style
- Language: TypeScript (strict mode always)
- Linter: ESLint + Prettier
- Commit format: `feat(module): description` or `fix(module): description`
- Branch strategy: Feature branches only, PR + review before merge

---

## 📝 Story File Structure (How SM Formats Each Story)

When SM creates a story, it MUST include ALL of this (Dev relies on it):

```markdown
# Story X.Y: [Feature Name]

## Objective
[One sentence: What we're building and why]

## Acceptance Criteria (Gherkin Format)
Given [context]
When [action]
Then [result]

[Repeat for each criterion]

## Architecture References
- See: docs/architecture.md → "API Design Pattern" section
- See: docs/architecture.md → "Authentication" ADR
- Pattern used: [Specific pattern name]

## Implementation Guidance
- Files to create: [list]
- Files to modify: [list]
- Patterns to follow: [reference code examples]
- Tests required: [specific test cases]

## Dependencies
- Depends on: Story X.Y (must be DONE first)
- Blocks: Story X.Z (cannot start until this is merged)

## Definition of Done
- [ ] Code passes linter (ESLint)
- [ ] Tests written & passing (Jest, >80% for this file)
- [ ] Database migration added (if needed)
- [ ] Story status updated in docs/stories/
- [ ] PR created with reference to this story