Best Practices

### 1. Todo List - CRITICAL
**Description**: Users can see their todos
 
**Acceptance Criteria**:
- [ ] Display list of todos
- [ ] Each todo shows text

### 1. Todo List - CRITICAL
**Description**: Users can see and manage their todos
 
**Acceptance Criteria**:
- [ ] Display list of todos
- [ ] Each todo shows text and completion status
- [ ] Toggle completion with click
- [ ] Delete todo with button
- [ ] Empty state illustration
- [ ] Loading state while fetching

### 1. Todo List - CRITICAL
**Description**: Users can see and manage their todos
 
**Acceptance Criteria**:
- [ ] Display list of todos with text and status
- [ ] Toggle completion with click
- [ ] Delete button with confirmation
- [ ] Empty state with illustration and "Create your first todo" message
- [ ] Loading skeleton (not spinner) while fetching
- [ ] Error state with retry button
- [ ] Filter: all / active / completed
- [ ] Sort by date (newest first)
- [ ] Keyboard shortcuts: 't' to toggle, 'd' to delete

- [ ] User can login

- [ ] GIVEN user is on login page
  WHEN they enter valid email and password
  AND click "Login" button
  THEN they are redirected to /dashboard
  AND JWT token is stored in httpOnly cookie
  AND success toast appears

- [ ] Login form accepts email and password
- [ ] On success, redirect to dashboard

- [ ] Login form accepts email and password
- [ ] On success, redirect to dashboard
- [ ] Edge case - Empty fields: Show "Email and password required"
- [ ] Edge case - Invalid email format: Show "Invalid email format"
- [ ] Edge case - Wrong password: Show "Invalid credentials" (don't reveal which)
- [ ] Edge case - Unverified email: Show "Please verify your email first"
- [ ] Edge case - Account locked: Show "Account locked, contact support"
- [ ] Edge case - Network error: Show "Connection failed, try again"
- [ ] Edge case - Rate limit exceeded: Show "Too many attempts, try again in 15 minutes"

### 1. Product Listing - CRITICAL
- [ ] Display products in grid
- [ ] Each card shows name, price, image

### 1. Product Listing - CRITICAL
**Description**: Display products in grid layout
 
**Acceptance Criteria**:
- [ ] Display products in responsive grid (1/2/3/4 columns)
- [ ] Each card shows name, price, image
 
**Performance Requirements**:
- [ ] Initial render in < 1.5 seconds on 3G
- [ ] Images lazy load below fold
- [ ] List virtualizes for 100+ items (react-window)
- [ ] API response < 500ms p95
 
**Security Requirements**:
- [ ] Sanitize all user inputs (prevent XSS)
- [ ] Image URLs validated (prevent XXE)
- [ ] Rate limit API endpoint (100 req/min per IP)
 
**Accessibility Requirements**:
- [ ] WCAG 2.1 AA compliant
- [ ] Keyboard navigation works (Tab, Enter, Escape)
- [ ] Screen reader announces product info
- [ ] Focus indicators visible on all interactive elements
- [ ] Color contrast ratio ≥ 4.5:1

**Acceptance Criteria**:
- [ ] Use React Hook Form's useForm hook
- [ ] Use Zod schema with .string().email().min(5)
- [ ] Use useState for form data
- [ ] Use useEffect to fetch user on mount
- [ ] Store token in document.cookie
- [ ] Use axios for API calls with baseURL
- [ ] Use Tailwind classes: flex, flex-col, gap-4

**Acceptance Criteria**:
- [ ] Login form with email/password fields
- [ ] Client-side validation (email format, password length)
- [ ] Form submits to /api/auth/login
- [ ] On success: store auth token, redirect to /dashboard
- [ ] On failure: show inline error message
- [ ] Form uses existing validation library (Zod or Yup)
- [ ] Styling matches design system (Tailwind CSS)

### 1. User Management - CRITICAL
**Description**: Users can manage their accounts
 
**Acceptance Criteria**:
- [ ] Register new account
- [ ] Login with email/password
- [ ] Logout
- [ ] Edit profile
- [ ] Upload avatar
- [ ] Change password
- [ ] Reset password via email
- [ ] Delete account
- [ ] View account history
- [ ] Manage notifications
- [ ] Connect social accounts

### 1. Authentication - CRITICAL
**Description**: Users can login and logout
**Acceptance Criteria**:
- [ ] Login form with email/password
- [ ] JWT token generation
- [ ] Logout functionality
- [ ] Protected routes
 
### 2. Registration - HIGH
**Description**: New users can create accounts
**Acceptance Criteria**:
- [ ] Registration form
- [ ] Email verification
- [ ] Welcome email
 
### 3. Profile Management - HIGH
**Description**: Users can edit their profile
**Acceptance Criteria**:
- [ ] Edit name and avatar
- [ ] Change password
- [ ] Manage notifications
 
### 4. Password Reset - MEDIUM
...
 
### 5. Account Deletion - LOW
...

## Tech Stack
- Next.js
- TypeScript
- Tailwind

## Tech Stack
 
### Frontend
- **Framework**: Next.js 14 (App Router, NOT Pages Router)
- **Language**: TypeScript 5.3+ (strict mode enabled)
- **Styling**: Tailwind CSS 3.4+ with CSS variables for theming
- **State**: Zustand 4.4+ (NOT Redux)
- **Forms**: React Hook Form 7.48+ with Zod 3.22+ validation
- **Tables**: TanStack Table 8.11+ (NOT react-table)

- **Database**: PostgreSQL
- **ORM**: Prisma

- **Database**: PostgreSQL (chosen for ACID compliance, JSON support, and existing team expertise)
- **ORM**: Prisma (type-safe, team standard, good migration system)
 
**Constraints**:
- Must use Prisma for all DB queries (no raw SQL)
- Follow existing schema in prisma/schema.prisma
- All schema changes require migration files
- Use Prisma Client for queries, no raw queries without approval

## Tech Stack Integration Patterns
 
### API + State Management
- Use TanStack Query for all data fetching (caching, revalidation)
- Use Zustand for UI state (modals, forms, theme)
- Don't fetch in components, use custom hooks in src/hooks/
 
### Styling + Components
- Use shadcn/ui as base component library
- Extend components in src/components/ui/ for customization
- Use Tailwind for layout and styling
- Follow existing design tokens in src/tokens/
 
### Testing + Mocking
- Use Vitest for unit tests (fast, integrates with Vite)
- Use MSW for API mocking (NOT nock)
- Use Testing Library for component tests (NOT Enzyme)
- Mock external dependencies (Stripe API, email service)

### Frontend
- **Framework**: Next.js 14
- **State**: Redux Toolkit
- **Forms**: React Hook Form
- **Validation**: Zod
 
### BUT ALSO
- Use Zustand for state
- Use Formik for forms
- Use Yup for validation

### Frontend
- **Framework**: Next.js 14
- **State**: Zustand (primary), Redux (only for complex state if needed)
- **Forms**: React Hook Form
- **Validation**: Zod
 
**When to use Redux**:
- Only for complex global state (user session, cart with 50+ items)
- Default to Zustand for simpler state

# After every file
/agentful-status
# After every test
/agentful-status
# After every validation
/agentful-status

# Checkpoints:
# 1. When starting new feature
/agentful-status
 
# 2. When agentful seems stuck (10+ iterations without progress)
/agentful-status
 
# 3. When feature should be complete
/agentful-status
 
# 4. Before making manual changes
/agentful-status

**Technical Notes**:
- Run /agentful-validate after every file change

**Technical Notes**:
- Run validation only when:
  * Feature implementation complete
  * Tests written
  * Before marking feature complete

# Add to team dashboard script
cat .agentful/completion.json | jq '
  {
    project: "Product A",
    overall: .overall,
    current_task: .current_task,
    gates: .gates,
    pending_decisions: (.decisions.pending | length)
  }
'

# Generate team dashboard
./scripts/generate-dashboard.sh > dashboard.html
# Shows all projects, progress, blockers

# 2 minutes in
"agentful is slow, let me just do it myself"
# Manually write code
# Break agentful's flow

# 15 minutes later
/agentful-status
 
# If still stuck:
# - Check state files
# - Check validation
# - Check for decisions
# - Intervene if truly stuck

// You write the complex types (agentful struggles)
interface AuthState {
  user: User | null;
  token: string | null;
  permissions: Permission[];
  sessionExpiry: number;
}
 
// agentful writes the basic store (agentful excels)
const useAuthStore = create<AuthState>((set) => ({
  user: null,
  token: null,
  permissions: [],
  sessionExpiry: 0,
  login: (user, token) => set({ user, token }),
  logout: () => set({ user: null, token: null, permissions: [] }),
}));

**Technical Notes**:
- Line 5: Must be exactly "const foo = ..."
- Line 6: Must be exactly "const bar = ..."
- Function name must be "processData"
- Use for loop, not forEach
- Use template literals, not string concat

**Technical Notes**:
- Follow existing pattern in src/lib/processor.ts
- Must handle empty input gracefully
- Must return array of processed items
- Performance: O(n) complexity is acceptable

For each feature, verify:
 
Clarity:
- [ ] Can I visualize what this will look like?
- [ ] Would a new developer understand this?
- [ ] Is there any ambiguity?
 
Completeness:
- [ ] Are all user flows covered?
- [ ] Are edge cases addressed?
- [ ] Is error handling specified?
 
Testability:
- [ ] Can I write a test for each criterion?
- [ ] Is success measurable?
- [ ] Is failure defined?
 
Feasibility:
- [ ] Is this realistic to build?
- [ ] Are dependencies available?
- [ ] Is timeline reasonable?
 
If any checklist item fails, refine acceptance criteria.

After agentful completes feature:
 
Functionality:
- [ ] All acceptance criteria pass
- [ ] Edge cases handled
- [ ] Error handling complete
- [ ] User flows work end-to-end
 
Code Quality:
- [ ] Follows team patterns
- [ ] No code duplication
- [ ] Functions are focused and small
- [ ] Names are clear and descriptive
 
Testing:
- [ ] Tests cover all acceptance criteria
- [ ] Tests cover edge cases
- [ ] Tests are readable
- [ ] Mocks are appropriate
 
Performance:
- [ ] No obvious performance issues
- [ ] Database queries are optimized
- [ ] No unnecessary re-renders
- [ ] Bundle size reasonable
 
Security:
- [ ] Input validation present
- [ ] No hardcoded secrets
- [ ] Proper auth checks
- [ ] No SQL/ XSS vulnerabilities
 
Documentation:
- [ ] Complex functions have JSDoc
- [ ] API endpoints documented
- [ ] Setup instructions clear

### 1. User Login - CRITICAL
**Acceptance Criteria**:
- [ ] Login form with email/password
- [ ] On success, redirect to dashboard
- [ ] On failure, show error

### 1. User Login - CRITICAL
**Acceptance Criteria**:
- [ ] Login form with email/password
- [ ] Client-side validation (email format, password length)
- [ ] On success, redirect to dashboard
- [ ] On failure, show specific error message
- [ ] Loading state during submission
- [ ] Disable submit button while submitting
- [ ] Enter key submits form

### 1. E-commerce Platform - CRITICAL
**Description**: Complete e-commerce functionality
 
**Acceptance Criteria**:
- [ ] Products, categories, search
- [ ] Cart, checkout, payment
- [ ] User accounts, orders, history
- [ ] Admin panel, inventory
- [ ] Reviews, ratings, recommendations

### Phase 1: Core Shopping
### 1. Product Catalog - CRITICAL
### 2. Shopping Cart - CRITICAL
### 3. Checkout - CRITICAL
 
### Phase 2: User Features
### 4. User Authentication - HIGH
### 5. Order Management - HIGH
 
### Phase 3: Admin
### 6. Admin Product Management - MEDIUM
### 7. Order Processing - MEDIUM
 
### Phase 4: Enhancements
### 8. Product Reviews - LOW
### 9. Recommendations - LOW

### 1. User Authentication - CRITICAL
- [ ] Email/password login
- [ ] JWT token
- [ ] Basic session management

### 8. Social Login - MEDIUM
- [ ] Google OAuth
- [ ] GitHub OAuth

### 9. Multi-Factor Auth - LOW
- [ ] TOTP support
- [ ] SMS backup codes

### 1. User Reviews - CRITICAL (blocked on users, products, orders)
### 2. Order Processing - CRITICAL (blocked on users, products, checkout)
### 3. Checkout - CRITICAL (blocked on users, products, cart)
### 4. Shopping Cart - CRITICAL (blocked on products)
### 5. Product Catalog - CRITICAL (no dependencies)

### 1. Product Catalog - CRITICAL (foundation)
### 2. Shopping Cart - CRITICAL (depends on #1)
### 3. Checkout - CRITICAL (depends on #1, #2)
### 4. User Authentication - HIGH (parallel to #2, #3)
### 5. Order Processing - HIGH (depends on #3, #4)
### 6. User Reviews - MEDIUM (depends on #1, #4, #5)

### 1. Product Listing - CRITICAL
- [ ] Display products in grid
 
# Later: "This is slow, need to optimize"

### 1. Product Listing - CRITICAL
**Acceptance Criteria**:
- [ ] Display products in responsive grid
 
**Performance Requirements**:
- [ ] Initial render < 1.5s on 3G connection
- [ ] Time to interactive < 3s
- [ ] Database query < 500ms p95
- [ ] API response < 200ms p95
- [ ] Images lazy load, prioritize above-fold
- [ ] Virtualize list for 100+ items
- [ ] Cache API responses for 5 minutes

### 1. User Dashboard - CRITICAL
- [ ] Display user's recent orders

### 1. User Dashboard - CRITICAL
- [ ] Display user's recent orders (last 10)
 
**Performance Notes**:
- [ ] Use indexed query on user_id
- [ ] Select only needed fields (avoid SELECT *)
- [ ] Pagination: 10 per page
- [ ] Cache for 2 minutes
- [ ] Use JOIN instead of N+1 queries

### 1. Product Feed - CRITICAL
**Acceptance Criteria**:
- [ ] Infinite scroll product feed
 
**Performance Requirements**:
- [ ] Use react-window for virtualization
- [ ] Lazy load images (use Intersection Observer)
- [ ] De-bounce search input by 300ms
- [ ] Use React.memo for product cards
- [ ] Pagination: 20 items per page
- [ ] Prefetch next page when user reaches 80% scroll

### 1. User Authentication - CRITICAL
**Acceptance Criteria**:
- [ ] Login form with email/password
 
**Security Requirements**:
- [ ] Rate limiting: 5 attempts per 15 min per IP
- [ ] Password requirements: min 8 chars, 1 uppercase, 1 number
- [ ] Hash passwords with bcrypt (cost factor 12)
- [ ] JWT token expires in 7 days
- [ ] Store JWT in httpOnly cookie (NOT localStorage)
- [ ] CSRF protection on all mutation endpoints
- [ ] Input sanitization (prevent XSS)
- [ ] SQL injection prevention (use parameterized queries)
- [ ] Don't reveal if email exists (use generic error messages)

**Acceptance Criteria**:
- [ ] Email validation: required, valid format
- [ ] Password validation: required, min 8 chars
- [ ] Show inline errors

**Security Requirements**:
- [ ] Validate all inputs with Zod schema
- [ ] Sanitize HTML (prevent XSS)
- [ ] Validate JWT on every protected route
- [ ] Check user permissions for resources

**Security Requirements**:
- [ ] Use parameterized queries (Prisma handles this)
- [ ] Validate data types at schema level
- [ ] Add CHECK constraints for business rules

const API_KEY = "sk-1234567890abcdef";

**Security Requirements**:
- [ ] All secrets in environment variables (.env.local)
- [ ] Add secrets to .env.example (with placeholder values)
- [ ] Never commit .env.local to Git
- [ ] Document required environment variables
- [ ] Validate required env vars on startup

// agentful generates this instead:
const API_KEY = process.env.STRIPE_SECRET_KEY;
 
if (!API_KEY) {
  throw new Error("STRIPE_SECRET_KEY environment variable is required");
}

**Acceptance Criteria**:
- [ ] Login form works

**Acceptance Criteria**:
- [ ] Login form works
 
**Testing Requirements**:
- [ ] Unit tests for:
  - Email validation function
  - Password validation function
  - JWT generation function
  - Token verification function
- [ ] Integration tests for:
  - POST /api/auth/login (success case)
  - POST /api/auth/login (wrong password)
  - POST /api/auth/login (non-existent user)
- [ ] E2E tests for:
  - Complete login flow
  - Redirect after successful login
  - Error message display

**Testing Notes**:
- Use factory pattern for test data (see src/__tests__/factories/)
- Each test should create fresh data (don't share between tests)
- Clean up test data after each test (use afterEach)
- Use deterministic data (not random) for reproducibility
- Mock external dependencies (Stripe API, email service)

**Success Criteria**:
- 100% test coverage

**Success Criteria**:
- 80% overall test coverage
- 90% for business logic (services, utils)
- 70% for components (UI has lower priority)
- 100% for authentication and security code

### 1. User Authentication - CRITICAL
...
 
**Documentation Requirements**:
- [ ] JSDoc on all exported functions
- [ ] API endpoint documentation (OpenAPI/Swagger)
- [ ] Setup instructions in README
- [ ] Environment variables documented in .env.example
- [ ] Architecture diagram for auth flow

## Architecture Decisions
 
### Authentication Strategy
**Decision**: JWT with httpOnly cookies
 
**Rationale**:
- Stateless, scales horizontally
- httpOnly cookies prevent XSS
- No token storage in localStorage
- 7-day expiry balances security and UX
 
**Alternatives Considered**:
- Sessions: Rejected (requires session store, doesn't scale)
- localStorage: Rejected (vulnerable to XSS)
- Clerk: Rejected (vendor lock-in, cost)
 
**Trade-offs**:
- Pros: Scalable, secure, simple
- Cons: Can't revoke tokens without blacklist (future enhancement)
 
**Decision Date**: 2026-01-18
**Decision Maker**: Team

You: 20% (decisions, architecture, design, complex cases)
agentful: 80% (implementation, tests, boilerplate, refactoring)