ctx-cc 3.4.0 → 3.4.1

package/workflows/map-codebase.md

@@ -0,0 +1,329 @@
+<purpose>
+Orchestrate parallel codebase mapper agents to analyze codebase and produce structured documents in .ctx/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: .ctx/codebase/ folder with 4 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 Claude when planning/executing. Always include actual file paths formatted with backticks: `src/services/user.ts`.
+</philosophy>
+
+<process>
+
+<step name="resolve_model_profile" priority="first">
+Read model profile for agent spawning:
+
+```bash
+MODEL_PROFILE=$(cat .ctx/config.json 2>/dev/null | grep -o '"profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")
+```
+
+Default to "balanced" if not set.
+
+**Model lookup table:**
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| ctx-*-mapper | sonnet | haiku | haiku |
+
+Store resolved model for use in Task calls below.
+</step>
+
+<step name="check_existing">
+Check if .ctx/codebase/ already exists:
+
+```bash
+ls -la .ctx/codebase/ 2>/dev/null
+```
+
+**If exists:**
+
+```
+.ctx/codebase/ already exists with these documents:
+[List files found]
+
+What's next?
+1. Refresh - Delete existing and remap codebase
+2. Skip - Use existing codebase map as-is
+```
+
+Wait for user response.
+
+If "Refresh": Delete .ctx/codebase/, continue to create_structure
+If "Skip": Exit workflow
+
+**If doesn't exist:**
+Continue to create_structure.
+</step>
+
+<step name="create_structure">
+Create .ctx/codebase/ directory:
+
+```bash
+mkdir -p .ctx/codebase
+```
+
+**Expected output files:**
+- TECH.md (from ctx-tech-mapper)
+- ARCH.md (from ctx-arch-mapper)
+- QUALITY.md (from ctx-quality-mapper)
+- CONCERNS.md (from ctx-concerns-mapper)
+
+Continue to spawn_agents.
+</step>
+
+<step name="spawn_agents">
+Spawn 4 parallel ctx-*-mapper agents.
+
+Use Task tool with the appropriate `subagent_type`, `model="{mapper_model}"`, and `run_in_background=true` for parallel execution.
+
+**CRITICAL:** Use the dedicated mapper agents. The mapper agent writes documents directly.
+
+**Agent 1: Tech Focus**
+
+Task tool parameters:
+```
+subagent_type: "ctx-tech-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase tech stack"
+```
+
+Prompt:
+```
+Analyze this codebase for technology stack.
+
+Write comprehensive analysis to: .ctx/codebase/TECH.md
+
+Include:
+- Languages and their proportions
+- Frameworks and libraries
+- Dependencies and versions
+- Build tools and scripts
+- Runtime requirements
+
+Return confirmation with line count when complete.
+```
+
+**Agent 2: Architecture Focus**
+
+Task tool parameters:
+```
+subagent_type: "ctx-arch-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase architecture"
+```
+
+Prompt:
+```
+Analyze this codebase architecture.
+
+Write comprehensive analysis to: .ctx/codebase/ARCH.md
+
+Include:
+- Architectural pattern (MVC, hexagonal, etc.)
+- Layer structure
+- Module boundaries
+- Entry points
+- Data flow patterns
+
+Return confirmation with line count when complete.
+```
+
+**Agent 3: Quality Focus**
+
+Task tool parameters:
+```
+subagent_type: "ctx-quality-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase quality"
+```
+
+Prompt:
+```
+Analyze this codebase for quality patterns.
+
+Write comprehensive analysis to: .ctx/codebase/QUALITY.md
+
+Include:
+- Test coverage and patterns
+- Linting and formatting status
+- Type safety
+- Documentation coverage
+- Code smells
+
+Return confirmation with line count when complete.
+```
+
+**Agent 4: Concerns Focus**
+
+Task tool parameters:
+```
+subagent_type: "ctx-concerns-mapper"
+model: "{mapper_model}"
+run_in_background: true
+description: "Map codebase concerns"
+```
+
+Prompt:
+```
+Analyze this codebase for concerns and risks.
+
+Write comprehensive analysis to: .ctx/codebase/CONCERNS.md
+
+Include:
+- Security vulnerabilities
+- Technical debt
+- Performance issues
+- Operational risks
+- Compliance gaps
+
+Return confirmation with line count when complete.
+```
+
+Continue to collect_confirmations.
+</step>
+
+<step name="collect_confirmations">
+Wait for all 4 agents to complete using TaskOutput.
+
+Read each agent's output to collect confirmations.
+
+**Expected confirmation format from each agent:**
+```
+## Mapping Complete
+
+**Focus:** {focus}
+**Document written:**
+- `.ctx/codebase/{DOC}.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 .ctx/codebase/
+wc -l .ctx/codebase/*.md
+```
+
+**Verification checklist:**
+- All 4 documents exist
+- No empty documents (each should have >20 lines)
+
+If any documents missing or empty, note which agents may have failed.
+
+Continue to create_summary.
+</step>
+
+<step name="create_summary">
+Create SUMMARY.md by reading and synthesizing the 4 documents:
+
+```bash
+# Read each document for synthesis
+cat .ctx/codebase/TECH.md
+cat .ctx/codebase/ARCH.md
+cat .ctx/codebase/QUALITY.md
+cat .ctx/codebase/CONCERNS.md
+```
+
+Write `.ctx/codebase/SUMMARY.md`:
+
+```markdown
+# Codebase Summary
+
+## Tech Stack
+{Key findings from TECH.md}
+
+## Architecture
+{Key findings from ARCH.md}
+
+## Quality
+{Key findings from QUALITY.md}
+
+## Concerns
+{Top 3-5 concerns from CONCERNS.md}
+
+## Recommendations
+1. {Most important action}
+2. {Second priority}
+3. {Third priority}
+```
+
+Continue to offer_next.
+</step>
+
+<step name="offer_next">
+Present completion summary and next steps.
+
+**Get line counts:**
+```bash
+wc -l .ctx/codebase/*.md
+```
+
+**Output format:**
+
+```
+Codebase mapping complete.
+
+Created .ctx/codebase/:
+- TECH.md ([N] lines) - Technologies and dependencies
+- ARCH.md ([N] lines) - System design and patterns
+- QUALITY.md ([N] lines) - Code quality assessment
+- CONCERNS.md ([N] lines) - Technical debt and issues
+- SUMMARY.md ([N] lines) - Executive summary
+
+
+---
+
+## Next Up
+
+**Initialize project** - use codebase context for planning
+
+/ctx:init
+
+---
+
+**Also available:**
+- Re-run mapping: /ctx:map-codebase --refresh
+- Review specific file: cat .ctx/codebase/TECH.md
+
+---
+```
+
+End workflow.
+</step>
+
+</process>
+
+<success_criteria>
+- .ctx/codebase/ directory created
+- 4 parallel mapper agents spawned with run_in_background=true
+- Agents write documents directly (orchestrator doesn't receive document contents)
+- Use TaskOutput to wait for agent completion
+- All 4 codebase documents exist
+- SUMMARY.md created with synthesis
+- Clear completion summary with line counts
+- User offered clear next steps
+</success_criteria>