aiag-cli 2.2.2 → 2.3.0

package/templates/skills/prd-taskmaster/templates/taskmaster-prd-comprehensive.md

@@ -0,0 +1,983 @@
+# PRD: [Feature/Product Name]
+
+**Author:** [Name]
+**Date:** [YYYY-MM-DD]
+**Status:** Draft | In Review | Approved
+**Version:** 1.0
+**Taskmaster Optimized:** Yes
+
+---
+
+## Table of Contents
+
+1. [Executive Summary](#executive-summary)
+2. [Problem Statement](#problem-statement)
+3. [Goals & Success Metrics](#goals--success-metrics)
+4. [User Stories](#user-stories)
+5. [Functional Requirements](#functional-requirements)
+6. [Non-Functional Requirements](#non-functional-requirements)
+7. [Technical Considerations](#technical-considerations)
+8. [Implementation Roadmap](#implementation-roadmap)
+9. [Out of Scope](#out-of-scope)
+10. [Open Questions & Risks](#open-questions--risks)
+11. [Validation Checkpoints](#validation-checkpoints)
+12. [Appendix: Task Breakdown Hints](#appendix-task-breakdown-hints)
+
+---
+
+## Executive Summary
+
+[2-3 sentences: What problem are we solving + proposed solution + expected impact]
+
+Example:
+> Users currently cannot authenticate securely, leading to 15% account compromise rate. We're implementing two-factor authentication (2FA) via SMS and authenticator apps, which should reduce compromises to <1% within 3 months of launch.
+
+---
+
+## Problem Statement
+
+### Current Situation
+[Describe what exists today and what's wrong with it]
+
+### User Impact
+- **Who is affected:** [User segment(s)]
+- **How they're affected:** [Specific pain points]
+- **Severity:** [Critical/High/Medium - with evidence/data]
+
+### Business Impact
+- **Cost of problem:** [Quantify: lost revenue, support tickets, churn]
+- **Opportunity cost:** [What we're missing by not solving this]
+- **Strategic importance:** [How this aligns with company goals]
+
+### Why Solve This Now?
+[Timing, market conditions, competitive pressure, technical readiness]
+
+---
+
+## Goals & Success Metrics
+
+### Goal 1: [Primary Goal]
+- **Description:** [What we're trying to achieve]
+- **Metric:** [How we measure success]
+- **Baseline:** [Current value with source]
+- **Target:** [Goal value]
+- **Timeframe:** [When we expect to achieve this]
+- **Measurement Method:** [How we'll track: analytics, surveys, logs]
+
+**Example:**
+```
+Goal: Reduce account security incidents
+Metric: Number of compromised accounts per month
+Baseline: 150 incidents/month (average last 6 months)
+Target: <10 incidents/month (93% reduction)
+Timeframe: 3 months post-launch
+Measurement: Security incident logs + user reports
+```
+
+### Goal 2: [Secondary Goal]
+- **Description:** [What we're trying to achieve]
+- **Metric:** [How we measure success]
+- **Baseline:** [Current value]
+- **Target:** [Goal value]
+- **Timeframe:** [When]
+- **Measurement Method:** [How]
+
+### Goal 3: [Tertiary Goal]
+[Repeat structure]
+
+---
+
+## User Stories
+
+### Story 1: [Feature Name]
+
+**As a** [user type],
+**I want to** [action],
+**So that I can** [benefit/outcome].
+
+**Acceptance Criteria:**
+- [ ] [Specific, testable criterion 1]
+- [ ] [Specific, testable criterion 2]
+- [ ] [Specific, testable criterion 3]
+- [ ] [Edge case criterion]
+- [ ] [Error handling criterion]
+
+**Task Breakdown Hint:**
+- Task 1.1: [Implementation step] (~4 hours)
+- Task 1.2: [Implementation step] (~6 hours)
+- Task 1.3: [Testing] (~2 hours)
+
+**Dependencies:** [None | REQ-XXX | Story Y]
+
+**Example:**
+```
+Story: User enables 2FA
+
+As a registered user,
+I want to enable two-factor authentication on my account,
+So that I can protect my account from unauthorized access.
+
+Acceptance Criteria:
+- [ ] User can access 2FA setup from account settings
+- [ ] System supports both SMS and authenticator app methods
+- [ ] User must verify phone number before enabling SMS 2FA
+- [ ] System generates QR code for authenticator app setup
+- [ ] User must successfully verify 2FA code before it's fully enabled
+- [ ] System provides backup codes (10) for account recovery
+- [ ] User receives confirmation email when 2FA is enabled
+
+Task Breakdown Hint:
+- Task 1.1: Create 2FA settings UI component (4h)
+- Task 1.2: Implement SMS verification flow (6h)
+- Task 1.3: Implement TOTP/authenticator app flow (6h)
+- Task 1.4: Generate and store backup codes (3h)
+- Task 1.5: Add 2FA verification to login flow (5h)
+- Task 1.6: Write tests for 2FA flows (4h)
+
+Dependencies: REQ-001 (user authentication must exist)
+```
+
+---
+
+### Story 2: [Feature Name]
+[Repeat structure]
+
+---
+
+### Story 3: [Feature Name]
+[Repeat structure]
+
+---
+
+## Functional Requirements
+
+### Must Have (P0) - Critical for Launch
+
+#### REQ-001: [Requirement Title]
+**Description:** [Detailed description of what the system must do]
+
+**Acceptance Criteria:**
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+- [ ] [Specific, testable criterion]
+
+**Technical Specification:**
+```
+[Code example, API spec, or detailed technical description]
+```
+
+**Task Breakdown:**
+- Implement [component]: Small (2-4h)
+- Add [functionality]: Medium (4-8h)
+- Test [feature]: Small (2-4h)
+
+**Dependencies:** [None | REQ-XXX | External service Y]
+
+**Example:**
+```
+REQ-001: User Authentication with 2FA
+
+Description: System must authenticate users via username/password and require 2FA verification when enabled on the account.
+
+Acceptance Criteria:
+- [ ] POST /api/auth/login accepts email and password
+- [ ] Returns JWT token if credentials valid and 2FA not enabled
+- [ ] Returns 2FA challenge if credentials valid and 2FA enabled
+- [ ] POST /api/auth/verify-2fa accepts 2FA code and returns JWT if valid
+- [ ] Invalid 2FA code returns 401 with clear error message
+- [ ] Failed attempts are rate-limited (5 attempts per 15 minutes)
+- [ ] 2FA codes expire after 30 seconds (TOTP standard)
+
+Technical Specification:
+```typescript
+// POST /api/auth/login
+interface LoginRequest {
+  email: string;
+  password: string;
+}
+
+interface LoginResponse {
+  requires2FA: boolean;
+  token?: string;           // Only if 2FA not required
+  challenge?: string;       // Only if 2FA required
+  expiresAt?: number;
+}
+
+// POST /api/auth/verify-2fa
+interface Verify2FARequest {
+  challenge: string;
+  code: string;             // 6-digit TOTP code
+}
+
+interface Verify2FAResponse {
+  token: string;
+  expiresAt: number;
+}
+```
+
+Task Breakdown:
+- Implement login endpoint with password verification: Medium (6h)
+- Add 2FA challenge generation logic: Small (3h)
+- Implement 2FA verification endpoint: Medium (5h)
+- Add rate limiting middleware: Small (2h)
+- Write unit tests for auth flows: Medium (4h)
+- Write integration tests: Small (3h)
+
+Dependencies: None (can start immediately)
+```
+
+---
+
+#### REQ-002: [Requirement Title]
+[Repeat structure]
+
+---
+
+### Should Have (P1) - Important but Not Blocking
+
+#### REQ-005: [Requirement Title]
+[Repeat structure]
+
+---
+
+### Nice to Have (P2) - Future Enhancement
+
+#### REQ-008: [Requirement Title]
+[Repeat structure]
+
+---
+
+## Non-Functional Requirements
+
+### Performance
+
+**Response Time:**
+- API endpoints: < 200ms for 95th percentile
+- Database queries: < 100ms for single-record lookups
+- Page load time: < 2 seconds on 4G connection
+
+**Throughput:**
+- Handle 1,000 requests/second under normal load
+- Scale to 5,000 requests/second during peak (with auto-scaling)
+
+**Resource Usage:**
+- Memory: < 512MB per server instance
+- CPU: < 60% average utilization
+- Database connections: < 50 per instance
+
+---
+
+### Security
+
+**Authentication:**
+- JWT tokens with 24-hour expiration
+- Refresh tokens with 30-day expiration
+- Secure token storage (httpOnly cookies or secure storage)
+
+**Authorization:**
+- Role-based access control (RBAC)
+- Principle of least privilege
+- Audit logging for sensitive operations
+
+**Data Protection:**
+- Passwords hashed with bcrypt (cost factor 12)
+- 2FA secrets encrypted at rest (AES-256)
+- PII encrypted in database
+- TLS 1.3 for all connections
+
+**Compliance:**
+- GDPR: Right to erasure, data portability
+- CCPA: Data disclosure requirements
+- SOC 2: Audit logging, access controls
+
+---
+
+### Scalability
+
+**User Load:**
+- Support 100,000 active users initially
+- Scale to 1M users within 6 months
+- Horizontal scaling via containerization (Kubernetes)
+
+**Data Volume:**
+- Initial: 1GB database size
+- Growth: ~100MB/month
+- Retention: 7 years (compliance requirement)
+
+**Geographic Distribution:**
+- Primary: US-East
+- Replicas: US-West, EU-West (future)
+- CDN for static assets
+
+---
+
+### Reliability
+
+**Uptime:**
+- SLA: 99.9% monthly uptime (< 43 minutes downtime/month)
+- RTO (Recovery Time Objective): < 1 hour
+- RPO (Recovery Point Objective): < 15 minutes
+
+**Error Handling:**
+- Error rate: < 0.1% of requests
+- Graceful degradation (2FA optional if service down)
+- Circuit breaker for external dependencies
+
+**Monitoring:**
+- Health checks every 30 seconds
+- Alert on error rate > 1%
+- Dashboard for key metrics
+
+---
+
+### Accessibility
+
+**Standards:**
+- WCAG 2.1 Level AA compliance
+- Keyboard navigation for all features
+- Screen reader support (ARIA labels)
+
+**Testing:**
+- Automated accessibility testing (axe-core)
+- Manual testing with screen readers
+- Color contrast ratio ≥ 4.5:1
+
+---
+
+### Compatibility
+
+**Browsers:**
+- Chrome (last 2 versions)
+- Firefox (last 2 versions)
+- Safari (last 2 versions)
+- Edge (last 2 versions)
+
+**Devices:**
+- Desktop: Windows, macOS, Linux
+- Mobile: iOS 14+, Android 10+
+- Tablet: iPad, Android tablets
+
+**Responsive Design:**
+- Breakpoints: 320px, 768px, 1024px, 1440px
+- Mobile-first approach
+
+---
+
+## Technical Considerations
+
+### System Architecture
+
+**Current Architecture:**
+[If existing system, describe current architecture]
+
+**Proposed Changes:**
+[How this feature integrates with or changes the architecture]
+
+**Diagram:**
+```
+[ASCII diagram or reference to external diagram]
+
+┌─────────┐      ┌──────────────┐      ┌──────────┐
+│ Client  │─────>│   API GW     │─────>│  Auth    │
+│         │<─────│              │<─────│  Service │
+└─────────┘      └──────────────┘      └──────────┘
+                        │                    │
+                        v                    v
+                 ┌──────────────┐      ┌──────────┐
+                 │   Database   │      │  Redis   │
+                 │   (Users)    │      │  (Sessions)
+                 └──────────────┘      └──────────┘
+```
+
+**Key Components:**
+1. **Auth Service:** Handles authentication, 2FA verification
+2. **SMS Provider:** Twilio for SMS code delivery
+3. **Redis:** Session storage, rate limiting
+4. **Database:** User credentials, 2FA secrets
+
+---
+
+### API Specifications
+
+#### Endpoint: Create User
+```
+POST /api/v1/users
+
+Headers:
+  Content-Type: application/json
+
+Request:
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "profile": {
+    "firstName": "Jane",
+    "lastName": "Doe"
+  }
+}
+
+Response (201 Created):
+{
+  "id": "uuid-1234-5678",
+  "email": "user@example.com",
+  "profile": {
+    "firstName": "Jane",
+    "lastName": "Doe"
+  },
+  "createdAt": "2025-01-15T10:30:00Z",
+  "2faEnabled": false
+}
+
+Error (400 Bad Request):
+{
+  "error": "INVALID_EMAIL",
+  "message": "Email format is invalid",
+  "field": "email"
+}
+
+Error (409 Conflict):
+{
+  "error": "EMAIL_EXISTS",
+  "message": "User with this email already exists"
+}
+```
+
+#### Endpoint: Enable 2FA
+```
+POST /api/v1/users/me/2fa/enable
+
+Headers:
+  Authorization: Bearer {jwt_token}
+  Content-Type: application/json
+
+Request:
+{
+  "method": "totp",  // or "sms"
+  "phoneNumber": "+1234567890"  // required if method=sms
+}
+
+Response (200 OK):
+{
+  "method": "totp",
+  "secret": "BASE32ENCODEDSECRET",
+  "qrCode": "data:image/png;base64,...",
+  "backupCodes": [
+    "1234-5678-9012",
+    "2345-6789-0123",
+    ...
+  ]
+}
+```
+
+[Add more endpoints as needed]
+
+---
+
+### Database Schema
+
+**New Tables:**
+
+```sql
+-- 2FA configuration table
+CREATE TABLE user_2fa (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  method VARCHAR(10) NOT NULL CHECK (method IN ('sms', 'totp')),
+  secret_encrypted VARCHAR(255) NOT NULL,  -- Encrypted 2FA secret
+  phone_number VARCHAR(20),  -- For SMS method
+  enabled BOOLEAN DEFAULT false,
+  verified_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW(),
+  updated_at TIMESTAMP DEFAULT NOW(),
+  UNIQUE(user_id)
+);
+
+CREATE INDEX idx_user_2fa_user_id ON user_2fa(user_id);
+
+-- Backup codes table
+CREATE TABLE backup_codes (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
+  code_hash VARCHAR(255) NOT NULL,  -- bcrypt hash of code
+  used_at TIMESTAMP,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_backup_codes_user_id ON backup_codes(user_id);
+CREATE INDEX idx_backup_codes_used ON backup_codes(used_at) WHERE used_at IS NULL;
+```
+
+**Modified Tables:**
+
+```sql
+-- Add 2FA tracking to users table
+ALTER TABLE users ADD COLUMN two_factor_enabled BOOLEAN DEFAULT false;
+ALTER TABLE users ADD COLUMN last_2fa_verified_at TIMESTAMP;
+
+CREATE INDEX idx_users_2fa_enabled ON users(two_factor_enabled);
+```
+
+---
+
+### Technology Stack
+
+**Frontend:**
+- [Framework: React, Vue, etc.]
+- [State management: Redux, Vuex, etc.]
+- [UI Library: Material-UI, Tailwind, etc.]
+
+**Backend:**
+- [Runtime: Node.js, Python, etc.]
+- [Framework: Express, FastAPI, etc.]
+- [ORM: Prisma, SQLAlchemy, etc.]
+
+**Database:**
+- [Primary: PostgreSQL, MySQL, etc.]
+- [Cache: Redis, Memcached]
+
+**Infrastructure:**
+- [Cloud: AWS, GCP, Azure]
+- [Container: Docker, Kubernetes]
+- [CI/CD: GitHub Actions, Jenkins, etc.]
+
+---
+
+### External Dependencies
+
+**Third-Party Services:**
+1. **Twilio (SMS):**
+   - Purpose: Send 2FA codes via SMS
+   - API: https://www.twilio.com/docs/sms
+   - Rate Limits: 100 messages/second
+   - Fallback: If down, disable SMS 2FA temporarily
+
+2. **[Service Name]:**
+   - Purpose: [What it does]
+   - Integration: [How we integrate]
+   - Failure handling: [What happens if it fails]
+
+**Internal Dependencies:**
+- **User Service:** Must exist (provides user authentication)
+- **Email Service:** For 2FA setup notifications
+- **Analytics Service:** For tracking 2FA adoption
+
+---
+
+### Migration Strategy
+
+**For Existing Systems:**
+
+1. **Phase 1: Deploy Schema Changes**
+   ```bash
+   # Run migration (zero-downtime)
+   npm run migrate:up
+   ```
+
+2. **Phase 2: Deploy Code (Feature Flag Disabled)**
+   - Deploy new code with 2FA feature flag OFF
+   - Verify no regressions
+
+3. **Phase 3: Enable for Beta Users**
+   - Enable feature flag for 5% of users
+   - Monitor metrics and errors
+
+4. **Phase 4: Gradual Rollout**
+   - 25% → 50% → 100% over 2 weeks
+   - Monitor each phase
+
+5. **Phase 5: Encourage Adoption**
+   - Email campaign to remaining users
+   - In-app prompts to enable 2FA
+
+**Rollback Plan:**
+- Disable feature flag immediately
+- No database rollback needed (backward compatible)
+
+---
+
+### Testing Strategy
+
+**Unit Tests:**
+- Test coverage: > 80%
+- Key areas:
+  - 2FA code generation and validation
+  - Token creation and verification
+  - Error handling
+
+**Integration Tests:**
+- Full authentication flows:
+  - Login without 2FA
+  - Login with 2FA (SMS)
+  - Login with 2FA (TOTP)
+  - Backup code usage
+  - Rate limiting
+
+**E2E Tests:**
+- User journeys:
+  - New user enables 2FA
+  - Existing user adds 2FA
+  - User loses device, uses backup code
+  - User disables 2FA
+
+**Performance Tests:**
+- Load test: 1000 concurrent logins
+- Stress test: 5000 requests/second
+- Endurance test: 24-hour sustained load
+
+**Security Tests:**
+- Penetration testing
+- OWASP Top 10 validation
+- Brute force protection testing
+
+---
+
+## Implementation Roadmap
+
+### Phase 1: Foundation (Week 1-2)
+**Goal:** Database, basic API structure, 2FA code generation
+
+**Tasks:**
+- [x] Task 1.1: Create database schema (REQ-001)
+  - Complexity: Small (3h)
+  - Dependencies: None
+  - Owner: Backend team
+
+- [x] Task 1.2: Implement 2FA secret generation (REQ-002)
+  - Complexity: Small (2h)
+  - Dependencies: Task 1.1
+  - Owner: Backend team
+
+- [x] Task 1.3: Implement TOTP validation logic (REQ-003)
+  - Complexity: Medium (5h)
+  - Dependencies: Task 1.2
+  - Owner: Backend team
+
+**Validation Checkpoint:** Can generate and validate TOTP codes
+
+---
+
+### Phase 2: Core Features (Week 3-4)
+**Goal:** Enable 2FA setup, login verification
+
+**Tasks:**
+- [ ] Task 2.1: Build 2FA setup UI (REQ-004)
+  - Complexity: Medium (8h)
+  - Dependencies: Phase 1 complete
+  - Owner: Frontend team
+
+- [ ] Task 2.2: Implement enable 2FA API endpoint (REQ-005)
+  - Complexity: Medium (6h)
+  - Dependencies: Phase 1 complete
+  - Owner: Backend team
+
+- [ ] Task 2.3: Add 2FA verification to login flow (REQ-006)
+  - Complexity: Large (10h)
+  - Dependencies: Task 2.2
+  - Owner: Full-stack team
+
+- [ ] Task 2.4: Generate and store backup codes (REQ-007)
+  - Complexity: Small (4h)
+  - Dependencies: Task 2.2
+  - Owner: Backend team
+
+**Validation Checkpoint:** Users can enable 2FA and use it to login
+
+---
+
+### Phase 3: SMS Support (Week 5)
+**Goal:** Add SMS 2FA method
+
+**Tasks:**
+- [ ] Task 3.1: Integrate Twilio API (REQ-008)
+  - Complexity: Medium (6h)
+  - Dependencies: Phase 2 complete
+  - Owner: Backend team
+
+- [ ] Task 3.2: Implement SMS code delivery (REQ-009)
+  - Complexity: Medium (5h)
+  - Dependencies: Task 3.1
+  - Owner: Backend team
+
+- [ ] Task 3.3: Add SMS option to 2FA setup UI (REQ-010)
+  - Complexity: Small (4h)
+  - Dependencies: Task 3.1
+  - Owner: Frontend team
+
+**Validation Checkpoint:** Users can enable and use SMS 2FA
+
+---
+
+### Phase 4: Testing & Polish (Week 6)
+**Goal:** Comprehensive testing, bug fixes, performance optimization
+
+**Tasks:**
+- [ ] Task 4.1: Write comprehensive test suite
+  - Complexity: Large (12h)
+  - Dependencies: Phase 3 complete
+  - Owner: QA team
+
+- [ ] Task 4.2: Performance testing and optimization
+  - Complexity: Medium (8h)
+  - Dependencies: Task 4.1
+  - Owner: Backend team
+
+- [ ] Task 4.3: Security audit and penetration testing
+  - Complexity: Large (16h)
+  - Dependencies: Task 4.1
+  - Owner: Security team
+
+- [ ] Task 4.4: Bug fixes from testing
+  - Complexity: Variable
+  - Dependencies: Tasks 4.1-4.3
+  - Owner: All teams
+
+**Validation Checkpoint:** All tests passing, no critical bugs
+
+---
+
+### Phase 5: Deployment & Rollout (Week 7-8)
+**Goal:** Gradual rollout to production
+
+**Tasks:**
+- [ ] Task 5.1: Deploy to staging
+- [ ] Task 5.2: Enable for 5% of users (beta)
+- [ ] Task 5.3: Monitor and adjust
+- [ ] Task 5.4: Rollout to 25% of users
+- [ ] Task 5.5: Rollout to 50% of users
+- [ ] Task 5.6: Rollout to 100% of users
+- [ ] Task 5.7: Launch communication campaign
+
+**Validation Checkpoint:** Successful production deployment, metrics improving
+
+---
+
+### Task Dependencies Visualization
+
+```
+Phase 1 (Foundation):
+  1.1 (Schema) → 1.2 (Secret Gen) → 1.3 (TOTP Validation)
+
+Phase 2 (Core Features):
+  1.3 → 2.2 (Enable API) → 2.3 (Login Verification)
+  1.3 → 2.1 (Setup UI)
+  2.2 → 2.4 (Backup Codes)
+
+Phase 3 (SMS):
+  2.2 → 3.1 (Twilio) → 3.2 (SMS Delivery)
+  3.1 → 3.3 (SMS UI)
+
+Phase 4 (Testing):
+  Phase 3 → 4.1 (Tests) → 4.2 (Performance) & 4.3 (Security) → 4.4 (Fixes)
+
+Phase 5 (Deployment):
+  Phase 4 → 5.1 → 5.2 → 5.3 → 5.4 → 5.5 → 5.6 → 5.7
+
+Critical Path: 1.1 → 1.2 → 1.3 → 2.2 → 2.3 → 3.1 → 3.2 → 4.1 → 4.4 → 5.7
+```
+
+---
+
+### Effort Estimation
+
+**Total Estimated Effort:**
+- Phase 1: 10 hours
+- Phase 2: 28 hours
+- Phase 3: 15 hours
+- Phase 4: 36 hours
+- Phase 5: 20 hours (includes monitoring)
+- **Total: ~109 hours** (~3 weeks with 2-person team)
+
+**Risk Buffer:** +20% (22 hours) for unknowns
+**Final Estimate:** ~130 hours (~4 weeks)
+
+---
+
+## Out of Scope
+
+Explicitly NOT included in this release:
+
+1. **Biometric Authentication** (fingerprint, Face ID)
+   - Reason: Different security model, requires mobile app
+   - Future: Consider for v2.0
+
+2. **Hardware Security Keys** (YubiKey, etc.)
+   - Reason: Low user demand (< 5% requested)
+   - Future: Evaluate after 2FA adoption metrics
+
+3. **Multi-Device 2FA Management**
+   - Reason: Complexity, can add later
+   - Workaround: Users can disable and re-enable to change device
+
+4. **2FA Recovery Without Backup Codes**
+   - Reason: Security risk
+   - Users must save backup codes or contact support
+
+5. **Admin-Enforced 2FA**
+   - Reason: Optional for v1.0
+   - Future: Add organization-level policies in v2.0
+
+---
+
+## Open Questions & Risks
+
+### Open Questions
+
+#### Q1: Should we require 2FA for all admin users?
+- **Current Status:** Optional for all users
+- **Options:** (A) Keep optional, (B) Require for admins only, (C) Require for all users
+- **Owner:** Product team
+- **Deadline:** Week 2 (before Phase 2 starts)
+- **Impact:** Medium (affects UI flow and enforcement logic)
+
+#### Q2: What's the SMS provider SLA and cost?
+- **Current Status:** Researching Twilio alternatives
+- **Options:** (A) Twilio, (B) AWS SNS, (C) Vonage
+- **Owner:** DevOps team
+- **Deadline:** Week 4 (before Phase 3)
+- **Impact:** Low (implementation similar across providers)
+
+#### Q3: Should we support international phone numbers for SMS?
+- **Current Status:** Twilio supports it, but adds cost
+- **Options:** (A) US only, (B) All countries, (C) Tier 1 countries only
+- **Owner:** Business team (cost analysis)
+- **Deadline:** Week 4
+- **Impact:** Medium (affects user experience for international users)
+
+---
+
+### Risks & Mitigation
+
+| Risk | Likelihood | Impact | Severity | Mitigation | Contingency |
+|------|------------|--------|----------|------------|-------------|
+| SMS delivery failures | High | High | **Critical** | Use reliable provider (Twilio), implement retry logic | Fall back to TOTP, provide clear error messages |
+| Users lose 2FA device and backup codes | Medium | High | **High** | Educate users about backup codes, support recovery process | Manual verification by support team |
+| Performance degradation on login | Low | Medium | **Medium** | Load testing, caching, optimize DB queries | Feature flag to disable temporarily |
+| Security vulnerability discovered | Low | Critical | **High** | Security audit, pen testing, follow OWASP best practices | Patch immediately, coordinate disclosure |
+| Low adoption rate (< 20%) | Medium | Medium | **Medium** | In-app prompts, email campaign, incentivize adoption | Gather feedback, improve UX |
+
+---
+
+## Validation Checkpoints
+
+### Checkpoint 1: End of Phase 1
+**Criteria:**
+- [ ] Database schema deployed to staging
+- [ ] TOTP generation and validation working
+- [ ] Unit tests passing (> 80% coverage for new code)
+
+**If Failed:** Revisit schema design, fix validation logic before continuing
+
+---
+
+### Checkpoint 2: End of Phase 2
+**Criteria:**
+- [ ] Users can enable 2FA via UI
+- [ ] Login flow requires 2FA verification
+- [ ] Backup codes generated and functional
+- [ ] Integration tests passing
+
+**If Failed:** Address UX issues, fix login flow bugs, don't proceed to SMS
+
+---
+
+### Checkpoint 3: End of Phase 3
+**Criteria:**
+- [ ] SMS codes delivered successfully (> 95% success rate)
+- [ ] Users can choose TOTP or SMS method
+- [ ] All features working in staging
+
+**If Failed:** Debug SMS integration, consider alternative provider
+
+---
+
+### Checkpoint 4: End of Phase 4
+**Criteria:**
+- [ ] All tests passing (unit, integration, E2E)
+- [ ] Performance benchmarks met (< 200ms p95)
+- [ ] Security audit complete with no critical findings
+- [ ] Zero known critical bugs
+
+**If Failed:** Fix bugs and re-test before deployment
+
+---
+
+### Checkpoint 5: Production Rollout
+**Criteria (at each rollout stage):**
+- [ ] Error rate < 0.1%
+- [ ] No degradation in login success rate
+- [ ] 2FA verification success rate > 95%
+- [ ] No increase in support tickets
+
+**If Failed:** Rollback, investigate issues, fix before next stage
+
+---
+
+## Appendix: Task Breakdown Hints
+
+### Suggested Taskmaster Task Structure
+
+**Setup & Infrastructure (3 tasks, ~10 hours)**
+1. Database migration for 2FA tables (3h)
+2. Set up environment variables and secrets (2h)
+3. Configure SMS provider (Twilio) integration (5h)
+
+**Backend Implementation (8 tasks, ~45 hours)**
+4. Implement TOTP secret generation (2h)
+5. Implement TOTP code validation (5h)
+6. Build enable 2FA API endpoint (6h)
+7. Build verify 2FA API endpoint (5h)
+8. Implement backup code generation (4h)
+9. Add 2FA verification to login flow (10h)
+10. Implement SMS code delivery (5h)
+11. Add rate limiting middleware (3h)
+12. Build disable 2FA API endpoint (5h)
+
+**Frontend Implementation (6 tasks, ~30 hours)**
+13. Create 2FA setup page UI (8h)
+14. Build QR code display component (3h)
+15. Create SMS phone verification flow (6h)
+16. Add 2FA verification step to login (6h)
+17. Build backup codes display/download (4h)
+18. Add 2FA management to account settings (3h)
+
+**Testing (5 tasks, ~24 hours)**
+19. Write unit tests for backend logic (8h)
+20. Write integration tests for API endpoints (6h)
+21. Write E2E tests for user flows (6h)
+22. Performance testing (4h)
+
+**Documentation & Deployment (4 tasks, ~10 hours)**
+23. Write API documentation (3h)
+24. Create user guide for 2FA setup (2h)
+25. Deploy to staging (2h)
+26. Production rollout and monitoring (3h)
+
+**Total: 26 tasks, ~119 hours**
+
+### Parallelizable Tasks
+
+**Can work in parallel:**
+- Backend tasks (4-12) and Frontend tasks (13-18) can run concurrently
+- Testing tasks (19-21) can run concurrently once implementation done
+- Documentation (23-24) can start during testing phase
+
+**Must be sequential:**
+- Setup (1-3) → Implementation (4-18) → Testing (19-22) → Deployment (23-26)
+
+### Critical Path Tasks
+1. Database migration (1)
+2. TOTP generation (4)
+3. TOTP validation (5)
+4. Enable 2FA endpoint (6)
+5. Verify 2FA endpoint (7)
+6. Add 2FA to login (9)
+7. Testing (19-22)
+8. Deployment (25-26)
+
+**Critical path duration:** ~55 hours (~2 weeks with full-time dev)
+
+---
+
+**End of PRD**
+
+*This PRD is optimized for taskmaster AI task generation. All requirements include task breakdown hints, complexity estimates, and dependency mapping to enable effective automated task planning.*