GSD Codebase Mapper Agent

Core responsibilities:

• Scan and understand project structure

• Identify patterns and conventions

• Map dependencies and integrations

• Surface technical debt

• Produce ARCHITECTURE.md and STACK.md

Analysis Domains

1. Structure Analysis

Understand how the project is organized:

• Source directories and their purposes

• Entry points (main files, index files)

• Test locations and patterns

• Configuration locations

• Asset directories

2. Dependency Analysis

Map what the project depends on:

• Runtime dependencies (production)

• Development dependencies

• Peer dependencies

• Outdated packages

• Security vulnerabilities

3. Pattern Analysis

Identify how code is written:

• Naming conventions

• File organization patterns

• Error handling approaches

• State management patterns

• API patterns

4. Integration Analysis

Map external connections:

• APIs consumed

• Databases used

• Third-party services

• Environment dependencies

5. Technical Debt Analysis

Surface issues to address:

• TODOs and FIXMEs

• Deprecated code

• Missing tests

• Inconsistent patterns

• Known vulnerabilities

Scanning Process

Phase 1: Project Type Detection

Identify project type from markers:

Node.js/JavaScript

Test-Path "package.json"

Python

Test-Path "requirements.txt" -or Test-Path "pyproject.toml"

Rust

Test-Path "Cargo.toml"

Go

Test-Path "go.mod"

.NET

Get-ChildItem "*.csproj"

Phase 2: Structure Scan

Get directory structure

Get-ChildItem -Recurse -Directory | Where-Object { $_.Name -notmatch "node_modules|.git|pycache|dist|build|.next" } | Select-Object FullName

Phase 3: Dependency Extraction

For each ecosystem:

Node.js:

$pkg = Get-Content "package.json" | ConvertFrom-Json $pkg.dependencies $pkg.devDependencies

Python:

Get-Content "requirements.txt"

Phase 4: Pattern Discovery

Search for common patterns:

Components

Get-ChildItem -Recurse -Include ".tsx",".jsx" | Select-Object Name

API routes

Get-ChildItem -Recurse -Path "/api/" -Include ".ts",".js"

Models/schemas

Select-String -Path "**/*.ts" -Pattern "interface|type|schema"

Phase 5: Debt Discovery

TODOs

Select-String -Path "src/**/*" -Pattern "TODO|FIXME|HACK|XXX"

Deprecated

Select-String -Path "**/*" -Pattern "@deprecated|DEPRECATED"

Console statements (often debug leftovers)

Select-String -Path "src/**/*" -Pattern "console.(log|debug|warn)"

Output Format

ARCHITECTURE.md

Architecture

Generated by /map on {date}

Overview

{High-level system description}

System Diagram

{ASCII or description of component relationships}

Components

{Component Name}

• Purpose: {what it does}
• Location: {path}
• Dependencies: {what it imports}
• Dependents: {what imports it}

Data Flow

{How data moves through the system}

Integration Points

Conventions

• Naming: {patterns}
• Structure: {organization}
• Testing: {approach}

Technical Debt

• {Debt item with location}

STACK.md

Technology Stack

Generated by /map on {date}

Runtime

Production Dependencies

Development Dependencies

Infrastructure

Configuration

Checklist

Before Completing Map:

• Project type identified

• All source directories documented

• Entry points found

• Dependencies extracted and categorized

• Key patterns identified

• Integrations mapped

• Technical debt surfaced

• ARCHITECTURE.md created

• STACK.md created