plans/
├── .gitignore              # Exclude plans from git (optional)
├── README.md              # How to use plans directory
│
├── jwt-authentication/     # Feature 1
│   ├── plan.md            # Planning phase (Athena)
│   ├── phase-1-complete.md
│   ├── phase-2-complete.md
│   ├── phase-3-complete.md
│   └── complete.md        # Final summary (Mnemosyne)
│
├── email-verification/     # Feature 2
│   ├── plan.md
│   ├── phase-1-complete.md
│   ├── phase-2-complete.md
│   └── complete.md
│
├── payment-integration/    # Feature 3
│   ├── plan.md
│   ├── phase-1-complete.md
│   ├── phase-2-complete.md
│   ├── phase-3-complete.md
│   ├── phase-4-complete.md
│   └── complete.md

# Feature: [Feature Name]

**Status:** APPROVED by [user/team] on [date]  
**Estimated Duration:** [X hours/days]  
**Archive Date:** [When will this feature be "done"?]

## Overview

[2-3 sentence summary of feature purpose and user value]

**Why:** [Business/user value]  
**Scope:** [What's included, what's NOT included]  
**Out of Scope:** [Explicitly list what NOT to do]

---

## Architecture Overview

[Brief architecture description]

**Technology Stack:**
- Backend: FastAPI, SQLAlchemy, PostgreSQL
- Frontend: React 18, TypeScript, Vite
- Database: PostgreSQL 14+
- Testing: pytest, vitest

**Key Design Decisions:**
- Decision 1: [Why we chose this]
- Decision 2: [Alternative considered, why rejected]

---

## Implementation Phases (TDD-Driven)

### Phase 1: Database Schema
**Duration:** ~1-2 hours  
**Owner:** Maat  
**Files to create/modify:**
- `migrations/001_create_jwt_tokens.py` (new)
- `models/JWTToken.py` (new)
- `tests/test_jwt_token_model.py` (new)

**Test Requirements (RED phase):**

**Acceptance Criteria:**
- ✅ Migration applies cleanly (up + down)
- ✅ Schema matches diagram below
- ✅ Coverage >80%

**Potential Risks:**
- Risk: Database lock during migration
- Mitigation: Use zero-downtime expand-contract strategy

---

### Phase 2: Backend Services
**Duration:** ~2-3 hours  
**Owner:** Hermes  
**Files to create/modify:**
- `services/JWTService.py` (new)
- `services/AuthService.py` (modify)
- `endpoints/auth.py` (modify)
- `tests/test_jwt_service.py` (new)
- `tests/test_auth_endpoints.py` (modify)

**Test Requirements (RED phase):**

**API Contracts:**

**Acceptance Criteria:**
- ✅ All 8 test cases passing
- ✅ Coverage >80%
- ✅ Security: No secrets in logs
- ✅ Performance: Token verify <10ms

**Potential Risks:**
- Risk: Token expiry race condition
- Mitigation: Use server time, not client time

---

### Phase 3: Frontend Integration
**Duration:** ~2-3 hours  
**Owner:** Athena  
**Files to create/modify:**
- `components/LoginForm.tsx` (new)
- `hooks/useAuth.ts` (modify)
- `utils/tokenStorage.ts` (new)
- `tests/LoginForm.test.tsx` (new)
- `tests/useAuth.test.ts` (modify)

**Test Requirements (RED phase):**

**Component Contracts:**
```typescript
// LoginForm.tsx
interface LoginFormProps {
  onLoginSuccess: () => void;
  onError?: (error: string) => void;
}

// useAuth.ts
interface AuthState {
  isLoggedIn: boolean;
  user?: User;
  login: (email: string, password: string) => Promise<void>;
  logout: () => void;
  refreshToken: () => Promise<void>;
}

After each phase completes:

Phase Complete
    ↓
Temis Review:
  ✓ Coverage >80%?
  ✓ Security pass?
  ✓ Tests all green?
    ↓
  ✅ APPROVED → Next phase
  ❌ BLOCKED  → Fix + retry

**plan.md Checklist:**
- ✅ Overview is clear & reasons explained
- ✅ Architecture diagram included (if complex)
- ✅ 3-10 phases clearly defined
- ✅ Each phase has: owner, files to modify, test requirements, risks
- ✅ API contracts defined (if backend feature)
- ✅ Component contracts defined (if frontend feature)
- ✅ Approval gates documented
- ✅ Timeline realistic
- ✅ FAQ addresses common questions

---

### 2️⃣ Artifact Type: phase-N-complete.md (Created by Mnemosyne)

**Purpose:** Document single phase results, metrics, and approval status  
**Created by:** @mnemosyne after each phase completes  
**Created after:** Temis approves phase (coverage >80%, security pass, all tests pass)  
**Stored at:** `plans/[feature-name]/phase-N-complete.md`

**Template:**

```markdown
# Phase N Complete: [Phase Description]

**Completion Date:** [YYYY-MM-DD]  
**Completed by:** [Agent names: Hermes + Athena + Maat]  
**Reviewed by:** Temis  
**Status:** ✅ APPROVED

---

## Summary

[1-2 paragraph summary of what was implemented in this phase]

**Phase Objective:** [Repeat from plan.md]  
**Result:** ✅ Successfully completed

---

## Files Modified/Created

### Created (New Files)
- `services/JWTService.py` - JWT generation, verification, refresh
- `tests/test_jwt_service.py` - 24 test cases, all passing
- `migrations/001_create_jwt_tokens.py` - Database schema

### Modified (Existing Files)
- `services/AuthService.py` - Added refresh token method (line 45-62)
- `endpoints/auth.py` - Added 3 new endpoints (POST /auth/login, etc)
- `tests/test_auth_endpoints.py` - Added 12 new integration tests

### Unchanged
- `models/User.py` - No changes needed
- `database/__init__.py` - Backward compatible

**Total Lines Added:** 1,247  
**Total Lines Modified:** 89  
**Total Lines Deleted:** 0 (no breaking changes)

---

## Tests Summary

### Backend (Hermes)

### Frontend (Athena)

### Database (Maat)

---

## Code Quality Metrics

| Metric | Target | Actual | Status |
|--------|--------|--------|--------|
| Coverage | >80% | 95% | ✅ |
| Cyclomatic Complexity | <10 | 4 | ✅ |
| Type Hints | 100% | 100% | ✅ |
| Doc Strings | 100% | 100% | ✅ |
| Linting (pylint) | 0 errors | 0 errors | ✅ |

---

## Security Audit (Temis Review)

**OWASP Top 10 Check:**
- ✅ A01 Broken Access Control: Token validation implemented
- ✅ A02 Cryptographic Failures: bcrypt + secure random (not MD5)
- ✅ A03 Injection: Parameterized queries only
- ✅ A04 Insecure Design: Rate limiting on login (5 attempts/min)
- ✅ A05 Security Misconfiguration: Secrets from env, not hardcoded
- ✅ A06 Vulnerable Components: Dependencies up-to-date
- ✅ A07 Auth Failures: Proper timeout + refresh logic
- ✅ A08 Software Data Integrity: Signed JWTs
- ✅ A09 Logging & Monitoring: Errors logged with context
- ✅ A10 SSRF: No external calls in token flow

**Additional Security Checks:**
- ✅ No SQL injection vulnerabilities
- ✅ No hardcoded secrets/credentials in code
- ✅ No sensitive data in logs
- ✅ No XXE vulnerabilities
- ✅ CORS properly configured
- ✅ API rate limiting enabled

**Result:** ✅ APPROVED

---

## Performance Analysis

### Backend
- Token generation: 2.3ms (target <5ms) ✅
- Token verification: 1.8ms (target <5ms) ✅
- Database queries: 0 N+1 detected ✅
- Memory usage: No leaks detected ✅

### Frontend
- LoginForm render time: 12ms (target <50ms) ✅
- Token storage/retrieval: 0.5ms (target <5ms) ✅
- No console errors ✅
- Accessibility score: 98/100 ✅

### Database
- Migration forward: 45ms ✅
- Migration backward: 38ms ✅
- Index creation: 12ms ✅
- Query performance: All <100ms ✅

**Result:** ✅ APPROVED

---

## Deployment Considerations

### Backward Compatibility
- ✅ Existing auth flow unchanged
- ✅ No database schema breaking changes
- ✅ New endpoints are additive only
- ✅ Frontend works with or without tokens

### Zero-Downtime Deployment
1. Deploy backend first (adds JWT endpoints, doesn't remove old)
2. Wait 5 minutes for load balancers
3. Deploy frontend (uses new endpoints)
4. Monitor 15 minutes for errors
5. Remove old auth endpoints (next release)

### Rollback Plan
- If critical issue: Revert frontend first
- Then revert backend (JWT endpoints still live, no harm)
- Database migration reversible (alembic downgrade)

---

## Decisions Made This Phase

**Decision 1: JWT vs Session Tokens**
- Chosen: JWT (stateless, scalable)
- Alternative: Session tokens (stateful, simpler auth)
- Reason: Microservices future-proof, no server-side state

**Decision 2: Refresh Token in Secure Cookie vs Response**
- Chosen: HttpOnly secure cookie (XSS protected)
- Alternative: Response body (easier to refresh)
- Reason: Better security for web, httpOnly prevents JS access

**Decision 3: Token Expiry Time**
- Chosen: 15 minutes access + 7 days refresh
- Alternative: 1 hour access + 30 days refresh
- Reason: Better security balance for typical usage

---

## Test Coverage Map

---

## Lessons Learned

**What Went Well:**
- ✅ TDD approach caught edge cases early
- ✅ Parallel phases (backend + frontend) saved 2 hours
- ✅ Good API contract specs prevented rework
- ✅ Security audit early prevented late fixes

**What Could Improve:**
- ⚠️ Database indexes added late (should be in plan)
- ⚠️ Frontend storage decision changed mid-phase (sync earlier)
- ⚠️ Edge case: token refresh race condition (add test)

**Recommendations for Next Time:**
- Start performance benchmarks earlier
- Lock API contracts before implementation
- Include index strategy in database phase plan

---

## Next Steps

1. ✅ Phase N approved for production
2. 🔄 Prepare Phase N+1 (Frontend integration)
3. 📋 User: Review & commit this phase
4. 🚀 After all phases: Deploy to staging & QA

---

## Sign-Off

| Role | Name | Status | Date |
|------|------|--------|------|
| Developer | Hermes | ✅ Ready | [date] |
| Developer | Athena | ✅ Ready | [date] |
| Developer | Maat | ✅ Ready | [date] |
| Code Reviewer | Temis | ✅ Approved | [date] |
| QA/Product | [User] | ⏳ Pending | [date] |

---

[END OF PHASE-N-COMPLETE.MD TEMPLATE]

# Feature Complete: [Feature Name]

**Project Duration:** [Start date] to [End date]  
**Total Time:** [X hours/days]  
**Team:** Athena (planning) + Hermes (backend) + Athena (frontend) + Maat (database) + Temis (review) + Mnemosyne (docs)  
**Status:** ✅ READY FOR PRODUCTION

---

## Executive Summary

[2-3 paragraph summary of feature, value delivered, and quality metrics]

---

## Phases Completed

| Phase | Owner | Status | Coverage | Duration |
|-------|-------|--------|----------|----------|
| 1. Database Schema | Maat | ✅ Complete | 100% | 1.5h |
| 2. Backend Services | Hermes | ✅ Complete | 96% | 2.5h |
| 3. Frontend Integration | Athena | ✅ Complete | 94% | 2.5h |
| **TOTAL** | **All** | **✅ Complete** | **95% avg** | **6.5h** |

---

## Feature Metrics

### Code Quality
- Total Coverage: **95%** (target: >80%) ✅
- Lines of Code Added: 2,487
- Test Cases Added: 41
- Test Pass Rate: **100%**
- Bugs Found in Testing: 0
- Security Issues Found: 0

### Performance
- Backend Response Time: <50ms (target: <100ms) ✅
- Frontend Render Time: 12ms (target: <50ms) ✅
- Database Query Time: <20ms (target: <100ms) ✅
- No N+1 queries detected ✅

### Accessibility
- WCAG AAA Compliance: **100%** ✅
- Automated audit score: **98/100** ✅
- Keyboard navigation: **100%** ✅
- Screen reader compatible: **Yes** ✅

---

## Files Summary

### Backend
- 3 new service files
- 2 modified endpoint files
- 1 new migration
- 24 new tests (+12 modified)

### Frontend
- 1 new component (LoginForm)
- 1 modified hook (useAuth)
- 1 new utility (tokenStorage)
- 13 new tests (+5 modified)

### Database
- 1 new migration (forward + backward)
- 4 new index definitions
- 0 breaking changes

**Total Files: 18 changed (+5 new)**

---

## What's Included ✅

- ✅ JWT authentication with refresh tokens
- ✅ Secure token storage (httpOnly cookies)
- ✅ Login/logout UI with validation
- ✅ Auto-token-refresh on expiry
- ✅ API rate limiting (5 attempts/min)
- ✅ OWASP compliance (all 10 checks)
- ✅ >95% code coverage
- ✅ Zero-downtime deployment strategy
- ✅ Full TDD test suite (41 tests)
- ✅ Backward compatible

---

## What's NOT Included (Out of Scope) ❌

- ❌ Social login (Google, GitHub)
- ❌ Multi-factor authentication (2FA)
- ❌ Single sign-on (SSO)
- ❌ Password reset flow
- ❌ Email verification

*These can be added in future features*

---

## Deployment Instructions

### Prerequisites
- PostgreSQL 14+
- Python 3.11+
- Node.js 18+
- Redis (optional, for session cache)

### Steps

1. **Backup Database**
   ```bash
   pg_dump production_db > backup_$(date +%s).sql

# Frontend first
kubectl set image deployment/frontend frontend=frontend:old

# Then backend (JWT endpoints still live, no harm)
kubectl set image deployment/backend backend=backend:old

# Database (backward compatible)
alembic downgrade -1

git log --oneline [base]..feature/jwt-auth | head -20

abc1234 feat: Complete JWT authentication feature
  - 3 phases completed
  - 95% coverage
  - All security  checks passed
  - Ready for production

abc1235 feat: Add frontend login form with token storage
abc1236 feat: Add JWT service and auth endpoints
abc1237 feat: Create JWT token database schema

# Can now:
git log --stat feature/jwt-auth
git log --patch feature/jwt-auth
git diff main..feature/jwt-auth | wc -l  # 2,487 lines changed

git checkout main
git merge --no-ff feature/jwt-auth
git push origin main
# Triggers CI/CD → automatically deploys to staging

gh pr create --title "feat: Add JWT authentication" \
  --body "See: plans/jwt-authentication/complete.md"
# Let human reviewers approve before merge

# Deploy feature branch to QA environment
git checkout feature/jwt-auth
./deploy.sh qa

# Test manually in QA
# If no issues: Merge to main

plans/jwt-authentication/
├── plan.md (Initial plan, 12KB)
├── phase-1-complete.md (Schema, 8KB)
├── phase-2-complete.md (Backend, 15KB)
├── phase-3-complete.md (Frontend, 12KB)
└── complete.md (This file, 18KB)

Total: ~65KB of documentation
Archive forever for: Future team reference, audits, similar features

**complete.md Checklist:**
- ✅ Executive summary (1-2 paragraphs)
- ✅ Phase summary table (all phases + coverage)
- ✅ Feature metrics (coverage, lines, tests, bugs)
- ✅ Performance analysis
- ✅ Accessibility results
- ✅ All files listed (created, modified, unchanged)
- ✅ What's included vs what's NOT included
- ✅ Deployment instructions (step-by-step)
- ✅ Rollback procedure
- ✅ Full test summary (unit + integration + E2E)
- ✅ Security audit results (OWASP 10/10)
- ✅ Known limitations & workarounds
- ✅ Recommendations for next time
- ✅ Git log + merge instructions
- ✅ Team summary by agent
- ✅ Success criteria checklist
- ✅ Recommended roadmap (next features)
- ✅ Artifact trail (where everything is stored)
- ✅ Sign-off section (accountability)

---

## Best Practices

### ✅ DO

✅ **Create plan.md BEFORE starting implementation**
- Prevents rework
- Communicates design early
- Gets user buy-in before effort

✅ **Complete phase-N-complete.md AFTER Temis approves**
- Documents what actually happened (vs what was planned)
- Shows metrics & decisions made
- Creates audit trail

✅ **Store in plans/[feature-name]/ directory**
- Organized by feature
- Easy to find all artifacts for one feature
- Can archive old features

✅ **Use standardized templates**
- Consistency across team
- Easier to read/search
- Reduces documentation work

✅ **Update artifacts as you learn**
- Decisions change mid-phase - document why
- Metrics differ from estimates - explain
- Risks emerge - explain mitigation

✅ **Reference artifacts in git commits**
```bash
git commit -m "feat: Add JWT service

See: plans/jwt-auth/phase-2-complete.md for details
Coverage: 96%, Security: ✅, Tests: 24/24 passing"

Feature: Email Verification Flow
Plan Duration: 3 phases, 6-8 hours

Timeline:
Morning:
  09:00 - Athena creates plans/email-verification/plan.md
  09:30 - User reviews & approves plan
  10:00 - Hermes starts Phase 1 (Email service)
  
Afternoon:
  12:00 - Hermes Phase 1 done, Temis reviews (coverage 92%)
  12:30 - Mnemosyne creates phase-1-complete.md
  12:45 - User commits Phase 1
  13:00 - Athena Phase 2 (Verification form) + Maat (migration) parallel
  
Next morning:
  09:00 - Athena + Maat phases done
  09:30 - Temis reviews both (coverage 94%) 
  10:00 - Mnemosyne creates phase-2 & phase-3-complete.md
  10:30 - Mnemosyne creates complete.md (final summary)
  11:00 - User merges to main
  11:30 - Deployed to staging
  12:00 - QA testing in staging
  14:00 - Deploy to production
  
Total: 1.5 days of work
Artifacts: plan.md + 3x phase-N-complete.md + complete.md
Knowledge: Everything documented for future reference