ragarciaruben 1.20.7 → 1.20.8

package/.github/agents/executor.agent.md

@@ -0,0 +1,59 @@
+---
+name: Executor
+description: Implements planned phases — writes code, runs tests, and makes atomic commits following established conventions. Use me to execute a ready plan.
+tools:
+  - editFiles
+  - runTerminalCommand
+  - search
+model: gpt-4.1
+handoffs:
+  - label: Verify This Work
+    agent: Verifier
+    prompt: "Implementation is complete. Please verify the completed phase against the requirements in .planning/REQUIREMENTS.md and the phase success criteria in .planning/ROADMAP.md."
+  - label: Pause & Save State
+    agent: Pause
+    prompt: "Please save the current session state to .planning/continue-here.md so we can resume in a new session."
+---
+
+# Executor Agent
+
+I am an implementation specialist. I execute plans precisely, follow established conventions, commit atomically, and verify with tests at every step.
+
+## My Approach
+
+1. **Load context first:** Before writing a single line of code, I read:
+   - The plan files in `.planning/phases/[current-phase]/`
+   - `.planning/codebase/CONVENTIONS.md` — coding standards
+   - `.planning/codebase/STRUCTURE.md` — where to place files
+   - `.planning/codebase/CONCERNS.md` — fragile areas to handle carefully
+
+2. **Pre-flight check:** Run `npm test` to confirm baseline before I start
+
+3. **Implement step by step:** Follow the plan's steps in order — no shortcuts, no improvising architecture
+
+4. **Test continuously:** Run tests after each meaningful change; fix failures immediately
+
+5. **Commit per plan:** After each plan is complete, commit with a descriptive message
+
+6. **Update ROADMAP.md:** Mark completed plans with `[x]`
+
+7. **Hand off to Verifier when done**
+
+## My Rules
+
+- **Never skip tests** — if a plan says "write tests", tests are written before moving to the next step
+- **Never improvise architecture** — if the plan is unclear, ask before implementing
+- **Follow conventions exactly** — refer to `.planning/codebase/CONVENTIONS.md` on every new file
+- **Atomic commits** — one commit per completed plan, not per file
+- **If I hit a blocker** — document it in `.planning/STATE.md`, save state, and surface it to you
+
+## Trigger Phrases
+
+"Execute phase [N]", "Implement the plan", "Build [feature] from the plan", "Continue implementing"
+
+## Reference Documents
+
+- [.planning/codebase/CONVENTIONS.md](../../../.planning/codebase/CONVENTIONS.md) — coding standards
+- [.planning/codebase/STRUCTURE.md](../../../.planning/codebase/STRUCTURE.md) — file placement
+- [.planning/codebase/CONCERNS.md](../../../.planning/codebase/CONCERNS.md) — fragile areas
+- [.planning/codebase/TESTING.md](../../../.planning/codebase/TESTING.md) — test patterns

package/.github/agents/planner.agent.md

@@ -0,0 +1,58 @@
+---
+name: Planner
+description: Plans implementation phases — reads requirements and codebase context to produce executable step-by-step plans. Use me before starting new work.
+tools:
+  - search
+model: gpt-4.1
+handoffs:
+  - label: Start Executing
+    agent: Executor
+    prompt: "The plan is ready. Please execute the phase plan just created, following the steps in .planning/phases/ and the conventions in .planning/codebase/CONVENTIONS.md."
+---
+
+# Planner Agent
+
+I am a planning specialist. My job is to analyze requirements, study the codebase, and produce concrete, executable plans — but **I do not write implementation code**.
+
+## My Constraints
+
+- **Read-only tools only** — I search and read, but never write application code
+- I produce plan documents (written to `.planning/phases/`) and stop
+- I hand off to the Executor agent when a plan is ready
+
+## How I Work
+
+When you ask me to plan a phase, I will:
+
+1. **Read the context:** Load `.planning/ROADMAP.md`, `.planning/REQUIREMENTS.md`, `.planning/PROJECT.md`, and the relevant codebase docs from `.planning/codebase/`
+
+2. **Explore the code:** Search for existing patterns, find files that will need modification, understand the current architecture
+
+3. **Ask clarifying questions** (if needed): Ambiguous requirements, architectural tradeoffs, or scope boundaries before committing to an approach
+
+4. **Write the plan:** Produce detailed, step-by-step plan files in `.planning/phases/[NN]-[phase-name]/` with exact file paths, function signatures, and success criteria
+
+5. **Update ROADMAP.md:** Add the plan list to the phase
+
+6. **Hand off:** Offer to hand off to the Executor agent to implement
+
+## Trigger Phrases
+
+"Plan phase [N]", "Plan the next phase", "What should we build next?", "Create a plan for [feature]"
+
+## What a Good Plan Includes
+
+- Exact file paths for files to create and modify
+- Function/method signatures and their contracts
+- Data structures and API schemas
+- Test cases to write (not just "add tests")
+- Success criteria that are verifiable
+
+## Reference Documents
+
+Always load relevant docs before planning:
+- [.planning/PROJECT.md](../../../.planning/PROJECT.md) — requirements and constraints
+- [.planning/REQUIREMENTS.md](../../../.planning/REQUIREMENTS.md) — requirement IDs
+- [.planning/ROADMAP.md](../../../.planning/ROADMAP.md) — phase structure
+- [.planning/codebase/ARCHITECTURE.md](../../../.planning/codebase/ARCHITECTURE.md) — layer design
+- [.planning/codebase/STRUCTURE.md](../../../.planning/codebase/STRUCTURE.md) — where files go

package/.github/agents/verifier.agent.md

@@ -0,0 +1,68 @@
+---
+name: Verifier
+description: Verifies completed work against requirements — checks tests, inspects implementation, and produces a verification report. Use me after implementing a phase.
+tools:
+  - runTerminalCommand
+  - search
+model: gpt-4.1
+handoffs:
+  - label: Fix Gaps
+    agent: Executor
+    prompt: "Verification found gaps. Please implement the gap closures identified in the VERIFICATION.md report, then re-run verification."
+---
+
+# Verifier Agent
+
+I am a verification specialist. I verify completed work against requirements, run tests, inspect code, and produce verification reports — but **I do not fix code**.
+
+## My Constraints
+
+- **Read + run commands only** — I don't write application code; I run tests and inspect
+- I produce verification reports and identify gaps
+- I hand off to the Executor agent when fixes are needed
+
+## How I Work
+
+1. **Load requirements:** Read `.planning/REQUIREMENTS.md` for the phase's requirement IDs, `.planning/ROADMAP.md` for success criteria
+
+2. **Run the test suite:**
+   ```bash
+   npm test
+   npm run test:coverage
+   npx tsc --noEmit
+   npm run lint
+   ```
+
+3. **Check each requirement:** For each requirement ID listed for the phase, verify:
+   - Is there test coverage?
+   - Does the implementation exist?
+   - Does it match the requirement description?
+
+4. **Check success criteria:** Evaluate each criterion from ROADMAP.md — TRUE or FALSE with evidence
+
+5. **Write the report:** `.planning/phases/[NN]-[phase-name]/VERIFICATION.md`
+
+6. **Update REQUIREMENTS.md:** Mark completed requirements as `[x]`
+
+7. **Hand off:**
+   - If PASS: inform the user the phase is verified ✅
+   - If FAIL: hand off to Executor with a list of gaps to close
+
+## What I Produce
+
+A VERIFICATION.md file with:
+- Test results (counts, coverage %, TypeScript errors, lint warnings)
+- Requirements coverage table (each req ID with status and evidence)
+- Success criteria evaluation
+- PASS / FAIL verdict
+- Gap list (if FAIL) with fix descriptions
+
+## Trigger Phrases
+
+"Verify phase [N]", "Check my work", "Does this meet the requirements?", "Run verification"
+
+## Reference Documents
+
+- [.planning/REQUIREMENTS.md](../../../.planning/REQUIREMENTS.md) — requirements with IDs
+- [.planning/ROADMAP.md](../../../.planning/ROADMAP.md) — success criteria per phase
+- [.planning/codebase/TESTING.md](../../../.planning/codebase/TESTING.md) — how to run tests

package/.github/instructions/architecture.instructions.md

@@ -0,0 +1,33 @@
+---
+name: System Architecture
+description: System architecture, layer organization, data flow, and component boundaries for backend, API, and refactoring work
+---
+
+# System Architecture
+
+> Full architecture reference: [.planning/codebase/ARCHITECTURE.md](../../../.planning/codebase/ARCHITECTURE.md)
+>
+> Read this document when: designing new features, deciding where logic belongs, refactoring, or resolving layer violations.
+
+## Core Principle
+
+Code belongs in the correct layer. Moving logic between layers is a refactoring task, not a shortcut.
+
+## Layer Summary
+
+Read `.planning/codebase/ARCHITECTURE.md` for the full diagram and data flow examples. Key rules:
+
+- **Routes/Controllers:** parse input, validate, delegate to service — no business logic here
+- **Services:** all business logic lives here — no direct DB calls, no HTTP knowledge
+- **Repositories:** all database access here — raw queries or ORM calls only, no business logic
+- **Middleware:** cross-cutting concerns (auth, logging, error handling) — applied at application level
+- **Models:** data shapes and ORM definitions — no behavior
+
+## Decision Guide
+
+| Question | Answer in |
+|----------|-----------|
+| Where does this request flow? | `.planning/codebase/ARCHITECTURE.md` → Data Flow |
+| What layer handles this logic? | `.planning/codebase/ARCHITECTURE.md` → Layers |
+| What are the entry points? | `.planning/codebase/ARCHITECTURE.md` → Entry Points |
+| How are errors propagated? | `.planning/codebase/ARCHITECTURE.md` → Cross-Cutting Concerns |

package/.github/instructions/concerns.instructions.md

@@ -0,0 +1,30 @@
+---
+name: Technical Concerns
+description: Technical debt, known bugs, fragile code areas, security considerations, and areas to approach with caution
+---
+
+# Technical Concerns
+
+> Full concerns reference: [.planning/codebase/CONCERNS.md](../../../.planning/codebase/CONCERNS.md)
+>
+> Read this document when: refactoring, touching legacy code, working near known fragile areas, or doing security-sensitive work.
+
+## Core Rule
+
+**Before modifying code in a warning area, check `.planning/codebase/CONCERNS.md`.** Modifying fragile code without understanding why it's fragile frequently introduces regressions.
+
+## Quick Guide
+
+Read `.planning/codebase/CONCERNS.md` for:
+- **Critical issues:** Active bugs or broken functionality — don't make them worse
+- **High-priority debt:** Significant friction or risk areas worth knowing about
+- **Fragile areas table:** Specific files that are risky to modify and HOW to proceed safely
+- **Security notes:** Known vulnerabilities, applied mitigations, what not to bypass
+- **Performance bottlenecks:** Known slow paths and their workarounds
+
+## Rules
+
+- After fixing a known issue, **remove it from CONCERNS.md** or mark it resolved
+- After discovering a new issue, **add it to CONCERNS.md** — don't leave land mines undocumented
+- When a fix is deferred, add a `// TODO(issue-ref):` comment at the affected location
+- **Never introduce new `any` types, disable linting rules, or skip test coverage** without documenting the reason in CONCERNS.md

package/.github/instructions/conventions.instructions.md

@@ -0,0 +1,25 @@
+---
+name: Coding Conventions
+description: Coding style, naming conventions, error handling, and formatting standards for this codebase
+applyTo: "**/*.{ts,tsx,js,jsx,mts,cts}"
+---
+
+# Coding Conventions
+
+> Full conventions reference: [.planning/codebase/CONVENTIONS.md](../../../.planning/codebase/CONVENTIONS.md)
+>
+> **This file is auto-loaded when you edit source files. Always follow these patterns.**
+> When in doubt, look at existing files in the codebase and match their style.
+
+## Quick Reference
+
+Read `.planning/codebase/CONVENTIONS.md` for the full guide. Key rules:
+
+- **Naming:** variables/functions = `camelCase`, classes = `PascalCase`, constants = `SCREAMING_SNAKE_CASE`, files = `kebab-case.ts`
+- **Imports:** built-ins → external packages → internal (`@/`) → relative — always in this order
+- **Error handling:** never swallow errors silently; use custom error classes; let `src/middleware/error.ts` handle HTTP errors
+- **Functions:** single responsibility; max ~50 lines; prefer early returns over deep nesting; always annotate return types
+- **Comments:** explain WHY not WHAT; JSDoc on all exported functions; include ticket ref in TODO comments
+- **No `any`:** use `unknown` + type guards instead; strict TypeScript throughout
+
+When writing new code, always check `.planning/codebase/CONVENTIONS.md` to confirm you're matching the exact patterns established in this codebase.

package/.github/instructions/integrations.instructions.md

@@ -0,0 +1,30 @@
+---
+name: External Integrations
+description: External API integrations, third-party services, SDK usage patterns, and service configuration
+---
+
+# External Integrations
+
+> Full integrations reference: [.planning/codebase/INTEGRATIONS.md](../../../.planning/codebase/INTEGRATIONS.md)
+>
+> Read this document when: touching external service code, adding a new integration, debugging third-party API issues, or handling webhooks.
+
+## Core Rule
+
+**Before writing code that touches an external service, read the relevant section in `.planning/codebase/INTEGRATIONS.md`.** It documents which SDK is used, where the client is initialized, how errors are handled, and which environment variables are required.
+
+## Quick Guide
+
+Read `.planning/codebase/INTEGRATIONS.md` for:
+- **Database:** ORM/client used, connection config location, migration commands
+- **Authentication:** Provider, middleware location, how user identity is propagated
+- **Payment / billing:** SDK, webhook handling location, key operations
+- **Email:** Provider, template locations, key send operations  
+- **CI/CD:** Pipeline config, what triggers what
+
+## Rules
+
+- **Client singletons:** never create a new SDK client instance inside a function — use the initialized instance from `src/config/`
+- **Environment variables:** required vars for each service are documented in INTEGRATIONS.md — ensure they're in `.env.example`
+- **Webhook security:** always verify webhook signatures; never trust payload without verification
+- New integrations: add the service to INTEGRATIONS.md with its SDK, config location, and env vars before implementing

package/.github/instructions/stack.instructions.md

@@ -0,0 +1,30 @@
+---
+name: Technology Stack
+description: Technology stack, framework choices, key dependencies, runtime environment, and configuration
+---
+
+# Technology Stack
+
+> Full stack reference: [.planning/codebase/STACK.md](../../../.planning/codebase/STACK.md)
+>
+> Read this document when: adding dependencies, modifying configuration, setting up environments, or debugging infrastructure issues.
+
+## Core Rule
+
+**Do not introduce new dependencies or change the build configuration without first checking `.planning/codebase/STACK.md`.** The stack is intentional — changes to core dependencies have broad impact.
+
+## Quick Guide
+
+Read `.planning/codebase/STACK.md` for:
+- **Runtime:** Language version, Node.js version, package manager
+- **Key frameworks:** Web framework, ORM, auth library — and how they're configured
+- **Dev toolchain:** TypeScript config, ESLint, Prettier, test runner setup
+- **Infrastructure:** Database, cache, object storage, message queue details
+- **Environment variables:** Full list of required env vars and their purpose
+
+## Rules
+
+- Always check if a required capability already exists in the stack before adding a new package
+- New dependencies: add to the appropriate section in STACK.md after installation
+- Breaking upgrades: document the upgrade decision in `.planning/PROJECT.md` Key Decisions
+- **Never read `.env` file contents** — work only with `.env.example` and environment variable names

package/.github/instructions/structure.instructions.md

@@ -0,0 +1,32 @@
+---
+name: File Structure
+description: File and directory organization, naming conventions, and where to place new code, components, routes, or modules
+---
+
+# File Structure
+
+> Full structure reference: [.planning/codebase/STRUCTURE.md](../../../.planning/codebase/STRUCTURE.md)
+>
+> Read this document when: creating new files, deciding on location for new code, or setting up new modules.
+
+## Core Rule
+
+**Always check `.planning/codebase/STRUCTURE.md` before creating a new file.** It contains a "Where to Put New Code" table that answers exactly where each type of file belongs and what naming convention to use.
+
+## Quick Guide
+
+| I'm creating... | Check STRUCTURE.md section |
+|----------------|---------------------------|
+| A new API endpoint | "Where to Put New Code" → routes row |
+| A new service | "Where to Put New Code" → services row |
+| A new component | "Where to Put New Code" → components row |
+| A test for existing code | Mirror the source path in the `tests/` directory |
+| A new database model | "Where to Put New Code" → models row |
+| A utility function | "Where to Put New Code" → utilities row |
+
+## Rules
+
+- **Never create files at the root of `src/`** — always find the correct subdirectory
+- **Follow the naming convention exactly** as specified in STRUCTURE.md for each file type
+- **Use barrel exports (`index.ts`)** where the pattern exists — don't skip them for convenience
+- When creating a feature that spans multiple layers (route + service + repository), create all files before wiring them together

package/.github/instructions/testing.instructions.md

@@ -0,0 +1,25 @@
+---
+name: Testing Patterns
+description: Test framework, patterns, mocking strategy, and test organization for writing and running tests
+applyTo: "**/*.{test,spec}.{ts,tsx,js,jsx}"
+---
+
+# Testing Patterns
+
+> Full testing reference: [.planning/codebase/TESTING.md](../../../.planning/codebase/TESTING.md)
+>
+> **This file is auto-loaded when you edit test files. Always follow these patterns.**
+
+## Quick Reference
+
+Read `.planning/codebase/TESTING.md` for the full guide. Key rules:
+
+- **Structure:** `describe('[ClassName/Function]')` → `describe('[methodName()]')` → `it('[readable description of behavior]')`
+- **Pattern:** Arrange-Act-Assert — comment each section if the test is non-trivial
+- **Test data:** always use factory functions from `tests/helpers/factories.ts`, never hardcoded raw objects
+- **Mocking:** mock at the outermost layer (repositories for service tests, network for integration tests); use `vi.mock()` / `jest.mock()`
+- **Isolation:** each test must pass in isolation and in any order; no shared mutable state between tests
+- **What to test:** business logic, API contract (status codes + response shape), error paths, edge cases
+- **What NOT to test:** framework internals, private implementation details, trivial getters/setters
+
+When writing a new test, check `.planning/codebase/TESTING.md` for the exact patterns used in this project, including how the test database is set up for integration tests.

package/.github/prompts/execute-phase.prompt.md

@@ -0,0 +1,148 @@
+---
+name: execute-phase
+description: Execute a planned phase step-by-step, implementing each plan and running tests
+mode: agent
+tools:
+  - editFiles
+  - runTerminalCommand
+  - search
+---
+
+# Execute Phase
+
+**Usage:** `/execute-phase [phase-number]` — e.g., `/execute-phase 1`
+
+Implement the planned phase. Execute each plan in sequence, following established conventions and committing after each completed plan.
+
+## Step 1: Load Execution Context
+
+Read these files:
+- `.planning/ROADMAP.md` — find the phase and its plans
+- `.planning/phases/[NN]-[phase-name]/` — load all plan files for this phase
+- `.planning/codebase/CONVENTIONS.md` — coding standards to follow throughout
+- `.planning/codebase/STRUCTURE.md` — where to place new files
+- `.planning/codebase/CONCERNS.md` — fragile areas to handle carefully
+- `.planning/STATE.md` — current position and any blockers
+
+If `.planning/continue-here.md` exists, read it first — it tells you exactly where to resume.
+
+## Step 2: Pre-flight Check
+
+Before writing any code:
+```bash
+# Verify tests are passing before starting
+npm test 2>&1 | tail -20
+
+# Check TypeScript compilation
+npx tsc --noEmit 2>&1 | head -20
+
+# Confirm current branch and status
+git status
+git branch --show-current
+```
+
+If tests are already failing before you start, note them in STATE.md and proceed cautiously.
+
+## Step 3: Execute Plans
+
+For each plan file in the phase (in order):
+
+### 3a. Read the plan fully before writing any code
+
+Understand all steps and success criteria before implementing step 1.
+
+### 3b. Implement step by step
+
+Follow the plan's steps precisely:
+- Create files in the correct location (check `.planning/codebase/STRUCTURE.md`)
+- Follow naming conventions (check `.planning/codebase/CONVENTIONS.md`)
+- Before touching any file listed in `.planning/codebase/CONCERNS.md` fragile areas — re-read that section
+- Write tests for each piece of functionality before moving to the next
+
+### 3c. Verify after each step
+
+```bash
+# Run tests after each meaningful change
+npm test
+
+# Type-check
+npx tsc --noEmit
+```
+
+Fix failures immediately — don't accumulate broken tests.
+
+### 3d. Commit after each completed plan
+
+```bash
+git add -A
+git commit -m "[NN]-[plan]: [descriptive message]
+
+- [What was implemented]
+- [Tests written]
+- [Key decisions]"
+```
+
+### 3e. Update ROADMAP.md
+
+Mark the completed plan:
+```
+- [x] [NN]-01: [Description]  ← mark completed
+```
+
+## Step 4: Post-Phase Verification
+
+After all plans in the phase are complete:
+
+```bash
+# Full test suite
+npm test
+
+# Coverage check
+npm run test:coverage
+
+# Type check
+npx tsc --noEmit
+
+# Lint
+npm run lint
+```
+
+Verify against the phase's **Success Criteria** in ROADMAP.md — each criterion must be TRUE.
+
+## Step 5: Update State
+
+Update `.planning/STATE.md`:
+- Mark phase complete if all plans done
+- Update progress percentage
+- Advance to next phase
+
+Update `.planning/ROADMAP.md`:
+- Mark phase checkbox: `- [x] **Phase N: ...**`
+
+## Handling Blockers
+
+If you hit a significant blocker (ambiguous requirement, architectural conflict, missing context):
+1. Document the blocker in `.planning/STATE.md`
+2. Run `/pause-work` to save session state
+3. Describe the blocker clearly for the user to resolve
+
+## Completion
+
+Print a summary:
+```
+✅ Phase [N] complete: [Phase Name]
+
+Implemented:
+  - [NN]-01: [Name] — [key outcome]
+  - [NN]-02: [Name] — [key outcome]
+
+Tests: [N] passing, 0 failing
+Coverage: [X]%
+
+Success Criteria:
+  ✅ [Criterion 1]
+  ✅ [Criterion 2]
+  ✅ [Criterion 3]
+
+Run /verify-work [N] to validate against requirements.
+```

package/.github/prompts/map-codebase.prompt.md

@@ -0,0 +1,115 @@
+---
+name: map-codebase
+description: Analyze the codebase and generate structured context documents in .planning/codebase/
+mode: agent
+tools:
+  - editFiles
+  - runTerminalCommand
+  - search
+  - fetch
+---
+
+# Map Codebase
+
+Analyze this codebase thoroughly and generate 7 structured context documents in `.planning/codebase/`. These documents will be used by Copilot on every future request to understand the project's architecture, conventions, and constraints.
+
+## Process
+
+Work through 4 focus areas in sequence. For each area, explore the codebase using the terminal and search tools, then write the document(s) directly to `.planning/codebase/`.
+
+---
+
+### Focus 1: Technology Stack → STACK.md + INTEGRATIONS.md
+
+**Explore:**
+```bash
+# Package manifests
+cat package.json 2>/dev/null | head -100
+cat requirements.txt 2>/dev/null || cat pyproject.toml 2>/dev/null | head -50
+cat go.mod 2>/dev/null | head -30
+
+# Config files (list only — NEVER read .env contents)
+ls -la *.config.* tsconfig.json .nvmrc .python-version 2>/dev/null
+ls .env* 2>/dev/null   # Note existence only
+
+# Find external integrations
+grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*prisma\|import.*redis\|import.*sendgrid\|import.*twilio\|import.*openai" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
+```
+
+**Write `.planning/codebase/STACK.md`** with: runtime, frameworks, key dependencies table, dev toolchain, infrastructure, environment variables.
+
+**Write `.planning/codebase/INTEGRATIONS.md`** with: a section per external service including SDK used, config file location, required env vars, key operations.
+
+---
+
+### Focus 2: Architecture + Structure → ARCHITECTURE.md + STRUCTURE.md
+
+**Explore:**
+```bash
+# Directory structure
+find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/.planning/*' -not -path '*/.github/*' | sort | head -60
+
+# Entry points
+ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
+
+# Understanding layer imports
+grep -r "^import\|^from" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -80
+```
+
+**Write `.planning/codebase/ARCHITECTURE.md`** with: architectural style + rationale, layer diagram with file paths, data flow example (trace a typical request end-to-end), key abstractions table, entry points table, cross-cutting concerns (error handling, logging, auth, validation).
+
+**Write `.planning/codebase/STRUCTURE.md`** with: root layout, source tree, and most importantly a **"Where to Put New Code"** table that tells exactly which directory and naming convention to use for each type of file (routes, services, repositories, models, utils, tests, components, etc.).
+
+---
+
+### Focus 3: Conventions + Testing → CONVENTIONS.md + TESTING.md
+
+**Explore:**
+```bash
+# Formatting/linting config
+cat .prettierrc .eslintrc.js .eslintrc.json biome.json 2>/dev/null | head -60
+cat pyproject.toml 2>/dev/null | grep -A 20 "\[tool\."
+
+# Test framework
+ls jest.config.* vitest.config.* pytest.ini setup.cfg 2>/dev/null
+find . -name "*.test.*" -o -name "*.spec.*" | grep -v node_modules | head -20
+
+# Look at real code for patterns
+find src/ -name "*.ts" -not -name "*.test.*" 2>/dev/null | head -5 | xargs head -40 2>/dev/null
+find tests/ -name "*.test.*" 2>/dev/null | head -3 | xargs head -60 2>/dev/null
+```
+
+**Write `.planning/codebase/CONVENTIONS.md`** — be prescriptive ("Use X" not "X is used"). Include: language/formatting rules, naming conventions table, import ordering, error handling patterns, function patterns, TypeScript specifics, comment style. Include real code examples from the codebase.
+
+**Write `.planning/codebase/TESTING.md`** with: test framework and run commands, file organization, test structure pattern with real example, mocking strategy, test data approach (factories), integration test setup, what to test and what NOT to test.
+
+---
+
+### Focus 4: Technical Concerns → CONCERNS.md
+
+**Explore:**
+```bash
+# TODO/FIXME/HACK comments
+grep -rn "TODO\|FIXME\|HACK\|XXX\|TEMP\|@deprecated" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -40
+
+# Potential issues
+grep -rn "any\b\|@ts-ignore\|@ts-nocheck\|eslint-disable\|# type: ignore\|# noqa" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -30
+
+# Security patterns
+grep -rn "eval\|innerHTML\|dangerouslySetInnerHTML\|exec\|shell=True" src/ --include="*.ts" --include="*.py" 2>/dev/null | head -20
+
+# Large/complex files
+find src/ -name "*.ts" -o -name "*.py" 2>/dev/null | xargs wc -l 2>/dev/null | sort -rn | head -15
+```
+
+**Write `.planning/codebase/CONCERNS.md`** with: health summary table (critical/high/medium counts), critical issues section (with file paths, impact, root cause, fix approach), high-priority debt, fragile areas table with safe-approach guidance, security notes, performance bottlenecks, scaling limits.
+
+---
+
+## Completion
+
+After all 7 files are written, update `.github/copilot-instructions.md`:
+- Fill in the "What This Project Is" section from what you learned
+- Keep it to 2-3 sentences describing what the product does
+
+Then confirm: "Codebase mapping complete. Generated 7 documents in `.planning/codebase/`. Use `/sync-instructions` to update the Copilot instructions digest."