ragarciaruben 1.20.7

package/.github/copilot-context/README.md

@@ -0,0 +1,313 @@
+# Copilot Context Engineering System
+
+> A Copilot-native port of the context engineering concepts from [get-shit-done](https://github.com/closedwiki/get-shit-done) — adapted to work inside **VS Code GitHub Copilot** using its native instruction/prompt/agent/skill/hook system.
+
+---
+
+## What This Is
+
+A structured context engineering system that keeps GitHub Copilot grounded in your codebase across sessions. It solves the "blank slate" problem — where every new Copilot session starts with no knowledge of your project's architecture, conventions, decisions, or current state.
+
+**How it works:**
+1. **`.planning/`** (project root) holds the source-of-truth documents about your project
+2. **`.github/copilot-context/`** (this folder) holds the Copilot consumption layer — instructions, prompt commands, agents, and skills that feed context to Copilot at the right time
+3. **`.vscode/settings.json`** tells Copilot where to find these files
+
+---
+
+## Folder Structure
+
+```
+.github/
+├── copilot-instructions.md          ← Always-on digest (auto-loaded every request)
+└── copilot-context/
+    ├── README.md                    ← This file
+    ├── instructions/                ← Conditional instructions (loaded when relevant)
+    │   ├── conventions.instructions.md   applyTo: source files
+    │   ├── testing.instructions.md       applyTo: test files
+    │   ├── architecture.instructions.md  description-based (backend/API work)
+    │   ├── structure.instructions.md     description-based (adding new files)
+    │   ├── stack.instructions.md         description-based (dependencies/config)
+    │   ├── integrations.instructions.md  description-based (external services)
+    │   └── concerns.instructions.md      description-based (refactoring/debt)
+    ├── prompts/                     ← Slash commands for structured workflows
+    │   ├── map-codebase.prompt.md        /map-codebase
+    │   ├── new-project.prompt.md         /new-project
+    │   ├── plan-phase.prompt.md          /plan-phase [N]
+    │   ├── execute-phase.prompt.md       /execute-phase [N]
+    │   ├── verify-work.prompt.md         /verify-work [N]
+    │   ├── progress.prompt.md            /progress
+    │   ├── pause-work.prompt.md          /pause-work
+    │   ├── resume-work.prompt.md         /resume-work
+    │   └── sync-instructions.prompt.md   /sync-instructions
+    ├── agents/                      ← Specialized personas with constrained tools
+    │   ├── planner.agent.md              Read-only — plans phases
+    │   ├── executor.agent.md             Full tools — implements plans
+    │   └── verifier.agent.md             Read + run — verifies requirements
+    ├── skills/                      ← Progressive-loading reference capabilities
+    │   ├── map-codebase/SKILL.md         Codebase analysis capability
+    │   └── project-history/SKILL.md      Historical context access
+    └── hooks/                       ← Lifecycle automation (Preview feature)
+        ├── hooks.json                    SessionStart hook config
+        └── inject-context.js             Injects STATE.md at session start
+
+.planning/                           ← Source of truth (project root)
+    ├── PROJECT.md                   Project description, requirements, decisions
+    ├── REQUIREMENTS.md              Requirements with IDs and traceability
+    ├── ROADMAP.md                   Phase list with plans and success criteria
+    ├── STATE.md                     Current position and session continuity
+    ├── continue-here.md             Session resume snapshot (written by /pause-work)
+    └── codebase/
+        ├── ARCHITECTURE.md          Layers, data flow, entry points
+        ├── STRUCTURE.md             Where to put new code
+        ├── STACK.md                 Runtime, frameworks, env vars
+        ├── CONVENTIONS.md           Coding style and naming
+        ├── TESTING.md               Test framework and patterns
+        ├── INTEGRATIONS.md          External services and SDKs
+        └── CONCERNS.md              Tech debt and fragile areas
+```
+
+---
+
+## Quick Start
+
+### For a new project
+
+```
+1. Copy this repo's .github/ and .planning/ into your project
+2. Open Copilot Chat and run:  /new-project
+3. Follow the questions → fills in PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+4. Run: /map-codebase
+5. Copilot analyzes your code → fills all 7 .planning/codebase/ documents
+6. Run: /sync-instructions
+7. .github/copilot-instructions.md is updated with your project digest
+```
+
+### For an existing project with established context
+
+```
+1. Copy this repo's .github/ and .planning/ into your project
+2. Fill in .planning/PROJECT.md manually (description, core value, constraints)
+3. Run: /map-codebase  ← generates all codebase analysis docs automatically
+4. Run: /sync-instructions  ← updates the always-on instructions digest
+```
+
+---
+
+## How Each Layer Works
+
+### Always-On Instructions — `copilot-instructions.md`
+
+Automatically loaded on **every** Copilot Chat request. Contains a synthesized ~80-line digest with:
+- Project identity and core value
+- Current phase/status
+- Active constraints
+- Recent key decisions
+- Links to `.planning/` for deep context
+
+**Regenerate it with:** `/sync-instructions` (reads `.planning/` and rewrites the file)
+
+**Principle:** Keep it short. Every line competes with your conversation for context tokens. Deep context lives in `.planning/` — not here.
+
+---
+
+### Conditional Instructions — `instructions/*.instructions.md`
+
+Loaded only when relevant, using two mechanisms:
+
+| File | Trigger |
+|------|---------|
+| `conventions.instructions.md` | `applyTo: "**/*.{ts,tsx,js,jsx}"` — auto on source files |
+| `testing.instructions.md` | `applyTo: "**/*.{test,spec}.*"` — auto on test files |
+| `architecture.instructions.md` | `description:` — semantic match when doing backend/API work |
+| `structure.instructions.md` | `description:` — semantic match when creating new files |
+| `stack.instructions.md` | `description:` — semantic match for dependency/config questions |
+| `integrations.instructions.md` | `description:` — semantic match for external service work |
+| `concerns.instructions.md` | `description:` — semantic match when refactoring/near tech debt |
+
+Each instruction file is a **thin reference** — it doesn't duplicate the full content, it points to the relevant `.planning/codebase/` document and surfaces the top rules.
+
+---
+
+### Prompt Files — `prompts/*.prompt.md`
+
+Invoked manually via `/command-name` in Copilot Chat. Each prompt implements a full structured workflow:
+
+| Command | What it does | Mode |
+|---------|-------------|------|
+| `/map-codebase` | Analyzes codebase → generates 7 `.planning/codebase/` docs | agent |
+| `/new-project` | Sets up `.planning/` docs via guided questions | agent |
+| `/plan-phase [N]` | Plans a phase → produces step-by-step plan files | agent |
+| `/execute-phase [N]` | Executes a planned phase with commits | agent |
+| `/verify-work [N]` | Verifies implementation against requirements | agent |
+| `/progress` | Shows phase/requirement completion status | ask |
+| `/pause-work` | Saves session state to `.planning/continue-here.md` | agent |
+| `/resume-work` | Loads saved state and orients the new session | ask |
+| `/sync-instructions` | Regenerates `copilot-instructions.md` from `.planning/` | agent |
+
+---
+
+### Agents — `agents/*.agent.md`
+
+Specialized personas that mirror the GSD multi-agent architecture:
+
+```
+User → Planner (read-only tools)
+              ↓ handoff: "Start Executing"
+         Executor (full tools — edit, terminal, search)
+              ↓ handoff: "Verify This Work"
+          Verifier (read + run terminal)
+              ↓ handoff: "Fix Gaps" → loops back to Executor
+```
+
+Each agent has constrained tools matching its role:
+- **Planner** — `search` only. Can't edit code; designs plans.
+- **Executor** — `editFiles + runTerminalCommand + search`. Implements plans with commits.
+- **Verifier** — `runTerminalCommand + search`. Runs tests and checks requirements.
+
+Switch between agents via the agents dropdown in Copilot Chat, or trigger handoffs with the buttons they surface.
+
+---
+
+### Skills — `skills/*/SKILL.md`
+
+Progressive-loading reference capabilities. Only `name` + `description` is initially loaded; the full content is fetched when the agent decides they're relevant (or when explicitly mentioned).
+
+| Skill | When used |
+|-------|-----------|
+| `map-codebase` | When asked to analyze/refresh codebase context |
+| `project-history` | When asked about past decisions or previous phase work |
+
+---
+
+### Session Hook — `hooks/inject-context.js`
+
+> **Status: Preview** — requires VS Code 1.109.3+
+
+A `SessionStart` hook that automatically injects your current project state at the beginning of every new Copilot chat session. It reads `.planning/STATE.md` and `.planning/continue-here.md` and injects the key fields (phase, status, next action) as `additionalContext`.
+
+**Effect:** Every session starts knowing where you left off — no manual `/resume-work` needed.
+
+**Config:** Registered in `hooks/hooks.json`. Must be enabled in VS Code settings:
+```json
+{ "chat.hooks.enabled": true }
+```
+
+**Fallback:** If hooks aren't available, use `/resume-work` manually at the start of each session.
+
+---
+
+## The `.planning/` Source of Truth
+
+`.planning/` lives at the **project root** (not inside `.github/`). It is the source of truth that all Copilot context is derived from.
+
+### Core Project Documents
+
+| Document | Purpose | Updated by |
+|----------|---------|------------|
+| `PROJECT.md` | What this project is, core value, requirements, constraints, decisions | `/new-project`, `/sync-instructions`, manually |
+| `REQUIREMENTS.md` | All requirements with IDs (AUTH-01, CORE-02), v1/v2 split, traceability | `/new-project`, `/verify-work` |
+| `ROADMAP.md` | Phase list with plans, success criteria, completion status | `/plan-phase`, `/execute-phase` |
+| `STATE.md` | Living memory — current position, metrics, last activity, next action | `/execute-phase`, `/pause-work` |
+| `continue-here.md` | Session snapshot — exact resume point, decisions, blockers | `/pause-work` |
+
+### Codebase Analysis Documents
+
+Generated once by `/map-codebase`, then kept up to date:
+
+| Document | Fill first time | Keep updated when |
+|----------|----------------|-------------------|
+| `ARCHITECTURE.md` | `/map-codebase` | Major architectural changes |
+| `STRUCTURE.md` | `/map-codebase` | New directory patterns added |
+| `STACK.md` | `/map-codebase` | New major dependencies added |
+| `CONVENTIONS.md` | `/map-codebase` | Style guide changes |
+| `TESTING.md` | `/map-codebase` | Test framework changes |
+| `INTEGRATIONS.md` | `/map-codebase` | New external services integrated |
+| `CONCERNS.md` | `/map-codebase` | New debt found or old debt resolved |
+
+---
+
+## Typical Session Workflow
+
+```
+New session:
+  1. /resume-work    ← orient the session (or auto-injected via hook)
+
+  Planning session:
+  2. /plan-phase 3   ← or switch to Planner agent
+
+  Execution session:
+  3. /execute-phase 3    ← or switch to Executor agent
+
+  Verification:
+  4. /verify-work 3      ← or switch to Verifier agent
+
+  End of session:
+  5. /pause-work     ← save state for next session
+  6. /sync-instructions  ← update copilot-instructions.md if context shifted
+```
+
+---
+
+## Adapting to Your Project
+
+### Customizing instruction `applyTo` patterns
+
+Edit `instructions/conventions.instructions.md` to match your language extensions:
+```yaml
+# Python project:
+applyTo: "**/*.py"
+
+# Java project:
+applyTo: "**/*.java"
+
+# Multi-language:
+applyTo: "**/*.{ts,tsx,js,jsx,py}"
+```
+
+### Adding new instruction domains
+
+Create a new `instructions/[topic].instructions.md`:
+```yaml
+---
+name: Database Patterns
+description: ORM patterns, query conventions, and migration rules for database work
+applyTo: "**/*.migration.*"
+---
+# Instructions here...
+```
+
+### Extending the workflow
+
+Add new prompts to `prompts/` for domain-specific tasks your team repeats:
+- `debug-session.prompt.md` — structured debugging workflow
+- `write-adr.prompt.md` — create Architecture Decision Records
+- `code-review.prompt.md` — systematic code review checklist
+
+---
+
+## Compatibility
+
+| Feature | Requires |
+|---------|---------|
+| `copilot-instructions.md` | VS Code + GitHub Copilot (any recent version) |
+| `*.instructions.md` files | VS Code 1.102+ |
+| `*.prompt.md` files | VS Code 1.102+ |
+| `*.agent.md` files | VS Code 1.106+ |
+| Agent handoffs | VS Code 1.106+ |
+| Skills (`SKILL.md`) | VS Code 1.106+ |
+| `SessionStart` hooks | VS Code 1.109.3+ (Preview) |
+| `chat.*FilesLocations` settings | VS Code 1.102+ |
+
+---
+
+## Credits
+
+Context engineering architecture inspired by [get-shit-done](https://github.com/closedwiki/get-shit-done) (GSD) — a spec-driven development system for Claude Code and other terminal-based AI agents. This system implements the same principles natively for VS Code GitHub Copilot.
+
+**Key concepts borrowed from GSD:**
+- Structured `.planning/` documents as persistent cross-session context
+- Codebase mapper that generates 7 specialized analysis documents
+- Phase-based lifecycle: plan → execute → verify
+- Context-efficient progressive disclosure (thin always-on + conditional loading)
+- Session continuity via `continue-here.md` + `STATE.md`

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

@@ -0,0 +1,11 @@
+{
+  "_comment": "Copilot Hooks — Preview feature (VS Code 1.109.3+). See: https://code.visualstudio.com/docs/copilot/chat/chat-hooks",
+  "_note": "SessionStart hook: Reads .planning/STATE.md and .planning/continue-here.md at session start and injects them as additional context. Every new chat session immediately knows where you left off.",
+  "hooks": [
+    {
+      "event": "SessionStart",
+      "command": "node .github/copilot-context/hooks/inject-context.js",
+      "description": "Inject project state and session continuity context at session start"
+    }
+  ]
+}

package/.github/copilot-context/hooks/inject-context.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Copilot SessionStart Hook — Context Injector
+ *
+ * Reads .planning/STATE.md and .planning/continue-here.md, then outputs
+ * additionalContext JSON for Copilot to inject at session start.
+ *
+ * This ensures every new chat session automatically knows where you left off.
+ *
+ * Protocol: Read JSON from stdin, write JSON to stdout.
+ * See: https://code.visualstudio.com/docs/copilot/chat/chat-hooks
+ *
+ * Usage: Configured in .github/copilot-context/hooks/hooks.json as a SessionStart event hook.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read hook input from stdin (Copilot passes session info here)
+let stdin = '';
+process.stdin.on('data', (chunk) => { stdin += chunk; });
+
+process.stdin.on('end', () => {
+  const workspaceRoot = resolveWorkspaceRoot();
+  const contextParts = [];
+
+  // Load STATE.md
+  const statePath = path.join(workspaceRoot, '.planning', 'STATE.md');
+  if (fs.existsSync(statePath)) {
+    const content = fs.readFileSync(statePath, 'utf8');
+    // Extract just the essential sections (avoid dumping the whole file)
+    const essential = extractEssentialState(content);
+    if (essential) {
+      contextParts.push(`## Project State\n\n${essential}`);
+    }
+  }
+
+  // Load continue-here.md if it exists (session resumption)
+  const continuePath = path.join(workspaceRoot, '.planning', 'continue-here.md');
+  if (fs.existsSync(continuePath)) {
+    const content = fs.readFileSync(continuePath, 'utf8');
+    contextParts.push(`## Resume Context\n\n${content}`);
+  }
+
+  if (contextParts.length === 0) {
+    // No context to inject — exit cleanly without output
+    process.exit(0);
+  }
+
+  // Output additionalContext for Copilot to inject
+  const output = {
+    additionalContext: contextParts.join('\n\n---\n\n')
+  };
+
+  process.stdout.write(JSON.stringify(output));
+});
+
+/**
+ * Extract essential sections from STATE.md to avoid injecting the whole file.
+ * Gets: core value, current position, last activity, next action.
+ */
+function extractEssentialState(content) {
+  const lines = content.split('\n');
+  const essential = [];
+  let inRelevantSection = false;
+  let sectionDepth = 0;
+
+  for (const line of lines) {
+    // Always include core value and current position lines
+    if (
+      line.includes('Core value:') ||
+      line.includes('Current focus:') ||
+      line.includes('Phase:') ||
+      line.includes('Status:') ||
+      line.includes('Last activity:') ||
+      line.includes('Next action:') ||
+      line.includes('Progress:')
+    ) {
+      essential.push(line);
+    }
+  }
+
+  return essential.join('\n').trim();
+}
+
+/**
+ * Resolve workspace root — walk up from script location until we find .planning/
+ */
+function resolveWorkspaceRoot() {
+  // Try to get from stdin (Copilot may pass workspace info)
+  try {
+    const input = JSON.parse(stdin || '{}');
+    if (input.workspaceFolder) return input.workspaceFolder;
+  } catch {}
+
+  // Walk up from script directory
+  let dir = __dirname;
+  for (let i = 0; i < 5; i++) {
+    if (fs.existsSync(path.join(dir, '.planning'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+
+  // Fallback to cwd
+  return process.cwd();
+}

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