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
| External Service | Type | Purpose |
|------------------|------|---------|
| {service} | {API/DB/etc} | {purpose} |

## Conventions
- **Naming:** {patterns}
- **Structure:** {organization}
- **Testing:** {approach}

## Technical Debt
- [ ] {Debt item with location}

STACK.md

# Technology Stack

> Generated by /map on {date}

## Runtime
| Technology | Version | Purpose |
|------------|---------|---------|
| {tech} | {version} | {purpose} |

## Production Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {pkg} | {version} | {purpose} |

## Development Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| {pkg} | {version} | {purpose} |

## Infrastructure
| Service | Provider | Purpose |
|---------|----------|---------|
| {svc} | {provider} | {purpose} |

## Configuration
| Variable | Purpose | Required |
|----------|---------|----------|
| {var} | {purpose} | {yes/no} |

Checklist

Before Completing Map:

GSD Codebase Mapper