317 lines
8.6 KiB
Markdown
317 lines
8.6 KiB
Markdown
<purpose>
|
|
Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .planning/codebase/
|
|
|
|
Each agent has fresh context, explores a specific focus area, and **writes documents directly**. The orchestrator only receives confirmation + line counts, then writes a summary.
|
|
|
|
Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
|
|
</purpose>
|
|
|
|
<philosophy>
|
|
**Why dedicated mapper agents:**
|
|
- Fresh context per domain (no token contamination)
|
|
- Agents write documents directly (no context transfer back to orchestrator)
|
|
- Orchestrator only summarizes what was created (minimal context usage)
|
|
- Faster execution (agents run simultaneously)
|
|
|
|
**Document quality over length:**
|
|
Include enough detail to be useful as reference. Prioritize practical examples (especially code patterns) over arbitrary brevity.
|
|
|
|
**Always include file paths:**
|
|
Documents are reference material for OpenCode when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
|
|
</philosophy>
|
|
|
|
<process>
|
|
|
|
<step name="init_context" priority="first">
|
|
Load codebase mapping context:
|
|
|
|
```bash
|
|
INIT=$(node "./.opencode/get-shit-done/bin/gsd-tools.cjs" init map-codebase)
|
|
if [[ "$INIT" == @file:* ]]; then INIT=$(cat "${INIT#@file:}"); fi
|
|
```
|
|
|
|
Extract from init JSON: `mapper_model`, `commit_docs`, `codebase_dir`, `existing_maps`, `has_maps`, `codebase_dir_exists`.
|
|
</step>
|
|
|
|
<step name="check_existing">
|
|
Check if .planning/codebase/ already exists using `has_maps` from init context.
|
|
|
|
If `codebase_dir_exists` is true:
|
|
```bash
|
|
ls -la .planning/codebase/
|
|
```
|
|
|
|
**If exists:**
|
|
|
|
```
|
|
.planning/codebase/ already exists with these documents:
|
|
[List files found]
|
|
|
|
What's next?
|
|
1. Refresh - Delete existing and remap codebase
|
|
2. Update - Keep existing, only update specific documents
|
|
3. Skip - Use existing codebase map as-is
|
|
```
|
|
|
|
Wait for user response.
|
|
|
|
If "Refresh": Delete .planning/codebase/, continue to create_structure
|
|
If "Update": Ask which documents to update, continue to spawn_agents (filtered)
|
|
If "Skip": Exit workflow
|
|
|
|
**If doesn't exist:**
|
|
Continue to create_structure.
|
|
</step>
|
|
|
|
<step name="create_structure">
|
|
Create .planning/codebase/ directory:
|
|
|
|
```bash
|
|
mkdir -p .planning/codebase
|
|
```
|
|
|
|
**Expected output files:**
|
|
- STACK.md (from tech mapper)
|
|
- INTEGRATIONS.md (from tech mapper)
|
|
- ARCHITECTURE.md (from arch mapper)
|
|
- STRUCTURE.md (from arch mapper)
|
|
- CONVENTIONS.md (from quality mapper)
|
|
- TESTING.md (from quality mapper)
|
|
- CONCERNS.md (from concerns mapper)
|
|
|
|
Continue to spawn_agents.
|
|
</step>
|
|
|
|
<step name="spawn_agents">
|
|
Spawn 4 parallel gsd-codebase-mapper agents.
|
|
|
|
Use task tool with `subagent_type="gsd-codebase-mapper"`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
|
|
|
|
**CRITICAL:** Use the dedicated `gsd-codebase-mapper` agent, NOT `Explore`. The mapper agent writes documents directly.
|
|
|
|
**Agent 1: Tech Focus**
|
|
|
|
```
|
|
task(
|
|
subagent_type="gsd-codebase-mapper",
|
|
model="{mapper_model}",
|
|
run_in_background=true,
|
|
description="Map codebase tech stack",
|
|
prompt="Focus: tech
|
|
|
|
Analyze this codebase for technology stack and external integrations.
|
|
|
|
write these documents to .planning/codebase/:
|
|
- STACK.md - Languages, runtime, frameworks, dependencies, configuration
|
|
- INTEGRATIONS.md - External APIs, databases, auth providers, webhooks
|
|
|
|
Explore thoroughly. write documents directly using templates. Return confirmation only."
|
|
)
|
|
```
|
|
|
|
**Agent 2: Architecture Focus**
|
|
|
|
```
|
|
task(
|
|
subagent_type="gsd-codebase-mapper",
|
|
model="{mapper_model}",
|
|
run_in_background=true,
|
|
description="Map codebase architecture",
|
|
prompt="Focus: arch
|
|
|
|
Analyze this codebase architecture and directory structure.
|
|
|
|
write these documents to .planning/codebase/:
|
|
- ARCHITECTURE.md - Pattern, layers, data flow, abstractions, entry points
|
|
- STRUCTURE.md - Directory layout, key locations, naming conventions
|
|
|
|
Explore thoroughly. write documents directly using templates. Return confirmation only."
|
|
)
|
|
```
|
|
|
|
**Agent 3: Quality Focus**
|
|
|
|
```
|
|
task(
|
|
subagent_type="gsd-codebase-mapper",
|
|
model="{mapper_model}",
|
|
run_in_background=true,
|
|
description="Map codebase conventions",
|
|
prompt="Focus: quality
|
|
|
|
Analyze this codebase for coding conventions and testing patterns.
|
|
|
|
write these documents to .planning/codebase/:
|
|
- CONVENTIONS.md - Code style, naming, patterns, error handling
|
|
- TESTING.md - Framework, structure, mocking, coverage
|
|
|
|
Explore thoroughly. write documents directly using templates. Return confirmation only."
|
|
)
|
|
```
|
|
|
|
**Agent 4: Concerns Focus**
|
|
|
|
```
|
|
task(
|
|
subagent_type="gsd-codebase-mapper",
|
|
model="{mapper_model}",
|
|
run_in_background=true,
|
|
description="Map codebase concerns",
|
|
prompt="Focus: concerns
|
|
|
|
Analyze this codebase for technical debt, known issues, and areas of concern.
|
|
|
|
write this document to .planning/codebase/:
|
|
- CONCERNS.md - Tech debt, bugs, security, performance, fragile areas
|
|
|
|
Explore thoroughly. write document directly using template. Return confirmation only."
|
|
)
|
|
```
|
|
|
|
Continue to collect_confirmations.
|
|
</step>
|
|
|
|
<step name="collect_confirmations">
|
|
Wait for all 4 agents to complete.
|
|
|
|
read each agent's output file to collect confirmations.
|
|
|
|
**Expected confirmation format from each agent:**
|
|
```
|
|
## Mapping Complete
|
|
|
|
**Focus:** {focus}
|
|
**Documents written:**
|
|
- `.planning/codebase/{DOC1}.md` ({N} lines)
|
|
- `.planning/codebase/{DOC2}.md` ({N} lines)
|
|
|
|
Ready for orchestrator summary.
|
|
```
|
|
|
|
**What you receive:** Just file paths and line counts. NOT document contents.
|
|
|
|
If any agent failed, note the failure and continue with successful documents.
|
|
|
|
Continue to verify_output.
|
|
</step>
|
|
|
|
<step name="verify_output">
|
|
Verify all documents created successfully:
|
|
|
|
```bash
|
|
ls -la .planning/codebase/
|
|
wc -l .planning/codebase/*.md
|
|
```
|
|
|
|
**Verification checklist:**
|
|
- All 7 documents exist
|
|
- No empty documents (each should have >20 lines)
|
|
|
|
If any documents missing or empty, note which agents may have failed.
|
|
|
|
Continue to scan_for_secrets.
|
|
</step>
|
|
|
|
<step name="scan_for_secrets">
|
|
**CRITICAL SECURITY CHECK:** Scan output files for accidentally leaked secrets before committing.
|
|
|
|
Run secret pattern detection:
|
|
|
|
```bash
|
|
# Check for common API key patterns in generated docs
|
|
grep -E '(sk-[a-zA-Z0-9]{20,}|sk_live_[a-zA-Z0-9]+|sk_test_[a-zA-Z0-9]+|ghp_[a-zA-Z0-9]{36}|gho_[a-zA-Z0-9]{36}|glpat-[a-zA-Z0-9_-]+|AKIA[A-Z0-9]{16}|xox[baprs]-[a-zA-Z0-9-]+|-----BEGIN.*PRIVATE KEY|eyJ[a-zA-Z0-9_-]+\.eyJ[a-zA-Z0-9_-]+\.)' .planning/codebase/*.md 2>/dev/null && SECRETS_FOUND=true || SECRETS_FOUND=false
|
|
```
|
|
|
|
**If SECRETS_FOUND=true:**
|
|
|
|
```
|
|
⚠️ SECURITY ALERT: Potential secrets detected in codebase documents!
|
|
|
|
Found patterns that look like API keys or tokens in:
|
|
[show grep output]
|
|
|
|
This would expose credentials if committed.
|
|
|
|
**Action required:**
|
|
1. Review the flagged content above
|
|
2. If these are real secrets, they must be removed before committing
|
|
3. Consider adding sensitive files to OpenCode "Deny" permissions
|
|
|
|
Pausing before commit. Reply "safe to proceed" if the flagged content is not actually sensitive, or edit the files first.
|
|
```
|
|
|
|
Wait for user confirmation before continuing to commit_codebase_map.
|
|
|
|
**If SECRETS_FOUND=false:**
|
|
|
|
Continue to commit_codebase_map.
|
|
</step>
|
|
|
|
<step name="commit_codebase_map">
|
|
Commit the codebase map:
|
|
|
|
```bash
|
|
node "./.opencode/get-shit-done/bin/gsd-tools.cjs" commit "docs: map existing codebase" --files .planning/codebase/*.md
|
|
```
|
|
|
|
Continue to offer_next.
|
|
</step>
|
|
|
|
<step name="offer_next">
|
|
Present completion summary and next steps.
|
|
|
|
**Get line counts:**
|
|
```bash
|
|
wc -l .planning/codebase/*.md
|
|
```
|
|
|
|
**Output format:**
|
|
|
|
```
|
|
Codebase mapping complete.
|
|
|
|
Created .planning/codebase/:
|
|
- STACK.md ([N] lines) - Technologies and dependencies
|
|
- ARCHITECTURE.md ([N] lines) - System design and patterns
|
|
- STRUCTURE.md ([N] lines) - Directory layout and organization
|
|
- CONVENTIONS.md ([N] lines) - Code style and patterns
|
|
- TESTING.md ([N] lines) - Test structure and practices
|
|
- INTEGRATIONS.md ([N] lines) - External services and APIs
|
|
- CONCERNS.md ([N] lines) - Technical debt and issues
|
|
|
|
|
|
---
|
|
|
|
## ▶ Next Up
|
|
|
|
**Initialize project** — use codebase context for planning
|
|
|
|
`/gsd-new-project`
|
|
|
|
*`/new` first → fresh context window*
|
|
|
|
---
|
|
|
|
**Also available:**
|
|
- Re-run mapping: `/gsd-map-codebase`
|
|
- Review specific file: `cat .planning/codebase/STACK.md`
|
|
- edit any document before proceeding
|
|
|
|
---
|
|
```
|
|
|
|
End workflow.
|
|
</step>
|
|
|
|
</process>
|
|
|
|
<success_criteria>
|
|
- .planning/codebase/ directory created
|
|
- 4 parallel gsd-codebase-mapper agents spawned with run_in_background=true
|
|
- Agents write documents directly (orchestrator doesn't receive document contents)
|
|
- read agent output files to collect confirmations
|
|
- All 7 codebase documents exist
|
|
- Clear completion summary with line counts
|
|
- User offered clear next steps in GSD style
|
|
</success_criteria>
|