ctx-cc 2.3.0 → 3.0.0

package/README.md

@@ -1,6 +1,25 @@
-# CTX 2.3 - Continuous Task eXecution
+<div align="center">
 
-> Smart workflow orchestration for Claude Code. PRD-driven. Design-first. 8 commands. Debug loop until 100% fixed.
+# CTX
+
+### Continuous Task eXecution
+
+**Production-grade workflow orchestration for Claude Code.**
+
+[![npm version](https://img.shields.io/npm/v/ctx-cc.svg?style=flat-square)](https://www.npmjs.com/package/ctx-cc)
+[![npm downloads](https://img.shields.io/npm/dm/ctx-cc.svg?style=flat-square)](https://www.npmjs.com/package/ctx-cc)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
+[![GitHub stars](https://img.shields.io/github/stars/jufjuf/CTX?style=flat-square)](https://github.com/jufjuf/CTX/stargazers)
+
+<img src="./assets/terminal.png" alt="CTX Terminal" width="700">
+
+**Repository mapping. Discussion phase. Model profiles. Git-native. Persistent debug. Parallel analysis.**
+
+[Installation](#installation) · [Quick Start](#quick-start) · [New in 3.0](#new-in-30) · [Commands](#commands) · [Why CTX](#why-ctx)
+
+</div>
+
+---
 
 ## Installation
 
@@ -8,97 +27,157 @@
 npx ctx-cc
 ```
 
-Options:
+That's it. CTX installs itself to your Claude Code environment.
+
 ```bash
+# Options
 npx ctx-cc --global     # Install to ~/.claude (default)
 npx ctx-cc --project    # Install to .claude in current directory
 npx ctx-cc --force      # Overwrite existing installation
 ```
 
-## Why CTX 2.3?
-
-| Feature | Before | CTX 2.3 |
-|---------|--------|---------|
-| Requirements | Ad-hoc goals | **PRD.json with stories** |
-| Design | Manual workflow | **Full design system** |
-| Accessibility | Manual checks | **WCAG 2.2 AA + EAA 2025** |
-| Tokens | Custom formats | **W3C Design Tokens** |
-| Verification | Task-based | **Acceptance criteria** |
-| Commands | 12-27 | **8** (organized) |
-| Router | Manual | **Smart (auto-routing)** |
-| Debug | Manual | **Loop until 100% fixed** |
-| Browser Verify | No | **Playwright/DevTools** |
-| Planning | Any size | **Atomic (2-3 tasks max)** |
-| Resume cost | ~50k tokens | **~2.5k tokens** |
+---
 
 ## Quick Start
 
 ```
-1. /ctx init           Gather ALL info upfront (requirements + credentials)
-2. /ctx                Autonomous execution with minimal interruption
-3. /ctx pause          Checkpoint when needed
+1. /ctx init           Gather requirements + credentials + design context
+2. /ctx map            Build repository map (existing codebases)
+3. /ctx                Autonomous execution with minimal interruption
 ```
 
 **The Flow:**
 ```
-/ctx init → Gather everything → /ctx → Autonomous loop → Delivered!
+/ctx init → /ctx map → /ctx → Autonomous loop → Delivered!
 ```
 
-## Front-Loaded Approach
+---
 
-CTX gathers EVERYTHING at initialization:
-- **Requirements** → PRD.json stories
-- **Acceptance criteria** → How to verify each story
-- **Test credentials** → .ctx/.env (gitignored)
-- **Constitution** → Rules for autonomous decisions
-- **Design context** → Brand personality, inspirations, accessibility needs
+## New in 3.0
 
-Then executes autonomously:
-- Only interrupts for architecture decisions (Rule 4)
-- Only interrupts for design approvals at gates
-- Uses stored credentials for browser testing
-- Loops through stories until all pass
+### Repository Mapping (like Aider)
+```bash
+/ctx map                 # Build token-optimized codebase map
+/ctx map --expand        # Include call graph (8k tokens)
+/ctx map --refresh       # Force full rebuild
+```
 
-## Design System (New in 2.3)
+Creates `REPO-MAP.md` with symbols, dependencies, and navigation hints.
 
-CTX handles visual work with dedicated agents and approval gates.
+### Discussion Phase (like GSD)
+```bash
+/ctx discuss S001        # Capture decisions BEFORE planning
+/ctx discuss --review    # Review locked decisions
+```
+
+Prevents mid-implementation questions by locking decisions in `CONTEXT.md`.
 
-### Story Types
-| Type | Agent | Purpose |
-|------|-------|---------|
-| feature | ctx-executor | Standard implementation |
-| brand | ctx-designer | BRAND_KIT.md + W3C tokens |
-| design | ctx-designer | UI components/pages |
+### Model Profiles (Cost Optimization)
+```bash
+/ctx profile             # Show current profile
+/ctx profile quality     # Best models (Opus everywhere)
+/ctx profile balanced    # Smart mix (default)
+/ctx profile budget      # Fast models (60% savings)
+```
 
-### 3 Options Pattern
-All design decisions present three options:
-- **Option A**: Conservative (safe, proven)
-- **Option B**: Balanced (recommended)
-- **Option C**: Bold (distinctive)
+| Profile | Research | Execute | Verify | Cost |
+|---------|----------|---------|--------|------|
+| quality | Opus | Opus | Sonnet | 3x |
+| balanced | Opus | Sonnet | Haiku | 1x |
+| budget | Sonnet | Sonnet | Haiku | 0.4x |
 
-### Design Approval Gates
+### Git-Native Workflow
+Every completed task auto-commits:
 ```
-Mood Board → Direction (A/B/C) → Prototype → Final
+[CTX] Implement user login endpoint
+
+Story: S001 - User Authentication
+Criteria: User can log in with credentials
+Files: src/auth/login.ts, src/routes/auth.ts
+
+Co-Authored-By: Claude <noreply@anthropic.com>
 ```
-Each gate requires user approval before proceeding.
 
-### WCAG 2.2 AA + EAA 2025
-| Criterion | Requirement |
-|-----------|-------------|
-| 2.4.11 | Focus not obscured |
-| 2.5.7 | Drag alternatives |
-| 2.5.8 | 24x24px targets |
-| 3.3.8 | Accessible auth |
+Configure in `.ctx/config.json`:
+```json
+{
+  "git": {
+    "autoCommit": true,
+    "commitPerTask": true
+  }
+}
+```
 
-EU markets require EAA 2025 compliance (enforcement: June 28, 2025).
+### Persistent Debug State
+Debug sessions survive context resets:
+```bash
+/ctx debug --resume      # Continue previous session
+```
 
-## The 8 Commands
+State stored in `.ctx/debug/sessions/`:
+- `STATE.json` - Machine-readable progress
+- `TRACE.md` - Human-readable log
+- `hypotheses.json` - All theories tested
+- `screenshots/` - Visual evidence
+
+### Parallel Codebase Analysis
+```bash
+/ctx map-codebase        # Full analysis with 4 parallel agents
+```
+
+Spawns 4 agents simultaneously:
+| Agent | Output | Analyzes |
+|-------|--------|----------|
+| TECH | TECH.md | Languages, frameworks, dependencies |
+| ARCH | ARCH.md | Patterns, data flow, modules |
+| QUALITY | QUALITY.md | Test coverage, lint, type safety |
+| CONCERNS | CONCERNS.md | Security, tech debt, performance |
+
+Results synthesized into `SUMMARY.md`.
+
+---
+
+## Why CTX?
+
+| Feature | Aider | GSD | CTX 3.0 |
+|---------|-------|-----|---------|
+| Repository Map | Yes | No | **Yes** |
+| Discussion Phase | No | Yes | **Yes** |
+| Model Profiles | Yes | Partial | **Yes** |
+| Git-Native Commits | Yes | No | **Yes** |
+| Persistent Debug | No | Partial | **Yes** |
+| Parallel Analysis | No | Yes | **Yes** |
+| PRD-Driven | No | Yes | **Yes** |
+| Design System | No | No | **Yes** |
+| Browser Verification | No | No | **Yes** |
+
+**CTX 3.0 combines the best of Aider and GSD.**
+
+---
+
+## 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 |
+
+### Mapping
+| Command | Purpose |
+|---------|---------|
+| `/ctx map` | Build repository map (REPO-MAP.md) |
+| `/ctx map-codebase` | Deep analysis (4 parallel agents) |
+
+### Discussion
+| Command | Purpose |
+|---------|---------|
+| `/ctx discuss [story]` | Capture decisions before planning |
+
+### Configuration
+| Command | Purpose |
+|---------|---------|
+| `/ctx profile [name]` | Switch model profile (quality/balanced/budget) |
 
 ### Inspect (Read-only)
 | Command | Purpose |
@@ -123,206 +202,184 @@ EU markets require EAA 2025 compliance (enforcement: June 28, 2025).
 | `/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 |
 
-### Smart Router States
-
-| State | What `/ctx` does |
-|-------|------------------|
-| initializing | Research + Plan (ArguSeek + ChunkHound) |
-| executing | Execute current task |
-| debugging | **Debug loop until 100% fixed** |
-| verifying | Three-level verification |
-| paused | Resume from checkpoint |
-
-## Debug Loop (Key Feature)
+---
 
-When something breaks, CTX enters debug mode and loops until fixed:
+## State Machine
 
 ```
-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
+initializing → discussing → executing → verifying → COMPLETE
+                    ↑            ↓
+                    └── debugging ──┘
 ```
 
-**Browser verification for UI:**
-- Navigates to affected page
-- Checks elements exist
-- Takes screenshot proof
-- Saves to `.ctx/debug/`
-
-## Key Design Principles
-
-### Atomic Planning (2-3 Tasks Max)
-Why? Context degradation is real:
-| Context | Quality |
-|---------|---------|
-| 0-30% | Peak |
-| 30-50% | Good |
-| 50%+ | Degrading |
-
-Big work = multiple phases, not bigger plans.
-
-### 95% Auto-Deviation Handling
-| Trigger | Action |
-|---------|--------|
-| Bug in existing code | Auto-fix |
-| Missing validation | Auto-add |
-| Blocking issue | Auto-fix |
-| Architecture decision | Ask user |
-
-### Three-Level Verification
-1. **Exists** - File on disk?
-2. **Substantive** - Real code, not stub?
-3. **Wired** - Imported and used?
-
-### STATE.md - Single Source of Truth
-~100 lines. Always accurate. Always read first.
-
-## 6 Specialized Agents
-
-| Agent | Spawned when |
+| State | What happens |
 |-------|--------------|
-| ctx-researcher | status = initializing |
-| ctx-planner | after research |
-| ctx-executor | status = executing (feature stories) |
-| ctx-designer | status = executing (brand/design stories) |
-| ctx-debugger | status = debugging |
-| ctx-verifier | status = verifying |
+| 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 |
 
-## Integrations
+---
 
-### ArguSeek (Web Research)
-Auto-runs during planning:
-- Best practices for the goal
-- Security considerations
-- Performance patterns
+## Context Management
 
-### ChunkHound (Semantic Code Search)
-Auto-runs during planning:
-- Semantic search for relevant code
-- Pattern detection
-- Entry point mapping
+CTX actively manages context budget:
 
-Install: `uv tool install chunkhound`
+| Usage | Quality | Action |
+|-------|---------|--------|
+| 0-30% | Peak | Continue |
+| 30-40% | Good | Continue |
+| 40-50% | Good | Prepare handoff notes |
+| 50-60% | Degrading | Auto-checkpoint |
+| 60-70% | Degrading | Create HANDOFF.md |
+| 70%+ | Poor | Force checkpoint |
 
-### Browser Verification (Playwright/Chrome DevTools)
-Auto-runs during debugging and verification:
-- Navigate to pages
-- Check elements exist
-- Take screenshot proof
+Smart handoff creates `HANDOFF.md` with:
+- Completed tasks with commit hashes
+- Current task progress
+- Key decisions made
+- Files modified
+- Next steps
 
-### Figma MCP (Design Context)
-Auto-runs during design stories:
-- Extract design tokens
-- Get component metadata
-- Screenshot references
+---
 
-### Gemini Design MCP (Visual Generation)
-Auto-runs during design stories:
-- Generate UI mockups
-- Create UI code
-- Analyze designs for accessibility
+## 10 Specialized Agents
+
+| Agent | Spawned when | Model (balanced) |
+|-------|--------------|------------------|
+| ctx-mapper | /ctx map | haiku |
+| ctx-tech-mapper | /ctx map-codebase | haiku |
+| ctx-arch-mapper | /ctx map-codebase | haiku |
+| ctx-quality-mapper | /ctx map-codebase | haiku |
+| ctx-concerns-mapper | /ctx map-codebase | haiku |
+| ctx-discusser | status = discussing | sonnet |
+| ctx-researcher | status = initializing | opus |
+| ctx-planner | after research | opus |
+| ctx-executor | status = executing | sonnet |
+| ctx-designer | design stories | sonnet |
+| ctx-debugger | status = debugging | sonnet |
+| ctx-verifier | status = verifying | haiku |
+
+---
 
 ## Directory Structure
 
 ```
 .ctx/
+├── config.json       # Model profiles, git settings
 ├── STATE.md          # Living digest - execution state
-├── PRD.json          # Requirements contract - stories + criteria
-├── 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)
+├── PRD.json          # Requirements contract
+├── REPO-MAP.md       # Token-optimized codebase map
+├── REPO-MAP.json     # Structured map data
+├── .env              # Test credentials (GITIGNORED)
+├── codebase/         # Deep analysis results
+│   ├── TECH.md
+│   ├── ARCH.md
+│   ├── QUALITY.md
+│   ├── CONCERNS.md
+│   └── SUMMARY.md
+├── phases/{story_id}/
+│   ├── CONTEXT.md    # Locked decisions (discussion phase)
+│   ├── RESEARCH.md   # ArguSeek results
+│   ├── PLAN.md       # Tasks mapped to criteria
+│   └── VERIFY.md     # Verification report
+├── debug/
+│   ├── sessions/     # Persistent debug state
+│   └── screenshots/  # Visual proof
 ├── checkpoints/      # Auto-checkpoints
-├── debug/            # Debug screenshots
 └── memory/           # Decision memory
-
-project/
-├── BRAND_KIT.md      # Visual foundation (brand stories)
-└── tokens/           # W3C design tokens
-    ├── primitive.tokens.json
-    ├── semantic.tokens.json
-    └── component.tokens.json
 ```
 
-## PRD.json - Requirements Contract
+---
+
+## Configuration
 
+`.ctx/config.json`:
 ```json
 {
-  "brand": {
-    "hasBrandKit": false,
-    "personality": ["professional", "modern"],
-    "euMarket": true
+  "activeProfile": "balanced",
+  "models": {
+    "architect": { "id": "claude-opus-4", "costTier": "high" },
+    "default": { "id": "claude-sonnet-4", "costTier": "medium" },
+    "fast": { "id": "claude-haiku-4", "costTier": "low" }
   },
-  "design": {
-    "wcagLevel": "AA",
-    "eaaCompliance": true,
-    "tokenFormat": "w3c"
-  },
-  "stories": [
-    {
-      "id": "S001",
-      "type": "brand",
-      "title": "Establish brand kit",
-      "acceptanceCriteria": [
-        "BRAND_KIT.md exists",
-        "tokens/ directory populated"
-      ],
-      "passes": false
+  "profiles": {
+    "quality": {
+      "research": "architect",
+      "discussion": "architect",
+      "planning": "architect",
+      "execution": "architect"
+    },
+    "balanced": {
+      "research": "architect",
+      "discussion": "default",
+      "planning": "architect",
+      "execution": "default"
     },
-    {
-      "id": "S002",
-      "type": "design",
-      "title": "Login page",
-      "acceptanceCriteria": [
-        "WCAG 2.2 AA compliant",
-        "All states implemented"
-      ],
-      "passes": false
+    "budget": {
+      "research": "default",
+      "planning": "default",
+      "execution": "default"
     }
-  ],
-  "metadata": {
-    "currentStory": "S001",
-    "passedStories": 0,
-    "totalStories": 2
+  },
+  "git": {
+    "autoCommit": true,
+    "commitPerTask": true
   }
 }
 ```
 
-When a story passes verification, `passes` becomes `true`.
-When all stories pass, project is complete.
+---
 
-## Secure Credentials (.ctx/.env)
+## Integrations
 
-During `/ctx init`, you'll be asked for test credentials:
+### ArguSeek (Web Research)
+Auto-runs during planning for best practices, security, and patterns.
 
+### ChunkHound (Semantic Code Search)
+Auto-runs during planning for semantic search and pattern detection.
 ```bash
-# .ctx/.env (automatically gitignored)
-APP_URL=http://localhost:3000
-TEST_USER_EMAIL=test@example.com
-TEST_USER_PASSWORD=testpass123
-ADMIN_EMAIL=admin@example.com
-ADMIN_PASSWORD=adminpass123
-API_KEY=your-api-key
+uv tool install chunkhound
 ```
 
-**Why?**
-- Enables autonomous browser verification
-- No interruptions asking "what's the login?"
-- Agents use credentials silently for testing
-- NEVER echoed in logs or committed
+### Browser Verification (Playwright/Chrome DevTools)
+Auto-runs during debugging and verification for visual proof.
+
+### Figma MCP (Design Context)
+Auto-runs during design stories for tokens and component metadata.
+
+### Gemini Design MCP (Visual Generation)
+Auto-runs during design stories for mockups and UI code.
+
+---
+
+## Key Principles
+
+### 95% Auto-Deviation Handling
+
+| Trigger | Action |
+|---------|--------|
+| Bug in existing code | Auto-fix, document in commit |
+| Missing validation | Auto-add, document |
+| Blocking issue | Auto-fix, document |
+| Architecture decision | **Ask user** |
+
+### Three-Level Verification
+
+| Level | Question | Check |
+|-------|----------|-------|
+| Exists | File on disk? | Glob |
+| Substantive | Real code, not stub? | No TODOs, no placeholders |
+| Wired | Imported and used? | Trace imports |
+
+### Atomic Planning
 
-**Security:**
-- `.ctx/.gitignore` automatically protects `.env`
-- Credentials used ONLY for test automation
-- Never hardcoded, always read from .env
+Plans limited to 2-3 tasks to prevent context degradation.
+
+---
 
 ## Updating
 
@@ -330,15 +387,18 @@ API_KEY=your-api-key
 npx ctx-cc --force
 ```
 
+---
+
 ## License
 
 MIT
 
-## Links
+---
 
-- [GitHub](https://github.com/jufjuf/CTX)
-- [Issues](https://github.com/jufjuf/CTX/issues)
+<div align="center">
 
----
+**[GitHub](https://github.com/jufjuf/CTX)** · **[Issues](https://github.com/jufjuf/CTX/issues)** · **[npm](https://www.npmjs.com/package/ctx-cc)**
+
+*CTX 3.0 - Repository mapping. Discussion phase. Model profiles. Git-native. Persistent debug.*
 
-*CTX 2.3 - PRD-driven, design-first, story-verified, debug loop until 100% fixed*
+</div>