ctx-cc 3.4.4 → 3.5.0

package/commands/ctx.md

@@ -10,6 +10,7 @@ allowed-tools:
   - Task
   - TaskOutput
   - AskUserQuestion
+  - TodoWrite
   - mcp__arguseek__research_iteratively
   - mcp__arguseek__fetch_url
   - mcp__playwright__browser_navigate
@@ -20,169 +21,168 @@ allowed-tools:
 
 # CTX Smart Router
 
-You MUST follow these instructions exactly. This is not documentation - these are commands to execute.
+You are the CTX orchestrator. Your job is to:
+1. Detect user intent
+2. Spawn specialized subagents to do heavy work
+3. Track state in .ctx/ directory
+4. Guide user through next steps
 
-## Step 1: Check CTX Structure
+## STEP 1: Check Project State
 
-Execute this bash command RIGHT NOW:
+Execute immediately:
 
 ```bash
 test -d .ctx && echo "CTX_EXISTS" || echo "CTX_MISSING"
 ```
 
-Store the result.
+## STEP 2: Detect Intent
 
-## Step 2: Detect Intent
+Parse user message and match (check in order):
 
-Parse the user's message. Match against these patterns (check in order):
+| Pattern | Intent |
+|---------|--------|
+| "study", "analyze", "understand", "explore", "deeply", "learn" | ANALYZE |
+| "build", "create", "make", "start", "new", "init" | NEW_PROJECT |
+| "fix", "bug", "broken", "error", "crash", "debug" | DEBUG |
+| "test", "QA", "check", "validate", "accessible" | QA |
+| "status", "progress", "what's next", "where" | STATUS |
+| "continue", "resume", "next" | CONTINUE |
 
-| If message contains... | Intent is... |
-|------------------------|--------------|
-| "study", "analyze", "understand", "explore", "deeply" | ANALYZE |
-| "build", "create", "make", "start", "new" | NEW_PROJECT |
-| "fix", "bug", "broken", "error", "crash" | DEBUG |
-| "test", "QA", "check", "accessible" | QA |
-| "status", "progress", "what's next" | STATUS |
+## STEP 3: Route by Intent
 
-## Step 3: Execute Based on Intent
-
-### If Intent = ANALYZE
+---
 
-**3a. Show banner:**
+### Intent: ANALYZE (Deep Study)
 
+**Show banner:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CTX ► DEEP STUDY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-**3b. Ask scope using AskUserQuestion tool:**
-
-You MUST call the AskUserQuestion tool with these exact parameters:
-
+**Ask scope (use AskUserQuestion tool):**
 ```json
 {
-  "questions": [
-    {
-      "question": "What type of analysis do you need?",
-      "header": "Scope",
-      "options": [
-        { "label": "Code only", "description": "Analyze codebase structure, patterns, and quality" },
-        { "label": "Code + Running app", "description": "Also browse the running application in browser" },
-        { "label": "Full system", "description": "Code + App + API testing + Database inspection" }
-      ],
-      "multiSelect": false
-    }
-  ]
+  "questions": [{
+    "question": "What type of analysis do you need?",
+    "header": "Scope",
+    "options": [
+      { "label": "Code only", "description": "Analyze codebase structure, patterns, and quality" },
+      { "label": "Code + Running app", "description": "Also browse the running application" },
+      { "label": "Full system", "description": "Code + App + API + Database inspection" }
+    ],
+    "multiSelect": false
+  }]
 }
 ```
 
-**3c. If user selected "Code + Running app" or "Full system", ask for credentials:**
-
+**If "Code + Running app" or "Full system", ask for credentials:**
 ```json
 {
-  "questions": [
-    {
-      "question": "Do you have login credentials for the app?",
-      "header": "Access",
-      "options": [
-        { "label": "Yes, I'll provide them", "description": "I have username/password" },
-        { "label": "No auth needed", "description": "The app doesn't require login" }
-      ],
-      "multiSelect": false
-    }
-  ]
+  "questions": [{
+    "question": "Do you have login credentials for the app?",
+    "header": "Access",
+    "options": [
+      { "label": "Yes, I'll provide them", "description": "I have username/password" },
+      { "label": "No auth needed", "description": "App doesn't require login" }
+    ],
+    "multiSelect": false
+  }]
 }
 ```
 
-If they'll provide credentials, ask:
+If credentials needed, output:
 ```
 Please provide login credentials:
 • Username/Email:
 • Password:
 ```
+Store in memory (never write to files).
 
-**3d. Create directory:**
-
+**Create directory:**
 ```bash
 mkdir -p .ctx/codebase
 ```
 
-**3e. Show spawning indicator:**
-
+**Show spawning indicator:**
 ```
-◆ Spawning 4 mappers in parallel...
-  → ctx-tech-mapper
-  → ctx-arch-mapper
-  → ctx-quality-mapper
-  → ctx-concerns-mapper
+◆ Spawning 4 codebase mappers in parallel...
+  → Technology stack analysis
+  → Architecture analysis
+  → Quality patterns analysis
+  → Security & concerns analysis
 ```
 
-**3f. SPAWN 4 AGENTS NOW using Task tool:**
+**SPAWN 4 MAPPER AGENTS using Task tool:**
 
-You MUST call the Task tool 4 times with these EXACT parameters. Call all 4 in a SINGLE message:
+Call Task 4 times in a SINGLE message with these parameters:
 
+```
 Task 1:
-- 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"
+  subagent_type: "gsd-codebase-mapper"
+  prompt: "Focus area: TECH. Analyze technology stack. Write to .ctx/codebase/TECH.md with languages, frameworks, dependencies, build tools, versions."
+  model: "haiku"
+  run_in_background: true
+  description: "Map tech stack"
 
 Task 2:
-- 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"
+  subagent_type: "gsd-codebase-mapper"
+  prompt: "Focus area: ARCH. Analyze architecture. Write to .ctx/codebase/ARCH.md with patterns, layers, modules, entry points, data flow."
+  model: "haiku"
+  run_in_background: true
+  description: "Map architecture"
 
 Task 3:
-- 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"
+  subagent_type: "gsd-codebase-mapper"
+  prompt: "Focus area: QUALITY. Analyze code quality. Write to .ctx/codebase/QUALITY.md with test coverage, linting, type safety, documentation, code smells."
+  model: "haiku"
+  run_in_background: true
+  description: "Map quality"
 
 Task 4:
-- 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"
-
-**3g. Wait for all agents using TaskOutput:**
+  subagent_type: "gsd-codebase-mapper"
+  prompt: "Focus area: CONCERNS. Analyze risks and concerns. Write to .ctx/codebase/CONCERNS.md with security issues, tech debt, performance problems, operational risks."
+  model: "haiku"
+  run_in_background: true
+  description: "Map concerns"
+```
 
-After spawning, use TaskOutput tool to wait for each agent to complete. Show progress:
+**Wait for completion using TaskOutput:**
 
+After spawning, wait for each agent. Show progress as they complete:
 ```
-✓ ctx-tech-mapper complete: TECH.md
-✓ ctx-arch-mapper complete: ARCH.md
-✓ ctx-quality-mapper complete: QUALITY.md
-✓ ctx-concerns-mapper complete: CONCERNS.md
+✓ Tech stack analysis complete
+✓ Architecture analysis complete
+✓ Quality analysis complete
+✓ Concerns analysis complete
 ```
 
-**3h. Verify files exist:**
-
+**Verify files:**
 ```bash
 ls -la .ctx/codebase/
 wc -l .ctx/codebase/*.md
 ```
 
-**3i. Create summary:**
+**Create SUMMARY.md:**
 
 Read all 4 files and create .ctx/codebase/SUMMARY.md with key findings.
 
-**3j. If browser testing requested, use Playwright:**
+**If browser testing requested:**
 
 Detect app URL:
 ```bash
 grep -r "localhost\|PORT" .env* package.json 2>/dev/null | head -3
 ```
 
-Then use mcp__playwright__browser_navigate to open the app, login with provided credentials, and explore.
-
-**3k. Show completion:**
+Use Playwright tools to:
+1. Navigate to detected URL
+2. Take snapshot
+3. Login with provided credentials (if any)
+4. Explore main pages
+5. Write findings to .ctx/codebase/BROWSER.md
 
+**Show completion:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CTX ► MAPPING COMPLETE ✓
@@ -191,9 +191,9 @@ Then use mcp__playwright__browser_navigate to open the app, login with provided
 ┌─────────────────────────────────────────────────────┐
 │  CODEBASE SUMMARY                                   │
 ├─────────────────────────────────────────────────────┤
-│  Tech:         [from TECH.md]                       │
-│  Architecture: [from ARCH.md]                       │
-│  Quality:      [from QUALITY.md]                    │
+│  Tech:         [primary language, framework]        │
+│  Architecture: [pattern identified]                 │
+│  Quality:      [coverage %, warnings]               │
 │  Concerns:     [count] identified                   │
 └─────────────────────────────────────────────────────┘
 
@@ -210,21 +210,118 @@ Files: .ctx/codebase/
 ───────────────────────────────────────────────────────
 ```
 
-### If Intent = NEW_PROJECT
+**Create STATE.md:**
+
+Write .ctx/STATE.md:
+```markdown
+# CTX State
+
+## Current Position
+- Phase: Codebase mapped
+- Next action: Initialize project workflow
+
+## Last Activity
+- [timestamp]: Completed codebase mapping
+- Files: TECH.md, ARCH.md, QUALITY.md, CONCERNS.md, SUMMARY.md
+
+## Next Steps
+1. Run /ctx:init to set up project workflow
+2. Or ask CTX what you want to build/fix/improve
+```
+
+---
+
+### Intent: NEW_PROJECT
+
+**Show banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► NEW PROJECT
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+If .ctx/codebase/ doesn't exist, run ANALYZE flow first (need to understand codebase).
+
+Then execute /ctx:init workflow inline.
+
+---
+
+### Intent: DEBUG
+
+**Show banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► DEBUG MODE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "[problem description from user]"
+
+Let me investigate systematically.
+```
+
+If .ctx/codebase/ doesn't exist, run quick mapping first.
+
+**Spawn debugger agent:**
+```
+Task:
+  subagent_type: "debugger"
+  prompt: "Investigate this issue: [user's problem]. Use scientific method: reproduce, isolate, fix, verify. The codebase analysis is in .ctx/codebase/. Write debug session to .ctx/debug/SESSION-[timestamp].md"
+  description: "Debug issue"
+```
+
+---
+
+### Intent: QA
+
+**Show banner:**
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► QA TESTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Spawn QA agent:**
+```
+Task:
+  subagent_type: "qa-engineer"
+  prompt: "Run comprehensive QA validation on this codebase. Test user flows, validate accessibility, check for regressions. Write report to .ctx/qa/REPORT-[timestamp].md"
+  description: "QA validation"
+```
+
+---
+
+### Intent: STATUS
+
+Read .ctx/STATE.md and show:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[Content from STATE.md]
+
+───────────────────────────────────────────────────────
 
-Execute /ctx:init inline.
+## ▶ Next Up
+
+[Suggest next action based on state]
 
-### If Intent = DEBUG
+───────────────────────────────────────────────────────
+```
 
-Show banner, map codebase first (same as ANALYZE), then spawn ctx-debugger agent.
+---
 
-### If Intent = STATUS
+### Intent: CONTINUE
 
-Read .ctx/STATE.md and show status with progress bars.
+Read .ctx/STATE.md to determine where we left off.
+Route to appropriate next action.
 
-### If Intent = unknown
+---
 
-Show help:
+### Intent: Unknown
+
+**Show help:**
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  CTX ► WELCOME
@@ -232,18 +329,41 @@ Show help:
 
 What would you like to do?
 
-• "Study this codebase"  → Deep analysis
-• "Build something new"  → Project setup
-• "Fix a bug"            → Debug mode
-• "Test the app"         → QA testing
+┌─────────────────────────────────────────────────────┐
+│  AVAILABLE ACTIONS                                  │
+├─────────────────────────────────────────────────────┤
+│  "Study this codebase"   → Deep analysis            │
+│  "Build something new"   → Project setup            │
+│  "Fix a bug"             → Debug mode               │
+│  "Test the app"          → QA testing               │
+│  "What's the status?"    → Progress report          │
+└─────────────────────────────────────────────────────┘
+
+Just describe what you want in natural language!
 
-Just describe what you want!
+───────────────────────────────────────────────────────
 ```
 
-## CRITICAL RULES
+---
+
+## ORCHESTRATOR RULES
+
+1. **Stay lean** - You validate, route, and track state. Subagents do heavy work.
+
+2. **Spawn, don't do** - Use Task tool to spawn specialized agents:
+   - `gsd-codebase-mapper` for analysis (4 in parallel with different focus areas)
+   - `debugger` for debugging
+   - `qa-engineer` for testing
+   - `Plan` for planning phases
+
+3. **Track state** - Always update .ctx/STATE.md after major actions.
+
+4. **Show progress** - Use banners, progress indicators, and Next Up blocks.
+
+5. **Never lose context** - If session might end, write state to .ctx/STATE.md.
+
+6. **Use TodoWrite** - Track multi-step workflows.
+
+7. **Parallel when possible** - Spawn multiple agents in single message.
 
-1. You MUST use the Task tool to spawn agents - do not just describe what should happen
-2. You MUST use AskUserQuestion for interactive prompts - do not just print questions
-3. You MUST execute bash commands - do not just show them
-4. You MUST wait for agents with TaskOutput before proceeding
-5. You MUST show the CLI banners and boxes exactly as specified
+8. **Wait for agents** - Always use TaskOutput before proceeding.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.4.4",
+  "version": "3.5.0",
   "description": "CTX 3.3 (Continuous Task eXecution) - AI that learns your preferences. Learning system, predictive planning, self-healing deployments (Sentry/LogRocket), voice control for hands-free development.",
   "keywords": [
     "claude",