ragarciaruben 1.20.7

package/.github/copilot-context/prompts/plan-phase.prompt.md

@@ -0,0 +1,137 @@
+---
+name: plan-phase
+description: Plan implementation for a roadmap phase — produces a detailed, executable step-by-step plan
+mode: agent
+tools:
+  - editFiles
+  - search
+  - runTerminalCommand
+---
+
+# Plan Phase
+
+**Usage:** `/plan-phase [phase-number]` — e.g., `/plan-phase 1` or `/plan-phase 2`
+
+Plan the implementation for the specified roadmap phase. Produces a concrete, step-by-step plan ready for execution.
+
+## Step 1: Load Phase Context
+
+Read these files:
+- `.planning/ROADMAP.md` — find the phase goal, dependencies, requirements, and success criteria
+- `.planning/REQUIREMENTS.md` — find the full requirements for this phase
+- `.planning/PROJECT.md` — constraints and key decisions
+- `.planning/STATE.md` — current position, any relevant accumulated context
+
+Load relevant codebase docs based on the phase type:
+| Phase involves... | Load these docs |
+|-------------------|----------------|
+| UI, frontend, components | `.planning/codebase/CONVENTIONS.md` + `.planning/codebase/STRUCTURE.md` |
+| API, backend, endpoints | `.planning/codebase/ARCHITECTURE.md` + `.planning/codebase/CONVENTIONS.md` |
+| Database, schema, models | `.planning/codebase/ARCHITECTURE.md` + `.planning/codebase/STACK.md` |
+| Testing | `.planning/codebase/TESTING.md` + `.planning/codebase/CONVENTIONS.md` |
+| Integration, external API | `.planning/codebase/INTEGRATIONS.md` + `.planning/codebase/STACK.md` |
+| Refactor, cleanup | `.planning/codebase/CONCERNS.md` + `.planning/codebase/ARCHITECTURE.md` |
+| Setup, config | `.planning/codebase/STACK.md` + `.planning/codebase/STRUCTURE.md` |
+
+## Step 2: Explore Relevant Code
+
+Before planning, explore the codebase to understand the current state:
+```bash
+# Find existing code related to the phase domain
+grep -rn "[relevant terms]" src/ --include="*.ts" 2>/dev/null | head -30
+
+# Check existing file structure for the area
+ls -la src/[relevant-directory]/ 2>/dev/null
+```
+
+Don't guess — look at actual code before designing the plan.
+
+## Step 3: Identify Implementation Decisions
+
+Before writing the plan, think through and document key decisions:
+
+- **Approach:** [The implementation strategy you've chosen and why]
+- **New files to create:** [List with exact paths]
+- **Existing files to modify:** [List with exact paths and what changes]
+- **Dependencies:** [Any new packages needed]
+- **Deferred:** [Things that could fit here but are out of scope]
+
+If you're uncertain about architectural choices, ask the user before proceeding.
+
+## Step 4: Write the Plan
+
+Write the plan file to `.planning/phases/[NN]-[phase-name]/[NN]-01-[plan-name].md`:
+
+```markdown
+---
+phase: [phase-number]
+plan: [NN]-01
+name: [descriptive plan name]
+goal: [what this plan delivers]
+status: ready
+---
+
+# Plan [NN]-01: [Plan Name]
+
+## Goal
+[What this plan delivers — user-observable outcome]
+
+## Context & Decisions
+[Key implementation decisions made for this plan and their rationale]
+
+## Steps
+
+### 1. [Step name]
+[Precise description — file paths, function signatures, what to implement]
+
+**Files:**
+- Create: `src/[path]/[file].ts`
+- Modify: `src/[path]/[existing].ts`
+
+**Implementation:**
+[Specifics — data structures, algorithms, API contracts, patterns to follow]
+
+### 2. [Step name]
+[etc.]
+
+### N. Tests
+[Specific test cases to write — description of each scenario]
+
+## Success Criteria
+- [ ] [Observable behavior that proves this plan is complete]
+- [ ] [Observable behavior]
+- [ ] All tests pass (`npm test`)
+- [ ] No TypeScript errors (`tsc --noEmit`)
+```
+
+If the phase requires multiple plans, create `[NN]-02-[name].md`, `[NN]-03-[name].md`, etc.
+
+## Step 5: Update ROADMAP.md
+
+Update the plan list in `.planning/ROADMAP.md` for this phase:
+```
+Plans:
+- [ ] [NN]-01: [Brief description]
+- [ ] [NN]-02: [Brief description]
+```
+
+## Step 6: Update STATE.md
+
+Update `.planning/STATE.md`:
+- Status: `Ready to execute`
+- Current focus: this phase
+- Note the key decisions made during planning under Accumulated Context
+
+## Completion
+
+Print a summary:
+```
+✅ Phase [N] planned: [Phase Name]
+   [N] plans created in .planning/phases/[NN]-[name]/
+
+Plans:
+  [NN]-01: [Name] — [brief description]
+  [NN]-02: [Name] — [brief description]
+
+Ready to execute. Run /execute-phase [N] to start implementation.
+```

package/.github/copilot-context/prompts/progress.prompt.md

@@ -0,0 +1,69 @@
+---
+name: progress
+description: Show current project progress — phase status, completion percentage, and what's next
+mode: ask
+tools:
+  - search
+---
+
+# Show Progress
+
+Read the following files and produce a progress report:
+
+1. `.planning/STATE.md` — current position, metrics, last activity
+2. `.planning/ROADMAP.md` — all phases, their plans, completion status
+3. `.planning/REQUIREMENTS.md` — requirement completion status
+
+Generate a progress report in this format:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  [Project Name] — Progress Report
+  [date]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Current Position
+  Phase [X] of [Y]: [Phase Name]
+  Status: [In progress / Ready to execute / Planning]
+  Last activity: [date] — [what happened]
+
+Progress: [███████░░░░░░░░] [N]%
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase Overview
+
+  ✅ Phase 1: [Name] — complete
+  ✅ Phase 2: [Name] — complete
+  🔄 Phase 3: [Name] — in progress ([N]/[M] plans done)
+     └─ ✅ 03-01: [Plan name]
+     └─ 🔄 03-02: [Plan name] ← current
+     └─ ⬜ 03-03: [Plan name]
+  ⬜ Phase 4: [Name] — not started
+  ⬜ Phase 5: [Name] — not started
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Requirements Coverage
+
+  v1: [N checked] / [M total] ([X]%)
+  ✅ [AUTH-01, AUTH-02, AUTH-03]
+  ❌ [CORE-02, CORE-03] — not yet started (Phase 4)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Metrics
+  Plans completed: [N]
+  Total time: [X] hours (est.)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Next Steps
+
+  [Immediate next action — what to run or do]
+
+  Commands:
+    /plan-phase [N]     — plan the current phase
+    /execute-phase [N]  — execute planned phase
+    /verify-work [N]    — verify completed phase
+```

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

@@ -0,0 +1,74 @@
+---
+name: resume-work
+description: Resume work from a saved session state — reads .planning/continue-here.md and .planning/STATE.md to orient the next session
+mode: ask
+tools:
+  - search
+  - runTerminalCommand
+---
+
+# Resume Work
+
+Load the saved session state and orient this session to continue exactly where the last one left off.
+
+## Step 1: Load Context
+
+Read these files in order:
+1. `.planning/continue-here.md` — exact resume point (if it exists)
+2. `.planning/STATE.md` — current project position and metrics
+3. `.planning/ROADMAP.md` — phase and plan context
+
+If `.planning/continue-here.md` does not exist, fall back to STATE.md and ROADMAP.md only.
+
+## Step 2: Verify Environment
+
+```bash
+# Confirm current git state
+git status
+git log --oneline -3
+git branch --show-current
+
+# Quick test health check
+npm test 2>&1 | tail -15
+```
+
+Note any unexpected test failures or uncommitted changes.
+
+## Step 3: Present Resume Summary
+
+Format the context summary clearly:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Resuming: [Project Name]
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Where We Left Off
+  Phase [X] — [Phase Name]
+  Plan [A] of [B]
+  Last session: [date] — [what happened]
+
+Last Completed
+  ✅ [Last completed item]
+  ✅ [Item before that]
+
+What Remains (current plan)
+  ◻ [Next task]
+  ◻ [Task after that]
+
+Decisions Locked In
+  • [Decision 1]
+  • [Decision 2]
+
+Watch-Outs
+  ⚠️ [Any blocker or fragile area to be aware of]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Exact Next Action
+  [Single concrete action to take now]
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Then ask: "Ready to continue? I'll [describe the immediate next action]."

package/.github/copilot-context/prompts/sync-instructions.prompt.md

@@ -0,0 +1,86 @@
+---
+name: sync-instructions
+description: Regenerate .github/copilot-instructions.md from .planning/ source documents — keeps the always-on context digest up to date
+mode: agent
+tools:
+  - editFiles
+  - search
+---
+
+# Sync Instructions
+
+Regenerate `.github/copilot-instructions.md` from the current state of `.planning/` documents. Run this after significant changes to PROJECT.md, STATE.md, or ROADMAP.md.
+
+## Step 1: Read Source Documents
+
+Read all of these:
+- `.planning/STATE.md` — current position, last activity, core value reference
+- `.planning/PROJECT.md` — project description, core value, constraints, recent key decisions
+- `.planning/ROADMAP.md` — phase count and current phase status
+
+## Step 2: Extract Key Information
+
+From the documents, extract:
+
+1. **Project description** — the "What This Is" section from PROJECT.md (2-3 sentences)
+2. **Core value** — the single-sentence core value
+3. **Current phase** — phase number, name, status from STATE.md
+4. **Last activity** — date and what happened from STATE.md
+5. **Active constraints** — from PROJECT.md Constraints (pick top 3-4 most impactful)
+6. **Recent key decisions** — from PROJECT.md Key Decisions (last 3-4 entries, most recent first)
+
+## Step 3: Rewrite copilot-instructions.md
+
+Overwrite `.github/copilot-instructions.md` with a fresh version. Keep it **under 100 lines**. Use this structure:
+
+```markdown
+# Project Copilot Instructions
+
+<!--
+  Auto-generated from .planning/ documents.
+  Regenerate with: /sync-instructions
+  Last synced: [date]
+-->
+
+## What This Project Is
+
+[2-3 sentence description from PROJECT.md]
+
+**Core value:** [Single sentence from PROJECT.md Core Value]
+
+## Current State
+
+- **Phase:** [X of Y — Phase Name]
+- **Status:** [Status from STATE.md]
+- **Last activity:** [Date — what happened]
+
+## Active Constraints
+
+[Top 3-4 constraints — format as "**Type:** What it means for code you write"]
+
+## Key Decisions (recent)
+
+[Last 3-4 decisions — format as "- [Decision] — [rationale and implication]"]
+
+## Where to Find Deep Context
+
+[Keep the reference table — update if new documents were added]
+
+## Quick Commands (run in Copilot Chat)
+
+[Keep the commands table unchanged]
+```
+
+## Step 4: Confirm
+
+Print:
+```
+✅ .github/copilot-instructions.md updated
+
+Synced from:
+  .planning/PROJECT.md    → description, constraints, decisions
+  .planning/STATE.md      → current position, last activity
+  .planning/ROADMAP.md    → phase count
+
+The updated instructions will be auto-loaded on your next Copilot Chat request.
+```

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

@@ -0,0 +1,126 @@
+---
+name: verify-work
+description: Verify that completed work meets requirements — checks implementation against .planning/REQUIREMENTS.md and phase success criteria
+mode: agent
+tools:
+  - runTerminalCommand
+  - search
+---
+
+# Verify Work
+
+**Usage:** `/verify-work [phase-number]` — e.g., `/verify-work 1`
+
+Verify that the completed phase meets its requirements. Produces a verification report.
+
+## Step 1: Load Verification Context
+
+Read:
+- `.planning/REQUIREMENTS.md` — requirements covered by this phase (use traceability table)
+- `.planning/ROADMAP.md` — phase success criteria
+- `.planning/codebase/TESTING.md` — test framework and run commands
+- `.planning/STATE.md` — current position
+
+## Step 2: Run the Test Suite
+
+```bash
+# Full test suite
+npm test 2>&1
+
+# Coverage report
+npm run test:coverage 2>&1
+
+# TypeScript
+npx tsc --noEmit 2>&1
+
+# Linting
+npm run lint 2>&1
+```
+
+Record: test count, pass/fail, coverage %, any errors.
+
+## Step 3: Check Each Requirement
+
+For every requirement ID listed for this phase in `REQUIREMENTS.md`:
+
+| Requirement | Description | Verification method | Status |
+|-------------|-------------|---------------------|--------|
+| AUTH-01 | User can sign up | Test `POST /auth/register` returns 201 | ✅ / ❌ |
+| AUTH-02 | Password hashed | Check `users` table never stores plaintext | ✅ / ❌ |
+
+For each requirement:
+1. Check if there are tests covering it
+2. Look at the implementation code
+3. Mark ✅ if verifiably complete, ❌ if missing or partial
+
+## Step 4: Check Phase Success Criteria
+
+Read the success criteria from ROADMAP.md for this phase.
+For each criterion — make a call: TRUE or FALSE based on evidence (tests, code inspection, running commands).
+
+## Step 5: Write Verification Report
+
+Write the report to `.planning/phases/[NN]-[phase-name]/VERIFICATION.md`:
+
+```markdown
+# Verification Report: Phase [N] — [Phase Name]
+
+**Date:** [date]
+**Verified by:** Copilot agent
+
+## Test Results
+- Tests: [N passing] / [M total]
+- Coverage: [X]%
+- TypeScript: [✅ clean / ❌ N errors]
+- Lint: [✅ clean / ❌ N warnings]
+
+## Requirements Coverage
+
+| Req ID | Description | Status | Evidence |
+|--------|-------------|--------|----------|
+| AUTH-01 | [Brief] | ✅ | [Test name / file:line] |
+| AUTH-02 | [Brief] | ❌ | [What's missing] |
+
+## Success Criteria
+
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| [Criterion 1] | ✅ | [Evidence] |
+| [Criterion 2] | ❌ | [What's missing / how to fix] |
+
+## Overall: [PASS ✅ / FAIL ❌]
+
+[Pass: "All requirements met. Phase [N] is complete."]
+[Fail: "N requirements not met. See gaps below."]
+
+## Gaps (if any)
+
+### [Requirement ID] — [Description]
+**What's missing:** [Specific gap]
+**Fix needed:** [What to implement]
+**Estimated effort:** [Small / Medium / Large]
+```
+
+## Step 6: Update Documents
+
+**If PASS:**
+- Mark requirements as complete in `.planning/REQUIREMENTS.md`: `- [x] **AUTH-01**:`
+- Update `.planning/STATE.md` to show phase verified
+- Move to next phase
+
+**If FAIL:**
+- Add gap closure plans to the phase plan directory
+- Update `.planning/STATE.md` with the gaps as blockers
+- Suggest running `/execute-phase [N] --gaps-only`
+
+## Completion
+
+```
+[PASS ✅ / FAIL ❌] Phase [N] Verification
+
+Requirements: [N]/[M] met
+Tests: [N passing]
+Coverage: [X]%
+
+[PASS message OR list of gaps to close]
+```

package/.github/copilot-context/skills/map-codebase/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: map-codebase
+description: Analyzes a codebase and generates 7 structured context documents in .planning/codebase/ — covering architecture, file structure, conventions, testing, tech stack, integrations, and technical concerns
+---
+
+# Codebase Mapper Skill
+
+This skill analyzes your codebase and generates 7 structured context documents that Copilot uses on every future request to provide project-aware assistance.
+
+## What This Skill Produces
+
+| Document | Contents |
+|----------|---------|
+| `ARCHITECTURE.md` | Layers, data flow, key abstractions, entry points |
+| `STRUCTURE.md` | Directory tree, "where to put new code" table, naming conventions |
+| `STACK.md` | Runtime, frameworks, dependencies, infrastructure, env vars |
+| `CONVENTIONS.md` | Coding style, naming, error handling, TypeScript rules |
+| `TESTING.md` | Test framework, patterns, mocking strategy, run commands |
+| `INTEGRATIONS.md` | External services, SDKs, connection patterns, webhook handling |
+| `CONCERNS.md` | Tech debt, known bugs, fragile areas, security notes |
+
+## When To Use This Skill
+
+- When first setting up context for an existing codebase
+- After a major architectural change
+- When onboarding a new project or team member
+- When context documents feel stale (> 1 month since major changes)
+
+## Incremental Refresh
+
+To refresh only specific documents, specify the focus area:
+- "Refresh just the conventions" → re-run quality focus
+- "Update the tech stack docs" → re-run tech focus
+- "Check for new concerns" → re-run concerns focus
+
+## Related
+
+Run corresponding prompt file: `/map-codebase`
+
+## Resources
+
+- [Analysis prompt template](.github/copilot-context/prompts/map-codebase.prompt.md)
+- [Architecture template](.planning/codebase/ARCHITECTURE.md)
+- [Structure template](.planning/codebase/STRUCTURE.md)
+- [Stack template](.planning/codebase/STACK.md)
+- [Conventions template](.planning/codebase/CONVENTIONS.md)
+- [Testing template](.planning/codebase/TESTING.md)
+- [Integrations template](.planning/codebase/INTEGRATIONS.md)
+- [Concerns template](.planning/codebase/CONCERNS.md)

package/.github/copilot-context/skills/project-history/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: project-history
+description: Accesses historical project context — phase summaries, decisions, retrospectives, and archived milestones. Use when you need to understand past decisions or trace why something was built a certain way.
+---
+
+# Project History Skill
+
+This skill provides access to historical project context — understanding past decisions, reviewing what was built in previous phases, and tracing the rationale behind architectural choices.
+
+## What's Available
+
+| Resource | Location | Contents |
+|----------|----------|---------|
+| Phase summaries | `.planning/phases/[NN]-[name]/*.SUMMARY.md` | What was implemented, files changed, decisions made |
+| Verification reports | `.planning/phases/[NN]-[name]/VERIFICATION.md` | Test results, requirement coverage per phase |
+| Key decisions | `.planning/PROJECT.md` → Key Decisions table | All major decisions with rationale |
+| Milestone archives | `.planning/milestones/` (if exists) | Completed milestone documentation |
+| Session logs | `.planning/phases/[NN]-[name]/.continue-here.md` | Saved session states |
+
+## When To Use This Skill
+
+- "Why was [X] implemented this way?"
+- "What changed in Phase [N]?"
+- "When was [feature] added?"
+- "Did we consider [alternative approach]?"
+- "What decisions locked in this constraint?"
+
+## Usage Examples
+
+**Trace a decision:**
+"Show me all architectural decisions made in Phase 1-3"
+→ I'll read the SUMMARY.md files and PROJECT.md Key Decisions table
+
+**Understand past work:**
+"What did we implement in Phase 2?"
+→ I'll read `.planning/phases/02-name/*.SUMMARY.md`
+
+**Check test history:**
+"What was the test coverage when we finished Phase 1?"
+→ I'll read `.planning/phases/01-name/VERIFICATION.md`
+
+## Resources
+
+- [Project decisions](.planning/PROJECT.md)
+- [Current state](.planning/STATE.md)
+- [Full roadmap](.planning/ROADMAP.md)

package/.github/copilot-instructions.md

@@ -0,0 +1,68 @@
+# Project Copilot Instructions
+
+<!--
+  This file is automatically loaded by GitHub Copilot Chat on every request in this workspace.
+  Keep it concise (under 100 lines). It is a synthesized digest — full details live in .planning/.
+
+  To regenerate this file from .planning/ documents, run: /sync-instructions
+-->
+
+## What This Project Is
+
+<!-- FILL IN: 2-3 sentences. What does this product do and who is it for? -->
+[Project description — update me after running /new-project or /map-codebase]
+
+**Core value:** [The one thing that must always work — from .planning/PROJECT.md]
+
+## Current State
+
+<!-- FILL IN: Keep updated after each session. Run /progress for full status. -->
+- **Phase:** [X of Y — Phase Name]
+- **Status:** [Ready to plan / In progress / Phase complete]
+- **Last activity:** [YYYY-MM-DD — what happened]
+
+## Active Constraints
+
+<!-- Non-negotiable constraints that apply to ALL work in this codebase. -->
+- **[Type]:** [What it means for code you write]
+- **[Type]:** [What it means for code you write]
+
+## Key Decisions (recent)
+
+<!-- Decisions that constrain future work. Full history in .planning/PROJECT.md -->
+- [Decision] — [rationale and implication]
+- [Decision] — [rationale and implication]
+
+## Where to Find Deep Context
+
+All detailed project context lives in `.planning/`:
+
+| Document | What's in it |
+|----------|-------------|
+| `.planning/PROJECT.md` | Full requirements, decisions, and constraints |
+| `.planning/REQUIREMENTS.md` | All requirements with IDs and traceability |
+| `.planning/ROADMAP.md` | Phase list with plans and success criteria |
+| `.planning/STATE.md` | Current position and session continuity |
+| `.planning/codebase/ARCHITECTURE.md` | System layers and data flow |
+| `.planning/codebase/STRUCTURE.md` | Where to put new code |
+| `.planning/codebase/CONVENTIONS.md` | Coding style and patterns |
+| `.planning/codebase/TESTING.md` | Test framework and patterns |
+| `.planning/codebase/STACK.md` | Technology stack and dependencies |
+| `.planning/codebase/INTEGRATIONS.md` | External services and APIs |
+| `.planning/codebase/CONCERNS.md` | Tech debt and fragile areas |
+
+## Quick Commands (run in Copilot Chat)
+
+| Command | Purpose |
+|---------|---------|
+| `/map-codebase` | Analyze codebase and fill in `.planning/codebase/` |
+| `/new-project` | Initialize `.planning/` docs for a new project |
+| `/plan-phase` | Plan implementation for a roadmap phase |
+| `/execute-phase` | Execute a planned phase step-by-step |
+| `/verify-work` | Verify implementation against requirements |
+| `/progress` | Show current progress and roadmap status |
+| `/pause-work` | Save session state to `.planning/continue-here.md` |
+| `/resume-work` | Load session state and continue where you left off |
+| `/sync-instructions` | Regenerate this file from `.planning/` docs |
+
+> Full system documentation: [.github/copilot-context/README.md](.github/copilot-context/README.md)