ragarciaruben 1.20.7

package/bin/setup-copilot-context.js

@@ -0,0 +1,180 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * setup-copilot-context.js
+ *
+ * Installs the GSD Copilot Context system into any project.
+ * Invoked as: npx get-shit-done-cc copilot-context [target-dir] [--force]
+ *
+ * What it installs:
+ *   .github/copilot-instructions.md   — always-on digest
+ *   .github/copilot-context/          — instructions, prompts, agents, skills, hooks
+ *   .planning/                        — source-of-truth template docs
+ *   .vscode/settings.json             — custom path config for VS Code Copilot
+ */
+
+const fs   = require('fs');
+const path = require('path');
+
+// ─── Colour helpers (cross-platform) ────────────────────────────────────────
+
+const hasColor = process.stdout.isTTY && (
+  process.platform !== 'win32' ||
+  !!process.env.WT_SESSION ||
+  process.env.TERM_PROGRAM === 'vscode' ||
+  /^xterm|^screen/.test(process.env.TERM || '')
+);
+
+const c = {
+  bold:  s => hasColor ? `\x1b[1m${s}\x1b[0m`  : s,
+  green: s => hasColor ? `\x1b[32m${s}\x1b[0m` : s,
+  blue:  s => hasColor ? `\x1b[34m${s}\x1b[0m` : s,
+  cyan:  s => hasColor ? `\x1b[36m${s}\x1b[0m` : s,
+  yellow:s => hasColor ? `\x1b[33m${s}\x1b[0m` : s,
+  dim:   s => hasColor ? `\x1b[2m${s}\x1b[0m`  : s,
+  red:   s => hasColor ? `\x1b[31m${s}\x1b[0m` : s,
+};
+
+// ─── Args ────────────────────────────────────────────────────────────────────
+// argv: node  install.js  copilot-context  [target-dir]  [--force]
+const userArgs  = process.argv.slice(3);
+const force     = userArgs.includes('--force') || userArgs.includes('-f');
+const targetArg = userArgs.find(a => !a.startsWith('-'));
+const TARGET    = targetArg ? path.resolve(targetArg) : process.cwd();
+
+// ─── Source paths (inside the npm package, sibling of bin/) ─────────────────
+const PKG_ROOT    = path.resolve(__dirname, '..');
+
+const SRC_INSTRUCT = path.join(PKG_ROOT, '.github', 'copilot-instructions.md');
+const SRC_CONTEXT  = path.join(PKG_ROOT, '.github', 'copilot-context');
+const SRC_PLANNING = path.join(PKG_ROOT, '.planning');
+const SRC_VSCODE   = path.join(PKG_ROOT, '.vscode', 'settings.json');
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+}
+
+/** Copy a single file; returns 'copied' | 'skipped' | 'overwritten' */
+function copyFile(src, dest) {
+  ensureDir(path.dirname(dest));
+  const exists = fs.existsSync(dest);
+  if (exists && !force) return 'skipped';
+  fs.copyFileSync(src, dest);
+  return exists ? 'overwritten' : 'copied';
+}
+
+/** Recursively copy a directory tree; collect status for each file */
+function copyDir(src, dest, results = []) {
+  ensureDir(dest);
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, entry.name);
+    const d = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(s, d, results);
+    } else {
+      results.push({ dest: d, status: copyFile(s, d) });
+    }
+  }
+  return results;
+}
+
+function rel(p) {
+  return path.relative(TARGET, p);
+}
+
+// ─── Pretty print ────────────────────────────────────────────────────────────
+
+function printResult(results) {
+  let copied = 0, skipped = 0, overwritten = 0;
+  for (const { dest, status } of results) {
+    if (status === 'copied')      { copied++;      console.log(`  ${c.green('+')} ${rel(dest)}`); }
+    if (status === 'overwritten') { overwritten++;  console.log(`  ${c.yellow('~')} ${rel(dest)}`); }
+    if (status === 'skipped')     { skipped++;     console.log(`  ${c.dim('·')} ${rel(dest)} ${c.dim('(skipped)')}`); }
+  }
+  return { copied, skipped, overwritten };
+}
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+console.log('');
+console.log(c.bold('GSD Copilot Context') + c.dim(' — installing into:'));
+console.log(c.cyan(TARGET));
+console.log('');
+
+if (force) console.log(c.yellow('--force: existing files will be overwritten') + '\n');
+
+const results = [];
+
+// 1. copilot-instructions.md
+if (fs.existsSync(SRC_INSTRUCT)) {
+  const dest   = path.join(TARGET, '.github', 'copilot-instructions.md');
+  const status = copyFile(SRC_INSTRUCT, dest);
+  results.push({ dest, status });
+} else {
+  console.error(c.red('Error: source not found: ' + SRC_INSTRUCT));
+  process.exit(1);
+}
+
+// 2. .github/copilot-context/
+if (fs.existsSync(SRC_CONTEXT)) {
+  const destDir = path.join(TARGET, '.github', 'copilot-context');
+  copyDir(SRC_CONTEXT, destDir, results);
+} else {
+  console.error(c.red('Error: source not found: ' + SRC_CONTEXT));
+  process.exit(1);
+}
+
+// 3. .planning/
+if (fs.existsSync(SRC_PLANNING)) {
+  const destDir = path.join(TARGET, '.planning');
+  copyDir(SRC_PLANNING, destDir, results);
+} else {
+  console.error(c.red('Error: source not found: ' + SRC_PLANNING));
+  process.exit(1);
+}
+
+// 4. .vscode/settings.json — merge-aware
+const destVscode = path.join(TARGET, '.vscode', 'settings.json');
+if (fs.existsSync(SRC_VSCODE)) {
+  if (fs.existsSync(destVscode) && !force) {
+    // Existing settings.json — print merge instructions instead of overwriting
+    results.push({ dest: destVscode, status: 'skipped' });
+    console.log(
+      c.yellow('\nNote:') +
+      ' .vscode/settings.json already exists.\n' +
+      'To enable Copilot custom paths, merge these keys into your settings.json:\n'
+    );
+    try {
+      const src = JSON.parse(fs.readFileSync(SRC_VSCODE, 'utf8'));
+      for (const [k, v] of Object.entries(src)) {
+        console.log(`  ${c.cyan(JSON.stringify(k))}: ${JSON.stringify(v)}`);
+      }
+    } catch (_) {
+      console.log(fs.readFileSync(SRC_VSCODE, 'utf8'));
+    }
+    console.log('');
+  } else {
+    const status = copyFile(SRC_VSCODE, destVscode);
+    results.push({ dest: destVscode, status });
+  }
+}
+
+// ─── Summary ─────────────────────────────────────────────────────────────────
+
+console.log(c.bold('Files:'));
+const totals = printResult(results);
+console.log('');
+console.log(
+  c.green(`✓ Done`) + '  ' +
+  `${totals.copied} copied, ${totals.skipped} skipped, ${totals.overwritten} overwritten`
+);
+console.log('');
+console.log(c.dim('Next steps:'));
+console.log(c.dim('  1. Fill in .planning/PROJECT.md with your project description'));
+console.log(c.dim('  2. Run /map-codebase in GitHub Copilot Chat to analyse your codebase'));
+console.log(c.dim('  3. Run /new-project to initialise .planning/ docs for a new project'));
+console.log(c.dim('  See: .github/copilot-context/README.md'));
+console.log('');

package/commands/gsd/add-phase.md

@@ -0,0 +1,43 @@
+---
+name: gsd:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+Routes to the add-phase workflow which handles:
+- Phase number calculation (next sequential integer)
+- Directory creation with slug generation
+- Roadmap structure updates
+- STATE.md roadmap evolution tracking
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/add-phase.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (phase description)
+
+Roadmap and state are resolved in-workflow via `init phase-op` and targeted tool calls.
+</context>
+
+<process>
+**Follow the add-phase workflow** from `@~/.claude/get-shit-done/workflows/add-phase.md`.
+
+The workflow handles all logic including:
+1. Argument parsing and validation
+2. Roadmap existence checking
+3. Current milestone identification
+4. Next phase number calculation (ignoring decimals)
+5. Slug generation from description
+6. Phase directory creation
+7. Roadmap entry insertion
+8. STATE.md updates
+</process>

package/commands/gsd/add-tests.md

@@ -0,0 +1,41 @@
+---
+name: gsd:add-tests
+description: Generate tests for a completed phase based on UAT criteria and implementation
+argument-hint: "<phase> [additional instructions]"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+argument-instructions: |
+  Parse the argument as a phase number (integer, decimal, or letter-suffix), plus optional free-text instructions.
+  Example: /gsd:add-tests 12
+  Example: /gsd:add-tests 12 focus on edge cases in the pricing module
+---
+<objective>
+Generate unit and E2E tests for a completed phase, using its SUMMARY.md, CONTEXT.md, and VERIFICATION.md as specifications.
+
+Analyzes implementation files, classifies them into TDD (unit), E2E (browser), or Skip categories, presents a test plan for user approval, then generates tests following RED-GREEN conventions.
+
+Output: Test files committed with message `test(phase-{N}): add unit and E2E tests from add-tests command`
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/add-tests.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/STATE.md
+@.planning/ROADMAP.md
+</context>
+
+<process>
+Execute the add-tests workflow from @~/.claude/get-shit-done/workflows/add-tests.md end-to-end.
+Preserve all workflow gates (classification approval, test plan approval, RED-GREEN verification, gap reporting).
+</process>

package/commands/gsd/add-todo.md

@@ -0,0 +1,47 @@
+---
+name: gsd:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a GSD session as a structured todo for later work.
+
+Routes to the add-todo workflow which handles:
+- Directory structure creation
+- Content extraction from arguments or conversation
+- Area inference from file paths
+- Duplicate detection and resolution
+- Todo file creation with frontmatter
+- STATE.md updates
+- Git commits
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/add-todo.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional todo description)
+
+State is resolved in-workflow via `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the add-todo workflow** from `@~/.claude/get-shit-done/workflows/add-todo.md`.
+
+The workflow handles all logic including:
+1. Directory ensuring
+2. Existing area checking
+3. Content extraction (arguments or conversation)
+4. Area inference
+5. Duplicate checking
+6. File creation with slug generation
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/gsd/audit-milestone.md

@@ -0,0 +1,36 @@
+---
+name: gsd:audit-milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/audit-milestone.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+Core planning files are resolved in-workflow (`init milestone-op`) and loaded only as needed.
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+Execute the audit-milestone workflow from @~/.claude/get-shit-done/workflows/audit-milestone.md end-to-end.
+Preserve all workflow gates (scope determination, verification reading, integration check, requirements coverage, routing).
+</process>

package/commands/gsd/check-todos.md

@@ -0,0 +1,45 @@
+---
+name: gsd:check-todos
+description: List pending todos and select one to work on
+argument-hint: [area filter]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+List all pending todos, allow selection, load full context for the selected todo, and route to appropriate action.
+
+Routes to the check-todos workflow which handles:
+- Todo counting and listing with area filtering
+- Interactive selection with full context loading
+- Roadmap correlation checking
+- Action routing (work now, add to phase, brainstorm, create phase)
+- STATE.md updates and git commits
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/check-todos.md
+</execution_context>
+
+<context>
+Arguments: $ARGUMENTS (optional area filter)
+
+Todo state and roadmap correlation are loaded in-workflow using `init todos` and targeted reads.
+</context>
+
+<process>
+**Follow the check-todos workflow** from `@~/.claude/get-shit-done/workflows/check-todos.md`.
+
+The workflow handles all logic including:
+1. Todo existence checking
+2. Area filtering
+3. Interactive listing and selection
+4. Full context loading with file summaries
+5. Roadmap correlation checking
+6. Action offering and execution
+7. STATE.md updates
+8. Git commits
+</process>

package/commands/gsd/cleanup.md

@@ -0,0 +1,18 @@
+---
+name: gsd:cleanup
+description: Archive accumulated phase directories from completed milestones
+---
+<objective>
+Archive phase directories from completed milestones into `.planning/milestones/v{X.Y}-phases/`.
+
+Use when `.planning/phases/` has accumulated directories from past milestones.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/cleanup.md
+</execution_context>
+
+<process>
+Follow the cleanup workflow at @~/.claude/get-shit-done/workflows/cleanup.md.
+Identify completed milestones, show a dry-run summary, and archive on confirmation.
+</process>

package/commands/gsd/complete-milestone.md

@@ -0,0 +1,136 @@
+---
+type: prompt
+name: gsd:complete-milestone
+description: Archive completed milestone and prepare for next version
+argument-hint: <version>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
+
+Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
+Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
+</objective>
+
+<execution_context>
+**Load these files NOW (before proceeding):**
+
+- @~/.claude/get-shit-done/workflows/complete-milestone.md (main workflow)
+- @~/.claude/get-shit-done/templates/milestone-archive.md (archive template)
+  </execution_context>
+
+<context>
+**Project files:**
+- `.planning/ROADMAP.md`
+- `.planning/REQUIREMENTS.md`
+- `.planning/STATE.md`
+- `.planning/PROJECT.md`
+
+**User input:**
+
+- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
+  </context>
+
+<process>
+
+**Follow complete-milestone.md workflow:**
+
+0. **Check for audit:**
+
+   - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
+   - If missing or stale: recommend `/gsd:audit-milestone` first
+   - If audit status is `gaps_found`: recommend `/gsd:plan-milestone-gaps` first
+   - If audit status is `passed`: proceed to step 1
+
+   ```markdown
+   ## Pre-flight Check
+
+   {If no v{{version}}-MILESTONE-AUDIT.md:}
+   ⚠ No milestone audit found. Run `/gsd:audit-milestone` first to verify
+   requirements coverage, cross-phase integration, and E2E flows.
+
+   {If audit has gaps:}
+   ⚠ Milestone audit found gaps. Run `/gsd:plan-milestone-gaps` to create
+   phases that close the gaps, or proceed anyway to accept as tech debt.
+
+   {If audit passed:}
+   ✓ Milestone audit passed. Proceeding with completion.
+   ```
+
+1. **Verify readiness:**
+
+   - Check all phases in milestone have completed plans (SUMMARY.md exists)
+   - Present milestone scope and stats
+   - Wait for confirmation
+
+2. **Gather stats:**
+
+   - Count phases, plans, tasks
+   - Calculate git range, file changes, LOC
+   - Extract timeline from git log
+   - Present summary, confirm
+
+3. **Extract accomplishments:**
+
+   - Read all phase SUMMARY.md files in milestone range
+   - Extract 4-6 key accomplishments
+   - Present for approval
+
+4. **Archive milestone:**
+
+   - Create `.planning/milestones/v{{version}}-ROADMAP.md`
+   - Extract full phase details from ROADMAP.md
+   - Fill milestone-archive.md template
+   - Update ROADMAP.md to one-line summary with link
+
+5. **Archive requirements:**
+
+   - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+   - Mark all v1 requirements as complete (checkboxes checked)
+   - Note requirement outcomes (validated, adjusted, dropped)
+   - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
+
+6. **Update PROJECT.md:**
+
+   - Add "Current State" section with shipped version
+   - Add "Next Milestone Goals" section
+   - Archive previous content in `<details>` (if v1.1+)
+
+7. **Commit and tag:**
+
+   - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
+   - Commit: `chore: archive v{{version}} milestone`
+   - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
+   - Ask about pushing tag
+
+8. **Offer next steps:**
+   - `/gsd:new-milestone` — start next milestone (questioning → research → requirements → roadmap)
+
+</process>
+
+<success_criteria>
+
+- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
+- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
+- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
+- ROADMAP.md collapsed to one-line entry
+- PROJECT.md updated with current state
+- Git tag v{{version}} created
+- Commit successful
+- User knows next steps (including need for fresh requirements)
+  </success_criteria>
+
+<critical_rules>
+
+- **Load workflow first:** Read complete-milestone.md before executing
+- **Verify completion:** All phases must have SUMMARY.md files
+- **User confirmation:** Wait for approval at verification gates
+- **Archive before deleting:** Always create archive files before updating/deleting originals
+- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
+- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
+- **Fresh requirements:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition
+  </critical_rules>