ctx-cc 3.4.2 → 3.4.4

package/commands/ctx.md

@@ -12,67 +12,238 @@ allowed-tools:
   - AskUserQuestion
   - mcp__arguseek__research_iteratively
   - mcp__arguseek__fetch_url
+  - mcp__playwright__browser_navigate
+  - mcp__playwright__browser_snapshot
+  - mcp__playwright__browser_type
+  - mcp__playwright__browser_click
 ---
 
-<objective>
-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: "Study the codebase"             -> Routes to map-codebase
-User: "What should I do next?"         -> Shows status + routes
-```
-</objective>
-
-<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>
+# CTX Smart Router
+
+You MUST follow these instructions exactly. This is not documentation - these are commands to execute.
+
+## Step 1: Check CTX Structure
+
+Execute this bash command RIGHT NOW:
+
+```bash
+test -d .ctx && echo "CTX_EXISTS" || echo "CTX_MISSING"
+```
+
+Store the result.
+
+## Step 2: Detect Intent
+
+Parse the user's message. Match against these patterns (check in order):
+
+| 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: Execute Based on Intent
+
+### If Intent = ANALYZE
+
+**3a. Show banner:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► DEEP STUDY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**3b. Ask scope using AskUserQuestion tool:**
+
+You MUST call the AskUserQuestion tool with these exact parameters:
+
+```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
+    }
+  ]
+}
+```
+
+**3c. If user selected "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
+    }
+  ]
+}
+```
+
+If they'll provide credentials, ask:
+```
+Please provide login credentials:
+• Username/Email:
+• Password:
+```
+
+**3d. Create directory:**
+
+```bash
+mkdir -p .ctx/codebase
+```
+
+**3e. Show spawning indicator:**
+
+```
+◆ Spawning 4 mappers in parallel...
+  → ctx-tech-mapper
+  → ctx-arch-mapper
+  → ctx-quality-mapper
+  → ctx-concerns-mapper
+```
+
+**3f. SPAWN 4 AGENTS NOW using Task tool:**
+
+You MUST call the Task tool 4 times with these EXACT parameters. Call all 4 in a SINGLE message:
+
+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"
+
+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"
+
+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"
+
+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:**
+
+After spawning, use TaskOutput tool to wait for each agent to complete. Show progress:
+
+```
+✓ ctx-tech-mapper complete: TECH.md
+✓ ctx-arch-mapper complete: ARCH.md
+✓ ctx-quality-mapper complete: QUALITY.md
+✓ ctx-concerns-mapper complete: CONCERNS.md
+```
+
+**3h. Verify files exist:**
+
+```bash
+ls -la .ctx/codebase/
+wc -l .ctx/codebase/*.md
+```
+
+**3i. Create summary:**
+
+Read all 4 files and create .ctx/codebase/SUMMARY.md with key findings.
+
+**3j. If browser testing requested, use Playwright:**
+
+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:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► MAPPING COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         [from TECH.md]                       │
+│  Architecture: [from ARCH.md]                       │
+│  Quality:      [from QUALITY.md]                    │
+│  Concerns:     [count] identified                   │
+└─────────────────────────────────────────────────────┘
+
+Files: .ctx/codebase/
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**Initialize project** — set up CTX workflow
+
+`/ctx:init`
+
+───────────────────────────────────────────────────────
+```
+
+### If Intent = NEW_PROJECT
+
+Execute /ctx:init inline.
+
+### If Intent = DEBUG
+
+Show banner, map codebase first (same as ANALYZE), then spawn ctx-debugger agent.
+
+### If Intent = STATUS
+
+Read .ctx/STATE.md and show status with progress bars.
+
+### If Intent = unknown
+
+Show help:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+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
+
+Just describe what you want!
+```
+
+## CRITICAL RULES
+
+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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.4.2",
+  "version": "3.4.4",
   "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",

package/workflows/ctx-router.md

@@ -74,17 +74,116 @@ Execute /ctx:init inline (don't tell user to run it separately).
 Output:
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
- CTX ► ANALYZING CODEBASE
+ CTX ► DEEP STUDY
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 I understood: "{{user_request}}"
 
-Let me analyze this codebase with 4 specialized mappers.
+Before I analyze, let me understand the scope.
+
+───────────────────────────────────────────────────────
+```
+
+**Step 0: Gather context with AskUserQuestion**
+
+Use the AskUserQuestion tool to ask:
+
+```
+AskUserQuestion({
+  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
+    },
+    {
+      question: "Is the application running locally?",
+      header: "Environment",
+      options: [
+        { label: "Yes, running", description: "App is running at localhost or local URL" },
+        { label: "Not yet", description: "I'll start it or you can help me start it" },
+        { label: "Remote/Staging", description: "App is deployed to a remote environment" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+**If user selects "Code + Running app" or "Full system":**
+
+Ask for credentials:
+```
+AskUserQuestion({
+  questions: [
+    {
+      question: "Do you have login credentials for the app?",
+      header: "Access",
+      options: [
+        { label: "Yes, I'll provide them", description: "I have username/password or API keys" },
+        { label: "No auth needed", description: "The app doesn't require login" },
+        { label: "OAuth/SSO only", description: "Login requires external provider" }
+      ],
+      multiSelect: false
+    }
+  ]
+})
+```
+
+**If user will provide credentials:**
+
+Output:
+```
+╔═══════════════════════════════════════════════════════╗
+║  LOGIN CREDENTIALS                                    ║
+╚═══════════════════════════════════════════════════════╝
+
+I'll detect the app URL from your config files.
+Please provide login credentials for browser testing:
+
+• Username/Email: _______________
+• Password: _______________
+
+───────────────────────────────────────────────────────
+→ Paste credentials or type "skip" to analyze code only
+───────────────────────────────────────────────────────
+```
+
+Store credentials in memory for browser testing (never write to files).
+
+**Detect app URL from codebase:**
+
+```bash
+# Check common locations for app URL
+grep -r "localhost\|127.0.0.1" .env* package.json 2>/dev/null | head -5
+grep -r "PORT\|port" .env* package.json 2>/dev/null | head -5
+```
+
+Extract URL like `http://localhost:3000` from config.
+
+**Step 1: Show analysis plan**
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► ANALYZING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Analysis scope: {{selected_scope}}
+Environment: {{selected_environment}}
+Access: {{access_level}}
+
+Starting analysis with 4 specialized mappers...
 
 ───────────────────────────────────────────────────────
 ```
 
-**Step 1: Create structure**
+**Step 2: Create structure**
 
 ```bash
 mkdir -p .ctx/codebase
@@ -150,7 +249,69 @@ cat .ctx/codebase/CONCERNS.md
 
 Write `.ctx/codebase/SUMMARY.md` with key findings from each document.
 
-**Step 7: Show completion banner**
+**Step 7: Browser testing (if scope includes running app)**
+
+If user selected "Code + Running app" or "Full system":
+
+Output:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► BROWSER TESTING
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Now testing the running application...
+
+───────────────────────────────────────────────────────
+```
+
+Use Playwright MCP tools to:
+
+1. Navigate to app URL:
+```
+mcp__playwright__browser_navigate({ url: "{{app_url}}" })
+```
+
+2. Take snapshot of initial state:
+```
+mcp__playwright__browser_snapshot({})
+```
+
+3. If credentials provided, log in:
+```
+mcp__playwright__browser_type({ element: "email/username field", ref: "{{ref}}", text: "{{username}}" })
+mcp__playwright__browser_type({ element: "password field", ref: "{{ref}}", text: "{{password}}" })
+mcp__playwright__browser_click({ element: "login button", ref: "{{ref}}" })
+```
+
+4. Take snapshot after login:
+```
+mcp__playwright__browser_snapshot({})
+```
+
+5. Explore key pages based on codebase analysis:
+   - Navigate to pages identified in ARCH.md
+   - Take screenshots of main flows
+   - Check for console errors
+
+6. Write browser findings to `.ctx/codebase/BROWSER.md`:
+   - Pages tested
+   - UI issues found
+   - Console errors
+   - Accessibility observations
+   - Screenshots taken
+
+Output progress:
+```
+◆ Testing application...
+  → Navigating to {{app_url}}
+  → Logging in as {{username}}
+  → Exploring dashboard
+  → Checking user flows
+
+✓ Browser testing complete: BROWSER.md ({{N}} lines)
+```
+
+**Step 8: Show completion banner**
 
 Output:
 ```