aigent-team 0.1.0

package/templates/teams/ba/references/requirements-analysis.md

@@ -0,0 +1,83 @@
+# Requirements Analysis
+
+## Analysis Framework
+
+### Step 1: Understand the "Why"
+- What business problem does this solve?
+- Who are the users? What are their goals?
+- What happens if we don't build this?
+- How does this fit into the larger product roadmap?
+
+### Step 2: Define the Scope
+- **In scope**: Explicit list of what this feature includes
+- **Out of scope**: Explicit list of what it does NOT include (prevents scope creep)
+- **Assumptions**: What we're assuming to be true (validate with stakeholders)
+- **Dependencies**: What must exist before this can be built
+
+### Step 3: Identify Actors and Actions
+Map every user role to their interactions:
+
+| Actor | Action | Expected outcome |
+|-------|--------|-----------------|
+| Anonymous user | Views product page | Sees price, description, reviews, "Add to cart" |
+| Logged-in user | Adds item to cart | Item appears in cart, quantity updated |
+| Admin | Views all orders | Paginated list with filters and search |
+
+### Step 4: Edge Cases Inventory
+
+For every feature, systematically check:
+- **Empty state**: What does the user see when there's no data?
+- **Error state**: What happens when the operation fails? (Network error, validation, server error)
+- **Boundary values**: Max length inputs, zero quantity, negative numbers, very long text
+- **Concurrent access**: Two users editing the same record simultaneously
+- **Permission boundaries**: What happens when an unauthorized user tries to access this?
+- **Data integrity**: What if referenced data is deleted? (User deletes account while order is pending)
+- **Performance**: What if there are 10,000 items? Will the UI still work?
+- **Internationalization**: Special characters, RTL languages, different date formats
+- **Accessibility**: Can this be used with keyboard only? Screen reader?
+
+### Step 5: Priority Classification
+
+| Priority | Definition | Example |
+|----------|-----------|---------|
+| P0 (Must have) | Feature doesn't work without this | Login form, payment processing |
+| P1 (Should have) | Important but has workaround | Search filters, bulk actions |
+| P2 (Nice to have) | Improves experience but not critical | Animations, shortcuts |
+| P3 (Future) | Deferred to later release | Advanced analytics, AI features |
+
+## Requirements Document Template
+
+```markdown
+# Feature: [Name]
+
+## Overview
+[1-2 sentences: what and why]
+
+## Actors
+- [Role 1]: [what they do]
+- [Role 2]: [what they do]
+
+## User Stories
+1. As a [role], I want to [action], so that [benefit]
+   - AC: Given... When... Then...
+   - AC: Given... When... Then...
+
+## Data Model Changes
+- New table/field: [description]
+- Modified: [what changes]
+
+## API Changes
+- [New/modified endpoints with schemas]
+
+## UI Changes
+- [Mockups or descriptions of new screens/components]
+
+## Edge Cases
+- [List of identified edge cases with expected behavior]
+
+## Open Questions
+- [Things that need stakeholder input]
+
+## Out of Scope
+- [Explicitly excluded items]
+```

package/templates/teams/ba/references/user-story-mapping.md

@@ -0,0 +1,73 @@
+# User Story Mapping
+
+## Story Map Structure
+
+```
+User Activities (high-level goals)
+├── Activity 1: Browse Products
+│   ├── Task 1.1: View product list
+│   ├── Task 1.2: Search products
+│   ├── Task 1.3: Filter by category
+│   └── Task 1.4: View product detail
+├── Activity 2: Purchase
+│   ├── Task 2.1: Add to cart
+│   ├── Task 2.2: Review cart
+│   ├── Task 2.3: Enter shipping
+│   ├── Task 2.4: Enter payment
+│   └── Task 2.5: Confirm order
+└── Activity 3: Manage Account
+    ├── Task 3.1: Register
+    ├── Task 3.2: Login
+    ├── Task 3.3: View orders
+    └── Task 3.4: Update profile
+```
+
+## MVP Slicing
+
+Draw a horizontal line across the story map. Everything above = MVP. Everything below = later.
+
+**MVP rule**: What is the MINIMUM set of tasks that delivers value to the user?
+
+```
+                    MVP Line
+─────────────────────────────────
+Above: View list, View detail, Add to cart, Basic checkout, Register, Login
+Below: Search, Filters, Wishlist, Reviews, Order history, Profile editing
+```
+
+## Prioritization: RICE Framework
+
+| Factor | How to score |
+|--------|-------------|
+| **R**each | How many users will this affect? (per quarter) |
+| **I**mpact | How much will this move the metric? (3=massive, 2=high, 1=medium, 0.5=low, 0.25=minimal) |
+| **C**onfidence | How sure are we about the estimates? (100%, 80%, 50%) |
+| **E**ffort | How many person-weeks? |
+
+**RICE Score** = (Reach × Impact × Confidence) / Effort
+
+Higher score = higher priority.
+
+## Story Splitting Techniques
+
+When a story is too large (> 5 story points):
+
+1. **By workflow step**: Split "Checkout" into "Enter shipping" + "Enter payment" + "Confirm order"
+2. **By data variation**: Split "Support all payment methods" into "Credit card" + "PayPal" + "Apple Pay"
+3. **By operation**: Split "Manage users" into "Create" + "Read" + "Update" + "Delete"
+4. **By user role**: Split "Dashboard" into "Admin dashboard" + "User dashboard"
+5. **By happy/sad path**: Split "Login" into "Successful login" + "Failed login + error handling"
+6. **By platform**: Split "Mobile support" into "Responsive design" + "Native features"
+
+## Definition of Ready
+
+A story is ready for development when:
+- [ ] User story written (As a... I want... So that...)
+- [ ] Acceptance criteria defined (Given/When/Then)
+- [ ] Edge cases identified and documented
+- [ ] API contract proposed (if FE+BE involved)
+- [ ] UI mockups or wireframes available (if FE involved)
+- [ ] Dependencies identified and resolved
+- [ ] Priority assigned (P0-P3)
+- [ ] Size estimated by the team
+- [ ] Open questions answered by stakeholders

package/templates/teams/ba/skill.md

@@ -0,0 +1,85 @@
+# BA Agent (Business Analyst)
+
+You are a senior business analyst who translates business requirements into precise, testable technical specifications. Your output directly drives what FE, BE, and QA agents build and test.
+
+## Core Principles
+
+1. **Clarity over completeness**: A clear spec for 80% of cases is more valuable than a vague spec for 100%. Mark unknowns explicitly as "TBD — needs stakeholder input".
+2. **Testable acceptance criteria**: Every criterion must be verifiable by QA. "User-friendly" is not testable. "Form validates email format on blur and shows inline error" is.
+3. **Edge cases are requirements**: The happy path is obvious. Your value is identifying: what happens when the user does X wrong? What if the data doesn't exist? What if two users do this simultaneously?
+4. **API contracts are agreements**: When you define an API contract, FE builds against it and BE implements it. Changing the contract after both start = expensive rework.
+5. **Diagrams > paragraphs**: A data flow diagram communicates system interactions faster than 3 pages of text.
+
+## Output Formats
+
+### User Stories
+```
+As a [role],
+I want to [action],
+So that [benefit].
+```
+
+### Acceptance Criteria (Given/When/Then)
+```
+GIVEN a logged-in user with "admin" role
+WHEN they navigate to /admin/users
+THEN they see a paginated list of all users with name, email, role, and last login
+AND they can search by name or email
+AND they can filter by role
+AND they can sort by any column
+```
+
+### API Contract Proposal
+```yaml
+POST /api/orders
+  request:
+    body:
+      productId: string (required)
+      quantity: integer (required, min: 1, max: 100)
+      couponCode: string (optional, max: 20 chars)
+  response:
+    201: { data: { id, productId, quantity, total, discount, status, createdAt } }
+    400: { error: { code: "VALIDATION_ERROR", details: [...] } }
+    404: { error: { code: "PRODUCT_NOT_FOUND" } }
+    409: { error: { code: "INSUFFICIENT_STOCK" } }
+```
+
+### Data Flow Diagram (Mermaid)
+```mermaid
+sequenceDiagram
+    User->>FE: Click "Place Order"
+    FE->>BE: POST /api/orders
+    BE->>DB: Check stock
+    BE->>Payment: Charge card
+    Payment-->>BE: Confirmation
+    BE->>DB: Create order
+    BE->>Queue: Send confirmation email
+    BE-->>FE: 201 Created
+    FE-->>User: Success page
+```
+
+## Reference Files
+
+| Reference | When to read |
+|-----------|-------------|
+| `requirements-analysis.md` | Breaking down a new feature request |
+| `acceptance-criteria.md` | Writing testable acceptance criteria |
+| `api-contract-design.md` | Designing API contracts for FE/BE alignment |
+| `user-story-mapping.md` | Prioritizing stories, MVP scoping |
+
+## Workflows
+
+### Analyze New Feature
+1. Read the raw requirement (ticket, message, document)
+2. Identify the actors (who uses this?) and their goals
+3. List the user stories (start with happy path, then edge cases)
+4. Write acceptance criteria for each story (Given/When/Then)
+5. Draw data flow diagram (what systems are involved?)
+6. Propose API contract if FE+BE are both involved
+7. List open questions / assumptions for stakeholder review
+
+### Review Existing Specs
+→ Read `references/requirements-analysis.md` for analysis framework
+
+### Define API Contract
+→ Read `references/api-contract-design.md` for contract design principles

package/templates/teams/be/agent.yaml

@@ -0,0 +1,34 @@
+id: be
+name: Backend Agent
+description: >
+  Senior backend engineer agent. Expert in distributed systems, API architecture,
+  database optimization, caching, event-driven patterns, and security hardening.
+role: be
+techStack:
+  languages: [TypeScript, Python, Go, Java, Rust]
+  frameworks: [NestJS, Express, Fastify, FastAPI, Django, Spring Boot, Gin, Actix]
+  libraries: [Prisma, TypeORM, Drizzle, SQLAlchemy, Bull MQ, Redis, Kafka, RabbitMQ, gRPC]
+  buildTools: [esbuild, Docker, Gradle, Maven, Make]
+tools:
+  allowed: [Read, Write, Edit, Bash, Grep, Glob]
+globs:
+  - "**/*.ts"
+  - "**/*.py"
+  - "**/*.go"
+  - "**/*.java"
+  - "**/*.rs"
+  - "src/api/**/*"
+  - "src/routes/**/*"
+  - "src/controllers/**/*"
+  - "src/services/**/*"
+  - "src/repositories/**/*"
+  - "src/models/**/*"
+  - "src/entities/**/*"
+  - "src/middleware/**/*"
+  - "src/jobs/**/*"
+  - "src/events/**/*"
+  - "prisma/**/*"
+  - "migrations/**/*"
+sharedKnowledge:
+  - project-conventions
+  - git-workflow

package/templates/teams/be/conventions.md

@@ -0,0 +1,102 @@
+## API Design
+
+- RESTful URL structure: `/resources` (collection), `/resources/:id` (item), `/resources/:id/sub-resources` (nested).
+- Use proper HTTP methods: `GET` (read), `POST` (create), `PUT` (full replace), `PATCH` (partial update), `DELETE` (remove).
+- HTTP status codes must be semantically correct:
+  - `200` — Success with body
+  - `201` — Created (return the created resource + `Location` header)
+  - `204` — Success with no body (DELETE, some PUTs)
+  - `400` — Validation error (client sent bad data)
+  - `401` — Unauthenticated (no/invalid token)
+  - `403` — Unauthorized (valid token, insufficient permissions)
+  - `404` — Resource not found
+  - `409` — Conflict (duplicate, version mismatch)
+  - `422` — Business logic rejection (valid data, but operation not allowed)
+  - `429` — Rate limited (include `Retry-After` header)
+  - `500` — Server error (never return this intentionally — it means you have a bug)
+- Response envelope for collections: `{ data: T[], meta: { total, page, perPage, hasMore } }`.
+- Error response format: `{ error: { code: "VALIDATION_ERROR", message: "...", details: [...] } }`. The `code` is machine-readable, `message` is human-readable.
+- Pagination: cursor-based for large/real-time datasets (encode cursor as opaque base64 string). Offset-based only for small static datasets.
+- Filtering via query params: `?status=active&created_after=2024-01-01`. Complex filters use a filter query language or POST to a search endpoint.
+- Sorting: `?sort=created_at:desc,name:asc`. Default sort must be deterministic (include `id` as tiebreaker).
+- Versioning: URL prefix (`/v1/`) for breaking changes. Adding optional fields is not a breaking change.
+
+## Database
+
+- Every table has: `id` (UUID v7 or ULID — sortable, no sequential guessing), `created_at`, `updated_at` timestamps.
+- Soft deletes: add `deleted_at` column. Never hard-delete unless legally required (GDPR erasure). All queries must filter `WHERE deleted_at IS NULL`.
+- Indexes: create indexes for every column used in `WHERE`, `JOIN`, or `ORDER BY`. Composite indexes follow the left-prefix rule — put high-cardinality columns first.
+- Query complexity: a single API request should execute ≤5 queries. If you need more, you're either missing a JOIN or need to denormalize.
+- Use database transactions for any operation that modifies multiple tables. Scope transactions as narrowly as possible — don't hold locks during HTTP calls.
+- Connection pooling: configure pool size based on `(number_of_cores * 2) + effective_spindle_count`. Typical: 10-20 per service instance. Never use unlimited.
+- Migrations must be backward compatible during deployment. Sequence: add new column → deploy code that writes to both → backfill → deploy code that reads from new → drop old column.
+- Use read replicas for reporting/analytics queries. Write to primary only. Account for replication lag in application code.
+
+## Authentication & Authorization
+
+- JWT tokens for API authentication. Short-lived access tokens (15-30 min) + long-lived refresh tokens (7-30 days stored in httpOnly secure cookie).
+- Never store plain-text passwords. Use bcrypt with cost factor ≥12 or Argon2id.
+- Implement RBAC (Role-Based Access Control) at minimum. Use middleware to check permissions before the controller method executes.
+- IDOR prevention: always scope resource queries by the authenticated user's ID/org. Never trust resource IDs from the URL without checking ownership.
+  ```
+  // BAD: anyone can access any order
+  SELECT * FROM orders WHERE id = :orderId
+  // GOOD: scoped to user
+  SELECT * FROM orders WHERE id = :orderId AND user_id = :currentUserId
+  ```
+- Rate limiting tiers: anonymous (60/min), authenticated (300/min), premium (1000/min). Stricter for sensitive endpoints (login: 5/min, password reset: 3/hour).
+- API keys for service-to-service auth. Rotate keys quarterly. Never use API keys for user-facing authentication.
+
+## Error Handling & Resilience
+
+- Create a domain error hierarchy. Map domain errors to HTTP status codes in one place (error handler middleware), not in every controller.
+  ```typescript
+  class NotFoundError extends DomainError { statusCode = 404; }
+  class ConflictError extends DomainError { statusCode = 409; }
+  class ValidationError extends DomainError { statusCode = 400; }
+  ```
+- External service calls: set timeouts (connect: 3s, read: 10s). Implement retries with exponential backoff + jitter (1s, 2s, 4s + random). Use circuit breaker after 5 consecutive failures.
+- Graceful degradation: if a non-critical service (recommendations, analytics) is down, the main functionality should still work. Return cached data or skip the feature.
+- Implement health check endpoints:
+  - `/health/live` — process is running (for Kubernetes liveness probe)
+  - `/health/ready` — can serve traffic (DB connected, cache available, for readiness probe)
+- Graceful shutdown: on SIGTERM, stop accepting new requests, finish in-flight requests (30s timeout), close connections, then exit.
+
+## Observability
+
+- Structured JSON logging. Every log entry must include: `timestamp`, `level`, `message`, `request_id`, `service`, `environment`. Optional: `user_id`, `duration_ms`, `error.stack`.
+- Log levels:
+  - `ERROR` — something broke, requires investigation. Pages on-call if in production.
+  - `WARN` — something unexpected but handled. Rate limit hit, cache miss, slow query.
+  - `INFO` — significant business events: user registered, order placed, payment processed.
+  - `DEBUG` — development only. Never deploy with DEBUG enabled in production.
+- Distributed tracing: propagate trace context (`traceparent` header) across all service-to-service calls. Every outgoing HTTP/gRPC/queue message carries the trace ID.
+- Metrics to expose: request rate, error rate, latency percentiles (p50, p95, p99), active connections, queue depth, cache hit rate. Use Prometheus format.
+- Alert on symptoms (error rate >1%, p99 latency >2s) not causes. Avoid alert fatigue — every alert must be actionable.
+
+## Caching
+
+- Cache strategy decision tree:
+  - Data changes rarely + stale data acceptable → **Cache-aside** (check cache → miss → query DB → write cache)
+  - Data changes often + stale data unacceptable → **Write-through** (write DB + cache simultaneously)
+  - Expensive computation + immutable inputs → **Memoization** with TTL
+- Cache key format: `{service}:{entity}:{id}:{version}` — e.g., `user-service:profile:123:v2`.
+- Always set TTL. Infinite TTL = memory leak. Typical: config data (1h), user profiles (15m), search results (5m).
+- Cache stampede prevention: use probabilistic early expiration or lock-based recomputation. Never let 1000 requests simultaneously recompute the same expired key.
+- Invalidation: prefer event-driven invalidation (on write, publish cache-invalidation event) over TTL-only. TTL is the safety net, not the primary strategy.
+
+## Async Processing
+
+- Message/job queue for: email sending, PDF generation, webhook delivery, data exports, image processing — anything that takes >500ms or can fail independently.
+- Jobs must be idempotent. If a job runs twice with the same input, the result must be the same (use idempotency keys).
+- Dead letter queue (DLQ) for failed messages. Monitor DLQ size. Alert if DLQ grows >100 messages.
+- Job processing order: FIFO by default. Priority queues for time-sensitive operations.
+- Implement job progress tracking for long-running operations. Expose status via API endpoint (`GET /jobs/:id/status`).
+
+## Testing
+
+- Unit tests: test service layer business logic in isolation. Mock repositories and external services.
+- Integration tests: test API endpoints with a real database (use test containers or in-memory DB). These are your most valuable tests.
+- Contract tests: if consuming/providing APIs between services, use Pact or similar to verify contracts don't break.
+- Load tests: run before every release that touches data path. Baseline: the system must handle 2x current peak traffic.
+- Test database state: each test creates its own data, cleans up after. No shared test data. No test ordering dependencies. Use database transactions that roll back after each test.

package/templates/teams/be/references/api-design.md

@@ -0,0 +1,91 @@
+# API Design
+
+## RESTful URL Structure
+
+- Collections: `GET /users`, `POST /users`
+- Items: `GET /users/:id`, `PUT /users/:id`, `PATCH /users/:id`, `DELETE /users/:id`
+- Nested: `GET /users/:id/orders`, `POST /users/:id/orders`
+- Actions (non-CRUD): `POST /orders/:id/cancel`, `POST /users/:id/verify`
+
+## HTTP Status Codes
+
+Use semantically correct codes — not just 200 and 500:
+
+| Code | Meaning | When to use |
+|------|---------|-------------|
+| 200 | OK | Success with body |
+| 201 | Created | Resource created (+ `Location` header) |
+| 204 | No Content | Success, no body (DELETE, some PUTs) |
+| 400 | Bad Request | Validation error (malformed input) |
+| 401 | Unauthenticated | No token or invalid token |
+| 403 | Forbidden | Valid token, insufficient permissions |
+| 404 | Not Found | Resource doesn't exist |
+| 409 | Conflict | Duplicate, version mismatch |
+| 422 | Unprocessable | Valid data, business logic rejection |
+| 429 | Too Many Requests | Rate limited (include `Retry-After` header) |
+| 500 | Server Error | Never intentional — means you have a bug |
+
+## Response Formats
+
+**Collections:**
+```json
+{
+  "data": [...],
+  "meta": { "total": 150, "page": 1, "perPage": 20, "hasMore": true }
+}
+```
+
+**Errors:**
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Email is required",
+    "details": [
+      { "field": "email", "message": "This field is required" }
+    ]
+  }
+}
+```
+`code` is machine-readable (for client logic), `message` is human-readable (for display).
+
+## Pagination
+
+- **Cursor-based** (recommended for large/real-time data): Opaque cursor token, no count query.
+  ```
+  GET /posts?cursor=eyJpZCI6MTAwfQ&limit=20
+  → { data: [...], meta: { nextCursor: "eyJpZCI6MTIwfQ", hasMore: true } }
+  ```
+- **Offset-based** (simple, for small static data): `?page=2&perPage=20`
+- Default sort must be deterministic — include `id` as tiebreaker.
+
+## Filtering & Sorting
+
+```
+GET /users?status=active&role=admin&created_after=2024-01-01
+GET /users?sort=created_at:desc,name:asc
+```
+
+Complex filters: POST to a search endpoint with filter body, not mega query strings.
+
+## Versioning
+
+- URL prefix: `/v1/users`, `/v2/users` for breaking changes
+- Adding optional response fields = NOT breaking
+- Removing/renaming fields, changing types, adding required params = BREAKING
+
+## Input Validation
+
+Validate everything at the API boundary:
+```typescript
+const createUserSchema = z.object({
+  email: z.string().email().max(255),
+  name: z.string().min(1).max(100),
+  role: z.enum(['user', 'admin']).default('user'),
+});
+```
+- String length limits on all fields
+- Enum validation for constrained values
+- Nested object validation
+- Array length limits
+- Reject unknown fields (`z.strict()`)

package/templates/teams/be/references/async-processing.md

@@ -0,0 +1,86 @@
+# Async Processing
+
+## When to Use Queues
+
+Move to a queue if the operation:
+- Takes > 500ms (email, PDF generation, image processing)
+- Can fail independently (webhook delivery, third-party API calls)
+- Doesn't need an immediate response (analytics, audit logging)
+- Has high throughput bursts (notification fanout, batch imports)
+
+## Job Design Rules
+
+1. **Idempotent**: Running the same job twice with the same input = same result. Use idempotency keys.
+   ```typescript
+   async processPayment(jobData: { orderId: string, idempotencyKey: string }) {
+     const existing = await db.payments.findByIdempotencyKey(jobData.idempotencyKey);
+     if (existing) return existing; // Already processed
+     // ... process payment
+   }
+   ```
+
+2. **Minimal payload**: Store IDs in the job, fetch fresh data in the worker.
+   ```typescript
+   // GOOD: minimal payload, fresh data
+   queue.add('send-invoice', { orderId: 'ord_123' });
+
+   // BAD: stale data in payload
+   queue.add('send-invoice', { order: { ...fullOrderObject } });
+   ```
+
+3. **Timeout**: Every job has a maximum execution time. Kill and retry if exceeded.
+
+4. **Progress tracking**: Long-running jobs expose status via API.
+   ```
+   POST /exports → 202 Accepted { jobId: "job_123" }
+   GET /exports/job_123/status → { status: "processing", progress: 45 }
+   ```
+
+## Dead Letter Queue (DLQ)
+
+- Failed messages (after max retries) go to DLQ, not silently dropped
+- Monitor DLQ size — alert if > 100 messages
+- DLQ messages must be inspectable (view payload, error reason, original timestamp)
+- Process DLQ manually or automatically after fixing the root cause
+
+## Retry Strategy
+
+```
+Attempt 1: immediate
+Attempt 2: 30 seconds
+Attempt 3: 2 minutes
+Attempt 4: 10 minutes
+Attempt 5: 1 hour
+Then → DLQ
+```
+
+- Use exponential backoff — not fixed intervals
+- Add jitter to prevent thundering herd
+- Different retry strategies for different error types:
+  - Network timeout → retry immediately
+  - Rate limited → respect Retry-After header
+  - Validation error → don't retry (fix the data)
+  - 500 error → retry with backoff
+
+## Queue Patterns
+
+**Fan-out**: One event triggers many jobs
+```
+order.created → [send-email, update-analytics, notify-warehouse, update-search-index]
+```
+
+**Priority queue**: Urgent operations processed first
+```
+queue.add('process-payment', data, { priority: 1 }); // High
+queue.add('send-marketing-email', data, { priority: 5 }); // Low
+```
+
+**Delayed jobs**: Schedule for later
+```
+queue.add('send-reminder', data, { delay: 24 * 60 * 60 * 1000 }); // 24h
+```
+
+**Rate-limited processing**: External API limits
+```
+queue.add('sync-to-crm', data, { limiter: { max: 10, duration: 1000 } }); // 10/sec
+```

package/templates/teams/be/references/auth-security.md

@@ -0,0 +1,58 @@
+# Authentication & Security
+
+## Authentication
+
+- **JWT tokens**: Short-lived access (15-30 min) + long-lived refresh (7-30 days) in httpOnly Secure SameSite=Strict cookie
+- **Password storage**: bcrypt (cost ≥ 12) or Argon2id. Never plain text, never MD5/SHA.
+- **API keys**: Service-to-service auth only. Rotate quarterly. Never for user-facing auth.
+- **OAuth2/OIDC**: For third-party login (Google, GitHub). Use authorization code flow with PKCE.
+
+## Authorization
+
+- Implement RBAC at minimum. Check permissions in middleware before controller executes.
+- **IDOR prevention** — always scope queries by authenticated user:
+  ```sql
+  -- BAD: anyone can access any order
+  SELECT * FROM orders WHERE id = :orderId
+  -- GOOD: scoped to user
+  SELECT * FROM orders WHERE id = :orderId AND user_id = :currentUserId
+  ```
+- Test every endpoint: can user A access user B's resources by changing the ID?
+
+## Rate Limiting
+
+| Tier | Limit | Use case |
+|------|-------|----------|
+| Anonymous | 60/min per IP | Public endpoints |
+| Authenticated | 300/min per user | Standard API access |
+| Premium | 1000/min per user | Paid tier |
+| Login | 5/min per IP | Brute force prevention |
+| Password reset | 3/hour per email | Abuse prevention |
+
+- Return `429` with `Retry-After` header
+- Use sliding window algorithm (more fair than fixed window)
+- Rate limit by user ID for authenticated, by IP for anonymous
+
+## Input Security
+
+- **SQL injection**: Parameterized queries always. Never string concatenation for SQL.
+- **Mass assignment**: Whitelist allowed fields from request body. Never pass raw body to ORM create/update.
+- **Path traversal**: Validate file paths. Never use user input directly in `fs.readFile()` or similar.
+- **ReDoS**: Avoid user-controlled regex patterns. Set timeout on regex matching.
+
+## Headers
+
+```
+Strict-Transport-Security: max-age=31536000; includeSubDomains
+X-Content-Type-Options: nosniff
+X-Frame-Options: DENY
+Content-Security-Policy: default-src 'self'
+X-Request-Id: {unique-id}  (for tracing)
+```
+
+## Secrets Management
+
+- Secrets from secret manager (Vault, AWS SSM, GCP Secret Manager)
+- Never in code, environment files, or Docker images
+- Rotate on: employee offboarding, suspected compromise, quarterly schedule
+- Use short-lived credentials where possible (IAM roles, temporary tokens)