ragarciaruben 1.20.7

package/.github/copilot-context/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/copilot-context/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/copilot-context/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/copilot-context/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/copilot-context/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/copilot-context/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/copilot-context/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."

package/.github/copilot-context/prompts/new-project.prompt.md

@@ -0,0 +1,85 @@
+---
+name: new-project
+description: Initialize .planning/ documentation for a new or existing project — creates PROJECT.md, REQUIREMENTS.md, ROADMAP.md, and STATE.md
+mode: agent
+tools:
+  - editFiles
+  - search
+---
+
+# New Project Initialization
+
+Initialize the `.planning/` documentation structure for this project. This generates the source-of-truth documents that power all other Copilot context.
+
+## Step 1: Gather Project Context
+
+Before writing anything, ask the user these questions (batch them together):
+
+1. **What is this project?** (2-3 sentence description of what it does and who uses it)
+2. **What is the core value?** (The one thing that MUST always work)
+3. **What are the v1 requirements?** (The features needed for initial release — list them, or paste existing ones)
+4. **What constraints apply?** (Tech stack locked in, timeline, compliance requirements, team size, etc.)
+5. **Is this greenfield or an existing codebase?** (If existing, I'll run map-codebase after this)
+
+If the user can't answer some questions, use reasonable defaults and note them as assumptions.
+
+## Step 2: Create PROJECT.md
+
+Write `.planning/PROJECT.md` with:
+- **What This Is:** User's description of the project
+- **Core Value:** Single sentence of what must always work
+- **Requirements > Active:** List of v1 requirements as checkboxes
+- **Requirements > Out of Scope:** Anything explicitly excluded (infer 2-3 common exclusions from the project type)
+- **Context:** Background from the conversation
+- **Constraints:** What the user listed + inferred constraints
+
+## Step 3: Create REQUIREMENTS.md
+
+Extract requirements from the conversation into `.planning/REQUIREMENTS.md`:
+- Assign IDs: `[CATEGORY]-[NN]` (e.g., AUTH-01, CORE-01, UI-01)
+- Group by logical category (Authentication, Core Features, UI, etc.)
+- v2 requirements: anything out of scope for now but likely future
+- Traceability table: leave Phase column as TBD until roadmap is created
+
+## Step 4: Create ROADMAP.md
+
+Design a logical phase sequence in `.planning/ROADMAP.md`:
+- Each phase delivers a user-visible increment
+- Earlier phases enable later phases (dependency chain)
+- Group related requirements into phases
+- Phase names should be clear and action-oriented (e.g., "Authentication & User Management", "Core Feature MVP")
+- Each phase: goal, dependencies, requirements covered, 2-4 success criteria, planned plan count (TBD is fine)
+- Typically 4-8 phases for a standard project
+
+## Step 5: Create STATE.md
+
+Initialize `.planning/STATE.md`:
+- Phase: 1 of [N]
+- Status: Ready to plan
+- Progress: 0%
+- Last activity: today's date + "Project initialized"
+- All metrics at zero
+
+## Step 6: Update copilot-instructions.md
+
+Update `.github/copilot-instructions.md`:
+- Fill in "What This Project Is" with the 2-3 sentence description
+- Fill in "Core value"
+- Set "Phase: 1 of [N] — [Phase Name]"
+- Set "Status: Ready to plan"
+- Fill in "Active Constraints" from the constraints list
+
+## Completion
+
+Print a summary:
+```
+✅ Project initialized: [Project Name]
+   .planning/PROJECT.md      — requirements + decisions
+   .planning/REQUIREMENTS.md — [N] requirements with IDs
+   .planning/ROADMAP.md      — [N] phases
+   .planning/STATE.md        — ready to plan
+
+Next steps:
+  1. Run /map-codebase (if existing codebase)
+  2. Run /plan-phase 1 to plan the first phase
+```

package/.github/copilot-context/prompts/pause-work.prompt.md

@@ -0,0 +1,104 @@
+---
+name: pause-work
+description: Save current session state so work can be resumed in a new session — writes .planning/continue-here.md
+mode: agent
+tools:
+  - editFiles
+  - runTerminalCommand
+  - search
+---
+
+# Pause Work
+
+Save the current session state to `.planning/continue-here.md` so the next session can resume exactly where you left off.
+
+## Step 1: Assess Current State
+
+Gather current state information:
+
+```bash
+# Last few commits
+git log --oneline -5
+
+# Uncommitted changes
+git status
+git diff --stat HEAD
+
+# Test status
+npm test 2>&1 | tail -10
+```
+
+Read `.planning/STATE.md` for project-level context.
+
+## Step 2: Document Current State
+
+Think through:
+- What was the last **completed** action? (Be concrete — a test passing, a file created, a PR merged)
+- What work is **in progress** and where exactly did it stop?
+- What **remains** in the current plan? What comes after?
+- What **decisions** were made this session?
+- Are there any **blockers** or watch-outs for the next session?
+- What is the **exact next action** to resume?
+
+## Step 3: Write continue-here.md
+
+Write `.planning/continue-here.md`:
+
+```markdown
+# Continue Here
+
+## Where We Are
+
+**Phase:** [X] — [Phase Name]
+**Plan:** [A] of [B]
+**As of:** [timestamp]
+
+## What Was Just Completed
+
+[Concrete description of the last completed action]
+
+- ✅ [Completed item 1 — file created / test passing / feature shipped]
+- ✅ [Completed item 2]
+
+## What Remains
+
+In current plan ([NN]-[plan]):
+- [ ] [Next task]
+- [ ] [Task after that]
+
+Upcoming plans:
+- [ ] [NN]-[N+1]: [Brief name]
+
+## Decisions Made This Session
+
+- [Decision and rationale — lock these in]
+- [Decision and rationale]
+
+## Blockers / Watch-Outs
+
+- [Any issue the next session needs to know before touching code]
+
+## Exact Next Action
+
+**Resume by doing:** [Single, concrete action — e.g., "Open `src/services/user.service.ts` and implement the `sendWelcomeEmail()` call at line ~45, then run `npm test` to verify"]
+
+---
+*Saved: [timestamp]*
+```
+
+## Step 4: Update STATE.md
+
+Update `.planning/STATE.md`:
+- `Last session:` — today's date/time
+- `Stopped at:` — what was last completed
+- `Resume file:` — `.planning/continue-here.md`
+- `Next action:` — the exact next step
+
+## Completion
+
+```
+✅ Session saved to .planning/continue-here.md
+
+Resume in any new session with: /resume-work
+Or start fresh with: /progress
+```