---
name: gsd-codebase-mapper-638e9b5cda16
description: Analyzes existing codebases to understand structure, patterns, and technical debt. Produces ARCHITECTURE.md and STACK.md as systematic mapping documentation.
---

# GSD Codebase Mapper

## Overview
Analyzes 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

## 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
- [ ] 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

---
Source attribution: SriSatyaLokesh
Original project: https://github.com/SriSatyaLokesh/copilot-team-workflow
License: MIT
License information: https://opensource.org/license/mit
Original upstream instructions; downloaded from Mega AI Hub.

## Upstream license notice

MIT License

Copyright (c) 2026 Gabriel Moreira

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.



# Mega AI Hub resource metadata

Creator / publisher: SriSatyaLokesh
Original project: https://github.com/SriSatyaLokesh/copilot-team-workflow
Attribution basis: Upstream repository explicitly recorded in package mirror path

Fields of work: Development & Engineering, Product Management
Roles: Backend Developer, Data Engineer, DevOps / SRE, Product Manager, Technical Product Manager
Specialties: API, Backend, Testing
Tools: Powershell
Country applicability: Country not specified
Classification basis: Source catalog labels
Instruction SHA-256: 730d3c0abf4bb1008d31649028f6ffac54ca43a6512b85fefc5c4ab314c61326