@sienklogic/plan-build-run 2.0.0

package/plugins/pbr/templates/VERIFICATION-DETAIL.md.tmpl

@@ -0,0 +1,116 @@
+<!-- Source: agents/verifier.md | Purpose: Detailed output format for verification reports produced by the verifier agent -->
+
+```yaml
+---
+phase: "{phase_id}"
+verified: "{ISO timestamp}"
+status: "passed"           # passed | gaps_found | human_needed
+is_re_verification: false  # true if re-verifying after gap closure
+score:
+  total_must_haves: {n}
+  verified: {n}
+  failed: {n}
+  partial: {n}
+  human_needed: {n}
+gaps:
+  - must_have: "{description of the failed must-have}"
+    level: "{existence | substantive | wired}"
+    evidence: "{what you found}"
+    recommendation: "{specific action to fix}"
+anti_patterns:
+  todos: {count}
+  stubs: {count}
+  console_logs: {count}
+  skipped_tests: {count}
+  hardcoded_secrets: {count}
+---
+
+# Phase Verification: {phase_name}
+
+> Verified: {date}
+> Status: **{STATUS}**
+> Score: {verified}/{total} must-haves verified
+> Re-verification: {yes/no}
+
+## Observable Truths
+
+| # | Truth | Status | Evidence |
+|---|-------|--------|----------|
+| 1 | {truth statement} | VERIFIED | {evidence summary with file paths and line numbers} |
+| 2 | {truth statement} | FAILED | {what's wrong, what was expected, what was found} |
+| 3 | {truth statement} | HUMAN_NEEDED | {why it can't be verified programmatically} |
+
+## Artifact Verification
+
+| # | Artifact | L1: Exists | L2: Substantive | L3: Wired | Status |
+|---|----------|-----------|-----------------|-----------|--------|
+| 1 | `{file/export}` | YES | YES (142 lines, real logic) | WIRED (imported by 3 files) | PASS |
+| 2 | `{file/export}` | YES | STUB (TODO at L42, empty handler L67) | N/A | FAIL |
+| 3 | `{file/export}` | YES | YES | ORPHANED (not imported anywhere) | FAIL |
+| 4 | `{file/export}` | NO | N/A | N/A | FAIL |
+
+## Key Link Verification
+
+| # | Link Description | Source | Target | Status | Evidence |
+|---|-----------------|--------|--------|--------|----------|
+| 1 | {what connects to what} | `{source_file}` | `{target_file}` | WIRED | Import at L12, called at L45 |
+| 2 | {what connects to what} | `{source_file}` | `{target_file}` | BROKEN | Imported but never called |
+
+## Gaps Found
+
+{Only present if status is gaps_found}
+
+### Gap 1: {Short description}
+
+- **Must-Have**: {which must-have this gap blocks}
+- **Level Failed**: {existence / substantive / wired}
+- **Evidence**: {specific evidence — file paths, line numbers, command output}
+- **Impact**: {what doesn't work because of this gap}
+- **Recommendation**: {specific action to close this gap}
+
+### Gap 2: {Short description}
+...
+
+## Human Verification Items
+
+{Only present if there are items requiring human verification}
+
+### Item 1: {What needs checking}
+
+- **Must-Have**: {which must-have this relates to}
+- **Why Manual**: {why it can't be verified automatically}
+- **How to Test**: {step-by-step instructions}
+- **Expected Result**: {what success looks like}
+
+## Anti-Pattern Scan
+
+| Pattern | Count | Severity | Files |
+|---------|-------|----------|-------|
+| TODO/FIXME comments | {n} | {low/medium/high} | {file list} |
+| Stub implementations | {n} | {high} | {file list} |
+| Console.log in production | {n} | {low} | {file list} |
+| Skipped tests | {n} | {medium} | {file list} |
+| Hardcoded secrets | {n} | {critical} | {file list} |
+| Empty catch blocks | {n} | {medium} | {file list} |
+
+## Regressions
+
+{Only present in re-verification mode}
+
+| # | Must-Have | Previous Status | Current Status | Evidence |
+|---|----------|----------------|----------------|----------|
+| 1 | {must-have} | VERIFIED | FAILED | {what changed} |
+
+## Summary
+
+### Phase Health
+- **Must-haves**: {n}/{total} verified ({percentage}%)
+- **Gaps**: {n} blocking, {n} non-blocking
+- **Anti-patterns**: {n} total ({n} critical)
+- **Human items**: {n} pending
+
+### Recommendations
+1. {Most important action to take}
+2. {Second most important}
+3. ...
+```

package/plugins/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/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/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/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} | - | - |

package/plugins/pbr/templates/codebase/STACK.md.tmpl

@@ -0,0 +1,78 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for STACK.md codebase analysis -->
+# Technology Stack
+
+> Analyzed: {date}
+> Project: {project name from package.json or directory}
+
+## Languages & Runtime
+
+| Language | Version | Config | Notes |
+|----------|---------|--------|-------|
+| TypeScript | {version from tsconfig target or dep} | `tsconfig.json` | {strict mode? path aliases?} |
+| Node.js | {version from engines or .nvmrc} | `.nvmrc` / `package.json engines` | {LTS?} |
+
+## Frameworks
+
+| Framework | Version | Role | Entry Point | Config |
+|-----------|---------|------|-------------|--------|
+| {Next.js} | {14.x} | {Web framework} | {src/app/} | {next.config.js} |
+| {Express} | {4.x} | {API server} | {src/server.ts} | - |
+
+## Key Dependencies
+
+### Production Dependencies
+
+| Package | Version | Purpose | Used In |
+|---------|---------|---------|---------|
+| {prisma} | {5.x} | {ORM / database} | {src/db/} |
+| {zod} | {3.x} | {Validation} | {src/validators/} |
+
+### Development Dependencies
+
+| Package | Version | Purpose | Config |
+|---------|---------|---------|--------|
+| {jest} | {29.x} | {Testing} | {jest.config.ts} |
+| {eslint} | {8.x} | {Linting} | {.eslintrc.js} |
+
+## Build & Tooling
+
+| Tool | Config File | Purpose | Commands |
+|------|-------------|---------|----------|
+| {TypeScript} | `tsconfig.json` | {Compilation} | `npx tsc --noEmit` |
+| {ESLint} | `.eslintrc.js` | {Linting} | `npm run lint` |
+| {Prettier} | `.prettierrc` | {Formatting} | `npm run format` |
+| {Jest} | `jest.config.ts` | {Testing} | `npm test` |
+
+## Package Manager
+
+- **Manager**: {npm / yarn / pnpm / bun}
+- **Lock file**: {package-lock.json / yarn.lock / pnpm-lock.yaml}
+- **Workspaces**: {yes/no, if yes: list workspace paths}
+
+## Environment Configuration
+
+| Variable | Required | Default | Purpose | Where Used |
+|----------|----------|---------|---------|------------|
+| DATABASE_URL | YES | - | Database connection | {src/db/} |
+| {VAR_NAME} | {YES/NO} | {value} | {purpose} | {files} |
+
+**Template**: {`.env.example` exists? Y/N}
+
+## Platform Requirements
+
+| Requirement | Value | Source |
+|------------|-------|--------|
+| Node version | {>=18} | {package.json engines} |
+| OS | {any / linux only / etc.} | {evidence} |
+| Memory | {if specified} | {evidence} |
+| External services | {list databases, caches, etc.} | {docker-compose, docs} |
+
+## Scripts
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `dev` | {command} | {Start dev server} |
+| `build` | {command} | {Build for production} |
+| `test` | {command} | {Run tests} |
+| `lint` | {command} | {Run linter} |
+| {others} | {command} | {purpose} |

package/plugins/pbr/templates/codebase/STRUCTURE.md.tmpl

@@ -0,0 +1,80 @@
+<!-- Source: agents/codebase-mapper.md | Purpose: Output format for STRUCTURE.md codebase analysis -->
+# Project Structure
+
+> Analyzed: {date}
+
+## Directory Layout
+
+```
+{project_root}/
+├── src/                          # Source code
+│   ├── app/                      # {Purpose: Next.js App Router pages}
+│   │   ├── api/                  # {API route handlers}
+│   │   ├── (auth)/               # {Auth-related pages}
+│   │   └── layout.tsx            # {Root layout}
+│   ├── components/               # {Shared UI components}
+│   │   ├── ui/                   # {Primitive UI components}
+│   │   └── features/             # {Feature-specific components}
+│   ├── lib/                      # {Shared utilities and configurations}
+│   ├── services/                 # {Business logic}
+│   ├── models/                   # {Data models / types}
+│   ├── hooks/                    # {Custom React hooks}
+│   └── styles/                   # {Global styles}
+├── prisma/                       # {Database schema and migrations}
+├── public/                       # {Static assets}
+├── tests/                        # {Test files}
+├── docs/                         # {Documentation}
+└── scripts/                      # {Build/deploy scripts}
+```
+
+## File Naming Conventions
+
+| Type | Pattern | Example |
+|------|---------|---------|
+| React components | {PascalCase.tsx} | `UserProfile.tsx` |
+| Hooks | {camelCase.ts, use* prefix} | `useAuth.ts` |
+| Utilities | {camelCase.ts} | `formatDate.ts` |
+| Types | {PascalCase.ts or types.ts} | `User.ts`, `types.ts` |
+| Tests | {*.test.ts or *.spec.ts} | `UserProfile.test.tsx` |
+| API routes | {route.ts in directory} | `app/api/users/route.ts` |
+| Config | {lowercase with dots} | `jest.config.ts` |
+| Constants | {UPPER_CASE or camelCase} | `constants.ts` |
+
+## Module Boundaries
+
+{How the code is organized into modules/features and what the boundaries are}
+
+| Module | Directory | Responsibility | Dependencies |
+|--------|-----------|---------------|-------------|
+| {Auth} | {src/auth/} | {Authentication & session} | {Database, Config} |
+| {Users} | {src/users/} | {User CRUD} | {Auth, Database} |
+
+## Import Patterns
+
+{How imports are organized in this codebase}
+
+```{language}
+// Standard import order observed in this project:
+// {example from actual codebase}
+```
+
+### Path Aliases
+
+| Alias | Maps To | Config |
+|-------|---------|--------|
+| `@/` | `src/` | `tsconfig.json paths` |
+| `@components/` | `src/components/` | `tsconfig.json paths` |
+
+## Where to Add Code
+
+| Type of Code | Location | Convention | Example |
+|-------------|----------|------------|---------|
+| New API route | `src/app/api/{resource}/route.ts` | {pattern} | {example} |
+| New component | `src/components/{feature}/` | {pattern} | {example} |
+| New service | `src/services/` | {pattern} | {example} |
+| New model | `src/models/` | {pattern} | {example} |
+| New test | `{co-located or tests/}` | {pattern} | {example} |
+| New utility | `src/lib/` or `src/utils/` | {pattern} | {example} |
+| New hook | `src/hooks/` | {pattern} | {example} |
+| New migration | `prisma/migrations/` | `npx prisma migrate dev` | - |
+| New env var | `.env` + `.env.example` | {pattern} | {example} |