ragarciaruben 1.20.19 → 1.20.21

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

@@ -1,556 +0,0 @@
-# GSD for GitHub Copilot — User Guide
-
-> **Get Shit Done (GSD)** is a context engineering system that makes GitHub Copilot actually understand your project — its architecture, conventions, current state, and what you're working on — across every session.
-
----
-
-## TL;DR
-
-```bash
-# Install into any project
-npx ragarciaruben@latest copilot-context
-
-# Or pick option 6 from the interactive menu
-npx ragarciaruben@latest
-```
-
-Then in VS Code Copilot Chat:
-1. `/map-codebase` — Copilot analyzes your code and writes structured docs
-2. `/new-project` — Set up project goals, requirements, and roadmap
-3. Start working with `/plan-phase`, `/execute-phase`, `/verify-work`
-
----
-
-## Table of Contents
-
-- [What It Does](#what-it-does)
-- [What It Can and Can't Do](#what-it-can-and-cant-do)
-- [Installation](#installation)
-- [Getting Started (5 minutes)](#getting-started-5-minutes)
-- [Daily Workflow](#daily-workflow)
-- [Slash Commands Reference](#slash-commands-reference)
-- [Agents — Planner, Executor, Verifier](#agents--planner-executor-verifier)
-- [Model Profiles](#model-profiles)
-- [How Instructions Work (you don't touch these)](#how-instructions-work)
-- [The .planning/ Folder — Your Source of Truth](#the-planning-folder--your-source-of-truth)
-- [Customizing for Your Project](#customizing-for-your-project)
-- [Session Continuity — How State Persists](#session-continuity--how-state-persists)
-- [FAQ](#faq)
-- [Compatibility](#compatibility)
-
----
-
-## What It Does
-
-Every time you open Copilot Chat, the AI starts from zero — it doesn't know your project's architecture, coding style, what phase you're in, or what you were doing yesterday. GSD fixes this.
-
-**It gives Copilot:**
-- A structured understanding of your codebase (architecture, conventions, testing patterns, tech stack, integrations, tech debt)
-- Your project requirements, roadmap, and current phase
-- Memory of where you left off across sessions
-- Specialized agents for planning, implementing, and verifying work
-- Slash commands that run structured workflows (not just chat)
-
-**Think of it as:** a project manual that Copilot reads automatically so it doesn't ask dumb questions or ignore your conventions.
-
----
-
-## What It Can and Can't Do
-
-### ✅ Can Do
-
-| Capability | How |
-|---|---|
-| **Analyze your codebase** and generate context docs | `/map-codebase` — reads your code, produces 7 structured docs |
-| **Plan work** with step-by-step phases | `/plan-phase 3` or `@Planner` agent |
-| **Execute plans** with code edits, terminal commands, commits | `/execute-phase 3` or `@Executor` agent |
-| **Verify work** against requirements automatically | `/verify-work 3` or `@Verifier` agent |
-| **Persist state** across chat sessions | `/pause-work` saves, `/resume-work` restores |
-| **Keep instructions fresh** when your project changes | `/sync-instructions` regenerates the digest |
-| **Switch AI model profiles** (Opus, Sonnet, GPT-4.1) | `/set-profile` — changes model for all agents |
-| **Auto-inject conventions** when editing source/test files | `.instructions.md` files trigger automatically |
-| **Agent handoffs** — Planner → Executor → Verifier | Built-in handoff buttons in agent mode |
-
-### ❌ Cannot Do
-
-| Limitation | Why | Workaround |
-|---|---|---|
-| **No background agents** — can't spawn subagents in parallel | VS Code Copilot doesn't support subprocess spawning like Claude Code | Use agents sequentially via handoffs |
-| **No automatic hooks** on older VS Code | Session hooks require VS Code 1.109.3+ (Preview) | Run `/resume-work` manually at session start |
-| **Won't auto-update `.planning/` docs** | Copilot won't edit docs unless you tell it to | Run `/map-codebase` periodically, especially after big changes |
-| **Agents don't remember across sessions** | Each Copilot Chat session starts fresh | Use `/pause-work` and `/resume-work` |
-| **Model profiles require manual switch** | No config-file-based auto-detection yet | Run `/set-profile` once per project |
-| **Can't run outside VS Code** | This is a VS Code Copilot system, not a CLI tool | For CLI: use the original GSD with Claude Code/Gemini/Codex |
-
----
-
-## Installation
-
-### Into an existing project
-
-```bash
-cd your-project
-npx ragarciaruben@latest copilot-context
-```
-
-This creates:
-```
-your-project/
-├── .github/
-│   ├── copilot-instructions.md     ← auto-loaded every chat
-│   ├── prompts/                    ← slash commands
-│   ├── instructions/               ← conditional context
-│   ├── agents/                     ← planner/executor/verifier
-│   └── copilot-context/            ← skills, hooks, reference README
-├── .planning/                      ← source-of-truth docs (you fill these in)
-└── .vscode/settings.json           ← comments only (no config needed)
-```
-
-### Re-install / update
-
-```bash
-npx ragarciaruben@latest copilot-context --force
-```
-
-`--force` overwrites existing files. Without it, existing files are skipped.
-
----
-
-## Getting Started (5 minutes)
-
-### Step 1: Install
-
-```bash
-cd your-project
-npx ragarciaruben@latest copilot-context
-```
-
-### Step 2: Map your codebase
-
-Open VS Code, open Copilot Chat (`Ctrl+Shift+I` or `Cmd+Shift+I`), and type:
-
-```
-/map-codebase
-```
-
-Copilot will analyze your project and generate 7 structured documents in `.planning/codebase/`:
-- `ARCHITECTURE.md` — layers, data flow, entry points
-- `STRUCTURE.md` — where to put new code
-- `CONVENTIONS.md` — coding style + naming rules
-- `TESTING.md` — test framework + patterns
-- `STACK.md` — runtime, dependencies, config
-- `INTEGRATIONS.md` — external services
-- `CONCERNS.md` — tech debt + fragile areas
-
-**This takes 1-3 minutes.** After this, Copilot knows your codebase.
-
-### Step 3: Set up your project
-
-```
-/new-project
-```
-
-Answer the guided questions. This fills in:
-- `.planning/PROJECT.md` — what your project is and its core value
-- `.planning/REQUIREMENTS.md` — requirements with IDs
-- `.planning/ROADMAP.md` — phases with goals and success criteria
-- `.planning/STATE.md` — current position
-
-### Step 4: Start working
-
-```
-/plan-phase 1
-```
-
-That's it. You're set up.
-
----
-
-## Daily Workflow
-
-### Starting a session
-
-```
-/resume-work
-```
-Copilot reads your saved state and orients itself to where you left off.
-
-### Planning work
-
-Use the `/plan-phase` command or talk to the `@Planner` agent:
-
-```
-/plan-phase 2
-```
-
-Or switch to the Planner agent in the agents dropdown and describe what you need planned.
-
-### Doing work
-
-```
-/execute-phase 2
-```
-
-Or switch to `@Executor`. It follows the plan, writes code, runs commands, and makes commits.
-
-### Checking work
-
-```
-/verify-work 2
-```
-
-Or switch to `@Verifier`. It runs tests, checks the implementation against requirements, and reports gaps.
-
-### Ending a session
-
-```
-/pause-work
-```
-
-This saves your current state to `.planning/continue-here.md` — what was done, what's remaining, decisions made, and the exact next action.
-
-### Quick check
-
-```
-/progress
-```
-
-Shows overall project progress — which phases are done, what's next, requirement coverage.
-
----
-
-## Slash Commands Reference
-
-| Command | What it does | When to use |
-|---------|-------------|-------------|
-| `/map-codebase` | Analyzes your code → generates 7 context docs | First time setup, or after major refactors |
-| `/new-project` | Guided project setup → fills `.planning/` docs | First time only |
-| `/plan-phase [N]` | Creates a step-by-step plan for phase N | Before starting new work |
-| `/execute-phase [N]` | Implements phase N following the plan | When plan is ready |
-| `/verify-work [N]` | Checks phase N against requirements | After implementation |
-| `/progress` | Shows project status and completion | Anytime — quick overview |
-| `/pause-work` | Saves session state for later | End of work session |
-| `/resume-work` | Loads saved state, orients session | Start of work session |
-| `/sync-instructions` | Regenerates `copilot-instructions.md` | After updating `.planning/` docs |
-| `/set-profile` | Switch AI model for all agents | When you want different quality/cost balance |
-
----
-
-## Agents — Planner, Executor, Verifier
-
-GSD provides three specialized agents. Each has a specific role and restricted tools to keep it focused.
-
-### @Planner
-
-- **Role:** Reads the codebase and requirements, produces detailed plans
-- **Tools:** `search` only — **cannot edit files or run commands**
-- **Model:** `claude-opus-4` (strongest reasoning)
-- **Use when:** Starting a new phase, designing architecture, breaking down work
-
-The Planner creates a plan document and then offers a handoff button: **"Start Executing"** → sends the plan to the Executor.
-
-### @Executor
-
-- **Role:** Implements the plan — writes code, runs tests, makes commits
-- **Tools:** `editFiles`, `runTerminalCommand`, `search`
-- **Model:** `claude-opus-4`
-- **Use when:** Plan is ready and you want to implement it
-
-After finishing, it offers: **"Verify This Work"** → sends to Verifier, or **"Pause & Save State"** → saves progress.
-
-### @Verifier
-
-- **Role:** Checks implementation against requirements — runs tests, inspects code
-- **Tools:** `runTerminalCommand`, `search` — **cannot edit files**
-- **Model:** `claude-sonnet-4`
-- **Use when:** After implementing a phase, before merging
-
-If gaps are found, it offers: **"Fix Gaps"** → sends back to Executor with specific issues.
-
-### How to use agents
-
-1. In Copilot Chat, click the agent dropdown (or type `@`)
-2. Select **Planner**, **Executor**, or **Verifier**
-3. Describe your task
-4. Use the handoff buttons to chain agents together
-
-**Typical flow:**
-```
-@Planner "Plan the authentication feature"
-  → produces plan
-  → click "Start Executing"
-
-@Executor receives the plan
-  → writes code, runs tests
-  → click "Verify This Work"
-
-@Verifier checks everything
-  → "All requirements met" ✅
-  → or "Fix Gaps" → back to Executor
-```
-
-You can also skip agents entirely and just use slash commands — they do the same thing inline.
-
----
-
-## Model Profiles
-
-Agents use specific AI models. The default is **quality** profile:
-
-| Agent | Default Model |
-|-------|--------------|
-| Planner | `claude-opus-4` |
-| Executor | `claude-opus-4` |
-| Verifier | `claude-sonnet-4` |
-
-### Switching profiles
-
-Run `/set-profile` in Copilot Chat:
-
-| Profile | Planner | Executor | Verifier | Best for |
-|---------|---------|----------|----------|----------|
-| **quality** | claude-opus-4 | claude-opus-4 | claude-sonnet-4 | Critical work, architecture decisions |
-| **balanced** | claude-sonnet-4 | claude-sonnet-4 | claude-sonnet-4 | Normal development |
-| **budget** | gpt-4.1 | gpt-4.1 | gpt-4.1-mini | High-volume, cost-sensitive |
-| **gpt** | gpt-4.1 | gpt-4.1 | gpt-4.1 | Prefer OpenAI models |
-
-`/set-profile` edits the `model:` field in all agent files and saves your choice to `.planning/config.json`.
-
-### Per-agent override
-
-You can also tell `/set-profile` to change just one agent:
-```
-/set-profile
-> "Use opus for the verifier too, keep everything else on quality"
-```
-
----
-
-## How Instructions Work
-
-> **You don't need to touch these** — they work automatically.
-
-When you open a file or ask a question, Copilot loads relevant instructions behind the scenes:
-
-| When you... | Copilot automatically loads |
-|------------|---------------------------|
-| Edit a `.ts`, `.js`, `.tsx`, `.jsx` file | `conventions.instructions.md` — your coding style |
-| Edit a `*.test.ts`, `*.spec.js` file | `testing.instructions.md` — test patterns |
-| Ask about architecture or backend | `architecture.instructions.md` |
-| Ask where to put a new file | `structure.instructions.md` |
-| Ask about dependencies or config | `stack.instructions.md` |
-| Ask about external APIs or services | `integrations.instructions.md` |
-| Work near tech debt or fragile code | `concerns.instructions.md` |
-
-Each instruction file points to the detailed doc in `.planning/codebase/`. This keeps instructions small and context-efficient.
-
-### Customizing for your language
-
-If your project isn't TypeScript/JavaScript, edit `.github/instructions/conventions.instructions.md`:
-
-```yaml
-# Python
-applyTo: "**/*.py"
-
-# Java
-applyTo: "**/*.{java,kt}"
-
-# Go
-applyTo: "**/*.go"
-```
-
----
-
-## The .planning/ Folder — Your Source of Truth
-
-All project knowledge lives in `.planning/`. Copilot reads these automatically via the instructions system.
-
-```
-.planning/
-├── PROJECT.md          ← What this project is, who it's for, core constraints
-├── REQUIREMENTS.md     ← Feature requirements with IDs (AUTH-01, API-02)
-├── ROADMAP.md          ← Phase list: goals, steps, success criteria
-├── STATE.md            ← Current phase, progress, recent decisions
-├── continue-here.md    ← Session snapshot (written by /pause-work)
-├── config.json         ← Model profile + agent override settings
-└── codebase/
-    ├── ARCHITECTURE.md ← System layers, data flow, entry points
-    ├── STRUCTURE.md    ← Directory layout, where to put new code
-    ├── CONVENTIONS.md  ← Naming, formatting, error handling patterns
-    ├── TESTING.md      ← Test framework, patterns, what to test
-    ├── STACK.md        ← Runtime, frameworks, key dependencies
-    ├── INTEGRATIONS.md ← External APIs, SDKs, service config
-    └── CONCERNS.md     ← Tech debt, fragile areas, security notes
-```
-
-### What to commit
-
-**Commit everything in `.planning/` and `.github/`.** This is shared project context — your whole team benefits when these are in the repo.
-
-### When to regenerate
-
-| Trigger | Action |
-|---------|--------|
-| Major refactor or new directory structure | `/map-codebase` |
-| New external service integrated | Edit `.planning/codebase/INTEGRATIONS.md` or re-run `/map-codebase` |
-| Phase completed | `/verify-work` then `/progress` to update state |
-| Instructions feel stale | `/sync-instructions` |
-
----
-
-## Session Continuity — How State Persists
-
-Copilot doesn't have memory between sessions. GSD solves this with two files:
-
-### `STATE.md` — living memory
-
-Updated automatically by `/execute-phase` and `/pause-work`. Contains:
-- Current phase and progress
-- Recent decisions
-- Active blockers
-- Velocity metrics
-
-### `continue-here.md` — exact resume point
-
-Written by `/pause-work`. Contains:
-- What was completed this session
-- What remains
-- Decisions that were locked
-- The **exact next action** to take
-
-### Resume flow
-
-```
-Start new session → /resume-work → Copilot reads both files → oriented in 5 seconds
-```
-
-If you have VS Code 1.109.3+ and enable hooks (`"chat.hooks.enabled": true`), state is injected automatically at session start — no `/resume-work` needed.
-
----
-
-## Customizing for Your Project
-
-### Add a new slash command
-
-Create `.github/prompts/your-command.prompt.md`:
-
-```yaml
----
-name: your-command
-description: What this command does
-mode: agent
-tools:
-  - editFiles
-  - search
----
-
-# Your Command
-
-Instructions for what Copilot should do when this command is invoked.
-```
-
-### Add a new instruction domain
-
-Create `.github/instructions/your-topic.instructions.md`:
-
-```yaml
----
-name: Your Topic
-description: When this context is relevant
-applyTo: "**/*.sql"
----
-
-# Rules for SQL files
-
-- Use parameterized queries only
-- ...
-```
-
-### Add a new agent
-
-Create `.github/agents/your-agent.agent.md`:
-
-```yaml
----
-name: YourAgent
-description: What this agent specializes in
-tools:
-  - search
-model: claude-sonnet-4
----
-
-# Your Agent
-
-Behavior instructions here.
-```
-
----
-
-## FAQ
-
-**Q: Do I need to fill in every `.planning/` file manually?**
-No. Run `/map-codebase` to auto-generate the 7 codebase docs, and `/new-project` to fill in project docs via guided questions. Only `PROJECT.md` benefits from some manual input.
-
-**Q: What happens if I don't run `/pause-work`?**
-Next session starts without saved state. Copilot can still read `.planning/` docs, but won't know exactly where you left off. Just run `/resume-work` and describe briefly what you were doing.
-
-**Q: Can I use this with other AI tools?**
-The `.planning/` docs are plain Markdown — any AI tool that reads files can use them. The `.github/` files (prompts, agents, instructions) are VS Code Copilot-specific.
-
-**Q: Does this cost extra?**
-No. This uses your existing GitHub Copilot subscription. Model selection (opus/sonnet/gpt) depends on your plan's model access.
-
-**Q: How do I update GSD when new versions come out?**
-```bash
-npx ragarciaruben@latest copilot-context --force
-```
-
-**Q: Can multiple team members use this simultaneously?**
-Yes. `.planning/` is committed to git. Everyone shares the same project context. Just be mindful of merge conflicts in `STATE.md` if two people `/pause-work` at the same time.
-
-**Q: The agents don't appear in the dropdown?**
-Reload VS Code: `Ctrl+Shift+P` → `Developer: Reload Window`. Agent files must be in `.github/agents/` (the default scan location).
-
-**Q: Why are there duplicate files in `.github/agents/` and `.github/copilot-context/agents/`?**
-`.github/agents/` is where VS Code actually reads them. `.github/copilot-context/agents/` is the reference copy that ships with the installer. The active ones are in `.github/agents/`.
-
----
-
-## Compatibility
-
-| Feature | Minimum VS Code Version |
-|---------|------------------------|
-| `copilot-instructions.md` (always-on) | Any recent version |
-| `*.instructions.md` (conditional) | 1.102+ |
-| `*.prompt.md` (slash commands) | 1.102+ |
-| `*.agent.md` (agents + handoffs) | 1.106+ |
-| `SessionStart` hooks | 1.109.3+ (Preview) |
-
----
-
-## Quick Reference Card
-
-```
-SETUP:
-  npx ragarciaruben@latest copilot-context    Install GSD
-  /map-codebase                                Analyze codebase (first time)
-  /new-project                                 Set up project docs (first time)
-
-DAILY:
-  /resume-work                                 Start of session
-  /plan-phase N                                Plan phase N
-  /execute-phase N                             Implement phase N
-  /verify-work N                               Check phase N
-  /pause-work                                  End of session
-
-MAINTENANCE:
-  /progress                                    Check overall status
-  /sync-instructions                           Refresh always-on digest
-  /set-profile                                 Switch AI model profile
-  /map-codebase                                Re-analyze after big changes
-
-AGENTS:
-  @Planner                                     Plans (read-only)
-  @Executor                                    Implements (full tools)
-  @Verifier                                    Checks (read + run)
-```

package/.github/copilot-context/agents/executor.agent.md

@@ -1,84 +0,0 @@
----
-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
-  - runInTerminal
-  - search
-  - geppetto/*
-  - geppetto-api/*
-  - jira/*
-model: Claude Opus 4.6
-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
-
-## Jira Integration
-
-When executing work tied to Jira tickets, I:
-
-- **Read ticket details** with `mcp_jira_jira_get_issue` for acceptance criteria and context
-- **Comment progress** with `mcp_jira_jira_add_comment` after completing significant steps
-- **Transition tickets** with `mcp_jira_jira_transition_issue` (e.g., To Do → In Progress → In Review)
-- Reference Jira ticket IDs in commit messages: `feat(PROJ-123): implement user auth flow`
-
-## Trigger Phrases
-
-"Execute phase [N]", "Implement the plan", "Build [feature] from the plan", "Continue implementing"
-
-## Corporate Context (Geppetto MCP)
-
-When implementing with corporate frameworks, APIs, or services, use the Geppetto MCP tools to look up Inditex-specific patterns:
-
-- **`mcp_geppetto_generic_search`** — Search all Inditex technical documentation (best general-purpose fallback)
-- **`mcp_geppetto_api_search`** — Search Inditex API best practices, guidelines, and REST API specifications
-
-Use these tools when:
-- Implementing against AMIGA framework patterns (Java, Node, Python, Go, Web)
-- Calling or building corporate REST APIs
-- Setting up CI/CD pipelines, Dockerfiles, or infrastructure config
-- Implementing authorization flows (Heimdal) or other internal service integrations
-
-## 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