ctx-cc 3.4.0 → 3.4.1

package/commands/ctx.md

@@ -1,6 +1,6 @@
 ---
 name: ctx
-description: Smart router - understands natural language, detects intent, and routes to the right workflow. No commands to memorize.
+description: Smart router - understands natural language, detects intent, and routes to the right workflow.
 allowed-tools:
   - Read
   - Write
@@ -8,6 +8,7 @@ allowed-tools:
   - Glob
   - Grep
   - Task
+  - TaskOutput
   - AskUserQuestion
   - mcp__arguseek__research_iteratively
   - mcp__arguseek__fetch_url
@@ -19,613 +20,42 @@ CTX Smart Router - Conversational-first workflow orchestration.
 **Users don't need to know commands.** They describe what they want, CTX routes automatically.
 
 ```
-User: "I want to build a todo app"     → Routes to init
-User: "Fix the login bug"              → Routes to debug
-User: "Is my app accessible?"          → Routes to QA
-User: "What should I do next?"         → Shows status + routes to next action
+User: "I want to build a todo app"     -> Routes to init
+User: "Fix the login bug"              -> Routes to debug
+User: "Study the codebase"             -> Routes to map-codebase
+User: "What should I do next?"         -> Shows status + routes
 ```
 </objective>
 
-<process>
-
-## Step 0: Verify CTX Structure
-
-**MANDATORY FIRST STEP — Execute before anything else:**
-
-```bash
-test -d .ctx && echo "exists" || echo "missing"
-```
-
-Store result for routing decisions below.
-
-## Step 1: Intent Detection
-
-Parse the user's message to detect intent. This runs BEFORE checking state.
+<execution_context>
+@~/.claude/ctx/workflows/ctx-router.md
+</execution_context>
 
-**Detection rules (check in order):**
+<process>
+1. Check if .ctx/ exists (bash: test -d .ctx)
+2. Detect intent from user message
+3. Route based on intent + ctx state:
+   - No .ctx/ + "build/create" -> /ctx:init
+   - No .ctx/ + "study/analyze" -> spawn 4 mapper agents in parallel
+   - No .ctx/ + "debug/fix" -> map codebase first, then debug
+   - Has .ctx/ + any intent -> load state, route accordingly
+4. Spawn appropriate agents with Task()
+5. Update STATE.md
+6. Show "Next Up" with clear next action
+</process>
 
+<intent_patterns>
 | Pattern | Intent | Route |
 |---------|--------|-------|
-| "build", "create", "make", "start new", "I want to..." + "app/project/feature" | `new-project` | /ctx:init |
-| "fix", "bug", "broken", "not working", "error", "crash", "fails" | `debug` | Debug flow |
-| "test", "QA", "check", "accessible", "works?", "validate" | `qa` | QA flow |
-| "production", "prod ready", "production ready", "make it ready" | `production-ready` | Full audit pipeline |
-| "study", "analyze", "understand", "learn", "explore", "what is this" | `analyze` | Map codebase |
-| "improve", "optimize", "better", "enhance", "upgrade", "refactor" | `improve` | Analyze + suggest |
-| "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` | Help guide |
-| "continue", "next", "go", "do it" | `continue` | Read STATE.md |
-
-State detected intent for routing.
-
-## Step 2: Route Based on CTX Existence + Intent
-
-**If NO .ctx/ folder (new user):**
-
-Route by intent:
-
-### Route A: New Project Intent
-
-If intent = `new-project`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{user_request}}"
-
-You want to build something new. Let's set it up!
-
-Starting project initialization...
-```
-
-Then execute /ctx:init inline (don't tell user to run it separately).
-
-### Route B: Debug/Fix Intent (no .ctx/)
-
-If intent = `debug`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{problem_description}}"
-
-You need to fix something. Let me understand the codebase first.
-```
-
-**Step 1: Map codebase (parallel agents)**
-
-Spawn 4 mapper agents in parallel:
-
-```bash
-mkdir -p .ctx/codebase
-```
-
-```
-Task(prompt="Analyze codebase technology stack. Write findings to .ctx/codebase/TECH.md", subagent_type="ctx-tech-mapper", model="haiku", description="Map tech stack")
-Task(prompt="Analyze codebase architecture. Write findings to .ctx/codebase/ARCH.md", subagent_type="ctx-arch-mapper", model="haiku", description="Map architecture")
-Task(prompt="Analyze code quality patterns. Write findings to .ctx/codebase/QUALITY.md", subagent_type="ctx-quality-mapper", model="haiku", description="Map quality")
-Task(prompt="Identify concerns and tech debt. Write findings to .ctx/codebase/CONCERNS.md", subagent_type="ctx-concerns-mapper", model="haiku", description="Map concerns")
-```
-
-**Step 2: Initialize minimal state**
-
-```bash
-cat > .ctx/STATE.md << 'EOF'
-# CTX State
-
-## Status
-debugging
-
-## Current Focus
-{{problem_description}}
-
-## Context Budget
-5%
-EOF
-```
-
-**Step 3: Route to debug**
-
-Go to **Debug Flow** below.
-
-### Route C: QA Intent (no .ctx/)
-
-If intent = `qa`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{qa_request}}"
-
-You want to test the system. I'll analyze the project first.
-```
-
-Map codebase (same as Route B Step 1), then go to **QA Flow** below.
-
-### Route D: Production-Ready Intent (no .ctx/)
-
-If intent = `production-ready`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{request}}"
-
-I'll audit everything and make it production ready.
-```
-
-Go to **Production-Ready Pipeline** below.
-
-### Route E: Analyze Intent (no .ctx/)
-
-If intent = `analyze`:
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{request}}"
-
-Let me study this codebase.
-```
-
-Go to **Map Codebase Flow** below.
-
-### Route F: Help or Unknown Intent (no .ctx/)
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-What would you like to do?
-
-  "Build something new"  → I'll set up your project
-  "Fix a bug"            → I'll debug the issue
-  "Test the app"         → I'll run full QA
-  "Study the codebase"   → I'll analyze the architecture
-
-Just describe what you want!
-```
-
----
-
-**If .ctx/ folder EXISTS:**
-
-### Step 2.1: Load State
-
-Read current state:
-
-```bash
-cat .ctx/STATE.md
-cat .ctx/config.json 2>/dev/null || echo "{}"
-```
-
-Extract:
-- `status`: Current workflow status
-- `currentStory`: Active story ID
-- `profile`: Model profile (quality/balanced/budget)
-
-### Step 2.2: Route by Intent + State
-
-| Intent | State | Action |
-|--------|-------|--------|
-| `new-project` | any | Warn project exists, offer to add story |
-| `debug` | any | Go to Debug Flow |
-| `qa` | any | Go to QA Flow |
-| `production-ready` | any | Go to Production-Ready Pipeline |
-| `analyze` | any | Go to Map Codebase Flow |
-| `improve` | any | Analyze → suggest improvements |
-| `status` | any | Show status report |
-| `continue` | initializing | Research phase |
-| `continue` | discussing | Discussion phase |
-| `continue` | executing | Execute current task |
-| `continue` | debugging | Resume debug |
-| `continue` | verifying | Run verification |
-| `continue` | paused | Resume from checkpoint |
-
-</process>
-
-<flows>
-
-## Debug Flow
-
-**Step 1: Research the problem with ArguSeek**
-
-```
-mcp__arguseek__research_iteratively({
-  query: "{{problem_description}} {{tech_stack}} common causes solutions"
-})
-```
-
-Store findings in memory.
-
-**Step 2: Spawn debugger agent**
-
-```
-Task(prompt="
-<problem>
-{{problem_description}}
-</problem>
-
-<codebase_context>
-{{.ctx/codebase/TECH.md content}}
-{{.ctx/codebase/ARCH.md content}}
-</codebase_context>
-
-<research_findings>
-{{ArguSeek results}}
-</research_findings>
-
-<instructions>
-1. Analyze the error
-2. Form hypothesis
-3. Apply minimal fix
-4. Verify (build + tests)
-5. If fixed: update STATE.md status to 'executing', commit fix
-6. If not fixed: log attempt, try next hypothesis (max 10 attempts)
-</instructions>
-
-Write debug progress to .ctx/DEBUG.md
-", subagent_type="ctx-debugger", model="sonnet", description="Debug {{problem}}")
-```
-
-**Step 3: Update state and report**
-
-Read debugger output. Update STATE.md:
-
-```bash
-# Update status based on outcome
-```
-
-**Step 4: Show next steps**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[CTX] Debug Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Status: {{fixed | still investigating}}
-Attempts: {{count}}
-Commit: {{hash if fixed}}
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## QA Flow
-
-**Step 1: Research QA best practices**
-
-```
-mcp__arguseek__research_iteratively({
-  query: "{{tech_stack}} E2E testing WCAG 2.1 AA accessibility best practices 2025"
-})
-```
-
-**Step 2: Spawn QA agent**
-
-```
-Task(prompt="
-<codebase_context>
-{{.ctx/codebase/TECH.md content}}
-</codebase_context>
-
-<qa_focus>
-{{qa_request or 'full system QA'}}
-</qa_focus>
-
-<research>
-{{ArguSeek results}}
-</research>
-
-<instructions>
-1. Use Playwright for browser testing
-2. Use stable locators (getByRole, getByText, getByLabel)
-3. Test WCAG 2.1 AA: touch targets 44x44, alt text, form labels, contrast
-4. Test at 3 viewports: mobile (375px), tablet (768px), desktop (1280px)
-5. Capture screenshots of issues
-6. Write QA report to .ctx/QA-REPORT.md
-</instructions>
-", subagent_type="ctx-qa", model="sonnet", description="QA testing")
-```
-
-**Step 3: Report results**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[CTX] QA Complete
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Pages tested: {{count}}
-WCAG 2.1 AA: {{score}}%
-Issues found: {{count}}
-  Critical: {{count}}
-  High: {{count}}
-  Medium: {{count}}
-
-Report: .ctx/QA-REPORT.md
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Production-Ready Pipeline
-
-Full audit for production readiness:
-
-**Step 1: Map codebase (if not already mapped)**
-
-```bash
-test -d .ctx/codebase && echo "mapped" || echo "needs_mapping"
-```
-
-If needs mapping, spawn 4 mapper agents (see Route B above).
-
-**Step 2: Research production requirements**
-
-```
-mcp__arguseek__research_iteratively({
-  query: "{{tech_stack}} production readiness checklist security performance 2025"
-})
-```
-
-**Step 3: Run full QA**
-
-Spawn ctx-qa agent (see QA Flow above).
-
-**Step 4: Security audit**
-
-```
-Task(prompt="
-<codebase>
-{{.ctx/codebase/TECH.md}}
-{{.ctx/codebase/CONCERNS.md}}
-</codebase>
-
-<instructions>
-Audit for:
-- SQL injection
-- XSS vulnerabilities
-- Exposed secrets
-- Auth/authz gaps
-- Input validation
-
-Write report to .ctx/SECURITY-AUDIT.md
-</instructions>
-", subagent_type="ctx-auditor", model="sonnet", description="Security audit")
-```
-
-**Step 5: Performance check**
-
-```
-Task(prompt="
-<codebase>
-{{.ctx/codebase/TECH.md}}
-{{.ctx/codebase/ARCH.md}}
-</codebase>
-
-<instructions>
-Check for:
-- Slow API calls (>500ms)
-- Large assets (>500KB)
-- Missing caching
-- N+1 queries
-- Memory leaks
-
-Write report to .ctx/PERF-AUDIT.md
-</instructions>
-", subagent_type="ctx-reviewer", model="sonnet", description="Performance check")
-```
-
-**Step 6: Create fix tasks**
-
-Read all reports, create prioritized fix list in .ctx/FIX-TASKS.md
-
-**Step 7: Execute fixes**
-
-For each critical/high fix:
-
-```
-Task(prompt="
-<fix>
-{{fix_description}}
-</fix>
-
-<context>
-{{relevant_code}}
-</context>
-
-<instructions>
-1. Apply minimal fix
-2. Verify (build + tests)
-3. Commit with descriptive message
-</instructions>
-", subagent_type="ctx-executor", model="sonnet", description="Fix: {{fix_name}}")
-```
-
-**Step 8: Final verification**
-
-Spawn ctx-verifier for three-level check.
-
-**Step 9: Report**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-PRODUCTION READINESS AUDIT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Codebase Analysis: ✓ Complete
-Full QA: ✓ Complete (WCAG {{score}}%)
-Security Audit: {{status}}
-Performance: {{status}}
-
-Issues Fixed: {{count}}
-Remaining: {{count}}
-
-Production Ready: {{YES | NO - reasons}}
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Map Codebase Flow
-
-**Step 1: Create structure**
-
-```bash
-mkdir -p .ctx/codebase
-```
-
-**Step 2: Spawn 4 mapper agents in parallel**
-
-```
-Task(prompt="
-Analyze the technology stack of this codebase.
-
-Look for:
-- package.json, Cargo.toml, go.mod, requirements.txt, etc.
-- Framework detection (React, Next.js, FastAPI, etc.)
-- Key dependencies and versions
-- Build tools and scripts
-
-Write comprehensive analysis to: .ctx/codebase/TECH.md
-", subagent_type="ctx-tech-mapper", model="haiku", description="Map tech stack")
-
-Task(prompt="
-Analyze the architecture of this codebase.
-
-Look for:
-- Directory structure
-- Entry points
-- Component boundaries
-- Data flow patterns
-- API structure
-
-Write comprehensive analysis to: .ctx/codebase/ARCH.md
-", subagent_type="ctx-arch-mapper", model="haiku", description="Map architecture")
-
-Task(prompt="
-Analyze code quality patterns.
-
-Look for:
-- Testing patterns and coverage
-- Error handling patterns
-- Logging patterns
-- Code style consistency
-- Documentation quality
-
-Write comprehensive analysis to: .ctx/codebase/QUALITY.md
-", subagent_type="ctx-quality-mapper", model="haiku", description="Map quality")
-
-Task(prompt="
-Identify concerns and technical debt.
-
-Look for:
-- TODO/FIXME comments
-- Deprecated dependencies
-- Security concerns
-- Performance bottlenecks
-- Accessibility gaps
-
-Write comprehensive analysis to: .ctx/codebase/CONCERNS.md
-", subagent_type="ctx-concerns-mapper", model="haiku", description="Map concerns")
-```
-
-**Step 3: Synthesize**
-
-After all agents complete, create summary:
-
-```bash
-cat > .ctx/codebase/SUMMARY.md << 'EOF'
-# Codebase Summary
-
-## Tech Stack
-{{from TECH.md}}
-
-## Architecture
-{{from ARCH.md}}
-
-## Quality
-{{from QUALITY.md}}
-
-## Concerns
-{{from CONCERNS.md}}
-EOF
-```
-
-**Step 4: Report**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[CTX] Codebase Mapped
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Tech: {{stack}}
-Architecture: {{pattern}}
-Quality: {{assessment}}
-Concerns: {{count}} identified
-
-Files: .ctx/codebase/
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
----
-
-## Status Report
-
-Read and display current state:
-
-```bash
-cat .ctx/STATE.md
-ls -la .ctx/phases/ 2>/dev/null | wc -l
-```
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-[CTX] Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Project: {{name}}
-Status: {{status}}
-Profile: {{profile}}
-
-Progress: [{{progress_bar}}] {{completed}}/{{total}} stories
-
-Current: {{current_story}}
-Next: {{next_action}}
-
-Context: {{percent}}%
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-</flows>
+| "build", "create", "make", "start new" | new-project | /ctx:init |
+| "fix", "bug", "broken", "error", "crash" | debug | Debug flow |
+| "test", "QA", "check", "accessible" | qa | QA flow |
+| "study", "analyze", "understand", "explore" | analyze | Map codebase |
+| "improve", "optimize", "refactor" | improve | Analyze + suggest |
+| "status", "progress", "what's next" | status | Show status |
+| "help", "how", "commands" | help | Show help |
+| "continue", "next", "go" | continue | Read STATE.md |
+</intent_patterns>
 
 <model_routing>
 Based on config.json profile, use these models for Task() calls:
@@ -633,35 +63,16 @@ Based on config.json profile, use these models for Task() calls:
 | Agent | quality | balanced | budget |
 |-------|---------|----------|--------|
 | Mappers | sonnet | haiku | haiku |
-| Researcher | opus | sonnet | sonnet |
-| Discusser | opus | sonnet | sonnet |
-| Planner | opus | sonnet | sonnet |
-| Executor | opus | sonnet | sonnet |
 | Debugger | opus | sonnet | sonnet |
 | QA | sonnet | sonnet | haiku |
-| Verifier | sonnet | haiku | haiku |
+| Executor | opus | sonnet | sonnet |
 </model_routing>
 
-<state_transitions>
-```
-initializing → discussing (after research)
-discussing → executing (after decisions locked)
-executing → debugging (if verification fails)
-executing → verifying (if all tasks done)
-debugging → executing (if fix works)
-debugging → ESCALATE (if max attempts fail)
-verifying → debugging (if any check fails)
-verifying → COMPLETE (if ALL pass 100%)
-paused → (previous state)
-```
-</state_transitions>
-
 <success_criteria>
 - [ ] Intent detected from user message
 - [ ] Correct flow routed
 - [ ] ArguSeek called for research (when applicable)
 - [ ] Task() agents spawned with full context
 - [ ] STATE.md updated after each action
-- [ ] Clear "Next Up" shown with /ctx reminder
-- [ ] User knows to run /ctx to continue
+- [ ] Clear "Next Up" shown
 </success_criteria>