ctx-cc 3.3.0 → 3.3.2

package/README.md

@@ -15,7 +15,7 @@
 
 **AI that learns your preferences. Predictive planning. Self-healing deployments. Voice control.**
 
-[Installation](#installation) · [Quick Start](#quick-start) · [New in 3.3](#new-in-33) · [Commands](#commands) · [Why CTX](#why-ctx)
+[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)
 
 </div>
 
@@ -403,12 +403,31 @@ Configure in `.ctx/config.json`:
 }
 ```
 
-### Persistent Debug State
-Debug sessions survive context resets:
+### Persistent Debug Mode
+Scientific debugging with persistent state across sessions:
+
 ```bash
-/ctx debug --resume      # Continue previous session
+/ctx debug "login fails"    # Start debugging
+/ctx debug --resume         # Resume after context reset
+/ctx debug --list           # See all sessions
+```
+
+**How it works:**
+```
+1. OBSERVE   → Capture exact error, context, state
+2. RESEARCH  → Search codebase and web for similar issues
+3. HYPOTHESIZE → Form testable theory with confidence level
+4. TEST      → Apply minimal fix
+5. VERIFY    → Build + Tests + Lint + Browser
+6. ITERATE   → Refine hypothesis, max 10 attempts
 ```
 
+**Key features:**
+- Sessions survive context resets and days between attempts
+- Browser verification with stored credentials
+- Screenshots saved for each attempt
+- Escalation report if max attempts reached
+
 State stored in `.ctx/debug/sessions/`:
 - `STATE.json` - Machine-readable progress
 - `TRACE.md` - Human-readable log
@@ -486,6 +505,15 @@ Results synthesized into `SUMMARY.md`.
 | `/ctx verify` | Force three-level verification |
 | `/ctx quick "task"` | Quick task bypass |
 
+### Debug
+| Command | Purpose |
+|---------|---------|
+| `/ctx debug` | Start debugging current issue |
+| `/ctx debug "issue"` | Debug specific problem |
+| `/ctx debug --resume` | Resume last debug session |
+| `/ctx debug --list` | List all debug sessions |
+| `/ctx debug --status` | Show current session status |
+
 ### Session
 | Command | Purpose |
 |---------|---------|

package/bin/ctx.js

@@ -19,9 +19,9 @@ if (options.help) {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝\x1b[0m
 
-  \x1b[1mCTX 2.2 - Continuous Task eXecution\x1b[0m
-  PRD-driven workflow orchestration for Claude Code.
-  8 commands. Story-verified. Debug loop.
+  \x1b[1mCTX 3.3 - Continuous Task eXecution\x1b[0m
+  Intelligent workflow orchestration for Claude Code.
+  20 agents. Learning system. Predictive planning. Self-healing.
 
   \x1b[1mUsage:\x1b[0m
     npx ctx-cc [options]

package/commands/debug.md

@@ -0,0 +1,461 @@
+---
+name: ctx:debug
+description: Systematic debugging with persistent state across sessions. Scientific method. Max 10 attempts. Browser verification.
+---
+
+<objective>
+Enter debug mode to systematically fix an issue using scientific method.
+
+Debug sessions are **persistent** - they survive context resets, session restarts, and days between attempts. No context is ever lost.
+</objective>
+
+<usage>
+```bash
+/ctx:debug                      # Start debug on current issue (from STATE.md)
+/ctx:debug "description"        # Start debug with specific issue
+/ctx:debug --resume             # Resume most recent debug session
+/ctx:debug --resume {id}        # Resume specific session
+/ctx:debug --list               # List all debug sessions
+/ctx:debug --status             # Show current debug session status
+/ctx:debug --abort              # Abort current session (mark failed)
+```
+</usage>
+
+<process>
+
+## Step 1: Parse Command
+
+Check arguments:
+- No args → Check STATE.md for debug_issue, or ask user
+- `"description"` → Start fresh session with description
+- `--resume` → Resume active session
+- `--resume {id}` → Resume specific session
+- `--list` → Show sessions and exit
+- `--status` → Show current session and exit
+- `--abort` → Mark session failed and exit
+
+## Step 2: Handle List/Status/Abort (if requested)
+
+### --list
+```bash
+echo "## Debug Sessions"
+echo ""
+for session in .ctx/debug/sessions/*/; do
+  id=$(basename "$session")
+  state=$(cat "$session/STATE.json" | jq -r '.status')
+  issue=$(cat "$session/STATE.json" | jq -r '.issue.description' | head -c 50)
+  attempts=$(cat "$session/STATE.json" | jq -r '.currentAttempt')
+  echo "- $id [$state] $attempts attempts"
+  echo "  $issue..."
+done
+```
+
+Output example:
+```
+## Debug Sessions
+
+- debug-20240120-143022 [resolved] 2 attempts
+  Login form shows blank error...
+
+- debug-20240119-091500 [escalated] 10 attempts
+  API returns 500 on checkout...
+
+- debug-20240118-160045 [in_progress] 3 attempts  ← ACTIVE
+  File upload fails silently...
+```
+
+### --status
+Read `.ctx/debug/active-session.json` and show:
+- Session ID
+- Issue description
+- Current attempt number
+- Last hypothesis
+- Last result
+- Time spent
+
+### --abort
+```json
+// Update STATE.json
+{
+  "status": "aborted",
+  "abortedAt": "{timestamp}",
+  "reason": "User requested abort"
+}
+```
+Clear active-session.json and return to main router.
+
+## Step 3: Initialize or Resume Session
+
+### Resume Existing
+```javascript
+// Check for active session
+const active = JSON.parse(fs.readFileSync('.ctx/debug/active-session.json'));
+if (active.sessionId) {
+  const state = JSON.parse(fs.readFileSync(`.ctx/debug/sessions/${active.sessionId}/STATE.json`));
+  // Continue from state.currentAttempt
+}
+```
+
+### Start Fresh
+```javascript
+const sessionId = `debug-${date}-${time}`;
+const sessionDir = `.ctx/debug/sessions/${sessionId}`;
+
+// Create session directory
+fs.mkdirSync(sessionDir, { recursive: true });
+fs.mkdirSync(`${sessionDir}/screenshots`, { recursive: true });
+
+// Initialize STATE.json
+const state = {
+  sessionId,
+  created: new Date().toISOString(),
+  updated: new Date().toISOString(),
+  status: "in_progress",
+  issue: {
+    description: userDescription,
+    type: null,  // Will classify
+    severity: null,
+    errorMessage: null,
+    stackTrace: null,
+    stepsToReproduce: []
+  },
+  attempts: [],
+  currentAttempt: 0,
+  maxAttempts: 10  // From config.json
+};
+
+// Set as active
+fs.writeFileSync('.ctx/debug/active-session.json', JSON.stringify({ sessionId }));
+```
+
+## Step 4: Gather Issue Context
+
+### Automatic Detection
+1. Check build output for errors
+2. Check test output for failures
+3. Check STATE.md for debug_issue
+4. Check git diff for recent changes
+
+### Classify Issue Type
+```
+build    → Compilation/bundling errors
+test     → Test failures
+runtime  → Crashes, exceptions
+ui       → Visual/interaction bugs
+api      → Backend/network errors
+perf     → Performance issues
+```
+
+### Document in STATE.json
+```json
+{
+  "issue": {
+    "description": "Login form submits but shows blank error",
+    "type": "ui",
+    "severity": "high",
+    "errorMessage": "TypeError: Cannot read property 'message' of undefined",
+    "stackTrace": "at handleSubmit (login.tsx:45)...",
+    "stepsToReproduce": [
+      "Go to /login",
+      "Enter invalid credentials",
+      "Click submit",
+      "Observe blank error message"
+    ],
+    "affectedFiles": ["src/auth/login.tsx"],
+    "relatedCommits": ["abc1234"]
+  }
+}
+```
+
+## Step 5: Spawn ctx-debugger Agent
+
+```
+Task tool:
+  subagent_type: ctx-debugger
+  prompt: |
+    Resume debug session: {sessionId}
+
+    Issue: {issue.description}
+    Type: {issue.type}
+    Error: {issue.errorMessage}
+
+    Previous attempts: {attempts.length}
+    Last result: {lastAttempt.result}
+    Last learning: {lastAttempt.learnings}
+
+    Continue debugging. Max {remainingAttempts} more attempts.
+
+    Credentials available in .ctx/.env for browser testing.
+```
+
+## Step 6: Monitor Progress
+
+The debugger agent will:
+
+1. **Form Hypothesis** based on:
+   - Error analysis
+   - Previous attempts (if any)
+   - Codebase patterns
+   - Web research
+
+2. **Apply Minimal Fix**
+   - Single focused change
+   - No collateral modifications
+
+3. **Verify All Layers**
+   - Build passes
+   - Tests pass
+   - Lint passes
+   - Browser works (if UI)
+
+4. **Record Result**
+   - Update STATE.json
+   - Append to TRACE.md
+   - Save screenshots
+
+5. **Loop or Exit**
+   - If fixed → Mark resolved
+   - If max attempts → Escalate
+   - Otherwise → Next hypothesis
+
+## Step 7: Handle Outcomes
+
+### Success (resolved)
+```
+[DEBUG] ✅ Issue resolved!
+
+Session: debug-20240120-143022
+Issue: Login form shows blank error
+Attempts: 2
+Duration: 15 minutes
+
+Root Cause:
+  Error state was logged but not set in React state
+
+Fix Applied:
+  src/auth/login.tsx:45 - Added setError() call
+
+Files Changed:
+  - src/auth/login.tsx
+
+Commit: abc1234
+
+Full trace: .ctx/debug/sessions/debug-20240120-143022/TRACE.md
+```
+
+Update STATE.md:
+- Set status = "executing"
+- Clear debug_issue
+- Log resolution
+
+### Escalation (max attempts)
+```
+[DEBUG] ⚠️ Max attempts reached (10)
+
+Session: debug-20240119-091500
+Issue: API returns 500 on checkout
+Duration: 2 hours
+
+What We Tried:
+  1. [FAIL] Null check on request body
+  2. [FAIL] Validate payment data format
+  3. [PARTIAL] Fix database connection pool
+  ...
+
+What We Know:
+  - Error occurs only with specific product combinations
+  - Database connection is stable
+  - Payment API returns valid response
+
+Possible Root Causes:
+  1. [60%] Race condition in inventory check
+  2. [30%] Stale cache invalidation
+
+Recommended:
+  - Add logging to checkInventory()
+  - Review concurrent order tests
+
+Full report: .ctx/debug/sessions/debug-20240119-091500/ESCALATION.md
+```
+
+Ask user:
+- Provide more context?
+- Try different approach?
+- Manual investigation?
+
+</process>
+
+<debug_philosophy>
+
+## Scientific Method
+
+```
+OBSERVE   → Exact error, context, state
+RESEARCH  → Similar issues, web search
+HYPOTHESIZE → Testable theory with confidence
+PREDICT   → Expected outcome if correct
+TEST      → Apply minimal fix
+ANALYZE   → Did prediction match?
+ITERATE   → Refine and repeat
+```
+
+## Hypothesis Confidence Levels
+
+| Confidence | Meaning | Action |
+|------------|---------|--------|
+| 90%+ | Strong evidence, likely root cause | Test first |
+| 70-90% | Good evidence, probable cause | Test early |
+| 50-70% | Some evidence, possible cause | Test if higher fails |
+| <50% | Weak evidence, unlikely | Last resort |
+
+## Fix Principles
+
+1. **Minimal** - Change only what's necessary
+2. **Focused** - One hypothesis per attempt
+3. **Reversible** - Easy to undo if wrong
+4. **Documented** - Clear diff and rationale
+
+## Verification Layers
+
+| Layer | What | How |
+|-------|------|-----|
+| 1 | Build | `npm run build` or equivalent |
+| 2 | Tests | Run affected test files |
+| 3 | Lint | `npm run lint` |
+| 4 | Browser | Playwright/Chrome DevTools |
+
+All layers must pass for "resolved" status.
+
+</debug_philosophy>
+
+<persistence>
+
+## Why Persistence Matters
+
+Regular debugging:
+```
+Session 1: Try 3 fixes, context resets
+Session 2: Forget what was tried, repeat same fixes
+Session 3: Still stuck, no progress
+```
+
+CTX debugging:
+```
+Session 1: Try 3 fixes, save state
+Session 2: Load state, know what failed, try fix 4
+Session 3: Load state, try fix 5, success!
+```
+
+## State Files
+
+```
+.ctx/debug/
+├── active-session.json     # Current session pointer
+└── sessions/
+    └── debug-20240120-143022/
+        ├── STATE.json      # Machine-readable state
+        ├── TRACE.md        # Human-readable log
+        ├── hypotheses.json # All hypotheses
+        └── screenshots/    # Visual evidence
+```
+
+## Resume After Days
+
+```bash
+# Monday - start debugging
+/ctx:debug "checkout fails"
+# Try 3 fixes, no luck, go home
+
+# Wednesday - resume
+/ctx:debug --resume
+# CTX knows: 3 attempts failed, here's what we learned
+# Continues from attempt 4
+```
+
+</persistence>
+
+<browser_verification>
+
+## Autonomous Browser Testing
+
+CTX uses stored credentials from `.ctx/.env`:
+
+```bash
+APP_URL=http://localhost:3000
+TEST_USER_EMAIL=test@example.com
+TEST_USER_PASSWORD=testpass123
+```
+
+### Verification Flow
+
+```javascript
+// 1. Navigate to app
+browser_navigate({ url: process.env.APP_URL });
+
+// 2. Login if needed
+browser_snapshot();
+if (page.includes('login')) {
+  browser_type({ ref: 'email-input', text: process.env.TEST_USER_EMAIL });
+  browser_type({ ref: 'password-input', text: process.env.TEST_USER_PASSWORD });
+  browser_click({ ref: 'submit-button' });
+}
+
+// 3. Navigate to affected page
+browser_navigate({ url: `${process.env.APP_URL}/affected-page` });
+
+// 4. Reproduce issue
+browser_snapshot();
+// ... interaction steps
+
+// 5. Verify fix
+browser_snapshot();
+browser_take_screenshot({ filename: `attempt-${n}.png` });
+```
+
+### Screenshot Evidence
+
+Every attempt saves screenshots:
+```
+screenshots/
+├── issue-initial.png    # Before any fixes
+├── attempt-1.png        # After fix 1
+├── attempt-2.png        # After fix 2
+├── attempt-3-success.png # Fixed!
+```
+
+</browser_verification>
+
+<config>
+
+## Debug Settings
+
+In `.ctx/config.json`:
+
+```json
+{
+  "debug": {
+    "maxAttempts": 10,
+    "persistSessions": true,
+    "screenshotOnFailure": true,
+    "autoResume": true
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| maxAttempts | 10 | Max tries before escalation |
+| persistSessions | true | Save state across sessions |
+| screenshotOnFailure | true | Capture on each failed attempt |
+| autoResume | true | Auto-resume if active session exists |
+
+</config>
+
+<output>
+After spawning ctx-debugger, report:
+- Session status (in_progress / resolved / escalated)
+- Attempts made
+- If resolved: root cause, fix, commit
+- If escalated: report path, recommendations
+- Next action for main router
+</output>

package/commands/help.md

@@ -4,134 +4,237 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 2.3 command reference.
+Display the CTX 3.3 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 2.3 Command Reference
+# CTX 3.3 Command Reference
 
-**CTX** (Continuous Task eXecution) - Smart workflow orchestration for Claude Code.
-8 commands. PRD-driven. Design-first. Smart routing. Debug loop until 100% fixed.
+**CTX** (Continuous Task eXecution) - Intelligent workflow orchestration for Claude Code.
+20 agents. Learning system. Predictive planning. Self-healing. Voice control.
 
 ## Quick Start
 
 ```
 1. /ctx init           Initialize project + generate PRD.json
-2. /ctx                Smart router does the right thing
-3. /ctx status         Check progress (read-only)
-4. /ctx pause          Checkpoint when needed
+2. /ctx map            Build repository map
+3. /ctx                Smart router does the right thing
+4. /ctx status         Check progress (read-only)
 ```
 
-## What's New in 2.3
+## What's New in 3.3
 
-- **Design System Integration** - Full brand + UI design workflow
-- **ctx-designer Agent** - WCAG 2.2 AA, W3C tokens, Figma MCP, Gemini
-- **Story Types** - feature, brand, design, fix, refactor
-- **3 Options Pattern** - Always present A/B/C for design decisions
-- **Visual Approval Gates** - Mood board → Direction → Prototype → Final
-- **BRAND_KIT.md** - Visual foundation with W3C design tokens
-- **EAA 2025 Ready** - European Accessibility Act compliance
+- **Learning System** - CTX learns your patterns, decisions, preferences
+- **Predictive Planning** - AI suggests what to build next with ROI scoring
+- **Self-Healing** - Monitor production errors, auto-create fixes
+- **Voice Control** - Speak commands and dictate stories
 
-## What's in 2.2
+## What's in 3.2
 
-- **Front-Loaded Approach** - Gather ALL info upfront, execute autonomously
-- **PRD.json** - Requirements contract with user stories
-- **Secure Credentials** - `.ctx/.env` for test credentials (gitignored)
-- **Acceptance Criteria** - Each story has verifiable criteria
-- **`passes` Flag** - Auto-tracks story completion
-- **Story-Driven Workflow** - Plan → Execute → Verify → Next Story
+- **Milestone Workflow** - Full release management with git tagging
+- **Team Collaboration** - File locking, conflict detection, notifications
+- **Audit Trail** - SOC2/HIPAA/GDPR compliance logging
+- **Metrics Dashboard** - Stories/day, cost analysis, ROI tracking
 
-## Front-Loaded Philosophy
+## What's in 3.1
 
-```
-/ctx init gathers:
-├── Requirements → PRD.json stories
-├── Context → problem, target user, success criteria
-├── Credentials → .ctx/.env (gitignored)
-└── Constitution → rules for autonomous decisions
-
-Then /ctx runs autonomously:
-├── Only interrupts for architecture decisions
-├── Uses stored credentials for browser testing
-└── Loops until all stories pass
-```
+- **Task Parallelization** - Run independent tasks simultaneously
+- **Pre-Commit Review** - Catch errors before commit
+- **Criteria Auto-Gen** - AI-suggested acceptance criteria
+- **Smart Handoff** - Seamless context transitions
+- **Issue Tracker Sync** - Linear, Jira, GitHub Issues
 
-## The 8 Commands
+## What's in 3.0
 
-### Smart (Auto-routing)
+- **Repository Mapping** - Token-optimized codebase map
+- **Discussion Phase** - Capture decisions before planning
+- **Model Profiles** - quality/balanced/budget routing
+- **Git-Native** - Auto-commit per task
+- **Persistent Debug** - Sessions survive context resets
+- **Parallel Codebase Analysis** - 4 mapper agents
+
+---
+
+## Commands
 
+### Smart (Auto-routing)
 | Command | Purpose |
 |---------|---------|
 | `/ctx` | **Smart router** - reads STATE.md, does the right thing |
-| `/ctx init` | Initialize project with STATE.md |
+| `/ctx init` | Initialize project with STATE.md + PRD.json |
 
-### Inspect (Read-only)
+### Mapping
+| Command | Purpose |
+|---------|---------|
+| `/ctx map` | Build repository map (REPO-MAP.md) |
+| `/ctx map-codebase` | Deep analysis (4 parallel agents) |
 
+### Discussion
 | Command | Purpose |
 |---------|---------|
-| `/ctx status` | See current state without triggering action |
+| `/ctx discuss [story]` | Capture decisions before planning |
 
-### Control (Override smart router)
+### Configuration
+| Command | Purpose |
+|---------|---------|
+| `/ctx profile [name]` | Switch model profile (quality/balanced/budget) |
 
+### Inspect (Read-only)
+| Command | Purpose |
+|---------|---------|
+| `/ctx status` | See current state without triggering action |
+
+### Control (Override)
 | Command | Purpose |
 |---------|---------|
 | `/ctx plan [goal]` | Force research + planning |
 | `/ctx verify` | Force three-level verification |
-| `/ctx quick "task"` | Quick task bypass (skip workflow) |
+| `/ctx quick "task"` | Quick task bypass |
 
-### Session
+### Debug
+| Command | Purpose |
+|---------|---------|
+| `/ctx debug` | Start debugging current issue |
+| `/ctx debug "issue"` | Debug specific problem |
+| `/ctx debug --resume` | Resume last debug session |
+| `/ctx debug --list` | List all debug sessions |
+| `/ctx debug --status` | Show current session status |
+| `/ctx debug --abort` | Abort current session |
 
+### Session
 | Command | Purpose |
 |---------|---------|
 | `/ctx pause` | Checkpoint for session resume |
 
 ### Phase Management
-
 | Command | Purpose |
 |---------|---------|
-| `/ctx phase list` | Show all phases with status |
-| `/ctx phase add "goal"` | Add new phase to roadmap |
+| `/ctx phase list` | Show all phases |
+| `/ctx phase add "goal"` | Add new phase |
 | `/ctx phase next` | Complete current, move to next |
-| `/ctx phase skip` | Skip current phase |
+
+### Integration
+| Command | Purpose |
+|---------|---------|
+| `/ctx integrate` | Show integration status |
+| `/ctx integrate linear` | Setup Linear |
+| `/ctx integrate jira` | Setup Jira |
+| `/ctx integrate github` | Setup GitHub Issues |
+
+### Milestone
+| Command | Purpose |
+|---------|---------|
+| `/ctx milestone` | Show current milestone |
+| `/ctx milestone list` | List all milestones |
+| `/ctx milestone audit` | Verify completion |
+| `/ctx milestone complete` | Archive and tag |
+| `/ctx milestone new [name]` | Start next version |
+
+### Metrics & Audit
+| Command | Purpose |
+|---------|---------|
+| `/ctx metrics` | Show productivity dashboard |
+| `/ctx metrics cost` | Cost analysis |
+| `/ctx metrics export` | Export HTML dashboard |
+| `/ctx audit` | Show audit summary |
+| `/ctx audit export` | Generate compliance report |
+
+### Learning & Prediction
+| Command | Purpose |
+|---------|---------|
+| `/ctx learn` | Show what CTX has learned |
+| `/ctx learn patterns` | Show code patterns |
+| `/ctx learn decisions` | Show architectural decisions |
+| `/ctx learn forget [id]` | Remove a learned pattern |
+| `/ctx predict` | Get feature suggestions |
+| `/ctx predict --quick` | Quick wins only |
+| `/ctx predict --create [id]` | Create story from suggestion |
+
+### Monitoring & Voice
+| Command | Purpose |
+|---------|---------|
+| `/ctx monitor` | Show monitoring status |
+| `/ctx monitor connect sentry` | Connect Sentry |
+| `/ctx monitor errors` | List recent errors |
+| `/ctx monitor auto-fix [id]` | Auto-fix with PR |
+| `/ctx monitor --watch` | Continuous monitoring |
+| `/ctx voice` | Start voice input |
+| `/ctx voice --continuous` | Always listening mode |
+| `/ctx voice --dictate` | Long-form dictation |
 
 ---
 
 ## Smart Router States
 
-When you run `/ctx`, it reads STATE.md and PRD.json, auto-routes:
-
 | State | What happens |
 |-------|--------------|
-| initializing | Research + Plan for current story |
-| executing | Execute tasks for current story |
-| debugging | **Debug loop until 100% fixed** |
-| verifying | Verify acceptance criteria → mark story as passed |
+| initializing | Research + Map + Plan |
+| discussing | Capture decisions in CONTEXT.md |
+| executing | Execute with git-native commits |
+| debugging | Persistent debug loop (max 10 attempts) |
+| verifying | Three-level verification |
 | paused | Resume from checkpoint |
 
-**Story Flow:**
+## Model Profiles
+
+| Profile | Research | Execute | Verify | Cost |
+|---------|----------|---------|--------|------|
+| quality | Opus | Opus | Sonnet | 3x |
+| balanced | Opus | Sonnet | Haiku | 1x |
+| budget | Sonnet | Sonnet | Haiku | 0.4x |
+
+## 20 Specialized Agents
+
+| Agent | Purpose |
+|-------|---------|
+| ctx-mapper | Repository mapping |
+| ctx-tech-mapper | Technology analysis |
+| ctx-arch-mapper | Architecture analysis |
+| ctx-quality-mapper | Quality analysis |
+| ctx-concerns-mapper | Security/debt analysis |
+| ctx-discusser | Decision capture |
+| ctx-researcher | Web research |
+| ctx-planner | Task planning |
+| ctx-executor | Code execution |
+| ctx-designer | Design/brand work |
+| ctx-debugger | Persistent debugging |
+| ctx-verifier | Three-level verification |
+| ctx-parallelizer | Task parallelization |
+| ctx-reviewer | Pre-commit review |
+| ctx-criteria-suggester | Criteria generation |
+| ctx-handoff | Context transitions |
+| ctx-team-coordinator | Team collaboration |
+| ctx-auditor | Compliance logging |
+| ctx-learner | Pattern learning |
+| ctx-predictor | Feature prediction |
+
+## Key Features
+
+### Learning System
 ```
-S001 → plan → execute → verify ✓ → S002 → plan → execute → verify ✓ → ...
+.ctx/memory/
+├── patterns.json      # Code patterns you prefer
+├── decisions.json     # Past architectural decisions
+├── failures.json      # What didn't work
+└── preferences.json   # Communication style
 ```
 
-## Debug Loop
-
-When something breaks, CTX enters debug mode:
+### Predictive Planning
+- Pattern matching (e-commerce, SaaS, social)
+- ROI scoring for suggestions
+- Auto story generation
 
-```
-Loop (max 5 attempts):
-  1. Analyze error
-  2. Form hypothesis
-  3. Apply fix
-  4. Verify (build + tests + browser)
-  5. If fixed → done
-     If not → new hypothesis, try again
-```
+### Self-Healing
+- Sentry, LogRocket, Bugsnag, Datadog
+- Auto-fix safe patterns
+- PR creation with tests
 
-**Browser verification for UI:**
-- Playwright or Chrome DevTools
-- Screenshots saved to `.ctx/debug/`
+### Voice Control
+- Command recognition
+- Story dictation
+- Continuous listening mode
 
 ## Three-Level Verification
 
@@ -141,148 +244,34 @@ Loop (max 5 attempts):
 | Substantive | Real code, not stub? | No TODOs, no placeholders |
 | Wired | Imported and used? | Trace imports |
 
-## Design Workflow
+## Context Budget
 
-CTX handles visual work with dedicated agents and approval gates.
-
-### Story Types
-| Type | Agent | Purpose |
-|------|-------|---------|
-| feature | ctx-executor | Standard implementation |
-| brand | ctx-designer | BRAND_KIT.md + tokens |
-| design | ctx-designer | UI components/pages |
-| fix | ctx-debugger | Bug fixes |
-| refactor | ctx-executor | Code improvements |
-
-### Design Approval Gates
-```
-Mood Board → Direction (A/B/C) → Prototype → Final
-```
-Each gate requires user approval before proceeding.
-
-### 3 Options Pattern
-All design decisions present:
-- **Option A**: Conservative (safe, proven)
-- **Option B**: Balanced (recommended)
-- **Option C**: Bold (distinctive)
-
-### WCAG 2.2 AA Compliance
-| Criterion | Requirement |
-|-----------|-------------|
-| 2.4.11 | Focus not obscured |
-| 2.5.7 | Drag alternatives |
-| 2.5.8 | 24x24px targets |
-| 3.3.8 | Accessible auth |
-
-### W3C Design Tokens
-```
-tokens/
-├── primitive.tokens.json  # Raw values
-├── semantic.tokens.json   # Purpose aliases
-└── component.tokens.json  # Component-specific
-```
-
-## Key Design Principles
-
-### Atomic Planning (2-3 Tasks Max)
-Prevents context degradation. Big work = multiple phases.
-
-### 95% Auto-Deviation Handling
-| Trigger | Action |
-|---------|--------|
-| Bug in existing code | Auto-fix |
-| Missing validation | Auto-add |
-| Blocking issue | Auto-fix |
-| Architecture decision | Ask user |
-
-### Context Budget
 | Usage | Quality | Action |
 |-------|---------|--------|
 | 0-30% | Peak | Continue |
-| 30-50% | Good | Continue |
-| 50%+ | Degrading | Auto-checkpoint |
-
-## 6 Specialized Agents
-
-| Agent | When spawned |
-|-------|--------------|
-| ctx-researcher | During planning (ArguSeek + ChunkHound) |
-| ctx-planner | After research |
-| ctx-executor | During execution (feature stories) |
-| ctx-designer | During execution (brand/design stories) |
-| ctx-debugger | When debugging |
-| ctx-verifier | During verification |
-
-## Integrations
-
-- **ArguSeek**: Web research during planning
-- **ChunkHound**: Semantic code search (`uv tool install chunkhound`)
-- **Playwright/DevTools**: Browser verification for UI
-- **Figma MCP**: Design context extraction and screenshots
-- **Gemini Design**: Image generation and UI code generation
+| 30-40% | Good | Continue |
+| 40-50% | Good | Prepare handoff |
+| 50-60% | Degrading | Auto-checkpoint |
+| 60-70% | Degrading | Create HANDOFF.md |
+| 70%+ | Poor | Force checkpoint |
 
 ## Directory Structure
 
 ```
 .ctx/
-├── STATE.md          # Living digest - execution state
-├── PRD.json          # Requirements contract - stories + criteria
-├── .env              # Test credentials (GITIGNORED)
-├── .gitignore        # Protects secrets
-├── phases/{story_id}/  # Per-story data
-│   ├── RESEARCH.md   # ArguSeek + ChunkHound results
-│   ├── PLAN.md       # Tasks mapped to acceptance criteria
-│   ├── VERIFY.md     # Verification report
-│   ├── MOOD_BOARD.md # Design references (design stories)
-│   └── DESIGN_BRIEF.md # Design decisions (design stories)
+├── config.json       # Model profiles, git settings
+├── STATE.md          # Execution state
+├── PRD.json          # Requirements contract
+├── REPO-MAP.md       # Codebase map
+├── codebase/         # Deep analysis
+├── phases/           # Per-story data
+├── memory/           # Learned patterns
+├── audit/            # Compliance logs
+├── metrics/          # Productivity data
+├── debug/            # Debug sessions
 ├── checkpoints/      # Auto-checkpoints
-├── debug/            # Debug screenshots
-└── verify/           # Verification screenshots
-
-project/
-├── BRAND_KIT.md      # Visual foundation (brand stories)
-└── tokens/           # W3C design tokens
-    ├── primitive.tokens.json
-    ├── semantic.tokens.json
-    └── component.tokens.json
-```
-
-## PRD.json Structure
-
-```json
-{
-  "brand": {
-    "hasBrandKit": false,
-    "personality": ["professional", "modern"],
-    "euMarket": true
-  },
-  "design": {
-    "wcagLevel": "AA",
-    "eaaCompliance": true,
-    "tokenFormat": "w3c"
-  },
-  "stories": [
-    {
-      "id": "S001",
-      "type": "brand",
-      "title": "Establish brand kit",
-      "acceptanceCriteria": ["BRAND_KIT.md exists", "tokens/ populated"],
-      "passes": false
-    },
-    {
-      "id": "S002",
-      "type": "design",
-      "title": "Login page",
-      "acceptanceCriteria": ["WCAG 2.2 AA compliant", "All states implemented"],
-      "passes": false
-    }
-  ],
-  "metadata": {
-    "currentStory": "S001",
-    "passedStories": 0,
-    "totalStories": 5
-  }
-}
+├── milestones/       # Milestone archives
+└── locks/            # Team file locks
 ```
 
 ## Updating CTX
@@ -292,5 +281,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 2.3 - PRD-driven, design-first, story-verified, debug loop until 100% fixed*
+*CTX 3.3 - Learning. Prediction. Self-healing. Voice control.*
 </reference>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.3.0",
+  "version": "3.3.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/src/install.js

@@ -28,9 +28,9 @@ function printBanner() {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝
 `));
-  console.log(`  ${bold('CTX 2.2')} ${dim(`v${VERSION}`)}`);
-  console.log('  PRD-driven workflow orchestration for Claude Code.');
-  console.log('  8 commands. Story-verified. Debug loop.\n');
+  console.log(`  ${bold('CTX 3.3')} ${dim(`v${VERSION}`)}`);
+  console.log('  Intelligent workflow orchestration for Claude Code.');
+  console.log('  20 agents. Learning system. Predictive planning. Self-healing.\n');
 }
 
 function copyDir(src, dest) {