Add configurable codebase map options via preferences.md (exclude_patterns,
max_files, collapse_threshold), expose --collapse-threshold as a CLI flag,
and auto-generate CODEBASE.md during project init for instant agent orientation.
Closes#3509
Generator (codebase-generator.ts):
- Fix truncation off-by-one: use filtered.length > maxFiles (not >=)
- Fix collapsed-directory round-trip: emit <!-- gsd:collapsed-descriptions -->
comment blocks so incremental updates recover descriptions for collapsed dirs
- Fix double-enumeration race in updateCodebaseMap: reuse files array from
generateCodebaseMap instead of calling enumerateFiles a second time
- Propagate truncated flag through updateCodebaseMap return type
- Fix getCodebaseMapStats to read Files: N from header (accurate for collapsed dirs)
- Remove redundant dead catch around lsFiles() in enumerateFiles
- parseCodebaseMap: use else-if for bare match (avoid unnecessary double-check)
- parseCodebaseMap: scan gsd:collapsed-descriptions comment blocks
Command handler (commands-codebase.ts):
- Bare /gsd codebase now shows stats (if map exists) or help (if no map)
instead of silently running generate
- Add explicit help subcommand with info-level output
- Guard update: warn if no CODEBASE.md exists instead of silently generating
- Validate --max-files: reject NaN, zero, and negative values with clear message
- Emit warning (not success) when generate produces 0 files
- Propagate truncated flag warning in both generate and update output
- Fix extractFlag regex: escape flag name and support --flag=value syntax
- Add actionable tip to stats output
Catalog (commands/catalog.ts):
- Add --max-files and help to codebase tab-completion entries
System context (bootstrap/system-context.ts):
- Cap CODEBASE.md injection at 8 000 chars (~2 000 tokens) per request
- Add generation timestamp and staleness notice to the injected block header
Paths (paths.ts):
- Fix LEGACY_GSD_ROOT_FILES.CODEBASE to use lowercase codebase.md (matches
the pattern of all other legacy root file names)
Tests (codebase-generator.test.ts):
- 15 new test cases: custom excludePatterns, collapseThreshold option,
truncation boundary conditions (below/at/above limit), non-git directory,
empty repo, collapsed-description round-trip, removed file tracking,
binary/lock exclusions, truncated flag propagation, collapsed-dir stats
accuracy, .gsd/ auto-creation, corrupted input, parseCodebaseMap comment blocks
- Fix collapse assertion to verify individual entries are absent from main body
- Fix git rm test to commit first so git rm succeeds
- 29/29 tests passing
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Add /gsd codebase command that generates .gsd/CODEBASE.md — a table of
contents for the project giving agents instant structural awareness.
Eliminates the 10-30+ tool call "exploration tax" that fresh agent
contexts pay to understand what exists and where things live.
Components:
- codebase-generator.ts: walks git ls-files, groups by directory,
renders with one-liner descriptions, supports incremental updates
that preserve existing descriptions
- commands-codebase.ts: CLI handler (generate, update, stats)
- system-context.ts: injects CODEBASE.md into system prompt at
session start (alongside KNOWLEDGE.md)
- paths.ts: adds CODEBASE to GSD_ROOT_FILES
- catalog.ts: registers command with nested completions
Features:
- Incremental update preserves agent-written descriptions
- Directories with >20 files collapsed to summary
- Token budget: ~2-4K for 100 files, scaling to ~20K for 500
- Configurable excludes and max file count
Closes#2229
14 unit tests, all passing.
