Merge pull request #19 from zeative/staging

feat: introduce agent system with numerous skills and workflows

Author: zeative

.agent/skills/codebase-mapper/SKILL.md

@@ -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