ctx-cc 3.4.1 → 3.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.4.1",
+  "version": "3.4.3",
   "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/references/ui-brand.md

@@ -0,0 +1,256 @@
+<ui_patterns>
+
+Visual patterns for user-facing CTX output. All workflows @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions. 55-character width.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `ANALYZING CODEBASE`
+- `MAPPING COMPLETE`
+- `INITIALIZING PROJECT`
+- `RESEARCHING`
+- `PLANNING PHASE {N}`
+- `EXECUTING`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `DEBUG MODE`
+- `QA TESTING`
+- `SHIP READY 🚀`
+
+---
+
+## Checkpoint Boxes
+
+User action required. 55-character width.
+
+```
+╔═══════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                   ║
+╚═══════════════════════════════════════════════════════╝
+
+{Content}
+
+───────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+───────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Approval Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select an option`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress / Active
+○  Pending / Queued
+⚡ Auto-completed
+⚠  Warning / Attention needed
+🚀 Ship ready (only in banner)
+```
+
+---
+
+## Progress Bars
+
+**Percentage-based:**
+```
+Progress: ████████░░ 80%
+```
+
+**For agent spawning:**
+```
+Mapping:  [████████████████████] TECH     ✓ 12s
+          [████████████████████] ARCH     ✓ 15s
+          [████████████████░░░░] QUALITY  ◆ ...
+          [░░░░░░░░░░░░░░░░░░░░] CONCERNS ○
+```
+
+**Task count:**
+```
+Tasks: 2/4 complete
+Phases: 1/5 complete
+```
+
+---
+
+## Spawning Indicators
+
+When spawning agents, show activity:
+
+```
+◆ Spawning 4 mappers in parallel...
+  → ctx-tech-mapper
+  → ctx-arch-mapper
+  → ctx-quality-mapper
+  → ctx-concerns-mapper
+
+✓ ctx-tech-mapper complete: TECH.md (156 lines)
+✓ ctx-arch-mapper complete: ARCH.md (203 lines)
+✓ ctx-quality-mapper complete: QUALITY.md (178 lines)
+✓ ctx-concerns-mapper complete: CONCERNS.md (145 lines)
+```
+
+---
+
+## Summary Boxes
+
+For displaying analysis results:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         TypeScript, Next.js 14, Prisma      │
+│  Architecture: Modular monolith                    │
+│  Quality:      67% coverage, 12 lint warnings      │
+│  Concerns:     3 security, 5 tech debt items       │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Next Up Block
+
+Always at end of major completions.
+
+```
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Action}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- `/ctx:alternative-1` — description
+- `/ctx:alternative-2` — description
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Error Box
+
+```
+╔═══════════════════════════════════════════════════════╗
+║  ERROR                                                ║
+╚═══════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Warning Box
+
+```
+┌─────────────────────────────────────────────────────┐
+│  ⚠ WARNING                                          │
+├─────────────────────────────────────────────────────┤
+│  {Warning message}                                  │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tables
+
+For structured data display:
+
+```
+| Phase | Status | Tasks | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 5/5   | 100%     |
+| 2     | ◆      | 2/4   | 50%      |
+| 3     | ○      | 0/3   | 0%       |
+```
+
+For concerns/issues:
+
+```
+| Severity | Count | Category        |
+|----------|-------|-----------------|
+| Critical | 0     | —               |
+| High     | 2     | Security        |
+| Medium   | 5     | Tech Debt       |
+| Low      | 8     | Code Quality    |
+```
+
+---
+
+## Welcome Banner
+
+First-time users:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{user_request}"
+
+{Brief explanation of what will happen next}
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Completion Banner
+
+End of workflow:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► {STAGE} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{Summary of what was accomplished}
+
+Files: {list of created/modified files}
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+{Next action recommendation}
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Anti-Patterns (AVOID)
+
+- Varying box/banner widths (use 55 chars consistently)
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `CTX ►` prefix in banners
+- Random emoji (only use defined symbols above)
+- Missing Next Up block after completions
+- Plain text output without structure
+- Inconsistent indentation
+- Missing progress indicators during long operations
+
+</ui_patterns>

package/workflows/ctx-router.md

@@ -4,6 +4,10 @@ Smart router for CTX - understands natural language, detects intent, and routes
 Users don't need to memorize commands. They describe what they want, CTX routes automatically.
 </purpose>
 
+<ui_reference>
+@~/.claude/ctx/references/ui-brand.md
+</ui_reference>
+
 <intent_detection>
 Parse the user's message to detect intent. Check patterns in order:
 
@@ -50,33 +54,153 @@ Route by detected intent:
 
 ### Intent: new-project
 
+Output:
 ```
-Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 I understood: "{{user_request}}"
 
 You want to build something new. Let's set it up!
+
+───────────────────────────────────────────────────────
 ```
 
 Execute /ctx:init inline (don't tell user to run it separately).
 
 ### Intent: analyze (study/explore)
 
+Output:
 ```
-Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► DEEP STUDY
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 I understood: "{{user_request}}"
 
-Let me analyze this codebase first.
+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:
 
-**Step 1: Create structure**
+• 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 2: Create structure**
 
 ```bash
 mkdir -p .ctx/codebase
 ```
 
-**Step 2: Spawn 4 mapper agents in parallel**
+**Step 2: Show spawning indicator**
+
+Output:
+```
+◆ Spawning 4 mappers in parallel...
+  → ctx-tech-mapper
+  → ctx-arch-mapper
+  → ctx-quality-mapper
+  → ctx-concerns-mapper
+```
+
+**Step 3: Spawn 4 mapper agents in parallel**
 
 Read model profile (default to "balanced"):
 ```bash
@@ -95,73 +219,180 @@ Task(prompt="Analyze this codebase for quality patterns. Write comprehensive ana
 Task(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")
 ```
 
-**Step 3: Wait for completion**
+**Step 4: Wait for completion and show progress**
 
-Use TaskOutput to wait for all 4 agents to complete.
+Use TaskOutput to wait for each agent. As each completes, output:
 
-**Step 4: Verify output**
+```
+✓ ctx-tech-mapper complete: TECH.md ({{N}} lines)
+✓ ctx-arch-mapper complete: ARCH.md ({{N}} lines)
+✓ ctx-quality-mapper complete: QUALITY.md ({{N}} lines)
+✓ ctx-concerns-mapper complete: CONCERNS.md ({{N}} lines)
+```
+
+**Step 5: Verify output**
 
 ```bash
 ls -la .ctx/codebase/
 wc -l .ctx/codebase/*.md
 ```
 
-**Step 5: Create summary**
-
-Read all 4 documents and create SUMMARY.md:
+**Step 6: Create summary**
 
+Read all 4 documents:
 ```bash
-cat .ctx/codebase/TECH.md .ctx/codebase/ARCH.md .ctx/codebase/QUALITY.md .ctx/codebase/CONCERNS.md
+cat .ctx/codebase/TECH.md
+cat .ctx/codebase/ARCH.md
+cat .ctx/codebase/QUALITY.md
+cat .ctx/codebase/CONCERNS.md
 ```
 
 Write `.ctx/codebase/SUMMARY.md` with key findings from each document.
 
-**Step 6: Report**
+**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:
 ```
-[CTX] Codebase Mapped
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► MAPPING COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-Tech: {{stack}}
-Architecture: {{pattern}}
-Quality: {{assessment}}
-Concerns: {{count}} identified
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         {{primary_language}}, {{framework}} │
+│  Architecture: {{pattern}}                          │
+│  Quality:      {{coverage}}% coverage, {{warnings}} │
+│  Concerns:     {{concern_count}} identified         │
+└─────────────────────────────────────────────────────┘
 
-Files: .ctx/codebase/
+Files created:
+  .ctx/codebase/TECH.md
+  .ctx/codebase/ARCH.md
+  .ctx/codebase/QUALITY.md
+  .ctx/codebase/CONCERNS.md
+  .ctx/codebase/SUMMARY.md
 
----
+───────────────────────────────────────────────────────
 
-Next Up:
+## ▶ Next Up
 
-/ctx:init - Initialize project with this context
+**Initialize project** — set up CTX workflow with this context
 
----
+`/ctx:init`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- `cat .ctx/codebase/SUMMARY.md` — view full summary
+- `/ctx:map-codebase --refresh` — re-analyze codebase
+
+───────────────────────────────────────────────────────
 ```
 
 ### Intent: debug
 
+Output:
 ```
-Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► DEBUG MODE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 I understood: "{{problem_description}}"
 
-Let me analyze the codebase and investigate.
+Let me analyze the codebase first, then investigate.
+
+───────────────────────────────────────────────────────
 ```
 
 First map codebase (same as analyze), then spawn debugger agent.
 
 ### Intent: help or unknown
 
+Output:
 ```
-Welcome to CTX!
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 What would you like to do?
 
-  "Build something new"  -> I'll set up your project
-  "Fix a bug"            -> I'll debug the issue
-  "Study the codebase"   -> I'll analyze everything
-  "Test the app"         -> I'll run full QA
+┌─────────────────────────────────────────────────────┐
+│  AVAILABLE ACTIONS                                  │
+├─────────────────────────────────────────────────────┤
+│  "Build something new"   → Set up your project      │
+│  "Fix a bug"             → Debug the issue          │
+│  "Study the codebase"    → Analyze everything       │
+│  "Test the app"          → Run full QA              │
+└─────────────────────────────────────────────────────┘
 
-Just describe what you want!
+Just describe what you want in natural language!
+
+───────────────────────────────────────────────────────
 ```
 </step>
 
@@ -193,23 +424,35 @@ Extract:
 
 ### Status Report Format
 
+Output:
 ```
-[CTX] Status
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► STATUS
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 Project: {{name}}
-Status: {{status}}
+Status:  {{status}}
 Profile: {{profile}}
 
-Progress: [{{progress_bar}}] {{completed}}/{{total}} phases
+Progress: ████████░░ {{percent}}%
+
+| Phase | Status | Tasks    |
+|-------|--------|----------|
+| 1     | ✓      | 5/5      |
+| 2     | ◆      | 2/4      |
+| 3     | ○      | 0/3      |
 
 Current: {{current_phase}}
-Next: {{next_action}}
 
----
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{{next_action}}**
 
-To continue: /ctx or describe what you want to do
+`/ctx` or describe what you want to do
 
----
+───────────────────────────────────────────────────────
 ```
 </step>
 
@@ -233,9 +476,10 @@ Include research findings in agent prompts.
 - [ ] .ctx structure checked first
 - [ ] Intent detected from user message
 - [ ] Correct flow routed
+- [ ] UI patterns used consistently (banners, boxes, progress)
 - [ ] ArguSeek called for research-worthy intents
 - [ ] Task() agents spawned with full context
 - [ ] STATE.md created/updated
-- [ ] Clear "Next Up" shown
+- [ ] Clear "Next Up" shown with command
 - [ ] User knows to run /ctx to continue
 </success_criteria>