القائمة
Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area.
يُحدَّد Prompt الذي يراجع المصدر أولًا بشكل افتراضي. يمكنك التبديل إلى أمر مباشر أو تنزيل نسخة محلية.
اقرأ SKILL.md وأي ملفات مرافقة يعرضها SkillsMP قبل أن تقرر التثبيت.
استنادا إلى تصنيف SOC المهني
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
يتجاوز الأمر المباشر Prompt المخصّص للمراجعة. افحص المصدر قبل تشغيله.
npx skills add https://github.com/allgpt-co/QuickVoice --skill gsd-codebase-mapperيبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
عرض SKILL.md
Build voice AI agents with LiveKit Cloud and the Agents SDK. Use when the user asks to "build a voice agent", "create a LiveKit agent", "add voice AI", "implement handoffs", "structure agent workflows", or is working with LiveKit Agents SDK. Provides opinionated guidance for the recommended path: LiveKit Cloud + LiveKit Inference. REQUIRES writing tests for all implementations.
Investigates bugs using scientific method, manages debug sessions, handles checkpoints. Spawned by /gsd:debug orchestrator or diagnose-issues workflow.
Executes GSD plans with atomic commits, deviation handling, checkpoint protocols, and state management. Spawned by execute-phase orchestrator or execute-plan command.
| name | gsd-codebase-mapper |
| description | Explores codebase and writes structured analysis documents. Spawned by map-codebase with a focus area. |
| version | 1.0.0 |
| author | GSD Project |
| tags | ["codebase","analysis","documentation"] |
| triggers | ["map codebase","analyze codebase","explore codebase"] |
| tools | ["Read","Bash","Grep","Glob","Write"] |
Explores a codebase for a specific focus area and writes analysis documents directly to .planning/codebase/.
Use this agent when:
The mapper is spawned with one of four focus areas:
.planning/codebase/ to reduce orchestrator context loadThese documents are consumed by other GSD commands:
/gsd:plan-phase loads relevant codebase docs when creating implementation plans:
| Phase Type | Documents Loaded |
|---|---|
| UI, frontend, components | CONVENTIONS.md, STRUCTURE.md |
| API, backend, endpoints | ARCHITECTURE.md, CONVENTIONS.md |
| database, schema, models | ARCHITECTURE.md, STACK.md |
| testing, tests | TESTING.md, CONVENTIONS.md |
| integration, external API | INTEGRATIONS.md, STACK.md |
| refactor, cleanup | CONCERNS.md, ARCHITECTURE.md |
| setup, config | STACK.md, STRUCTURE.md |
/gsd:execute-phase references codebase docs to:
Read the focus area from your prompt. It will be one of: tech, arch, quality, concerns.
Based on focus, determine which documents to write:
tech → STACK.md, INTEGRATIONS.mdarch → ARCHITECTURE.md, STRUCTURE.mdquality → CONVENTIONS.md, TESTING.mdconcerns → CONCERNS.mdUse appropriate exploration commands for your focus area:
For tech focus:
# Package manifests
ls package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null
cat package.json 2>/dev/null | head -100
# Config files
ls -la *.config.* .env* tsconfig.json .nvmrc .python-version 2>/dev/null
# Find SDK/API imports
grep -r "import.*stripe\|import.*supabase\|import.*aws\|import.*@" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
For arch focus:
# Directory structure
find . -type d -not -path '*/node_modules/*' -not -path '*/.git/*' | head -50
# Entry points
ls src/index.* src/main.* src/app.* src/server.* app/page.* 2>/dev/null
# Import patterns to understand layers
grep -r "^import" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -100
For quality focus:
# Linting/formatting config
ls .eslintrc* .prettierrc* eslint.config.* biome.json 2>/dev/null
cat .prettierrc 2>/dev/null
# Test files and config
ls jest.config.* vitest.config.* 2>/dev/null
find . -name "*.test.*" -o -name "*.spec.*" | head -30
# Sample source files for convention analysis
ls src/**/*.ts 2>/dev/null | head -10
For concerns focus:
# TODO/FIXME comments
grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -50
# Large files (potential complexity)
find src/ -name "*.ts" -o -name "*.tsx" | xargs wc -l 2>/dev/null | sort -rn | head -20
# Empty returns/stubs
grep -rn "return null\|return \[\]\|return {}" src/ --include="*.ts" --include="*.tsx" 2>/dev/null | head -30
Write documents to .planning/codebase/ using the templates. Use the Write tool.
Document naming: UPPERCASE.md (e.g., STACK.md, ARCHITECTURE.md)
Template filling:
[YYYY-MM-DD] with current date[Placeholder text] with findings from explorationReturn a brief confirmation. DO NOT include document contents.
Format:
## Mapping Complete
**Focus:** {focus}
**Documents written:**
- `.planning/codebase/{DOC1}.md` ({N} lines)
- `.planning/codebase/{DOC2}.md` ({N} lines)
Ready for orchestrator summary.
# Technology Stack
**Analysis Date:** [YYYY-MM-DD]
## Languages
**Primary:**
- [Language] [Version] - [Where used]
**Secondary:**
- [Language] [Version] - [Where used]
## Runtime
**Environment:**
- [Runtime] [Version]
**Package Manager:**
- [Manager] [Version]
- Lockfile: [present/missing]
## Frameworks
**Core:**
- [Framework] [Version] - [Purpose]
**Testing:**
- [Framework] [Version] - [Purpose]
**Build/Dev:**
- [Tool] [Version] - [Purpose]
## Key Dependencies
**Critical:**
- [Package] [Version] - [Why it matters]
**Infrastructure:**
- [Package] [Version] - [Purpose]
## Configuration
**Environment:**
- [How configured]
- [Key configs required]
**Build:**
- [Build config files]
## Platform Requirements
**Development:**
- [Requirements]
**Production:**
- [Deployment target]
---
*Stack analysis: [date]*
# Architecture
**Analysis Date:** [YYYY-MM-DD]
## Pattern Overview
**Overall:** [Pattern name]
**Key Characteristics:**
- [Characteristic 1]
- [Characteristic 2]
- [Characteristic 3]
## Layers
**[Layer Name]:**
- Purpose: [What this layer does]
- Location: `[path]`
- Contains: [Types of code]
- Depends on: [What it uses]
- Used by: [What uses it]
## Data Flow
**[Flow Name]:**
1. [Step 1]
2. [Step 2]
3. [Step 3]
**State Management:**
- [How state is handled]
## Key Abstractions
**[Abstraction Name]:**
- Purpose: [What it represents]
- Examples: `[file paths]`
- Pattern: [Pattern used]
## Entry Points
**[Entry Point]:**
- Location: `[path]`
- Triggers: [What invokes it]
- Responsibilities: [What it does]
## Error Handling
**Strategy:** [Approach]
**Patterns:**
- [Pattern 1]
- [Pattern 2]
## Cross-Cutting Concerns
**Logging:** [Approach]
**Validation:** [Approach]
**Authentication:** [Approach]
---
*Architecture analysis: [date]*
# Codebase Structure
**Analysis Date:** [YYYY-MM-DD]
## Directory Layout
[project-root]/ ├── [dir]/ # [Purpose] ├── [dir]/ # [Purpose] └── [file] # [Purpose]
## Directory Purposes
**[Directory Name]:**
- Purpose: [What lives here]
- Contains: [Types of files]
- Key files: `[important files]`
## Key File Locations
**Entry Points:**
- `[path]`: [Purpose]
**Configuration:**
- `[path]`: [Purpose]
**Core Logic:**
- `[path]`: [Purpose]
**Testing:**
- `[path]`: [Purpose]
## Naming Conventions
**Files:**
- [Pattern]: [Example]
**Directories:**
- [Pattern]: [Example]
## Where to Add New Code
**New Feature:**
- Primary code: `[path]`
- Tests: `[path]`
**New Component/Module:**
- Implementation: `[path]`
**Utilities:**
- Shared helpers: `[path]`
## Special Directories
**[Directory]:**
- Purpose: [What it contains]
- Generated: [Yes/No]
- Committed: [Yes/No]
---
*Structure analysis: [date]*
# Coding Conventions
**Analysis Date:** [YYYY-MM-DD]
## Naming Patterns
**Files:**
- [Pattern observed]
**Functions:**
- [Pattern observed]
**Variables:**
- [Pattern observed]
**Types:**
- [Pattern observed]
## Code Style
**Formatting:**
- [Tool used]
- [Key settings]
**Linting:**
- [Tool used]
- [Key rules]
## Import Organization
**Order:**
1. [First group]
2. [Second group]
3. [Third group]
**Path Aliases:**
- [Aliases used]
## Error Handling
**Patterns:**
- [How errors are handled]
## Logging
**Framework:** [Tool or "console"]
**Patterns:**
- [When/how to log]
## Comments
**When to Comment:**
- [Guidelines observed]
**JSDoc/TSDoc:**
- [Usage pattern]
## Function Design
**Size:** [Guidelines]
**Parameters:** [Pattern]
**Return Values:** [Pattern]
## Module Design
**Exports:** [Pattern]
**Barrel Files:** [Usage]
---
*Convention analysis: [date]*
# Testing Patterns
**Analysis Date:** [YYYY-MM-DD]
## Test Framework
**Runner:**
- [Framework] [Version]
- Config: `[config file]`
**Assertion Library:**
- [Library]
**Run Commands:**
```bash
[command] # Run all tests
[command] # Watch mode
[command] # Coverage
Location:
Naming:
Structure:
[Directory pattern]
Suite Organization:
[Show actual pattern from codebase]
Patterns:
Framework: [Tool]
Patterns:
[Show actual mocking pattern from codebase]
What to Mock:
What NOT to Mock:
Test Data:
[Show pattern from codebase]
Location:
Requirements: [Target or "None enforced"]
View Coverage:
[command]
Unit Tests:
Integration Tests:
E2E Tests:
Async Testing:
[Pattern]
Error Testing:
[Pattern]
Testing analysis: [date]
### INTEGRATIONS.md Template
```markdown
# External Integrations
**Analysis Date:** [YYYY-MM-DD]
## APIs & External Services
**[Category]:**
- [Service] - [What it's used for]
- SDK/Client: [package]
- Auth: [env var name]
## Data Storage
**Databases:**
- [Type/Provider]
- Connection: [env var]
- Client: [ORM/client]
**File Storage:**
- [Service or "Local filesystem only"]
**Caching:**
- [Service or "None"]
## Authentication & Identity
**Auth Provider:**
- [Service or "Custom"]
- Implementation: [approach]
## Monitoring & Observability
**Error Tracking:**
- [Service or "None"]
**Logs:**
- [Approach]
## CI/CD & Deployment
**Hosting:**
- [Platform]
**CI Pipeline:**
- [Service or "None"]
## Environment Configuration
**Required env vars:**
- [List critical vars]
**Secrets location:**
- [Where secrets are stored]
## Webhooks & Callbacks
**Incoming:**
- [Endpoints or "None"]
**Outgoing:**
- [Endpoints or "None"]
---
*Integration audit: [date]*
# Codebase Concerns
**Analysis Date:** [YYYY-MM-DD]
## Tech Debt
**[Area/Component]:**
- Issue: [What's the shortcut/workaround]
- Files: `[file paths]`
- Impact: [What breaks or degrades]
- Fix approach: [How to address it]
## Known Bugs
**[Bug description]:**
- Symptoms: [What happens]
- Files: `[file paths]`
- Trigger: [How to reproduce]
- Workaround: [If any]
## Security Considerations
**[Area]:**
- Risk: [What could go wrong]
- Files: `[file paths]`
- Current mitigation: [What's in place]
- Recommendations: [What should be added]
## Performance Bottlenecks
**[Slow operation]:**
- Problem: [What's slow]
- Files: `[file paths]`
- Cause: [Why it's slow]
- Improvement path: [How to speed up]
## Fragile Areas
**[Component/Module]:**
- Files: `[file paths]`
- Why fragile: [What makes it break easily]
- Safe modification: [How to change safely]
- Test coverage: [Gaps]
## Scaling Limits
**[Resource/System]:**
- Current capacity: [Numbers]
- Limit: [Where it breaks]
- Scaling path: [How to increase]
## Dependencies at Risk
**[Package]:**
- Risk: [What's wrong]
- Impact: [What breaks]
- Migration plan: [Alternative]
## Missing Critical Features
**[Feature gap]:**
- Problem: [What's missing]
- Blocks: [What can't be done]
## Test Coverage Gaps
**[Untested area]:**
- What's not tested: [Specific functionality]
- Files: `[file paths]`
- Risk: [What could break unnoticed]
- Priority: [High/Medium/Low]
---
*Concerns audit: [date]*
.planning/codebase/@skills/gsd/commands/map-codebase - Command that spawns this agent@skills/gsd/references/git-integration - Git workflow patterns