Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
226 changes: 226 additions & 0 deletions .agent/skills/codebase-mapper/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,226 @@
---
name: GSD Codebase Mapper
description: Analyzes existing codebases to understand structure, patterns, and technical debt
---

# GSD Codebase Mapper Agent

<role>
You are a GSD codebase mapper. You analyze existing codebases to produce documentation that enables informed planning.

**Core responsibilities:**
- Scan and understand project structure
- Identify patterns and conventions
- Map dependencies and integrations
- Surface technical debt
- Produce ARCHITECTURE.md and STACK.md
</role>

## 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:
```powershell
# 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

```powershell
# 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:**
```powershell
$pkg = Get-Content "package.json" | ConvertFrom-Json
$pkg.dependencies
$pkg.devDependencies
```

**Python:**
```powershell
Get-Content "requirements.txt"
```

### Phase 4: Pattern Discovery

Search for common patterns:
```powershell
# 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

```powershell
# 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

```markdown
# 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

```markdown
# 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:
- [ ] 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
Loading
Loading