e6e32da224
* test(#3561): failing-first coverage for the --fast dangling dispatch /gsd-map-codebase --fast routes to "the scan workflow" in prose, but commands/gsd/map-codebase.md names no resolvable path and its execution_context includes only map-codebase.md, so scan.md is never loaded. Same class as epic #1891's F8/F9: dispatch keyed on a token that never arrives. Adds workflowPathRefs() to command-contract-helpers.cjs — one shared pure resolver for the three reference shapes this repo uses (eager @-include, lazy absolute-ish path, lazy parent-relative steps//modes/ path). Placing it in the helpers module keeps the lint script and the test suite reading the same definition, which is what that module exists for; #3560 consumes the same function rather than re-deriving it. Tests 16/17 are RED until the routing fix lands. Refs #3561 * fix(#3561): route --fast to a scan.md path the runtime can resolve commands/gsd/map-codebase.md documented --fast and told the agent to "run the scan workflow", but named no path and included only map-codebase.md in execution_context, so gsd-core/workflows/scan.md was never loaded and the single-agent scan was improvised. Names the path in the routing line so it is read on demand, rather than adding an eager @-include: --fast is the minority path and the progressive-disclosure split (#717) exists to keep the common full-map invocation from paying for it. The accompanying test pins that choice — execution_context must still carry exactly one @-ref. skills/gsd-map-codebase/SKILL.md is regenerated, not hand-edited. Closes #3561 * fix(#3561): bound the .md match and bind the regression test to the --fast line Two majors from the isolated adversarial review. Both resolver regexes ended at a literal .md with no trailing boundary, so a longer extension was truncated into a plausible-looking but wrong path: workflows/foobar.mdx returned workflows/foobar.md. Adds a (?![A-Za-z0-9_]) lookahead to both shapes so .mdx and .md5 are rejected outright rather than silently rewritten. The regression test scanned the whole command file, so it did not bind to the defect — the reviewer showed that an unrelated comment mentioning scan.md anywhere made it pass while the dispatch defect was still present. It now extracts the "- If it is `--fast`" bullet and scans that line alone, and a new test drives a synthetic pre-fix fixture to prove the false-pass path is closed. Refs #3561 * chore(#3561): backfill changeset pr number to 3562 --------- Co-authored-by: sim <sim@local>
84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
---
|
|
name: gsd:map-codebase
|
|
description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
|
|
argument-hint: "[--fast [--focus tech|arch|quality|concerns]] [--query <term>|status|diff|refresh] [area]"
|
|
allowed-tools:
|
|
- Read
|
|
- Bash
|
|
- Glob
|
|
- Grep
|
|
- Write
|
|
- Agent
|
|
requires: [config, new-project, plan-phase, onboard]
|
|
---
|
|
|
|
<objective>
|
|
Analyze existing codebase using parallel gsd-codebase-mapper agents to produce structured codebase documents.
|
|
|
|
Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
|
|
|
|
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
|
|
</objective>
|
|
|
|
<execution_context>
|
|
@~/.claude/gsd-core/workflows/map-codebase.md
|
|
</execution_context>
|
|
|
|
<flags>
|
|
- **--fast**: Lightweight scan mode — spawns one mapper agent instead of four. Accepts an optional `--focus` value: `tech`, `arch`, `quality`, `concerns`, or `tech+arch` (default). Faster and lower-context than the full map.
|
|
- **--query**: Codebase intelligence query mode. Sub-commands: `query <term>`, `status`, `diff`, `refresh`. Requires intel to be enabled in config (`intel.enabled: true`). Runs inline for query/status/diff; spawns an agent for refresh.
|
|
- **(no flag)**: Full parallel map — spawns 4 mapper agents to produce all 7 codebase documents.
|
|
</flags>
|
|
|
|
<context>
|
|
Arguments: $ARGUMENTS
|
|
|
|
Parse the first token of $ARGUMENTS:
|
|
- If it is `--fast`: strip the flag, then read and execute `~/.claude/gsd-core/workflows/scan.md` (passing remaining args including optional --focus). Load it on demand here — it is deliberately not in `<execution_context>`, so the common full-map path does not pay for it.
|
|
- If it is `--query`: strip the flag, run the intel workflow (passing remaining args as the subcommand).
|
|
- Otherwise: pass all of $ARGUMENTS as focus area to the map-codebase workflow.
|
|
|
|
**Load project state if exists:**
|
|
Check for .planning/STATE.md - loads context if project already initialized
|
|
|
|
**This command can run:**
|
|
- Via /gsd:onboard for first-time brownfield setup - creates codebase map first
|
|
- After /gsd:new-project (greenfield codebases) - updates codebase map as code evolves
|
|
- Anytime to refresh codebase understanding
|
|
</context>
|
|
|
|
<when_to_use>
|
|
**Use map-codebase for:**
|
|
- Brownfield projects before initialization (understand existing code first)
|
|
- Refreshing codebase map after significant changes
|
|
- Refreshing or deepening an onboarded codebase map
|
|
- Before major refactoring (understand current state)
|
|
- When STATE.md references outdated codebase info
|
|
|
|
**Skip map-codebase for:**
|
|
- Greenfield projects with no code yet (nothing to map)
|
|
- Trivial codebases (<5 files)
|
|
</when_to_use>
|
|
|
|
<process>
|
|
1. Check if .planning/codebase/ already exists (offer to refresh or skip)
|
|
2. Create .planning/codebase/ directory structure
|
|
3. Spawn 4 parallel gsd-codebase-mapper agents:
|
|
- Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
|
|
- Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
|
|
- Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
|
|
- Agent 4: concerns focus → writes CONCERNS.md
|
|
4. Wait for agents to complete, collect confirmations (NOT document contents)
|
|
5. Verify all 7 documents exist with line counts
|
|
6. Commit codebase map
|
|
7. Offer next steps (typically: /gsd:onboard, /gsd:new-project, or /gsd:plan-phase)
|
|
</process>
|
|
|
|
<success_criteria>
|
|
- [ ] .planning/codebase/ directory created
|
|
- [ ] All 7 codebase documents written by mapper agents
|
|
- [ ] Documents follow template structure
|
|
- [ ] Parallel agents completed without errors
|
|
- [ ] User knows next steps
|
|
</success_criteria>
|