ctx-cc 3.3.4 → 3.3.6

package/README.md

@@ -13,7 +13,9 @@
 
 <img src="./assets/terminal.png" alt="CTX Terminal" width="700">
 
-**AI that learns your preferences. Predictive planning. Self-healing deployments. Voice control.**
+**Conversational-first. Just describe what you want — no commands to memorize.**
+
+AI that learns your preferences. Predictive planning. Self-healing deployments. 21 specialized agents.
 
 [Installation](#installation) · [Quick Start](#quick-start) · [New in 3.3](#new-in-33) · [Commands](#commands) · [Why CTX](#why-ctx) · [**Getting Started Guide**](./GETTING_STARTED.md)
 
@@ -40,6 +42,16 @@ npx ctx-cc --force      # Overwrite existing installation
 
 ## Quick Start
 
+**Just talk to CTX.** No commands to memorize:
+
+```
+"I want to build a todo app"     → CTX sets up your project
+"Fix the login bug"              → CTX starts debugging
+"Is my app accessible?"          → CTX runs accessibility QA
+"What should I do next?"         → CTX shows status + recommendation
+```
+
+Or use commands directly:
 ```
 1. /ctx init           Gather requirements + credentials + design context
 2. /ctx map            Build repository map (existing codebases)
@@ -48,13 +60,60 @@ npx ctx-cc --force      # Overwrite existing installation
 
 **The Flow:**
 ```
-/ctx init → /ctx map → /ctx → Autonomous loop → Delivered!
+Tell CTX what you want → CTX figures out the rest → Delivered!
 ```
 
 ---
 
 ## New in 3.3
 
+### Conversational-First Routing
+**No commands to memorize.** CTX understands natural language from your first prompt:
+
+| You Say | CTX Does |
+|---------|----------|
+| "I want to build a todo app" | Sets up project, researches best practices, creates plan |
+| "Fix the login bug" | Analyzes codebase, starts debugging |
+| "Is my app accessible?" | Runs WCAG 2.1 AA accessibility audit |
+| "Test everything" | Crawls every page, clicks every button |
+| "What's next?" | Shows status and recommended action |
+| "Ship it" | Runs verification, then deploys |
+
+**New user?** CTX welcomes you and guides setup:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+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
+```
+
+Commands still work as shortcuts for power users.
+
+### Full System QA
+Crawl every page, click every button, find all issues:
+
+```bash
+/ctx qa                     # Full system QA (WCAG 2.1 AA)
+/ctx qa --a11y-only         # Accessibility audit only
+/ctx qa --visual-only       # Visual regression (3 viewports)
+/ctx qa --resume            # Resume interrupted session
+```
+
+Features:
+- **WCAG 2.1 AA compliance** - Touch targets, alt text, labels, contrast, keyboard
+- **Multi-viewport testing** - Mobile (375px), Tablet (768px), Desktop (1280px)
+- **Performance monitoring** - Slow requests, large assets
+- **Trace capture** - Screenshots and logs for every failed interaction
+- **Fix tasks** - Issues organized by section, ready for execution
+
 ### Learning System
 CTX learns from your codebase and preferences:
 
@@ -517,8 +576,10 @@ Results synthesized into `SUMMARY.md`.
 ### QA (Full System Testing)
 | Command | Purpose |
 |---------|---------|
-| `/ctx qa` | Full system QA - every page, every button |
+| `/ctx qa` | Full system QA - WCAG 2.1 AA, every page, every button |
 | `/ctx qa --section "auth"` | QA specific section only |
+| `/ctx qa --a11y-only` | Accessibility audit only |
+| `/ctx qa --visual-only` | Visual regression (mobile/tablet/desktop) |
 | `/ctx qa --resume` | Resume interrupted QA session |
 | `/ctx qa --report` | Show last QA report |
 
@@ -790,6 +851,6 @@ MIT
 
 **[GitHub](https://github.com/jufjuf/CTX)** · **[Issues](https://github.com/jufjuf/CTX/issues)** · **[npm](https://www.npmjs.com/package/ctx-cc)**
 
-*CTX 3.3 - AI that learns your preferences. Predictive planning. Self-healing. Voice control.*
+*CTX 3.3 - Conversational-first. Just describe what you want. 21 agents. Learning system. Self-healing.*
 
 </div>

package/commands/ctx.md

@@ -1,16 +1,212 @@
 ---
 name: ctx
-description: Smart router - reads STATE.md, config.json, and does the right thing. Uses model profiles for cost optimization.
+description: Smart router - understands natural language, detects intent, and guides users from first prompt. No commands to memorize.
 ---
 
 <objective>
-CTX 3.0 Smart Router - One command that always knows what to do next.
+CTX Smart Router - Conversational-first workflow orchestration.
 
-Read STATE.md, load config.json, use appropriate model profile, and execute the right action.
+**Users don't need to know commands.** They just describe what they want, and CTX routes to the right workflow 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
+```
 </objective>
 
 <workflow>
-## Step 0: Load Configuration
+
+## 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)
@@ -22,20 +218,9 @@ If config.json doesn't exist:
 - Copy from templates/config.json
 - Set balanced as default profile
 
-## Step 1: Read State
-
-Read `.ctx/STATE.md` to understand current situation.
+## Step 4: Execute Routed Action
 
-If STATE.md doesn't exist:
-- Output: "No CTX project found. Run `/ctx init` to start."
-- Stop.
-
-Also check for:
-- `.ctx/REPO-MAP.md` - Codebase understanding
-- `.ctx/codebase/SUMMARY.md` - Deep codebase analysis
-- `.ctx/phases/{story_id}/CONTEXT.md` - Locked decisions
-
-## Step 2: Route Based on State
+Based on routing decision from Step 2:
 
 ### If status = "initializing"
 Route to: **Research Phase**
@@ -102,7 +287,7 @@ Route to: **Resume**
 3. Set status to previous state
 4. Continue workflow
 
-## Step 3: Model Selection
+## Step 5: Model Selection
 
 Based on current action and active profile:
 
@@ -118,7 +303,7 @@ Based on current action and active profile:
 
 Use Task tool with `model` parameter from routing table.
 
-## Step 4: Context Budget Check
+## Step 6: Context Budget Check
 
 After every action:
 - Calculate context usage
@@ -127,14 +312,14 @@ After every action:
 - If > 60%: Create HANDOFF.md, spawn fresh agent
 - If > 70%: Force checkpoint
 
-## Step 5: Git-Native Commit
+## 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 6: Update State
+## Step 8: Update State
 
 Always update STATE.md after any action:
 - Current status
@@ -188,7 +373,33 @@ DELIVERY GUARANTEE LOOP:
 </context_budget>
 
 <output_format>
-After routing, output:
+
+## 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}})
@@ -197,4 +408,86 @@ After routing, output:
 [CTX] Next: {{next_action}}
 [CTX] Context: {{percent}}% ({{quality}})
 ```
+
+## 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...]
+```
+
+### 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...]
+```
+
+### 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...
+```
+
+### 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...
+```
+
+</examples>

package/commands/help.md

@@ -13,10 +13,22 @@ Output ONLY the reference content below. Do NOT add project-specific analysis.
 # CTX 3.3 Command Reference
 
 **CTX** (Continuous Task eXecution) - Intelligent workflow orchestration for Claude Code.
-21 agents. Learning system. Predictive planning. Self-healing. Voice control. Full system QA.
+
+**Conversational-first.** Just describe what you want - no commands to memorize.
+21 agents. Learning system. Predictive planning. Self-healing. Full system QA.
 
 ## Quick Start
 
+**You don't need to memorize commands.** Just tell CTX what you want:
+
+```
+"I want to build a todo app"     → CTX sets up your project
+"Fix the login bug"              → CTX starts debugging
+"Is my app accessible?"          → CTX runs QA
+"What's next?"                   → CTX shows status
+```
+
+Or use commands directly:
 ```
 1. /ctx init           Initialize project + generate PRD.json
 2. /ctx map            Build repository map

package/package.json

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