ctx-cc 3.4.0 → 3.4.2

package/workflows/ctx-router.md

@@ -0,0 +1,324 @@
+<purpose>
+Smart router for CTX - understands natural language, detects intent, and routes to the right workflow.
+
+Users don't need to memorize commands. They describe what they want, CTX routes automatically.
+</purpose>
+
+<ui_reference>
+@~/.claude/ctx/references/ui-brand.md
+</ui_reference>
+
+<intent_detection>
+Parse the user's message to detect intent. Check patterns in order:
+
+| Pattern | Intent | Action |
+|---------|--------|--------|
+| "build", "create", "make", "start new", "I want to..." + "app/project/feature" | new-project | Route to init flow |
+| "fix", "bug", "broken", "not working", "error", "crash", "fails" | debug | Route to debug flow |
+| "test", "QA", "check", "accessible", "works?", "validate" | qa | Route to QA flow |
+| "study", "analyze", "understand", "learn", "explore", "what is this", "deeply study" | analyze | Route to map-codebase flow |
+| "improve", "optimize", "better", "enhance", "upgrade", "refactor" | improve | Analyze + suggest improvements |
+| "review", "audit", "security", "ready", "before deploy" | review | Verify flow |
+| "deploy", "ship", "publish", "release", "push", "launch" | ship | Ship flow |
+| "status", "progress", "where", "what's next", "current" | status | Status report |
+| "help", "how", "what can", "commands", "guide" | help | Show help |
+| "continue", "next", "go", "do it" | continue | Read STATE.md and continue |
+
+Store detected intent for routing.
+</intent_detection>
+
+<process>
+
+<step name="verify_ctx_structure" priority="first">
+**MANDATORY FIRST STEP - Execute before anything else:**
+
+```bash
+test -d .ctx && echo "exists" || echo "missing"
+```
+
+Store result:
+- If "exists": CTX is initialized, load state
+- If "missing": CTX not initialized, may need setup
+</step>
+
+<step name="detect_intent">
+Parse user message and detect intent using patterns above.
+
+Output detected intent for routing decision.
+</step>
+
+<step name="route_no_ctx">
+**If NO .ctx/ folder (new user):**
+
+Route by detected intent:
+
+### Intent: new-project
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{{user_request}}"
+
+You want to build something new. Let's set it up!
+
+───────────────────────────────────────────────────────
+```
+
+Execute /ctx:init inline (don't tell user to run it separately).
+
+### Intent: analyze (study/explore)
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► ANALYZING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{{user_request}}"
+
+Let me analyze this codebase with 4 specialized mappers.
+
+───────────────────────────────────────────────────────
+```
+
+**Step 1: Create structure**
+
+```bash
+mkdir -p .ctx/codebase
+```
+
+**Step 2: Show spawning indicator**
+
+Output:
+```
+◆ Spawning 4 mappers in parallel...
+  → ctx-tech-mapper
+  → ctx-arch-mapper
+  → ctx-quality-mapper
+  → ctx-concerns-mapper
+```
+
+**Step 3: Spawn 4 mapper agents in parallel**
+
+Read model profile (default to "balanced"):
+```bash
+MODEL_PROFILE="haiku"
+```
+
+Spawn all 4 agents with a SINGLE message containing multiple Task calls:
+
+```
+Task(prompt="Analyze this codebase for technology stack. Write comprehensive analysis to: .ctx/codebase/TECH.md. Include languages, frameworks, dependencies, versions, build tools. Return confirmation with line count when complete.", subagent_type="ctx-tech-mapper", model="haiku", run_in_background=true, description="Map tech stack")
+
+Task(prompt="Analyze this codebase architecture. Write comprehensive analysis to: .ctx/codebase/ARCH.md. Include architectural pattern, layer structure, module boundaries, entry points, data flow. Return confirmation with line count when complete.", subagent_type="ctx-arch-mapper", model="haiku", run_in_background=true, description="Map architecture")
+
+Task(prompt="Analyze this codebase for quality patterns. Write comprehensive analysis to: .ctx/codebase/QUALITY.md. Include test coverage, linting, type safety, documentation, code smells. Return confirmation with line count when complete.", subagent_type="ctx-quality-mapper", model="haiku", run_in_background=true, description="Map quality")
+
+Task(prompt="Analyze this codebase for concerns and risks. Write comprehensive analysis to: .ctx/codebase/CONCERNS.md. Include security issues, technical debt, performance problems, operational risks. Return confirmation with line count when complete.", subagent_type="ctx-concerns-mapper", model="haiku", run_in_background=true, description="Map concerns")
+```
+
+**Step 4: Wait for completion and show progress**
+
+Use TaskOutput to wait for each agent. As each completes, output:
+
+```
+✓ ctx-tech-mapper complete: TECH.md ({{N}} lines)
+✓ ctx-arch-mapper complete: ARCH.md ({{N}} lines)
+✓ ctx-quality-mapper complete: QUALITY.md ({{N}} lines)
+✓ ctx-concerns-mapper complete: CONCERNS.md ({{N}} lines)
+```
+
+**Step 5: Verify output**
+
+```bash
+ls -la .ctx/codebase/
+wc -l .ctx/codebase/*.md
+```
+
+**Step 6: Create summary**
+
+Read all 4 documents:
+```bash
+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` with key findings from each document.
+
+**Step 7: Show completion banner**
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► MAPPING COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         {{primary_language}}, {{framework}} │
+│  Architecture: {{pattern}}                          │
+│  Quality:      {{coverage}}% coverage, {{warnings}} │
+│  Concerns:     {{concern_count}} identified         │
+└─────────────────────────────────────────────────────┘
+
+Files created:
+  .ctx/codebase/TECH.md
+  .ctx/codebase/ARCH.md
+  .ctx/codebase/QUALITY.md
+  .ctx/codebase/CONCERNS.md
+  .ctx/codebase/SUMMARY.md
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Initialize project** — set up CTX workflow with this context
+
+`/ctx:init`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- `cat .ctx/codebase/SUMMARY.md` — view full summary
+- `/ctx:map-codebase --refresh` — re-analyze codebase
+
+───────────────────────────────────────────────────────
+```
+
+### Intent: debug
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► DEBUG MODE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{{problem_description}}"
+
+Let me analyze the codebase first, then investigate.
+
+───────────────────────────────────────────────────────
+```
+
+First map codebase (same as analyze), then spawn debugger agent.
+
+### Intent: help or unknown
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+What would you like to do?
+
+┌─────────────────────────────────────────────────────┐
+│  AVAILABLE ACTIONS                                  │
+├─────────────────────────────────────────────────────┤
+│  "Build something new"   → Set up your project      │
+│  "Fix a bug"             → Debug the issue          │
+│  "Study the codebase"    → Analyze everything       │
+│  "Test the app"          → Run full QA              │
+└─────────────────────────────────────────────────────┘
+
+Just describe what you want in natural language!
+
+───────────────────────────────────────────────────────
+```
+</step>
+
+<step name="route_with_ctx">
+**If .ctx/ folder EXISTS:**
+
+### Load state first
+
+```bash
+cat .ctx/STATE.md
+cat .ctx/config.json 2>/dev/null || echo "{}"
+```
+
+Extract:
+- `status`: Current workflow status
+- `currentPhase`: Active phase
+- `profile`: Model profile (quality/balanced/budget)
+
+### Route by Intent + State
+
+| Intent | Action |
+|--------|--------|
+| new-project | Warn project exists, offer to add phase |
+| analyze | Run map-codebase (refresh) |
+| debug | Spawn debugger with context |
+| qa | Spawn QA agent |
+| status | Show status from STATE.md |
+| continue | Resume from STATE.md status |
+
+### Status Report Format
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project: {{name}}
+Status:  {{status}}
+Profile: {{profile}}
+
+Progress: ████████░░ {{percent}}%
+
+| Phase | Status | Tasks    |
+|-------|--------|----------|
+| 1     | ✓      | 5/5      |
+| 2     | ◆      | 2/4      |
+| 3     | ○      | 0/3      |
+
+Current: {{current_phase}}
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{{next_action}}**
+
+`/ctx` or describe what you want to do
+
+───────────────────────────────────────────────────────
+```
+</step>
+
+</process>
+
+<research_integration>
+**When to use ArguSeek:**
+
+For debug, improve, and review intents, research BEFORE spawning agents:
+
+```
+mcp__arguseek__research_iteratively({
+  query: "{{tech_stack}} {{problem_or_goal}} best practices solutions 2025"
+})
+```
+
+Include research findings in agent prompts.
+</research_integration>
+
+<success_criteria>
+- [ ] .ctx structure checked first
+- [ ] Intent detected from user message
+- [ ] Correct flow routed
+- [ ] UI patterns used consistently (banners, boxes, progress)
+- [ ] ArguSeek called for research-worthy intents
+- [ ] Task() agents spawned with full context
+- [ ] STATE.md created/updated
+- [ ] Clear "Next Up" shown with command
+- [ ] User knows to run /ctx to continue
+</success_criteria>

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>