ctx-cc 3.3.8 → 3.4.0

package/commands/ctx.md

@@ -1,525 +1,667 @@
 ---
 name: ctx
-description: Smart router - understands natural language, detects intent, and guides users from first prompt. No commands to memorize.
+description: Smart router - understands natural language, detects intent, and routes to the right workflow. No commands to memorize.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+  - mcp__arguseek__research_iteratively
+  - mcp__arguseek__fetch_url
 ---
 
 <objective>
 CTX Smart Router - Conversational-first workflow orchestration.
 
-**Users don't need to know commands.** They just describe what they want, and CTX routes to the right workflow automatically.
+**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 + recommendation
+User: "What should I do next?"         → Shows status + routes to next action
 ```
 </objective>
 
-<workflow>
-
-## Step 0: Intent Detection (ALWAYS RUNS FIRST)
-
-Before checking state, parse the user's natural language request.
+<process>
 
-### Intent Patterns
+## Step 0: Verify CTX Structure
 
-| User Says | Detected Intent | Route To |
-|-----------|-----------------|----------|
-| "build", "create", "make", "start new", "I want to..." | `new-project` | /ctx:init |
-| "fix", "bug", "broken", "not working", "error" | `debug` | /ctx:debug |
-| "test", "QA", "check", "accessible", "works?" | `qa` | /ctx:qa |
-| "review", "audit", "security", "ready?" | `review` | /ctx:verify |
-| "production", "prod ready", "production ready" | `production-ready` | Full audit → QA → fixes |
-| "study", "analyze", "understand", "learn", "explore" | `analyze` | /ctx:map-codebase |
-| "improve", "optimize", "better", "enhance" | `improve` | Analyze → suggest → fix |
-| "deploy", "ship", "publish", "release" | `ship` | /ctx:verify → ship |
-| "status", "progress", "where", "what's next" | `status` | /ctx:status |
-| "help", "how", "what can", "commands" | `help` | /ctx:help |
-| "plan", "design", "architect" | `plan` | /ctx:plan |
-| "continue", "next", "go", "do it" | `continue` | (read STATE.md) |
+**MANDATORY FIRST STEP — Execute before anything else:**
 
-### Intent Detection Logic
+```bash
+test -d .ctx && echo "exists" || echo "missing"
+```
 
-```javascript
-function detectIntent(userMessage) {
-  const msg = userMessage.toLowerCase();
+Store result for routing decisions below.
 
-  // New project signals
-  if (msg.match(/\b(build|create|make|start|new|want to)\b.*\b(app|project|feature|site|api)\b/)) {
-    return 'new-project';
-  }
+## Step 1: Intent Detection
 
-  // Debug signals
-  if (msg.match(/\b(fix|bug|broken|error|crash|not working|fails?|issue)\b/)) {
-    return 'debug';
-  }
+Parse the user's message to detect intent. This runs BEFORE checking state.
 
-  // QA signals
-  if (msg.match(/\b(test|qa|check|accessible|works|validate|verify all)\b/)) {
-    return 'qa';
-  }
+**Detection rules (check in order):**
 
-  // Production-ready signals
-  if (msg.match(/\b(production|prod ready|production.?ready|make it ready)\b/)) {
-    return 'production-ready';
-  }
+| 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 |
 
-  // Analyze/study signals
-  if (msg.match(/\b(study|analyze|understand|learn|explore|what is this)\b/)) {
-    return 'analyze';
-  }
+State detected intent for routing.
 
-  // Improve signals
-  if (msg.match(/\b(improve|optimize|better|enhance|upgrade|refactor)\b/)) {
-    return 'improve';
-  }
+## Step 2: Route Based on CTX Existence + Intent
 
-  // Review signals
-  if (msg.match(/\b(review|audit|security|ready|before deploy)\b/)) {
-    return 'review';
-  }
+**If NO .ctx/ folder (new user):**
 
-  // Ship signals
-  if (msg.match(/\b(deploy|ship|publish|release|push|launch)\b/)) {
-    return 'ship';
-  }
+Route by intent:
 
-  // Status signals
-  if (msg.match(/\b(status|progress|where|what.?s next|current)\b/)) {
-    return 'status';
-  }
+### Route A: New Project Intent
 
-  // Help signals
-  if (msg.match(/\b(help|how|what can|commands|guide)\b/)) {
-    return 'help';
-  }
+If intent = `new-project`:
 
-  // Continue signals (or no clear intent)
-  return 'continue';
-}
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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/)
 
-## Step 1: Check Project State
+If intent = `debug`:
 
-Check if `.ctx/` folder exists:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### If NO `.ctx/` folder (New User)
+I understood: "{{problem_description}}"
 
-Based on detected intent:
+You need to fix something. Let me understand the codebase first.
+```
 
-| Intent | Action |
-|--------|--------|
-| `new-project` | "Let's set up your project!" → Run /ctx:init flow |
-| `debug` | "Let me understand the codebase first." → Run /ctx:map → /ctx:debug |
-| `qa` | "I'll analyze the project first." → Run /ctx:map → /ctx:qa |
-| `production-ready` | "I'll audit everything and make it production ready." → Full pipeline below |
-| `analyze` | "Let me study this codebase." → Run /ctx:map-codebase |
-| `improve` | "I'll analyze and suggest improvements." → Run /ctx:map → analyze → suggest |
-| `continue` | Guide user: "What would you like to do with this project?" |
-| `help` | Show quick start guide |
+**Step 1: Map codebase (parallel agents)**
 
-### Production-Ready Pipeline
+Spawn 4 mapper agents in parallel:
 
-When user says "make it production ready":
+```bash
+mkdir -p .ctx/codebase
+```
 
 ```
-1. /ctx:map-codebase     → Deep analysis (4 parallel agents)
-2. /ctx:qa               → Full system QA (WCAG 2.1 AA)
-3. Security audit        → Check for vulnerabilities
-4. Performance check     → Find slow requests, large assets
-5. Create fix tasks      → Prioritized by severity
-6. Execute fixes         → With verification loop
-7. Final verification    → Three-level check
-8. Report                → Production readiness score
+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")
 ```
 
-Output:
+**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`:
+
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-PRODUCTION READINESS AUDIT
+Welcome to CTX!
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Codebase Analysis: ✓ Complete
-├── Tech: React 18, Node.js, PostgreSQL
-├── Architecture: Clean, well-structured
-├── Quality: 78% test coverage
-└── Concerns: 3 security issues, 5 performance issues
+I understood: "{{qa_request}}"
 
-Full QA: ✓ Complete
-├── Pages tested: 24
-├── WCAG 2.1 AA: 92% compliant
-├── Issues found: 12
-└── Critical: 2
+You want to test the system. I'll analyze the project first.
+```
 
-Security Audit: ⚠ Issues Found
-├── SQL injection risk: 1
-├── XSS vulnerability: 1
-└── Exposed secrets: 1
+Map codebase (same as Route B Step 1), then go to **QA Flow** below.
 
-Performance: ⚠ Issues Found
-├── Slow API calls: 3
-├── Large assets: 2
-└── Missing caching: Yes
+### Route D: Production-Ready Intent (no .ctx/)
 
-Fix Tasks Created: 8
-├── Critical: 3 (security)
-├── High: 5 (performance, a11y)
-└── Medium: 4
+If intent = `production-ready`:
 
-Ready to fix? [Y] Fix all  [C] Critical only  [R] Review first
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{{request}}"
 
-**Output for new users:**
+I'll audit everything and make it production ready.
 ```
-[CTX] Welcome! I see this is a new project.
 
-Based on your request, I'll help you {{detected_action}}.
+Go to **Production-Ready Pipeline** below.
+
+### Route E: Analyze Intent (no .ctx/)
+
+If intent = `analyze`:
 
-{{guided_next_step}}
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-### If `.ctx/` folder EXISTS
+I understood: "{{request}}"
 
-Load configuration and state:
-- Read `.ctx/config.json` for profile settings
-- Read `.ctx/STATE.md` for current status
-- Check `.ctx/REPO-MAP.md` for codebase understanding
+Let me study this codebase.
+```
 
-## Step 2: Route Based on Intent + State
+Go to **Map Codebase Flow** below.
 
-Combine detected intent with current state:
+### 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 if project exists, offer to add story |
-| `debug` | any | Route to /ctx:debug |
-| `qa` | any | Route to /ctx:qa |
-| `production-ready` | any | Run full production-ready pipeline |
-| `analyze` | any | Route to /ctx:map-codebase |
-| `improve` | any | Analyze → suggest improvements → create stories |
-| `status` | any | Show STATE.md summary |
-| `continue` | initializing | Run research phase |
-| `continue` | discussing | Run discussion phase |
+| `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 session |
+| `continue` | debugging | Resume debug |
 | `continue` | verifying | Run verification |
 | `continue` | paused | Resume from checkpoint |
 
-## Step 3: Load Configuration
-
-Read `.ctx/config.json` for:
-- Active profile (quality/balanced/budget)
-- Model routing table
-- Git settings (autoCommit, commitPerTask)
-- Integration settings
-
-If config.json doesn't exist:
-- Copy from templates/config.json
-- Set balanced as default profile
-
-## Step 4: Execute Routed Action
-
-Based on routing decision from Step 2:
-
-### If status = "initializing"
-Route to: **Research Phase**
-1. Check if REPO-MAP exists, if not run ctx-mapper
-2. Use ArguSeek to research the project goal
-3. Create atomic plan (2-3 tasks max)
-4. Update STATE.md with plan
-5. Set status = "discussing"
-
-### If status = "discussing"
-Route to: **Discussion Phase**
-1. Spawn ctx-discusser agent
-2. Ask targeted questions about gray areas
-3. Lock decisions in CONTEXT.md
-4. Set status = "executing"
-
-### If status = "executing"
-Route to: **Execute Current Task**
-1. Read current task from STATE.md
-2. Load REPO-MAP for context
-3. Spawn ctx-executor agent (uses git-native workflow)
-4. Execute task with deviation handling:
-   - Auto-fix: bugs, validation, deps (95%)
-   - Ask user: architecture decisions only (5%)
-5. After task:
-   - Run verification (build, tests, lint)
-   - Auto-commit if config allows
-   - If passes: mark done, update STATE.md
-   - If fails: set status = "debugging"
-
-### If status = "debugging"
-Route to: **Persistent Debug Loop**
-1. Spawn ctx-debugger agent
-2. Check for existing debug session (resume if exists)
-3. Loop until fixed (max 10 attempts):
-   - Analyze error
-   - Form hypothesis
-   - Apply fix
-   - Verify (build + tests + browser if UI)
-   - Record in persistent state
-   - Take screenshot proof if browser test
-4. If fixed: set status = "executing", continue
-5. If max attempts: escalate with full report
-
-### If status = "verifying"
-Route to: **Three-Level Verification**
-1. Spawn ctx-verifier agent
-2. Check all artifacts:
-   - Level 1: Exists (file on disk?)
-   - Level 2: Substantive (real code, not stub?)
-   - Level 3: Wired (imported and used?)
-3. Scan for anti-patterns (TODO, empty catch, placeholders)
-4. Browser verification (if UI)
-5. **DELIVERY GUARANTEE:**
-   - If ALL pass: complete phase → COMPLETE
-   - If ANY fail: set status = "debugging" → fix → verify again
-   - Loop until 100% working or max attempts
-   - NEVER mark complete with failures
-
-### If status = "paused"
-Route to: **Resume**
-1. Read checkpoint from `.ctx/checkpoints/`
-2. Restore context (~2.5k tokens)
-3. Set status to previous state
-4. Continue workflow
-
-## Step 5: Model Selection
-
-Based on current action and active profile:
-
-| Action | quality | balanced | budget |
-|--------|---------|----------|--------|
-| Research | opus | opus | sonnet |
-| Discussion | opus | sonnet | sonnet |
-| Planning | opus | opus | sonnet |
-| Execution | opus | sonnet | sonnet |
-| Debugging | opus | sonnet | sonnet |
-| Verification | sonnet | haiku | haiku |
-| Mapping | sonnet | haiku | haiku |
-
-Use Task tool with `model` parameter from routing table.
-
-## Step 6: Context Budget Check
-
-After every action:
-- Calculate context usage
-- If > 40%: Prepare handoff notes
-- If > 50%: Auto-checkpoint, warn user
-- If > 60%: Create HANDOFF.md, spawn fresh agent
-- If > 70%: Force checkpoint
-
-## Step 7: Git-Native Commit
-
-If task completed successfully AND config.git.autoCommit = true:
-1. Stage modified files
-2. Create commit with CTX format
-3. Record commit hash in STATE.md
-
-## Step 8: Update State
-
-Always update STATE.md after any action:
-- Current status
-- Progress
-- Recent commits
-- Recent decisions
-- Next action
-- Context usage
-</workflow>
+</process>
 
-<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)    ← LOOP BACK
-verifying → COMPLETE (if ALL pass 100%)       ← ONLY EXIT
-paused → (previous state)
+<flows>
+
+## Debug Flow
+
+**Step 1: Research the problem with ArguSeek**
 
-DELIVERY GUARANTEE LOOP:
-  verifying ←→ debugging ←→ executing
-       ↓
-  COMPLETE (only when 100% verified)
 ```
-</state_transitions>
+mcp__arguseek__research_iteratively({
+  query: "{{problem_description}} {{tech_stack}} common causes solutions"
+})
+```
 
-<new_commands>
-## New in CTX 3.0
+Store findings in memory.
 
-| Command | Purpose |
-|---------|---------|
-| `/ctx map` | Build repository map (REPO-MAP.md) |
-| `/ctx map-codebase` | Deep codebase analysis (4 parallel agents) |
-| `/ctx discuss [story]` | Run discussion phase for story |
-| `/ctx profile [name]` | Switch model profile |
-| `/ctx debug --resume` | Resume previous debug session |
-</new_commands>
+**Step 2: Spawn debugger agent**
 
-<context_budget>
-| Usage | Quality | Action |
-|-------|---------|--------|
-| 0-30% | Peak | Continue |
-| 30-40% | Good | Continue |
-| 40-50% | Good | Prepare handoff |
-| 50-60% | Degrading | Auto-checkpoint |
-| 60-70% | Degrading | Create HANDOFF.md |
-| 70%+ | Poor | Force checkpoint |
-</context_budget>
+```
+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**
 
-<output_format>
+Read debugger output. Update STATE.md:
+
+```bash
+# Update status based on outcome
+```
 
-## For New Users (no .ctx/ folder)
+**Step 4: Show next steps**
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
+[CTX] Debug Complete
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-I understood: "{{user_request}}"
+Status: {{fixed | still investigating}}
+Attempts: {{count}}
+Commit: {{hash if fixed}}
 
-{{intent_response}}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+To continue with CTX, run: /ctx
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+---
 
-{{guided_action}}
+## 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"
+})
 ```
 
-**Intent Responses:**
+**Step 2: Spawn QA agent**
 
-| Intent | Response |
-|--------|----------|
-| new-project | "You want to build something new. Let's set it up!" |
-| debug | "You need to fix something. Let me understand the codebase first." |
-| qa | "You want to test the system. I'll analyze the project first." |
-| status | "This is a new project. Would you like to start building?" |
-| help | (Show quick start guide) |
+```
+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")
+```
 
-## For Existing Projects
+**Step 3: Report results**
 
 ```
-[CTX] Status: {{status}}
-[CTX] Profile: {{profile}} ({{costTier}})
-[CTX] Action: {{action_taken}}
-[CTX] Commit: {{commit_hash}} (if auto-committed)
-[CTX] Next: {{next_action}}
-[CTX] Context: {{percent}}% ({{quality}})
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[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
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
-## CRITICAL: Continuation Reminder
+---
+
+## Production-Ready Pipeline
 
-**ALWAYS end every CTX response with this footer:**
+Full audit for production readiness:
 
+**Step 1: Map codebase (if not already mapped)**
+
+```bash
+test -d .ctx/codebase && echo "mapped" || echo "needs_mapping"
 ```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+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"
+})
 ```
 
-This is essential because CTX commands only run for one turn. Without this reminder, users will continue chatting without CTX tracking their work.
+**Step 3: Run full QA**
 
-## Guided Prompts (When Intent Unclear)
+Spawn ctx-qa agent (see QA Flow above).
 
-If user's intent is ambiguous, ask:
+**Step 4: Security audit**
 
 ```
-I'm not sure what you'd like to do. Here are your options:
+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")
+```
 
-  "Build something new"  → I'll help you start a project
-  "Fix a bug"            → I'll debug the issue
-  "Test the app"         → I'll run full QA
-  "Show status"          → I'll show current progress
+**Step 5: Performance check**
 
-What would you like to do?
 ```
-</output_format>
+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")
+```
 
-<examples>
+**Step 6: Create fix tasks**
 
-## Example Conversations
+Read all reports, create prioritized fix list in .ctx/FIX-TASKS.md
 
-### New User - Build Intent
+**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}}")
 ```
-User: "I want to build a todo app with React"
 
-CTX: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     Welcome to CTX!
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**Step 8: Final verification**
+
+Spawn ctx-verifier for three-level check.
+
+**Step 9: Report**
 
-     I understood: "build a todo app with React"
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
 
-     You want to build something new. Let's set it up!
+---
 
-     I'll now:
-     1. Create your project structure
-     2. Research best practices for React todo apps
-     3. Create a plan with clear milestones
+## Map Codebase Flow
 
-     [Starting project setup...]
+**Step 1: Create structure**
 
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```bash
+mkdir -p .ctx/codebase
 ```
 
-### New User - Fix Intent
+**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")
 ```
-User: "The login is broken"
 
-CTX: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     Welcome to CTX!
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+**Step 3: Synthesize**
 
-     I understood: "login is broken"
+After all agents complete, create summary:
 
-     You need to fix something. Let me understand the codebase first.
+```bash
+cat > .ctx/codebase/SUMMARY.md << 'EOF'
+# Codebase Summary
 
-     I'll now:
-     1. Map your codebase structure
-     2. Find the login-related code
-     3. Start debugging
+## Tech Stack
+{{from TECH.md}}
 
-     [Analyzing codebase...]
+## Architecture
+{{from ARCH.md}}
 
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+## Quality
+{{from QUALITY.md}}
+
+## Concerns
+{{from CONCERNS.md}}
+EOF
 ```
 
-### Existing Project - Continue
+**Step 4: Report**
+
 ```
-User: "continue"
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[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:
 
-CTX: [CTX] Status: executing
-     [CTX] Profile: balanced (1x cost)
-     [CTX] Story: S002 - User Authentication
-     [CTX] Task: 2/3 - Implement login form validation
-     [CTX] Action: Executing task...
+```bash
+cat .ctx/STATE.md
+ls -la .ctx/phases/ 2>/dev/null | wc -l
+```
 
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+[CTX] Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Project: {{name}}
+Status: {{status}}
+Profile: {{profile}}
+
+Progress: [{{progress_bar}}] {{completed}}/{{total}} stories
+
+Current: {{current_story}}
+Next: {{next_action}}
 
-### Existing Project - QA Intent
+Context: {{percent}}%
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+To continue with CTX, run: /ctx
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
-User: "is the app accessible?"
 
-CTX: [CTX] Detected: QA request (accessibility)
-     [CTX] Routing to: /ctx:qa --a11y-only
+</flows>
+
+<model_routing>
+Based on config.json profile, use these models for Task() calls:
 
-     Running WCAG 2.1 AA accessibility audit...
+| 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 |
+</model_routing>
 
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+<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>
 
-</examples>
+<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
+</success_criteria>