ctx-cc 2.0.0 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
-# CTX 2.0 - Continuous Task eXecution
+# CTX 2.1 - Continuous Task eXecution
 
-> Smart workflow orchestration for Claude Code. 4 commands. Debug loop until 100% fixed.
+> Smart workflow orchestration for Claude Code. 8 commands. Smart routing. Debug loop until 100% fixed.
 
 ## Installation
 
@@ -15,11 +15,11 @@ npx ctx-cc --project    # Install to .claude in current directory
 npx ctx-cc --force      # Overwrite existing installation
 ```
 
-## Why CTX 2.0?
+## Why CTX 2.1?
 
-| Feature | Before | CTX 2.0 |
+| Feature | Before | CTX 2.1 |
 |---------|--------|---------|
-| Commands | 12-27 | **4** |
+| Commands | 12-27 | **8** (organized) |
 | Router | Manual | **Smart (auto-routing)** |
 | Debug | Manual | **Loop until 100% fixed** |
 | Browser Verify | No | **Playwright/DevTools** |
@@ -36,15 +36,39 @@ npx ctx-cc --force      # Overwrite existing installation
 
 That's it. `/ctx` reads STATE.md and knows what to do next.
 
-## The 4 Commands
+## The 8 Commands
 
+### Smart (Auto-routing)
 | Command | Purpose |
 |---------|---------|
-| `/ctx` | Smart router - reads STATE.md, does the right thing |
+| `/ctx` | **Smart router** - reads STATE.md, does the right thing |
 | `/ctx init` | Initialize project with STATE.md |
-| `/ctx quick "task"` | Quick task bypass (skip workflow) |
+
+### 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 |
+
+### Session
+| Command | Purpose |
+|---------|---------|
 | `/ctx pause` | Checkpoint for session resume |
 
+### Phase Management
+| Command | Purpose |
+|---------|---------|
+| `/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 |

package/bin/ctx.js

@@ -19,9 +19,9 @@ if (options.help) {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝\x1b[0m
 
-  \x1b[1mCTX 2.0 - Continuous Task eXecution\x1b[0m
+  \x1b[1mCTX 2.1 - Continuous Task eXecution\x1b[0m
   Smart workflow orchestration for Claude Code.
-  4 commands. Debug loop. 100% verified.
+  8 commands. Smart routing. Debug loop.
 
   \x1b[1mUsage:\x1b[0m
     npx ctx-cc [options]

package/commands/help.md

@@ -4,58 +4,79 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 2.0 command reference.
+Display the CTX 2.1 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 2.0 Command Reference
+# CTX 2.1 Command Reference
 
 **CTX** (Continuous Task eXecution) - Smart workflow orchestration for Claude Code.
-4 commands. One smart router. Debug loop until 100% fixed.
+8 commands. Smart routing. Debug loop until 100% fixed.
 
 ## Quick Start
 
 ```
-1. /ctx init           Initialize project with STATE.md
-2. /ctx                Smart router - does the right thing
-3. (repeat until done)
+1. /ctx init           Initialize project
+2. /ctx                Smart router does the right thing
+3. /ctx status         Check progress (read-only)
 4. /ctx pause          Checkpoint when needed
 ```
 
-That's it. `/ctx` reads STATE.md and knows what to do next.
+## The 8 Commands
 
-## The 4 Commands
+### Smart (Auto-routing)
 
-### `/ctx`
-**The smart router.** Reads STATE.md, does the right action:
+| Command | Purpose |
+|---------|---------|
+| `/ctx` | **Smart router** - reads STATE.md, does the right thing |
+| `/ctx init` | Initialize project with STATE.md |
+
+### Inspect (Read-only)
+
+| Command | Purpose |
+|---------|---------|
+| `/ctx status` | See current state without triggering action |
+
+### Control (Override smart router)
+
+| Command | Purpose |
+|---------|---------|
+| `/ctx plan [goal]` | Force research + planning |
+| `/ctx verify` | Force three-level verification |
+| `/ctx quick "task"` | Quick task bypass (skip workflow) |
+
+### 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 next` | Complete current, move to next |
+| `/ctx phase skip` | Skip current phase |
+
+---
+
+## Smart Router States
+
+When you run `/ctx`, it reads STATE.md and auto-routes:
 
 | State | What happens |
 |-------|--------------|
 | initializing | Research + Plan (ArguSeek + ChunkHound) |
 | executing | Execute current task |
-| debugging | Debug loop until 100% fixed |
+| debugging | **Debug loop until 100% fixed** |
 | verifying | Three-level verification |
 | paused | Resume from checkpoint |
 
-Just run `/ctx` and it figures out what's needed.
-
-### `/ctx init`
-Initialize a new project. Creates `.ctx/STATE.md`.
-
-### `/ctx quick "task"`
-Quick task bypass. Skip the workflow for small fixes.
-```
-/ctx quick "fix the button color"
-/ctx quick "add console.log for debugging"
-```
-
-### `/ctx pause`
-Create checkpoint. Safe to close session.
-Resume later with `/ctx` - auto-restores in ~2.5k tokens.
-
-## Debug Loop (New in 2.0)
+## Debug Loop
 
 When something breaks, CTX enters debug mode:
 
@@ -65,63 +86,23 @@ Loop (max 5 attempts):
   2. Form hypothesis
   3. Apply fix
   4. Verify (build + tests + browser)
-  5. If fixed: done
-     If not: new hypothesis, try again
+  5. If fixed → done
+     If not → new hypothesis, try again
 ```
 
 **Browser verification for UI:**
-- Navigates to affected page
-- Checks elements exist
-- Takes screenshot proof
-- Saves to `.ctx/debug/`
-
-## Architecture
-
-### STATE.md - Single Source of Truth
-~100 lines. Always accurate. Always read first.
-
-```markdown
-## Project
-- Name, Stack, Status
-
-## Current Phase
-- Goal, Progress
-
-## Active Task
-- What, Status, Attempts
-
-## Debug Session (if active)
-- Issue, Hypothesis, Attempt count
-
-## Context Budget
-- Usage %, Quality level
-```
-
-### 5 Specialized Agents
+- Playwright or Chrome DevTools
+- Screenshots saved to `.ctx/debug/`
 
-| Agent | When spawned |
-|-------|--------------|
-| ctx-researcher | status = initializing |
-| ctx-planner | after research |
-| ctx-executor | status = executing |
-| ctx-debugger | status = debugging |
-| ctx-verifier | status = verifying |
+## Three-Level Verification
 
-### Directory Structure
-
-```
-.ctx/
-├── STATE.md          # Living digest - ALWAYS read first
-├── phases/{id}/      # Phase data
-│   ├── RESEARCH.md   # ArguSeek + ChunkHound results
-│   ├── PLAN.md       # 2-3 tasks (atomic)
-│   └── VERIFY.md     # Three-level verification
-├── checkpoints/      # Auto-checkpoints
-├── debug/            # Debug screenshots
-└── memory/           # Decision memory
-```
+| Level | Question | Check |
+|-------|----------|-------|
+| Exists | File on disk? | Glob |
+| Substantive | Real code, not stub? | No TODOs, no placeholders |
+| Wired | Imported and used? | Trace imports |
 
-## Key Features
+## Key Design Principles
 
 ### Atomic Planning (2-3 Tasks Max)
 Prevents context degradation. Big work = multiple phases.
@@ -134,11 +115,6 @@ Prevents context degradation. Big work = multiple phases.
 | 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?
-
 ### Context Budget
 | Usage | Quality | Action |
 |-------|---------|--------|
@@ -146,27 +122,35 @@ Prevents context degradation. Big work = multiple phases.
 | 30-50% | Good | Continue |
 | 50%+ | Degrading | Auto-checkpoint |
 
-## Integrations
+## 5 Specialized Agents
 
-### ArguSeek (Web Research)
-Auto-runs during planning:
-- Best practices
-- Security considerations
-- Performance patterns
+| Agent | When spawned |
+|-------|--------------|
+| ctx-researcher | During planning (ArguSeek + ChunkHound) |
+| ctx-planner | After research |
+| ctx-executor | During execution |
+| ctx-debugger | When debugging |
+| ctx-verifier | During verification |
+
+## Integrations
 
-### ChunkHound (Semantic Search)
-Auto-runs during planning:
-- Find relevant code
-- Detect patterns
-- Map entry points
+- **ArguSeek**: Web research during planning
+- **ChunkHound**: Semantic code search (`uv tool install chunkhound`)
+- **Playwright/DevTools**: Browser verification for UI
 
-Install: `uv tool install chunkhound`
+## Directory Structure
 
-### Browser Verification (Playwright/Chrome DevTools)
-Auto-runs during debugging and verification:
-- Navigate to pages
-- Check elements
-- Screenshot proof
+```
+.ctx/
+├── STATE.md          # Living digest - ALWAYS read first
+├── phases/{id}/      # Phase data
+│   ├── RESEARCH.md   # ArguSeek + ChunkHound results
+│   ├── PLAN.md       # 2-3 tasks (atomic)
+│   └── VERIFY.md     # Verification report
+├── checkpoints/      # Auto-checkpoints
+├── debug/            # Debug screenshots
+└── verify/           # Verification screenshots
+```
 
 ## Updating CTX
 
@@ -175,5 +159,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 2.0 - 4 commands, debug loop, 100% verified*
+*CTX 2.1 - 8 commands, smart routing, debug loop, 100% verified*
 </reference>

package/commands/phase.md

@@ -0,0 +1,149 @@
+---
+name: ctx:phase
+description: Phase management - list, add, next, skip
+args: subcommand (list|add|next|skip)
+---
+
+<objective>
+Manage project phases explicitly. CRUD operations for the phase roadmap.
+</objective>
+
+<usage>
+```
+/ctx phase list              # Show all phases with status
+/ctx phase add "goal"        # Add new phase to roadmap
+/ctx phase next              # Mark current complete, move to next
+/ctx phase skip              # Skip current phase (mark skipped)
+```
+</usage>
+
+<subcommands>
+
+## /ctx phase list
+
+Show all phases with their status.
+
+**Output:**
+```
+[CTX Phases]
+
+  #   Status      Goal
+  ─────────────────────────────────────────
+  1   ✓ complete  Set up project structure
+  2   ● current   Add user authentication
+  3   ○ pending   Implement dashboard
+  4   ○ pending   Add API endpoints
+
+Current: Phase 2 - Add user authentication
+Progress: 1/3 tasks complete
+```
+
+**Status indicators:**
+- `✓` complete - Phase verified and done
+- `●` current - Currently active phase
+- `○` pending - Not yet started
+- `⊘` skipped - Explicitly skipped
+
+---
+
+## /ctx phase add "goal"
+
+Add a new phase to the end of the roadmap.
+
+**Process:**
+1. Generate phase ID (increment)
+2. Create `.ctx/phases/{id}/` directory
+3. Update STATE.md with new phase in roadmap
+4. Do NOT start planning yet (user runs `/ctx plan` when ready)
+
+**Output:**
+```
+[CTX Phase] Added phase {id}
+
+Goal: {goal}
+Status: pending
+
+Roadmap now has {n} phases.
+Run /ctx plan "{goal}" when ready to plan this phase.
+```
+
+---
+
+## /ctx phase next
+
+Mark current phase complete and move to the next.
+
+**Process:**
+1. Verify current phase is complete (all tasks done)
+2. If not complete, warn user
+3. Mark current phase as "complete"
+4. Set next pending phase as "current"
+5. Update STATE.md
+
+**Output (success):**
+```
+[CTX Phase] Completed phase {id}: {goal}
+
+Moving to phase {next_id}: {next_goal}
+Run /ctx to start planning.
+```
+
+**Output (not ready):**
+```
+[CTX Phase] Cannot complete phase {id}
+
+Remaining tasks:
+  - {task_1}
+  - {task_2}
+
+Run /ctx to continue, or /ctx phase skip to skip.
+```
+
+---
+
+## /ctx phase skip
+
+Skip the current phase without completing it.
+
+**Process:**
+1. Mark current phase as "skipped"
+2. Log reason (optional prompt)
+3. Move to next phase
+4. Update STATE.md
+
+**Output:**
+```
+[CTX Phase] Skipped phase {id}: {goal}
+
+Moving to phase {next_id}: {next_goal}
+Run /ctx to start planning.
+```
+
+</subcommands>
+
+<state_management>
+Phases are tracked in STATE.md:
+
+```markdown
+## Phases
+| ID | Status | Goal |
+|----|--------|------|
+| 1 | complete | Set up project structure |
+| 2 | current | Add user authentication |
+| 3 | pending | Implement dashboard |
+```
+
+And in individual directories:
+```
+.ctx/phases/
+├── 1/
+│   ├── RESEARCH.md
+│   ├── PLAN.md
+│   └── VERIFY.md
+├── 2/
+│   ├── RESEARCH.md
+│   └── PLAN.md
+└── 3/
+    (empty until planned)
+```
+</state_management>

package/commands/plan.md

@@ -0,0 +1,93 @@
+---
+name: ctx:plan
+description: Force research + planning phase regardless of current state
+args: goal (optional - new goal to plan for)
+---
+
+<objective>
+Force enter planning mode. Runs research (ArguSeek + ChunkHound) and creates atomic plan.
+Use when you want to explicitly plan rather than let smart router decide.
+</objective>
+
+<usage>
+```
+/ctx plan                    # Re-plan current phase goal
+/ctx plan "add user auth"    # Plan for new goal
+```
+</usage>
+
+<workflow>
+## Step 1: Validate Project
+If `.ctx/STATE.md` doesn't exist:
+- Error: "No project found. Run /ctx init first."
+
+## Step 2: Determine Goal
+If goal argument provided:
+- Use provided goal
+- Create new phase if needed
+
+If no goal argument:
+- Use current phase goal from STATE.md
+- If no current phase, ask user for goal
+
+## Step 3: Research Phase
+Spawn **ctx-researcher** agent:
+
+1. **ArguSeek Research**
+   - Best practices for goal
+   - Security considerations
+   - Common pitfalls
+   - Performance patterns
+
+2. **ChunkHound Analysis** (if available)
+   - Semantic search for related code
+   - Pattern detection
+   - Entry point mapping
+
+3. **Output**: `.ctx/phases/{id}/RESEARCH.md`
+
+## Step 4: Planning Phase
+Spawn **ctx-planner** agent:
+
+1. Read RESEARCH.md
+2. Define verification criteria
+3. Break into **2-3 atomic tasks** (strict limit)
+4. Assign execution order
+
+Output: `.ctx/phases/{id}/PLAN.md`
+
+## Step 5: Update State
+Update STATE.md:
+- Status: "executing"
+- Current phase: {id}
+- Phase goal: {goal}
+- Total tasks: {count}
+- Completed: 0
+</workflow>
+
+<output_format>
+```
+[CTX Plan] Goal: {goal}
+
+Research:
+  ArguSeek: {n} findings
+  ChunkHound: {n} relevant files
+
+Plan Created:
+  Tasks: {count} (atomic)
+  Files: .ctx/phases/{id}/PLAN.md
+
+Tasks:
+  1. {task_1_title}
+  2. {task_2_title}
+  3. {task_3_title} (if exists)
+
+Ready to execute. Run /ctx to start.
+```
+</output_format>
+
+<guardrails>
+- Plans are ALWAYS atomic: 2-3 tasks maximum
+- If goal requires more, split into multiple phases
+- Research runs even if ChunkHound unavailable (ArguSeek only)
+</guardrails>

package/commands/status.md

@@ -0,0 +1,78 @@
+---
+name: ctx:status
+description: Read-only status check - see state without triggering action
+---
+
+<objective>
+Display current project status without triggering any workflow action.
+Pure inspection - read STATE.md and report.
+</objective>
+
+<workflow>
+## Step 1: Check Project Exists
+If `.ctx/STATE.md` doesn't exist:
+```
+[CTX] No project found. Run /ctx init to start.
+```
+
+## Step 2: Read State
+Load `.ctx/STATE.md` and extract:
+- Project name and tech stack
+- Current status (initializing/executing/debugging/verifying/paused)
+- Current phase and goal
+- Task progress
+- Debug session info (if active)
+- Context budget usage
+
+## Step 3: Read Phase Data
+If phase exists, also load:
+- `.ctx/phases/{id}/PLAN.md` - task list
+- `.ctx/phases/{id}/RESEARCH.md` - research summary (if exists)
+- `.ctx/phases/{id}/VERIFY.md` - verification results (if exists)
+
+## Step 4: Calculate Metrics
+- Tasks completed vs total
+- Context usage percentage
+- Time since last checkpoint
+</workflow>
+
+<output_format>
+```
+┌─────────────────────────────────────────┐
+│  CTX Status                             │
+├─────────────────────────────────────────┤
+│  Project:  {name}                       │
+│  Stack:    {tech_stack}                 │
+│  Status:   {status}                     │
+└─────────────────────────────────────────┘
+
+Phase: {phase_id} - {phase_goal}
+Progress: {completed}/{total} tasks [{progress_bar}]
+
+Current Task: {task_name}
+Task Status: {pending|in_progress|blocked|debugging}
+
+{If debugging:}
+Debug Session:
+  Issue: {debug_issue}
+  Attempt: {n}/5
+  Last Error: {error_summary}
+
+Context Budget:
+  Used: {percent}% ({quality_level})
+  Action: {continue|checkpoint-soon|checkpoint-now}
+
+Last Checkpoint: {timestamp or "none"}
+
+Next Action: Run /ctx to {recommended_action}
+```
+</output_format>
+
+<key_principle>
+This command is READ-ONLY. It never:
+- Modifies STATE.md
+- Triggers any agent
+- Starts any workflow action
+
+It only inspects and reports.
+</key_principle>

package/commands/verify.md

@@ -0,0 +1,121 @@
+---
+name: ctx:verify
+description: Force three-level verification regardless of current state
+---
+
+<objective>
+Force verification of current phase. Runs three-level check + anti-pattern scan + browser verification.
+Use when you want to verify work before smart router would normally trigger it.
+</objective>
+
+<usage>
+```
+/ctx verify              # Verify current phase
+/ctx verify --browser    # Force browser verification even for non-UI
+```
+</usage>
+
+<workflow>
+## Step 1: Validate Project
+If `.ctx/STATE.md` doesn't exist:
+- Error: "No project found. Run /ctx init first."
+
+If no current phase:
+- Error: "No phase to verify. Run /ctx plan first."
+
+## Step 2: Load Context
+Read:
+- `.ctx/STATE.md` - current state
+- `.ctx/phases/{id}/PLAN.md` - verification criteria
+- Original phase goal
+
+## Step 3: Three-Level Verification
+Spawn **ctx-verifier** agent:
+
+### Level 1: EXISTS
+For each artifact in plan:
+```bash
+ls {file_path}
+```
+- Pass: File found
+- Fail: File missing
+
+### Level 2: SUBSTANTIVE
+Check for stubs/placeholders:
+```bash
+grep -n "TODO" {file}
+grep -n "not implemented" {file}
+```
+- Pass: Real, complete code
+- Fail: Stub detected
+
+### Level 3: WIRED
+Trace imports from entry point:
+```bash
+grep -r "import.*{module}" --include="*.ts"
+```
+- Pass: Code is imported and used
+- Fail: Orphan code (exists but unused)
+
+## Step 4: Anti-Pattern Scan
+Search for common issues:
+| Pattern | Severity |
+|---------|----------|
+| `// TODO` | Warning |
+| Empty catch blocks | Error |
+| `console.log` (debug) | Warning |
+| Placeholder returns | Error |
+
+## Step 5: Browser Verification (if UI)
+If phase involves UI or `--browser` flag:
+
+1. Navigate to affected page
+2. Take snapshot
+3. Check expected elements
+4. Take screenshot proof
+5. Save to `.ctx/verify/phase-{id}.png`
+
+## Step 6: Generate Report
+Write `.ctx/phases/{id}/VERIFY.md`
+
+## Step 7: Update State
+Based on results:
+- **PASS**: Log success, ready for next phase
+- **FAIL**: Create fix tasks, set status = "executing"
+</workflow>
+
+<output_format>
+```
+[CTX Verify] Phase: {id} - {goal}
+
+Three-Level Check:
+  ✓ Exists: {pass}/{total}
+  ✓ Substantive: {pass}/{total}
+  ✓ Wired: {pass}/{total}
+
+Anti-Pattern Scan:
+  Warnings: {count}
+  Errors: {count}
+
+{If browser:}
+Browser Verification:
+  URL: {url}
+  Status: PASS/FAIL
+  Screenshot: .ctx/verify/phase-{id}.png
+
+Overall: {PASS / FAIL}
+
+{If FAIL:}
+Fixes Required:
+  1. {fix_1}
+  2. {fix_2}
+
+{If PASS:}
+Phase verified. Run /ctx to continue.
+```
+</output_format>
+
+<key_principle>
+Verification is STRICT. Better to catch issues now than in production.
+A failing verification saves debugging time later.
+</key_principle>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "CTX 2.0 (Continuous Task eXecution) - Smart workflow orchestration for Claude Code. 4 commands, debug loop, 100% verified.",
   "keywords": [
     "claude",

package/src/install.js

@@ -28,9 +28,9 @@ function printBanner() {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝
 `));
-  console.log(`  ${bold('CTX 2.0')} ${dim(`v${VERSION}`)}`);
+  console.log(`  ${bold('CTX 2.1')} ${dim(`v${VERSION}`)}`);
   console.log('  Continuous Task eXecution for Claude Code.');
-  console.log('  4 commands. Debug loop. 100% verified.\n');
+  console.log('  8 commands. Smart routing. Debug loop.\n');
 }
 
 function copyDir(src, dest) {