ctx-cc 3.3.8 → 3.4.1

package/agents/ctx-arch-mapper.md

@@ -1,7 +1,7 @@
 ---
 name: ctx-arch-mapper
 description: Architecture mapper for CTX 3.0. Analyzes patterns, data flow, modules, and entry points. Part of parallel codebase mapping.
-tools: Read, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
 

package/agents/ctx-concerns-mapper.md

@@ -1,7 +1,7 @@
 ---
 name: ctx-concerns-mapper
 description: Concerns mapper for CTX 3.0. Analyzes security vulnerabilities, tech debt, performance issues, and risks. Part of parallel codebase mapping.
-tools: Read, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep
 color: red
 ---
 

package/agents/ctx-quality-mapper.md

@@ -1,7 +1,7 @@
 ---
 name: ctx-quality-mapper
 description: Quality mapper for CTX 3.0. Analyzes test coverage, lint status, type safety, and code smells. Part of parallel codebase mapping.
-tools: Read, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep
 color: green
 ---
 

package/agents/ctx-tech-mapper.md

@@ -1,7 +1,7 @@
 ---
 name: ctx-tech-mapper
 description: Tech stack mapper for CTX 3.0. Analyzes languages, frameworks, dependencies, and versions. Part of parallel codebase mapping.
-tools: Read, Bash, Glob, Grep
+tools: Read, Write, Bash, Glob, Grep
 color: blue
 ---
 

package/commands/ctx.md

@@ -1,525 +1,78 @@
 ---
 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.
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - TaskOutput
+  - 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: "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>
 
-<workflow>
-
-## Step 0: Intent Detection (ALWAYS RUNS FIRST)
-
-Before checking state, parse the user's natural language request.
-
-### Intent Patterns
-
-| 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) |
-
-### Intent Detection Logic
-
-```javascript
-function detectIntent(userMessage) {
-  const msg = userMessage.toLowerCase();
-
-  // 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';
-  }
-
-  // Debug signals
-  if (msg.match(/\b(fix|bug|broken|error|crash|not working|fails?|issue)\b/)) {
-    return 'debug';
-  }
-
-  // QA signals
-  if (msg.match(/\b(test|qa|check|accessible|works|validate|verify all)\b/)) {
-    return 'qa';
-  }
-
-  // Production-ready signals
-  if (msg.match(/\b(production|prod ready|production.?ready|make it ready)\b/)) {
-    return 'production-ready';
-  }
-
-  // Analyze/study signals
-  if (msg.match(/\b(study|analyze|understand|learn|explore|what is this)\b/)) {
-    return 'analyze';
-  }
-
-  // Improve signals
-  if (msg.match(/\b(improve|optimize|better|enhance|upgrade|refactor)\b/)) {
-    return 'improve';
-  }
-
-  // Review signals
-  if (msg.match(/\b(review|audit|security|ready|before deploy)\b/)) {
-    return 'review';
-  }
-
-  // Ship signals
-  if (msg.match(/\b(deploy|ship|publish|release|push|launch)\b/)) {
-    return 'ship';
-  }
-
-  // Status signals
-  if (msg.match(/\b(status|progress|where|what.?s next|current)\b/)) {
-    return 'status';
-  }
-
-  // Help signals
-  if (msg.match(/\b(help|how|what can|commands|guide)\b/)) {
-    return 'help';
-  }
-
-  // Continue signals (or no clear intent)
-  return 'continue';
-}
-```
-
-## Step 1: Check Project State
-
-Check if `.ctx/` folder exists:
-
-### If NO `.ctx/` folder (New User)
-
-Based on detected intent:
-
-| 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 |
-
-### Production-Ready Pipeline
-
-When user says "make it production ready":
-
-```
-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
-```
-
-Output:
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-PRODUCTION READINESS AUDIT
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Codebase Analysis: ✓ Complete
-├── Tech: React 18, Node.js, PostgreSQL
-├── Architecture: Clean, well-structured
-├── Quality: 78% test coverage
-└── Concerns: 3 security issues, 5 performance issues
-
-Full QA: ✓ Complete
-├── Pages tested: 24
-├── WCAG 2.1 AA: 92% compliant
-├── Issues found: 12
-└── Critical: 2
-
-Security Audit: ⚠ Issues Found
-├── SQL injection risk: 1
-├── XSS vulnerability: 1
-└── Exposed secrets: 1
-
-Performance: ⚠ Issues Found
-├── Slow API calls: 3
-├── Large assets: 2
-└── Missing caching: Yes
-
-Fix Tasks Created: 8
-├── Critical: 3 (security)
-├── High: 5 (performance, a11y)
-└── Medium: 4
-
-Ready to fix? [Y] Fix all  [C] Critical only  [R] Review first
-```
-
-**Output for new users:**
-```
-[CTX] Welcome! I see this is a new project.
-
-Based on your request, I'll help you {{detected_action}}.
-
-{{guided_next_step}}
-```
-
-### If `.ctx/` folder EXISTS
-
-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
-
-## Step 2: Route Based on Intent + State
-
-Combine detected intent with current 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 |
-| `continue` | executing | Execute current task |
-| `continue` | debugging | Resume debug session |
-| `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>
-
-<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)
-
-DELIVERY GUARANTEE LOOP:
-  verifying ←→ debugging ←→ executing
-       ↓
-  COMPLETE (only when 100% verified)
-```
-</state_transitions>
-
-<new_commands>
-## New in CTX 3.0
-
-| 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>
-
-<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>
-
-<output_format>
-
-## For New Users (no .ctx/ folder)
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Welcome to CTX!
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-I understood: "{{user_request}}"
-
-{{intent_response}}
-
-{{guided_action}}
-```
-
-**Intent Responses:**
-
-| 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) |
-
-## For Existing Projects
-
-```
-[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}})
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## CRITICAL: Continuation Reminder
-
-**ALWAYS end every CTX response with this footer:**
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-To continue with CTX, run: /ctx
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-This is essential because CTX commands only run for one turn. Without this reminder, users will continue chatting without CTX tracking their work.
-
-## Guided Prompts (When Intent Unclear)
-
-If user's intent is ambiguous, ask:
-
-```
-I'm not sure what you'd like to do. Here are your options:
-
-  "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
-
-What would you like to do?
-```
-</output_format>
-
-<examples>
-
-## Example Conversations
-
-### New User - Build Intent
-```
-User: "I want to build a todo app with React"
-
-CTX: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     Welcome to CTX!
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     I understood: "build a todo app with React"
-
-     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
-
-     [Starting project setup...]
-
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### New User - Fix Intent
-```
-User: "The login is broken"
-
-CTX: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     Welcome to CTX!
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-     I understood: "login is broken"
-
-     You need to fix something. Let me understand the codebase first.
-
-     I'll now:
-     1. Map your codebase structure
-     2. Find the login-related code
-     3. Start debugging
-
-     [Analyzing codebase...]
-
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Existing Project - Continue
-```
-User: "continue"
-
-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...
-
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Existing Project - QA Intent
-```
-User: "is the app accessible?"
-
-CTX: [CTX] Detected: QA request (accessibility)
-     [CTX] Routing to: /ctx:qa --a11y-only
-
-     Running WCAG 2.1 AA accessibility audit...
-
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-     To continue with CTX, run: /ctx
-     ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-</examples>
+<execution_context>
+@~/.claude/ctx/workflows/ctx-router.md
+</execution_context>
+
+<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" | 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:
+
+| Agent | quality | balanced | budget |
+|-------|---------|----------|--------|
+| Mappers | sonnet | haiku | haiku |
+| Debugger | opus | sonnet | sonnet |
+| QA | sonnet | sonnet | haiku |
+| Executor | opus | sonnet | sonnet |
+</model_routing>
+
+<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
+</success_criteria>