ctx-cc 3.4.1 → 3.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.4.1",
+  "version": "3.4.2",
   "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,24 +54,34 @@ 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 ► ANALYZING CODEBASE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
 I understood: "{{user_request}}"
 
-Let me analyze this codebase first.
+Let me analyze this codebase with 4 specialized mappers.
+
+───────────────────────────────────────────────────────
 ```
 
 **Step 1: Create structure**
@@ -76,7 +90,18 @@ Let me analyze this codebase first.
 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 +120,118 @@ 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 each agent. As each completes, output:
 
-Use TaskOutput to wait for all 4 agents to complete.
+```
+✓ 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 4: Verify output**
+**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: Show completion banner**
 
+Output:
 ```
-[CTX] Codebase Mapped
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► MAPPING COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         {{primary_language}}, {{framework}} │
+│  Architecture: {{pattern}}                          │
+│  Quality:      {{coverage}}% coverage, {{warnings}} │
+│  Concerns:     {{concern_count}} identified         │
+└─────────────────────────────────────────────────────┘
+
+Files created:
+  .ctx/codebase/TECH.md
+  .ctx/codebase/ARCH.md
+  .ctx/codebase/QUALITY.md
+  .ctx/codebase/CONCERNS.md
+  .ctx/codebase/SUMMARY.md
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
 
-Tech: {{stack}}
-Architecture: {{pattern}}
-Quality: {{assessment}}
-Concerns: {{count}} identified
+**Initialize project** — set up CTX workflow with this context
 
-Files: .ctx/codebase/
+`/ctx:init`
 
----
+<sub>`/clear` first → fresh context window</sub>
 
-Next Up:
+───────────────────────────────────────────────────────
 
-/ctx:init - Initialize project with this context
+**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 in natural language!
 
-Just describe what you want!
+───────────────────────────────────────────────────────
 ```
 </step>
 
@@ -193,23 +263,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 +315,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>