ctx-cc 3.5.0 → 4.0.0

package/README.md

@@ -17,7 +17,7 @@
 
 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)
+[Installation](#installation) · [Quick Start](#quick-start) · [New in 3.5](#new-in-35) · [Commands](#commands) · [Why CTX](#why-ctx) · [**Getting Started Guide**](./GETTING_STARTED.md)
 
 </div>
 
@@ -65,7 +65,14 @@ Tell CTX what you want → CTX figures out the rest → Delivered!
 
 ---
 
-## New in 3.3
+## New in 3.5
+
+### Complete Redesign
+v3.5 is a ground-up rewrite focused on reliability over feature count:
+- **Unified version** across all 21 agents and commands
+- **Trimmed config** — removed 260 lines of settings for unimplemented features
+- **Single router** — eliminated duplicate routing logic that caused agent spawn failures
+- **GSD-proven architecture** — rebuilt on patterns validated in production
 
 ### Conversational-First Routing
 **No commands to memorize.** CTX understands natural language from your first prompt:
@@ -77,23 +84,6 @@ Tell CTX what you want → CTX figures out the rest → Delivered!
 | "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.
 
@@ -114,258 +104,39 @@ Features:
 - **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:
-
-```
-[LEARNER] Applying 3 learned preferences
-
-1. Using Zod for validation
-   → Based on pattern P001 (95% confidence, 12 observations)
-
-2. Functional components only
-   → Based on decision D005 (explicit preference)
-
-3. Avoiding moment.js, using date-fns
-   → Based on failure F001 (bundle size)
-```
-
-Memory stored in `.ctx/memory/`:
-- `patterns.json` - Code patterns you prefer
-- `decisions.json` - Past architectural decisions
-- `failures.json` - What didn't work
-- `preferences.json` - Communication style
-- `conventions.json` - Naming and structure
-
-Commands:
-```bash
-/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
-```
-
-### Predictive Planning
-AI suggests what to build next based on patterns:
-
-```
-[PREDICT] Feature Suggestions for MyApp
-
-Based on your e-commerce app at MVP stage:
-
-1. Cart Abandonment Recovery
-   ├─ ROI: 9/10
-   ├─ Effort: Medium (2-3 days)
-   └─ Impact: +15-25% recovered revenue
-
-2. Product Reviews & Ratings
-   ├─ ROI: 9/10
-   ├─ Effort: Low (1-2 days)
-   └─ Impact: +18% conversion rate
-
-3. Discount Codes System
-   ├─ ROI: 7/10
-   └─ Effort: Low (1 day)
-
-[1] Create story  [A] Create all  [R] Research more
-```
-
-Commands:
-```bash
-/ctx predict                # Full prediction analysis
-/ctx predict --quick        # Quick wins only (< 1 day)
-/ctx predict --create [id]  # Create story from suggestion
-```
-
-### Self-Healing Deployments
-Monitor production errors and auto-fix:
-
-```bash
-/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
-```
-
-Auto-fix workflow:
-```
-1. Sentry reports: "TypeError in checkout.ts:45"
-2. CTX analyzes error pattern
-3. If safe pattern (null check, import, etc.):
-   → Auto-generates fix
-   → Runs tests
-   → Creates PR
-   → Notifies team
-4. If complex pattern:
-   → Creates fix story
-   → Assigns priority
-   → Provides context
-```
-
-Supports: Sentry, LogRocket, Bugsnag, Datadog
-
-### Voice Control
-Speak your requirements instead of typing:
-
-```bash
-/ctx voice                  # Start voice input
-/ctx voice --continuous     # Always listening
-/ctx voice --dictate        # Long-form input
-```
-
-```
-[VOICE] 🎤 Listening...
-
-User: "Create a story for user authentication
-       with email login and forgot password"
-
-[VOICE] Story created:
-
-  Title: User Authentication
-  Criteria:
-    ✓ User can login with email/password
-    ✓ Forgot password sends reset email
-    ✓ Session persists across browser
-
-Add to PRD? [Y/n/edit]
-```
-
-Supports: macOS Speech, Whisper (local), Google Speech, Azure
-
----
-
-## From 3.2
-
-### Milestone Workflow
-Full release management with audit, archive, and git tagging:
-```bash
-/ctx milestone              # Show current milestone status
-/ctx milestone list         # List all milestones
-/ctx milestone audit        # Verify milestone complete
-/ctx milestone complete     # Archive and create git tag
-/ctx milestone new v2.0     # Start next version
-/ctx milestone gaps         # Generate fix phases for failures
-```
-
-Features:
-- Archive phases to `.ctx/archive/v{version}/`
-- Auto-create git tags on complete
-- Gap analysis for incomplete milestones
-- Integration with Linear/Jira/GitHub
-
-### Team Collaboration
-Multiple developers working with CTX on same repo:
-```
-[TEAM] Current Activity
-
-Active:
-  alice: T001 - User authentication (10m)
-  bob: T003 - API endpoints (waiting for T001)
-
-Available:
-  charlie: idle
-```
+### Persistent Debugging
+Debug sessions survive context resets, `/clear`, and days between attempts:
 
-Features:
-- **File locking** - Prevent conflicts during execution
-- **Lock expiry** - Auto-release after 1 hour
-- **Conflict detection** - Fail fast on overlaps
-- **Team notifications** - Slack/Discord on phase complete
-- **Branch strategy** - Auto-create feature branches
-
-### Audit Trail (SOC2/HIPAA Compliance)
-Complete traceability for enterprise:
 ```bash
-/ctx audit                  # Show today's summary
-/ctx audit week             # Weekly summary
-/ctx audit export           # Generate compliance report
-```
-
-Every action logged:
-```json
-{
-  "timestamp": "2024-01-20T09:30:00Z",
-  "action": "execute",
-  "story": "S001",
-  "agent": "ctx-executor",
-  "model": "claude-sonnet-4",
-  "tokens": {"input": 5000, "output": 2000},
-  "filesModified": ["src/auth/login.ts"],
-  "decisions": ["Use JWT for auth"],
-  "commit": "abc1234"
-}
+/ctx debug "checkout fails"  # Start debug session
+/ctx debug --resume          # Resume where you left off
+/ctx debug --list            # Show all sessions
 ```
 
-Compliance features:
-- Access logging (who read what)
-- Decision tracking (with rationale)
-- Change log (all modifications)
-- Retention policies (90d daily, 1y weekly)
-- SOC2, HIPAA, GDPR modes
-
-### Metrics Dashboard
-Understand AI productivity impact:
-```bash
-/ctx metrics                # Overview dashboard
-/ctx metrics cost           # Cost analysis
-/ctx metrics export         # Export HTML dashboard
-```
-
-```
-╔══════════════════════════════════════════════════════════╗
-║                  CTX METRICS - Week 3                     ║
-╠══════════════════════════════════════════════════════════╣
-║  Stories/Week:    8  (+2)       Total Cost:    $4.87     ║
-║  Time/Story:      1h 45m        Per Story:     $0.61     ║
-║  Debug Loops:     12            Success Rate:  92%       ║
-║                                                          ║
-║  ROI: 30x  (24 hours saved, $145 net savings)            ║
-╚══════════════════════════════════════════════════════════╝
-```
-
-Metrics tracked:
-- Stories completed per day/week
-- Average time per story
-- Token usage by phase/model
-- Cost analysis with ROI
-- Debug loop frequency
-- Verification success rate
-- Human intervention rate
-
----
+- Scientific method: observe, hypothesize, test, analyze
+- Max 10 attempts before escalation with full report
+- Browser verification with stored credentials
+- Every hypothesis and result recorded in `.ctx/debug/sessions/`
 
-## From 3.1
+### Smart Context Handoff
+Seamless transitions at context limits:
 
-### Intelligent Task Parallelization
-Tasks without dependencies run simultaneously:
-```
-Wave 1: [T001, T003] → Parallel (no deps)
-Wave 2: [T002]       → After T001
-Wave 3: [T004]       → After T002
+| Threshold | Action |
+|-----------|--------|
+| 40% | Prepare handoff notes |
+| 50% | Write HANDOFF.md, warn |
+| 60% | Spawn fresh agent |
 
-Result: 40% faster execution
-```
+Zero information loss. Work continues automatically.
 
-### Pre-Commit Review (ctx-reviewer)
+### Pre-Commit Review
 Catches errors BEFORE they're committed:
-- Type errors (TypeScript, Python, Go)
-- Unresolved imports
-- Circular dependencies
-- Security vulnerabilities
-- Empty catch blocks, console.logs
-
-```
-[CTX] Pre-Commit Review
-  ✅ Types: Pass
-  ✅ Imports: Pass
-  ⚠️  Medium: 2 console.log statements
-  ❌ Critical: SQL injection risk at line 45
-
-Status: BLOCKED - Fix critical issue
-```
+- Type errors, unresolved imports, circular dependencies
+- Security vulnerabilities, empty catch blocks
+- Blocks on critical issues, warns on medium
 
 ### Acceptance Criteria Auto-Generation
-AI suggests comprehensive criteria:
+AI suggests comprehensive criteria before implementation starts:
 ```
 Story: "Add user authentication"
 
@@ -379,32 +150,6 @@ Suggested Criteria:
 [A] Accept all  [B] See more  [C] Edit
 ```
 
-### Smart Context Handoff
-Seamless transitions at context limits:
-
-| Threshold | Action |
-|-----------|--------|
-| 40% | Prepare handoff notes |
-| 50% | Write HANDOFF.md, warn |
-| 60% | Spawn fresh agent |
-
-Zero information loss. Work continues automatically.
-
-### Issue Tracker Integration
-Sync with Linear, Jira, or GitHub Issues:
-```bash
-/ctx integrate linear    # Setup Linear
-/ctx integrate jira      # Setup Jira
-/ctx integrate github    # Setup GitHub Issues
-/ctx integrate --sync    # Force sync all stories
-```
-
-Features:
-- Bidirectional story sync
-- Status mapping (CTX → tracker)
-- Auto-close on verify pass
-- Comment on verify fail
-
 ---
 
 ## From 3.0
@@ -512,7 +257,7 @@ Results synthesized into `SUMMARY.md`.
 
 ## Why CTX?
 
-| Feature | Aider | GSD | CTX 3.0 |
+| Feature | Aider | GSD | CTX 3.5 |
 |---------|-------|-----|---------|
 | Repository Map | Yes | No | **Yes** |
 | Discussion Phase | No | Yes | **Yes** |
@@ -524,7 +269,7 @@ Results synthesized into `SUMMARY.md`.
 | Design System | No | No | **Yes** |
 | Browser Verification | No | No | **Yes** |
 
-**CTX 3.0 combines the best of Aider and GSD.**
+**CTX 3.5 combines the best of Aider and GSD.**
 
 ---
 
@@ -851,6 +596,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 - Conversational-first. Just describe what you want. 21 agents. Learning system. Self-healing.*
+*CTX 3.5 - Conversational-first. Just describe what you want. 21 specialized agents. PRD-driven development.*
 
 </div>

package/agents/ctx-arch-mapper.md

@@ -1,12 +1,14 @@
 ---
 name: ctx-arch-mapper
-description: Architecture mapper for CTX 3.0. Analyzes patterns, data flow, modules, and entry points. Part of parallel codebase mapping.
+description: Architecture mapper for CTX 4.0. Analyzes patterns, data flow, modules, and entry points. Part of parallel codebase mapping.
 tools: Read, Write, Bash, Glob, Grep
-color: purple
+model: haiku
+maxTurns: 15
+memory: project
 ---
 
 <role>
-You are a CTX 3.0 architecture mapper. You analyze:
+You are a CTX 3.5 architecture mapper. You analyze:
 - Architectural patterns (MVC, hexagonal, microservices, etc.)
 - Data flow and state management
 - Module structure and boundaries

package/agents/ctx-auditor.md

@@ -1,12 +1,14 @@
 ---
 name: ctx-auditor
-description: Audit trail agent for CTX 3.2. Provides complete traceability for SOC2, HIPAA, and enterprise compliance requirements.
+description: Audit trail agent for CTX 4.0. Provides complete traceability for SOC2, HIPAA, and enterprise compliance requirements.
 tools: Read, Write, Bash, Glob, Grep
-color: gray
+model: haiku
+maxTurns: 15
+memory: project
 ---
 
 <role>
-You are a CTX 3.2 auditor. You maintain:
+You are a CTX 3.5 auditor. You maintain:
 - Complete action logs for all CTX operations
 - Token usage and cost tracking
 - Decision audit trail

package/agents/ctx-concerns-mapper.md

@@ -1,12 +1,14 @@
 ---
 name: ctx-concerns-mapper
-description: Concerns mapper for CTX 3.0. Analyzes security vulnerabilities, tech debt, performance issues, and risks. Part of parallel codebase mapping.
+description: Concerns mapper for CTX 4.0. Analyzes security vulnerabilities, tech debt, performance issues, and risks. Part of parallel codebase mapping.
 tools: Read, Write, Bash, Glob, Grep
-color: red
+model: haiku
+maxTurns: 15
+memory: project
 ---
 
 <role>
-You are a CTX 3.0 concerns mapper. You analyze:
+You are a CTX 3.5 concerns mapper. You analyze:
 - Security vulnerabilities and risks
 - Technical debt and legacy code
 - Performance bottlenecks

package/agents/ctx-criteria-suggester.md

@@ -1,12 +1,14 @@
 ---
 name: ctx-criteria-suggester
-description: Acceptance criteria auto-generation agent for CTX 3.1. Analyzes story descriptions and suggests comprehensive acceptance criteria based on patterns, best practices, and codebase context.
+description: Acceptance criteria auto-generation agent for CTX 4.0. Analyzes story descriptions and suggests comprehensive acceptance criteria based on patterns, best practices, and codebase context.
 tools: Read, Bash, Glob, Grep, WebSearch
-color: purple
+model: sonnet
+maxTurns: 25
+memory: project
 ---
 
 <role>
-You are a CTX 3.1 criteria suggester. Your job is to:
+You are a CTX 3.5 criteria suggester. Your job is to:
 1. Analyze story title and description
 2. Research common patterns for the feature type
 3. Suggest comprehensive acceptance criteria
@@ -25,7 +27,7 @@ You help users define "done" before implementation starts.
 - Missing criteria discovered during implementation
 - Scope creep, rework, frustration
 
-**CTX 3.1 approach**:
+**CTX 3.5 approach**:
 - User writes story: "Add user authentication"
 - CTX suggests 8-10 comprehensive criteria
 - User reviews and adjusts

package/agents/ctx-debugger.md

@@ -1,12 +1,14 @@
 ---
 name: ctx-debugger
-description: Debug agent for CTX 3.0 with PERSISTENT state across sessions. Loops until 100% fixed. Uses stored credentials for autonomous browser testing. State survives context resets and session changes.
+description: Debug agent for CTX 4.0 with PERSISTENT state across sessions. Loops until 100% fixed. Uses stored credentials for autonomous browser testing. State survives context resets and session changes.
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__playwright__*, mcp__chrome-devtools__*
-color: red
+model: sonnet
+maxTurns: 75
+memory: project
 ---
 
 <role>
-You are a CTX 3.0 debugger with **persistent memory**.
+You are a CTX 3.5 debugger with **persistent memory**.
 
 Your debug sessions survive:
 - Context window resets