@sienklogic/plan-build-run 2.3.0 → 2.4.0

package/plugins/copilot-pbr/templates/research-outputs/synthesis.md.tmpl

@@ -0,0 +1,36 @@
+# Research Synthesis: {Topic}
+
+> Synthesized: {date}
+> Mode: synthesis
+> Input documents: {count}
+> Confidence: {overall}
+
+## Executive Summary
+
+{Unified findings across all input documents}
+
+## Key Findings
+
+{Numbered list of the most important findings, with source document attribution}
+
+## Contradictions Resolved
+
+{Where input documents disagreed and how it was resolved}
+
+| Topic | Document A Says | Document B Says | Resolution | Basis |
+|-------|----------------|----------------|------------|-------|
+| ... | ... | ... | ... | ... |
+
+## Recommended Approach
+
+{The synthesized recommendation}
+
+## Risks and Mitigations
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| ... | ... | ... | ... |
+
+## Sources
+
+{Consolidated source list from all input documents}

package/plugins/cursor-pbr/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "pbr",
   "displayName": "Plan-Build-Run",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Plan-Build-Run — Structured development workflow for Cursor. Solves context rot through disciplined subagent delegation, structured planning, atomic execution, and goal-backward verification.",
   "author": {
     "name": "SienkLogic",
@@ -12,9 +12,19 @@
   "repository": "https://github.com/SienkLogic/plan-build-run",
   "license": "MIT",
   "logo": "../assets/logo.svg",
-  "keywords": ["cursor", "context-engineering", "development-workflow", "subagent-delegation"],
+  "keywords": [
+    "cursor",
+    "context-engineering",
+    "development-workflow",
+    "subagent-delegation"
+  ],
   "category": "developer-tools",
-  "tags": ["planning", "workflow", "structured-development", "context-management"],
+  "tags": [
+    "planning",
+    "workflow",
+    "structured-development",
+    "context-management"
+  ],
   "skills": "./skills/",
   "agents": "./agents/",
   "rules": "./rules/",

package/plugins/cursor-pbr/skills/dashboard/SKILL.md

@@ -8,15 +8,25 @@ argument-hint: "[--port N]"
 
 1. **Parse arguments**: Extract `--port N` from the user's input. Default to `3000`.
 
-2. **Check dependencies**: Check if the dashboard `node_modules/` exists in the plugin's dashboard directory. If not, run `npm install` in that directory.
+2. **Locate dashboard**: The dashboard lives at `../../dashboard/` relative to this plugin's root directory (i.e. two levels up from `plugins/cursor-pbr/`). Resolve the absolute path.
 
-3. **Launch dashboard**: Run in background:
+3. **Check dependencies**: Check if `node_modules/` exists in the dashboard directory. If not, run:
    ```
-   node <plugin-root>/dashboard/bin/cli.js --dir <cwd> --port <port> &
+   npm install --prefix <dashboard-dir>
    ```
 
-4. **Output to user**:
+4. **Launch dashboard**: Run in background:
+   ```
+   node <dashboard-dir>/bin/cli.js --dir <cwd> --port <port> &
+   ```
+
+5. **Output to user**:
    ```
    Dashboard running at http://localhost:<port>
    Open this URL in your browser to view your project's planning state.
    ```
+
+## Notes
+
+- If the port is already in use, the dashboard will fail to start — suggest the user try a different port with `--port`.
+- The dashboard watches `.planning/` for live updates via SSE.

package/plugins/cursor-pbr/skills/do/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: do
+description: "Route freeform text to the right PBR skill automatically."
+argument-hint: "<freeform description of what you want to do>"
+---
+
+# /pbr:do — Freeform Task Router
+
+You are running the **do** skill. Your job is to analyze freeform text from the user and route it to the most appropriate PBR skill. You are a dispatcher, not an executor — you never do the work yourself.
+
+## Step 0 — Immediate Output
+
+**Before ANY tool calls**, display this banner:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN-BUILD-RUN ► ROUTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then proceed to Step 1.
+
+## Step 1 — Validate Input
+
+If `$ARGUMENTS` is empty, ask the user what they want to do via AskUserQuestion:
+```
+What would you like to do? Describe the task, bug, or idea and I'll route it to the right skill.
+```
+
+## Step 2 — Analyze and Route
+
+Evaluate `$ARGUMENTS` against these routing criteria. Apply the **first matching** rule:
+
+| If the text describes... | Route to | Why |
+|--------------------------|----------|-----|
+| A bug, error, crash, failure, or something broken | `/pbr:debug` | Needs systematic investigation |
+| Exploration, research, comparison, or "how does X work" | `/pbr:explore` | Open-ended investigation |
+| A complex task: refactoring, migration, multi-file architecture, system redesign | `/pbr:plan add` | Needs a full phase with research/plan/build cycle |
+| A review or quality concern about existing work | `/pbr:review` | Needs verification against plan |
+| A note, idea, or "remember to..." | `/pbr:note` | Capture for later |
+| A specific, actionable task (add feature, fix typo, update config, write test) | `/pbr:quick` | Self-contained, single executor |
+
+**Ambiguity handling**: If the text could reasonably match multiple routes, ask the user via AskUserQuestion with the top 2-3 options. For example:
+
+```
+"Refactor the authentication system" could be:
+- /pbr:plan add — Full planning cycle (recommended for multi-file refactors)
+- /pbr:quick — Quick execution (if scope is small and clear)
+```
+
+## Step 3 — Confirm and Dispatch
+
+Display the routing decision:
+
+```
+**Input:** {first 80 chars of arguments}
+**Routing to:** {chosen skill}
+**Reason:** {one-line explanation}
+```
+
+Then invoke the chosen skill via the Skill tool, passing `$ARGUMENTS` as the args.
+
+**Special case for `/pbr:plan add`**: When routing to plan, check if `.planning/ROADMAP.md` exists first (via Read). If it doesn't, suggest `/pbr:begin` instead — the user needs to set up the project before they can add phases.
+
+## Step 4 — No Follow-Up
+
+After invoking the skill, your job is done. The dispatched skill handles everything from here (execution, commits, state updates). Do not add any additional output after the Skill tool call.

package/plugins/cursor-pbr/skills/milestone/SKILL.md

@@ -260,10 +260,13 @@ Archive a completed milestone and prepare for the next one.
 
 5. **Archive milestone documents:**
 
-   Copy/create archive files:
-   - `.planning/milestones/{version}-ROADMAP.md` — snapshot of ROADMAP.md at completion
-   - `.planning/milestones/{version}-REQUIREMENTS.md` — snapshot of REQUIREMENTS.md
-   - `.planning/milestones/{version}-STATS.md` — milestone statistics
+   Create a versioned archive directory and move phase directories into it:
+   - `.planning/milestones/{version}/ROADMAP.md` — snapshot of ROADMAP.md at completion
+   - `.planning/milestones/{version}/REQUIREMENTS.md` — snapshot of REQUIREMENTS.md
+   - `.planning/milestones/{version}/STATS.md` — milestone statistics
+   - `.planning/milestones/{version}/phases/{NN}-{slug}/` — move each milestone phase directory from `.planning/phases/` into the archive
+
+   **Move phases:** For each phase belonging to this milestone, move (not copy) its directory from `.planning/phases/{NN}-{slug}/` to `.planning/milestones/{version}/phases/{NN}-{slug}/`. This keeps the active phases directory clean for the next milestone.
 
    **Stats file content:**
 
@@ -290,7 +293,7 @@ Archive a completed milestone and prepare for the next one.
    ```markdown
    ## Milestone: {name} ({version}) -- COMPLETED
 
-   Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}-ROADMAP.md` for details.
+   Phases {start}-{end} completed on {date}. See `.planning/milestones/{version}/ROADMAP.md` for details.
 
    | Phase | Status |
    |-------|--------|
@@ -322,7 +325,7 @@ Archive a completed milestone and prepare for the next one.
 
 9. **Commit:**
    ```bash
-   git add .planning/milestones/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
+   git add .planning/milestones/ .planning/phases/ .planning/ROADMAP.md .planning/PROJECT.md .planning/STATE.md .planning/HISTORY.md
    git commit -m "docs(planning): complete milestone {version}"
    ```
 
@@ -339,7 +342,7 @@ Archive a completed milestone and prepare for the next one.
     - {count} commits, {lines} lines of code
     - {duration} days
 
-    Archived to: .planning/milestones/{version}-*
+    Archived to: .planning/milestones/{version}/
     Git tag: {version}
 
     ───────────────────────────────────────────────────────────────

package/plugins/cursor-pbr/skills/todo/SKILL.md

@@ -184,17 +184,38 @@ Todo {NNN} not found in pending todos.
 2. If not found, display the same error block as `done` — suggest `/pbr:todo list`
 3. Read the todo file content (frontmatter + body)
 4. Extract the `title` from frontmatter and the full body (Goal, Scope, Acceptance Criteria sections)
-5. Display branded output:
+
+5. **Assess complexity** to choose the right skill. Evaluate the todo content against these criteria:
+
+| Signal | Route to |
+|--------|----------|
+| Single file change, small fix, simple addition | `/pbr:quick` |
+| Multiple acceptance criteria, multi-file scope, architectural decisions, needs research | `/pbr:plan` (requires an active phase) |
+| Investigation needed, unclear root cause | `/pbr:debug` |
+| Open-ended exploration, no clear deliverable | `/pbr:explore` |
+
+If unsure, ask the user via AskUserQuestion:
+```
+Todo {NNN} could be handled as a quick task or may need full planning.
+
+Which approach?
+- Quick task (/pbr:quick) — single executor, atomic commit
+- Full planning (/pbr:plan) — research, plan, build cycle
+- Debug (/pbr:debug) — systematic investigation
+- Explore (/pbr:explore) — open-ended investigation
+```
+
+6. Display branded output:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  PLAN-BUILD-RUN ► WORKING ON TODO {NNN}
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 **Todo {NNN}:** {title}
-
-Launching /pbr:quick with todo context...
+**Routing to:** /pbr:{chosen-skill}
 ```
-6. Invoke the Skill tool: `skill: "pbr:quick"` with `args` set to the todo title followed by the body content. Format the args as:
+
+7. Invoke the chosen skill via the Skill tool, passing the todo title and body as args:
 
 ```
 {title}
@@ -203,7 +224,9 @@ Context from todo {NNN}:
 {body content — Goal, Scope, Acceptance Criteria sections}
 ```
 
-This hands off execution to `/pbr:quick`, which will spawn an executor agent, make atomic commits, and track the work. When quick completes, remind the user:
+For `/pbr:plan`, if no phase exists for this work yet, suggest the user run `/pbr:plan add` first to create one, then re-run `/pbr:todo work {NNN}`.
+
+8. When the skill completes, remind the user:
 
 ```
 ───────────────────────────────────────────────────────────────

package/plugins/cursor-pbr/templates/codebase/ARCHITECTURE.md.tmpl

@@ -0,0 +1,98 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for ARCHITECTURE.md codebase analysis -->
+# Architecture
+
+> Analyzed: {date}
+> Pattern: {MVC / Layered / Hexagonal / Microservices / Monolith / etc.}
+
+## Pattern Overview
+
+{2-3 paragraphs describing the overall architectural pattern with evidence from the codebase}
+
+**Evidence**: {file paths, import patterns, directory structure that support this classification}
+
+## Layers
+
+| Layer | Purpose | Directory | Key Files |
+|-------|---------|-----------|-----------|
+| {Presentation} | {UI rendering} | {src/components/} | {App.tsx, Layout.tsx} |
+| {API/Routes} | {HTTP handling} | {src/routes/ or src/app/api/} | {users.ts, auth.ts} |
+| {Business Logic} | {Core domain} | {src/services/} | {UserService.ts} |
+| {Data Access} | {Database interaction} | {src/repositories/ or src/db/} | {UserRepo.ts} |
+| {Infrastructure} | {External services} | {src/lib/ or src/integrations/} | {email.ts, storage.ts} |
+
+### Layer Rules
+
+{How layers communicate — what imports what? What are the dependency rules?}
+
+```
+Presentation → API → Business → Data Access → Database
+                ↓
+            Infrastructure
+```
+
+## Data Flow
+
+### Request Lifecycle
+
+{How a typical request flows through the system}
+
+```
+1. Client sends request
+2. → {Router/Framework} routes to handler
+3. → {Middleware} runs (auth, validation, logging)
+4. → {Controller/Handler} processes request
+5. → {Service} executes business logic
+6. → {Repository/Model} queries database
+7. → Response returns through the stack
+```
+
+### State Management
+
+| Context | Approach | Implementation | Files |
+|---------|----------|---------------|-------|
+| Client state | {Redux / Zustand / Context / etc.} | {how it's structured} | {store files} |
+| Server state | {React Query / SWR / etc.} | {how it's used} | {hook files} |
+| Session state | {JWT / cookies / etc.} | {how it's managed} | {auth files} |
+
+## Key Abstractions
+
+| Abstraction | Purpose | Implementation | Used By |
+|-------------|---------|---------------|---------|
+| {Repository} | {Database access} | {Abstract class + implementations} | {Services} |
+| {Middleware} | {Cross-cutting concerns} | {Function signature} | {Routes} |
+| {DTO/Schema} | {Data validation} | {Zod schemas / class-validator} | {Routes, Services} |
+
+## Entry Points
+
+| Type | File | Config | Notes |
+|------|------|--------|-------|
+| Web app | {src/app/page.tsx} | {port 3000} | {Next.js App Router} |
+| API server | {src/server.ts} | {port 8080} | {Express server} |
+| CLI | {src/cli.ts} | - | {Commander.js} |
+| Workers | {src/workers/} | {queue config} | {Bull/BullMQ} |
+| Cron | {src/cron/} | {schedule} | {node-cron} |
+
+## Error Handling Strategy
+
+| Layer | Pattern | Implementation |
+|-------|---------|---------------|
+| API | {Error middleware + HTTP status codes} | {src/middleware/error.ts} |
+| Service | {Custom error classes} | {src/errors/} |
+| Client | {Error boundaries + toast notifications} | {src/components/ErrorBoundary.tsx} |
+
+### Error Flow
+
+```
+Service throws AppError → Controller catches → Error middleware formats response → Client displays
+```
+
+## Security Architecture
+
+| Aspect | Implementation | Files |
+|--------|---------------|-------|
+| Authentication | {how auth works} | {files} |
+| Authorization | {RBAC / ABAC / etc.} | {files} |
+| Input validation | {where and how} | {files} |
+| CORS | {configuration} | {files} |
+| Rate limiting | {if present} | {files} |
+| CSRF protection | {if present} | {files} |

package/plugins/cursor-pbr/templates/codebase/CONCERNS.md.tmpl

@@ -0,0 +1,93 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for CONCERNS.md codebase analysis -->
+# Concerns & Technical Debt
+
+> Analyzed: {date}
+> Severity summary: {n critical, n high, n medium, n low}
+
+## Technical Debt
+
+| # | Area | Issue | Severity | Files | Evidence |
+|---|------|-------|----------|-------|----------|
+| 1 | {area} | {what's wrong} | critical/high/medium/low | {file paths} | {what you saw} |
+| 2 | {area} | {what's wrong} | {severity} | {file paths} | {what you saw} |
+
+### Debt Details
+
+#### TD-1: {Issue Title}
+
+**Severity**: {critical / high / medium / low}
+**Files**: {list of affected files}
+**Description**: {detailed description of the issue}
+**Evidence**: {specific code examples, line numbers}
+**Impact**: {what problems this causes or could cause}
+**Recommendation**: {specific action to fix}
+
+## Known Bugs
+
+| # | Description | Severity | Location | Reproduction |
+|---|-------------|----------|----------|--------------|
+| 1 | {bug description} | {severity} | {file:line} | {how to trigger} |
+
+## Security Considerations
+
+| # | Issue | Severity | Location | Recommendation |
+|---|-------|----------|----------|----------------|
+| 1 | {Missing input validation on API} | high | {src/routes/users.ts} | {Add zod schema validation} |
+| 2 | {Hardcoded secret in source} | critical | {src/config.ts:42} | {Move to environment variable} |
+| 3 | {SQL injection risk} | critical | {src/db/queries.ts:15} | {Use parameterized queries} |
+| 4 | {No rate limiting} | medium | {src/server.ts} | {Add express-rate-limit} |
+| 5 | {No CSRF protection} | medium | {src/routes/} | {Add csrf tokens} |
+
+## Performance Risks
+
+| # | Issue | Location | Impact | Recommendation |
+|---|-------|----------|--------|----------------|
+| 1 | {N+1 query in user list} | {src/routes/users.ts:30} | {Slow page load} | {Use eager loading} |
+| 2 | {No pagination on large queries} | {src/routes/posts.ts:15} | {Memory exhaustion} | {Add cursor pagination} |
+| 3 | {Synchronous file operations} | {src/utils/file.ts} | {Blocks event loop} | {Use async fs methods} |
+
+## Fragile Areas
+
+| # | Area | Why Fragile | Impact of Breaking | Files |
+|---|------|-------------|-------------------|-------|
+| 1 | {Auth middleware} | {Tightly coupled to 5 services} | {All protected routes fail} | {files} |
+| 2 | {Data migration} | {No rollback mechanism} | {Data loss on failure} | {files} |
+
+## Dependency Risks
+
+| Package | Version | Issue | Recommendation |
+|---------|---------|-------|----------------|
+| {package} | {version} | {Deprecated / EOL / Known vulnerability} | {Update to X / Replace with Y} |
+
+## Scaling Limitations
+
+| # | Limitation | When It Breaks | Current State | Fix Approach |
+|---|-----------|---------------|---------------|-------------|
+| 1 | {Single database instance} | {>1000 concurrent users} | {adequate for current load} | {Read replicas} |
+| 2 | {In-memory session store} | {Multiple server instances} | {single instance} | {Redis session store} |
+
+## Missing Infrastructure
+
+| Category | Status | Impact | Priority |
+|----------|--------|--------|----------|
+| Error monitoring | {absent/partial/present} | {bugs go unnoticed} | {high} |
+| Logging | {absent/partial/present} | {hard to debug production} | {high} |
+| CI/CD | {absent/partial/present} | {manual deployments} | {medium} |
+| Automated tests | {absent/partial/present} | {regressions not caught} | {high} |
+| Documentation | {absent/partial/present} | {onboarding difficulty} | {low} |
+| Backup/Recovery | {absent/partial/present} | {data loss risk} | {critical} |
+| Health checks | {absent/partial/present} | {outages not detected} | {medium} |
+
+## Recommendations (Prioritized)
+
+### Critical (Fix Immediately)
+1. {Recommendation with specific action}
+
+### High (Fix Soon)
+1. {Recommendation with specific action}
+
+### Medium (Plan to Fix)
+1. {Recommendation with specific action}
+
+### Low (When Convenient)
+1. {Recommendation with specific action}

package/plugins/cursor-pbr/templates/codebase/CONVENTIONS.md.tmpl

@@ -0,0 +1,104 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for CONVENTIONS.md codebase analysis -->
+# Code Conventions
+
+> Analyzed: {date}
+> Based on: {n} files inspected
+
+## Naming Conventions
+
+| Entity | Convention | Example |
+|--------|-----------|---------|
+| Files (components) | {PascalCase.tsx} | `UserProfile.tsx` |
+| Files (utilities) | {camelCase.ts} | `formatDate.ts` |
+| Functions | {camelCase} | `getUserById` |
+| Classes | {PascalCase} | `UserService` |
+| Interfaces | {PascalCase, no I prefix} | `UserProfile` |
+| Types | {PascalCase} | `CreateUserInput` |
+| Constants | {SCREAMING_SNAKE_CASE or camelCase} | `MAX_RETRIES` or `maxRetries` |
+| Enum members | {PascalCase} | `UserRole.Admin` |
+| Environment variables | {SCREAMING_SNAKE_CASE} | `DATABASE_URL` |
+| CSS classes | {kebab-case or camelCase modules} | `user-profile` |
+| Database tables | {snake_case} | `user_profiles` |
+| API endpoints | {kebab-case} | `/api/user-profiles` |
+
+## Code Style
+
+| Aspect | Setting | Config File |
+|--------|---------|-------------|
+| Indentation | {2 spaces / 4 spaces / tabs} | {.editorconfig / .prettierrc} |
+| Quotes | {single / double} | {.prettierrc} |
+| Semicolons | {yes / no} | {.prettierrc} |
+| Trailing commas | {all / es5 / none} | {.prettierrc} |
+| Line width | {80 / 100 / 120} | {.prettierrc} |
+| Line endings | {LF / CRLF} | {.editorconfig} |
+
+## Import Organization
+
+{Observed import order pattern from the codebase}
+
+```{language}
+// 1. Node.js built-in modules
+import path from 'path';
+
+// 2. External packages
+import React from 'react';
+import { z } from 'zod';
+
+// 3. Internal aliases
+import { Button } from '@/components/ui';
+import { useAuth } from '@/hooks/useAuth';
+
+// 4. Relative imports
+import { UserCard } from './UserCard';
+import type { User } from './types';
+
+// 5. Style imports
+import styles from './UserProfile.module.css';
+```
+
+## Function Patterns
+
+### Async Functions
+
+```{language}
+// Pattern used in this codebase: {evidence file:line}
+{actual code pattern from codebase}
+```
+
+### Error Handling
+
+```{language}
+// Pattern used in this codebase: {evidence file:line}
+{actual code pattern from codebase}
+```
+
+### API Route Handlers
+
+```{language}
+// Pattern used in this codebase: {evidence file:line}
+{actual code pattern from codebase}
+```
+
+### React Components
+
+```{language}
+// Pattern used in this codebase: {evidence file:line}
+{actual code pattern from codebase}
+```
+
+## Comment Conventions
+
+| When | Style | Example |
+|------|-------|---------|
+| {Complex logic} | {inline comment} | `// Calculate tax with progressive rates` |
+| {Public API} | {JSDoc} | `/** @param user - The user to validate */` |
+| {Temporary} | {TODO with ticket} | `// TODO(#123): refactor after migration` |
+| {Warning} | {IMPORTANT prefix} | `// IMPORTANT: this must run before auth` |
+
+## Git Conventions
+
+| Aspect | Convention | Example |
+|--------|-----------|---------|
+| Branch naming | {pattern} | `feature/add-user-auth` |
+| Commit format | {conventional commits / custom} | `feat(auth): add login flow` |
+| PR titles | {pattern} | `[Feature] Add user authentication` |

package/plugins/cursor-pbr/templates/codebase/INTEGRATIONS.md.tmpl

@@ -0,0 +1,78 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for INTEGRATIONS.md codebase analysis -->
+# External Integrations
+
+> Analyzed: {date}
+> Total integrations: {n}
+
+## APIs
+
+| Service | Type | Auth Method | Config Var | Used In | Documentation |
+|---------|------|-------------|------------|---------|---------------|
+| {Discord API} | REST | {OAuth2} | DISCORD_TOKEN | {src/integrations/discord.ts} | {URL} |
+| {Stripe} | REST | {API Key} | STRIPE_SECRET_KEY | {src/payments/} | {URL} |
+
+### API Client Patterns
+
+{How API calls are made in this codebase — fetch wrapper? axios instance? SDK?}
+
+```{language}
+// Example from codebase: {file:line}
+{actual code pattern}
+```
+
+## Databases
+
+| Database | Type | ORM/Driver | Config | Schema Location | Migrations |
+|----------|------|-----------|--------|-----------------|------------|
+| {PostgreSQL} | {Relational} | {Prisma} | DATABASE_URL | {prisma/schema.prisma} | {prisma/migrations/} |
+| {Redis} | {Key-value} | {ioredis} | REDIS_URL | - | - |
+
+### Database Patterns
+
+{How database access is structured — repository pattern? direct queries? ORM models?}
+
+## Authentication & Authorization
+
+| Aspect | Implementation | Config | Files |
+|--------|---------------|--------|-------|
+| Method | {JWT / Session / OAuth} | {env vars} | {files} |
+| Provider | {self / Auth0 / Clerk / etc.} | {env vars} | {files} |
+| Storage | {cookie / localStorage / header} | - | {files} |
+| Roles | {admin, user, etc.} | {where defined} | {files} |
+
+## Email/Notifications
+
+| Service | Purpose | Config | Used In |
+|---------|---------|--------|---------|
+| {SendGrid} | {Transactional email} | SENDGRID_KEY | {src/email/} |
+
+## File Storage
+
+| Service | Purpose | Config | Used In |
+|---------|---------|--------|---------|
+| {S3} | {User uploads} | AWS_* vars | {src/storage/} |
+
+## Monitoring & Logging
+
+| Tool | Purpose | Config | Used In |
+|------|---------|--------|---------|
+| {Sentry} | {Error tracking} | SENTRY_DSN | {src/lib/sentry.ts} |
+| {Winston} | {Logging} | - | {src/lib/logger.ts} |
+
+## CI/CD
+
+| Platform | Config | Stages | Deployment |
+|----------|--------|--------|------------|
+| {GitHub Actions} | {.github/workflows/} | {lint, test, build, deploy} | {Vercel / AWS / etc.} |
+
+### Pipeline Details
+
+{Description of the CI/CD pipeline flow}
+
+## Infrastructure
+
+| Component | Provider | Config | Notes |
+|-----------|----------|--------|-------|
+| {Hosting} | {Vercel} | {vercel.json} | {auto-deploy from main} |
+| {DNS} | {Cloudflare} | - | {if relevant} |
+| {CDN} | {included with host} | - | - |