feat(commands): add /gsd-scan for rapid single-focus codebase assessment (#1808)

Lightweight alternative to /gsd-map-codebase that spawns a single
mapper agent for one focus area instead of four parallel agents.
Supports --focus flag with 5 options: tech, arch, quality, concerns,
and tech+arch (default). Checks for existing documents and prompts
before overwriting.

Closes #1733

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

commands/gsd/scan.md

@@ -0,0 +1,26 @@
+---
+name: gsd:scan
+description: Rapid codebase assessment — lightweight alternative to /gsd-map-codebase
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Grep
+  - Glob
+  - Agent
+  - AskUserQuestion
+---
+<objective>
+Run a focused codebase scan for a single area, producing targeted documents in `.planning/codebase/`.
+Accepts an optional `--focus` flag: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default).
+
+Lightweight alternative to `/gsd-map-codebase` — spawns one mapper agent instead of four parallel ones.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/scan.md
+</execution_context>
+
+<process>
+Execute the scan workflow from @~/.claude/get-shit-done/workflows/scan.md end-to-end.
+</process>

get-shit-done/workflows/scan.md

@@ -0,0 +1,102 @@
+<purpose>
+Lightweight codebase assessment. Spawns a single gsd-codebase-mapper agent for one focus area,
+producing targeted documents in `.planning/codebase/`.
+</purpose>
+
+<required_reading>
+Read all files referenced by the invoking prompt's execution_context before starting.
+</required_reading>
+
+<available_agent_types>
+Valid GSD subagent types (use exact names — do not fall back to 'general-purpose'):
+- gsd-codebase-mapper — Maps project structure and dependencies
+</available_agent_types>
+
+<process>
+
+## Focus-to-Document Mapping
+
+| Focus | Documents Produced |
+|-------|-------------------|
+| `tech` | STACK.md, INTEGRATIONS.md |
+| `arch` | ARCHITECTURE.md, STRUCTURE.md |
+| `quality` | CONVENTIONS.md, TESTING.md |
+| `concerns` | CONCERNS.md |
+| `tech+arch` | STACK.md, INTEGRATIONS.md, ARCHITECTURE.md, STRUCTURE.md |
+
+## Step 1: Parse arguments and resolve focus
+
+Parse the user's input for `--focus <area>`. Default to `tech+arch` if not specified.
+
+Validate that the focus is one of: `tech`, `arch`, `quality`, `concerns`, `tech+arch`.
+
+If invalid:
+```
+Unknown focus area: "{input}". Valid options: tech, arch, quality, concerns, tech+arch
+```
+Exit.
+
+## Step 2: Check for existing documents
+
+```bash
+INIT=$(node "$HOME/.claude/get-shit-done/bin/gsd-tools.cjs" init map-codebase 2>/dev/null || echo "{}")
+if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
+```
+
+Look up which documents would be produced for the selected focus (from the mapping table above).
+
+For each target document, check if it already exists in `.planning/codebase/`:
+```bash
+ls -la .planning/codebase/{DOCUMENT}.md 2>/dev/null
+```
+
+If any exist, show their modification dates and ask:
+```
+Existing documents found:
+  - STACK.md (modified 2026-04-03)
+  - INTEGRATIONS.md (modified 2026-04-01)
+
+Overwrite with fresh scan? [y/N]
+```
+
+If user says no, exit.
+
+## Step 3: Create output directory
+
+```bash
+mkdir -p .planning/codebase
+```
+
+## Step 4: Spawn mapper agent
+
+Spawn a single `gsd-codebase-mapper` agent with the selected focus area:
+
+```
+Task(
+  prompt="Scan this codebase with focus: {focus}. Write results to .planning/codebase/. Produce only: {document_list}",
+  subagent_type="gsd-codebase-mapper",
+  model="{resolved_model}"
+)
+```
+
+## Step 5: Report
+
+```
+## Scan Complete
+
+**Focus:** {focus}
+**Documents produced:**
+{list of documents written with line counts}
+
+Use `/gsd-map-codebase` for a comprehensive 4-area parallel scan.
+```
+
+</process>
+
+<success_criteria>
+- [ ] Focus area correctly parsed (default: tech+arch)
+- [ ] Existing documents detected with modification dates shown
+- [ ] User prompted before overwriting
+- [ ] Single mapper agent spawned with correct focus
+- [ ] Output documents written to .planning/codebase/
+</success_criteria>

tests/scan-command.test.cjs

@@ -0,0 +1,52 @@
+const { describe, test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('fs');
+const path = require('path');
+
+describe('scan command', () => {
+  test('command file exists with correct name and description', () => {
+    const p = path.join(__dirname, '..', 'commands', 'gsd', 'scan.md');
+    assert.ok(fs.existsSync(p), 'commands/gsd/scan.md should exist');
+    const content = fs.readFileSync(p, 'utf-8');
+    assert.ok(content.includes('name: gsd:scan'), 'Command must have name: gsd:scan');
+    assert.ok(content.includes('description:'), 'Command must have description frontmatter');
+    assert.ok(content.includes('Rapid codebase assessment') || content.includes('lightweight alternative'),
+      'Description should mention rapid/lightweight assessment');
+  });
+
+  test('workflow file exists', () => {
+    const p = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'scan.md');
+    assert.ok(fs.existsSync(p), 'get-shit-done/workflows/scan.md should exist');
+  });
+
+  test('workflow has focus-to-document mapping table', () => {
+    const p = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'scan.md');
+    const content = fs.readFileSync(p, 'utf-8');
+    assert.ok(content.includes('Focus-to-Document Mapping') || content.includes('Focus | Documents'),
+      'Workflow should contain a focus-to-document mapping table');
+  });
+
+  test('all 5 focus areas are documented', () => {
+    const p = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'scan.md');
+    const content = fs.readFileSync(p, 'utf-8');
+    const focusAreas = ['tech', 'arch', 'quality', 'concerns', 'tech+arch'];
+    for (const area of focusAreas) {
+      assert.ok(content.includes(`\`${area}\``),
+        `Workflow should document the "${area}" focus area`);
+    }
+  });
+
+  test('overwrite prompt is mentioned', () => {
+    const p = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'scan.md');
+    const content = fs.readFileSync(p, 'utf-8');
+    assert.ok(content.includes('Overwrite') || content.includes('overwrite'),
+      'Workflow should mention overwrite prompt for existing documents');
+  });
+
+  test('workflow references gsd-codebase-mapper', () => {
+    const p = path.join(__dirname, '..', 'get-shit-done', 'workflows', 'scan.md');
+    const content = fs.readFileSync(p, 'utf-8');
+    assert.ok(content.includes('gsd-codebase-mapper'),
+      'Workflow should reference the gsd-codebase-mapper agent');
+  });
+});