ctx-cc 3.3.3 → 3.3.5

package/commands/ctx.md

@@ -1,16 +1,137 @@
 ---
 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 |
+| "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';
+  }
+
+  // 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:init --existing |
+| `qa` | "I'll analyze the project first." → Run /ctx:map then /ctx:qa |
+| `continue` | Guide user: "What would you like to build or work on?" |
+| `help` | Show quick start guide |
+
+**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 |
+| `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 +143,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.
-
-If STATE.md doesn't exist:
-- Output: "No CTX project found. Run `/ctx init` to start."
-- Stop.
+## Step 4: Execute Routed Action
 
-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 +212,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 +228,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 +237,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 +298,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 +333,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.
-20 agents. Learning system. Predictive planning. Self-healing. Voice control.
+
+**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
@@ -103,6 +115,17 @@ Output ONLY the reference content below. Do NOT add project-specific analysis.
 | `/ctx debug --status` | Show current session status |
 | `/ctx debug --abort` | Abort current session |
 
+### QA (Full System Testing)
+| Command | Purpose |
+|---------|---------|
+| `/ctx qa` | Full system QA - crawl all pages (WCAG 2.1 AA) |
+| `/ctx qa --pages` | List discovered pages first |
+| `/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 |
+| `/ctx qa --report` | Show last QA report |
+
 ### Session
 | Command | Purpose |
 |---------|---------|