ctx-cc 1.0.0 → 2.0.0

package/commands/init.md

@@ -1,132 +1,81 @@
 ---
 name: ctx:init
-description: Initialize CTX project with tech detection and codebase mapping
+description: Initialize CTX project with STATE.md
 ---
 
 <objective>
-Initialize a new CTX project. Detect tech stack, map codebase structure, create PROJECT.md and initial ROADMAP.md.
+Initialize a new CTX 2.0 project. Creates `.ctx/` directory with STATE.md as the single source of truth.
 </objective>
 
-<process>
-
-<step name="detect_tech_stack">
-Scan the project to detect:
-- Package managers: package.json, Cargo.toml, go.mod, requirements.txt, etc.
-- Frameworks: React, Next.js, FastAPI, Express, etc.
-- Languages: TypeScript, Python, Go, Rust, etc.
-- Build tools: Webpack, Vite, esbuild, etc.
-</step>
-
-<step name="create_ctx_directory">
-Create `.ctx/` directory structure:
-
+<workflow>
+## Step 1: Check Existing
+If `.ctx/STATE.md` exists:
+- Ask: "CTX project exists. Reinitialize? (will archive current state)"
+- If no: stop
+- If yes: backup to `.ctx/archive/STATE-{timestamp}.md`
+
+## Step 2: Detect Project
+Scan the codebase:
+1. **Package files**: package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml
+2. **Frameworks**: React, Next.js, FastAPI, Express, Django, etc.
+3. **Entry points**: main files, index files, app files
+4. **Key directories**: src/, lib/, app/, components/, etc.
+
+## Step 3: Create Structure
 ```
 .ctx/
-├── PROJECT.md
-├── ROADMAP.md
-├── config.json
-├── phases/
-├── memory/
-│   ├── working/
-│   ├── episodic/
-│   └── semantic/
-├── checkpoints/
-└── todos/
+├── STATE.md          # Living digest - ALWAYS read first
+├── phases/           # Phase-specific data
+│   └── {phase-id}/
+│       ├── RESEARCH.md
+│       ├── PLAN.md
+│       └── VERIFY.md
+├── checkpoints/      # Auto-checkpoints for resume
+├── memory/           # Decision memory
+└── archive/          # Archived states
 ```
-</step>
 
-<step name="map_codebase">
-If this is an existing codebase (not empty), analyze:
-- Entry points (main files, index files)
-- Key directories and their purposes
-- Architectural patterns used
-- Important dependencies
+## Step 4: Initialize STATE.md
+Create STATE.md from template with:
+- Project name (from package.json or directory name)
+- Detected tech stack
+- Status: "initializing"
+- Context budget: 0%
+- Empty current phase
 
-Use ChunkHound if available:
+## Step 5: Index with ChunkHound (if available)
 ```bash
-chunkhound index .
-```
-</step>
-
-<step name="create_project_md">
-Write `.ctx/PROJECT.md`:
-
-```markdown
-# Project: {name}
-
-## Tech Stack
-- Language: {detected}
-- Framework: {detected}
-- Build: {detected}
-
-## Architecture
-{brief description from codebase mapping}
-
-## Entry Points
-- {list of main files}
-
-## Key Patterns
-- {patterns identified}
-
-## Initialized
-{timestamp}
-```
-</step>
-
-<step name="create_config">
-Write `.ctx/config.json`:
-
-```json
-{
-  "version": "1.0.0",
-  "initialized": "{timestamp}",
-  "techStack": {
-    "language": "{detected}",
-    "framework": "{detected}",
-    "buildTool": "{detected}"
-  },
-  "integrations": {
-    "arguseek": true,
-    "chunkhound": true
-  },
-  "contextBudget": 50
-}
+chunkhound index . --output .ctx/chunks.json
 ```
-</step>
-
-<step name="ask_goal">
-Ask the user:
-
-"Project initialized! What's your goal for this project?"
+This enables semantic code search during planning.
 
-Based on their answer, create initial `.ctx/ROADMAP.md` with Phase 1.
-</step>
+## Step 6: Prompt for Goal
+Ask user: **"What do you want to build/fix/improve?"**
 
-</process>
+Do NOT start planning yet. Just store the goal in STATE.md and set status to "initializing".
+The user will run `/ctx` to begin the research + planning phase.
+</workflow>
 
-<output>
+<output_format>
 ```
-## CTX Initialized
+[CTX 2.0] Initialized
 
-**Project:** {name}
-**Tech Stack:** {language} + {framework}
-**Integrations:**
-  - ArguSeek: {available/not available}
-  - ChunkHound: {indexed/not available}
+Project: {{name}}
+Stack: {{language}} + {{framework}}
+Directory: .ctx/
 
-**Files Created:**
-  - .ctx/PROJECT.md
-  - .ctx/ROADMAP.md
-  - .ctx/config.json
+Integrations:
+  ArguSeek: ready
+  ChunkHound: {{indexed | not found}}
 
-**Next:** Run `/ctx:plan <goal>` to start your first phase.
+Next: Run /ctx to start planning
 ```
-</output>
+</output_format>
 
 <success_criteria>
-- [ ] Tech stack detected correctly
 - [ ] .ctx/ directory created
-- [ ] PROJECT.md written with accurate info
-- [ ] ChunkHound index attempted if available
-- [ ] User asked for project goal
+- [ ] STATE.md initialized with detected info
+- [ ] ChunkHound index attempted
+- [ ] User prompted for goal
+- [ ] Status set to "initializing"
 </success_criteria>

package/commands/pause.md

@@ -1,104 +1,103 @@
 ---
 name: ctx:pause
-description: Create checkpoint with handoff notes
+description: Create checkpoint with handoff notes - safe to close session
 ---
 
 <objective>
-Create a checkpoint of current state for seamless session resumption. Captures all context needed to continue later.
+Create a checkpoint for seamless session resumption. Captures all context in ~2.5k tokens.
 </objective>
 
-<process>
+<workflow>
+## Step 1: Capture State
+Read current STATE.md and capture:
+1. **Status** - Current workflow state
+2. **Phase** - Active phase and goal
+3. **Task** - Current task and progress
+4. **Debug** - If debugging, capture hypothesis and attempt count
+5. **Decisions** - Recent decisions made
 
-<step name="capture_state">
-Capture current state:
-
-1. **Active phase** - Which phase, which task
-2. **Progress** - What's done, what's pending
-3. **Working memory** - Recent facts and decisions
-4. **File state** - Files being worked on
-5. **Context usage** - Current percentage
-</step>
-
-<step name="generate_handoff">
-Create handoff notes:
+## Step 2: Generate Checkpoint
+Create `.ctx/checkpoints/checkpoint-{timestamp}.md`:
 
 ```markdown
 # Checkpoint: {timestamp}
 
-## Context
-**Phase:** {phase name}
-**Task:** {current task or "between tasks"}
-**Progress:** {percentage}%
+## Resume Context
+**Status:** {status from STATE.md}
+**Phase:** {phase_id} - {phase_goal}
+**Task:** {current_task}
+**Progress:** {completed}/{total} tasks
 
-## What Was Done
-- {completed item 1}
-- {completed item 2}
+## Session Summary
+### Completed
+- {completed_1}
+- {completed_2}
 
-## What's Next
-- {next task}
-- {considerations}
+### In Progress
+- {current_task}: {status}
 
-## Key Decisions Made
-- {decision 1}
-- {decision 2}
+### Next Steps
+1. {next_step_1}
+2. {next_step_2}
 
-## Open Questions
-- {question if any}
+## Key Decisions
+- {decision_1}
+- {decision_2}
 
-## Files in Progress
-- {file 1}: {state}
-- {file 2}: {state}
-```
-</step>
+## Debug State (if active)
+- Issue: {debug_issue}
+- Hypothesis: {current_hypothesis}
+- Attempt: {attempt}/5
+- Last Error: {error_summary}
 
-<step name="save_checkpoint">
-Save to `.ctx/checkpoints/{checkpoint-id}/`:
+## Files Modified
+- {file_1}: {change_summary}
+- {file_2}: {change_summary}
 
+## Context Budget
+- Used: {percent}%
+- Quality: {level}
+
+---
+*Resume with /ctx - state will be restored automatically*
 ```
-.ctx/checkpoints/{id}/
-├── HANDOFF.md          # Human-readable summary
-├── state.json          # Machine-readable state
-├── working-memory.json # Current session memory
-└── file-index.json     # Relevant files
-```
-</step>
 
-<step name="commit_checkpoint">
-Create git commit for checkpoint:
+## Step 3: Update STATE.md
+Set status to "paused" and record checkpoint ID.
 
+## Step 4: Git Commit (optional)
+If uncommitted changes exist:
 ```bash
 git add .ctx/
-git commit -m "ctx: checkpoint {id} - {phase name}"
+git commit -m "ctx: checkpoint - {phase_goal}"
 ```
-</step>
 
-<step name="output">
+## Step 5: Output
 ```
-## Checkpoint Created
-
-**ID:** {checkpoint-id}
-**Phase:** {phase name}
-**Progress:** {percentage}%
-**Context:** {context percentage}%
+[CTX] Checkpoint created
 
-**Handoff Summary:**
-{brief summary}
+Status: paused
+Phase: {phase_id} - {phase_goal}
+Progress: {completed}/{total} tasks
+Context: {percent}%
 
-**Resume Command:**
-```
-/ctx:resume
-```
+Checkpoint ID: {checkpoint_id}
+Resume: Run /ctx (auto-restores state)
 
-Safe to close this session. State preserved.
+Safe to close this session.
 ```
-</step>
+</workflow>
 
-</process>
+<resume_cost>
+Target: ~2.5k tokens to restore full context
+- STATE.md: ~100 lines
+- Checkpoint: ~50 lines
+- Phase data: ~100 lines
+</resume_cost>
 
 <success_criteria>
-- [ ] State fully captured
-- [ ] Handoff notes generated
-- [ ] Checkpoint saved to .ctx/checkpoints/
-- [ ] Git commit created
-- [ ] Resume instructions provided
+- [ ] STATE.md captured
+- [ ] Checkpoint file created
+- [ ] Status set to "paused"
+- [ ] Resume instructions clear
 </success_criteria>

package/commands/quick.md

@@ -0,0 +1,68 @@
+---
+name: ctx:quick
+description: Quick task bypass - execute without full workflow
+---
+
+<objective>
+Execute a quick task without the full CTX workflow.
+Use for small fixes, one-off tasks, or urgent work that doesn't need planning.
+</objective>
+
+<usage>
+```
+/ctx:quick "fix the login button styling"
+/ctx:quick "add console.log for debugging"
+/ctx:quick "update the README"
+```
+</usage>
+
+<workflow>
+## Step 1: Validate Task Size
+Quick tasks should be:
+- Single file or 2-3 files max
+- No architectural decisions
+- < 30 minutes of work
+- Clear, specific outcome
+
+If task seems large, suggest: "This looks like a bigger task. Consider `/ctx init` + `/ctx` for proper planning."
+
+## Step 2: Execute Directly
+1. Understand the task
+2. Find relevant files
+3. Make changes
+4. Verify (build + tests if applicable)
+
+## Step 3: Verify Success
+Run appropriate verification:
+- Build: `npm run build` / `go build` / etc.
+- Tests: Run affected tests
+- Lint: Check for errors
+
+If verification fails:
+- Auto-fix if simple (typo, import)
+- Otherwise report issue
+
+## Step 4: Update STATE.md (if exists)
+If `.ctx/STATE.md` exists, log the quick task:
+```
+## Quick Tasks Log
+- [timestamp] {{task_description}} - {{status}}
+```
+
+## Step 5: Output
+Report what was done:
+```
+[CTX Quick] {{task_description}}
+[CTX Quick] Changed: {{files}}
+[CTX Quick] Verified: {{build/tests status}}
+[CTX Quick] Done.
+```
+</workflow>
+
+<guardrails>
+- Max 3 files changed
+- No database schema changes
+- No API contract changes
+- No new dependencies without asking
+- No refactoring (use full workflow for that)
+</guardrails>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "1.0.0",
-  "description": "CTX - Smart Context Management for Claude Code. The GSD Killer.",
+  "version": "2.0.0",
+  "description": "CTX 2.0 (Continuous Task eXecution) - Smart workflow orchestration for Claude Code. 4 commands, debug loop, 100% verified.",
   "keywords": [
     "claude",
     "claude-code",

package/src/install.js

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

package/templates/STATE.md

@@ -0,0 +1,47 @@
+# STATE.md - Living Digest
+
+> This file is the single source of truth. Updated after every action.
+> ~100 lines max. Always accurate. Always current.
+
+## Project
+- **Name**: {{project_name}}
+- **Stack**: {{tech_stack}}
+- **Status**: {{status}} <!-- initializing | planning | executing | debugging | verifying | paused -->
+
+## Current Phase
+- **ID**: {{phase_id}}
+- **Goal**: {{phase_goal}}
+- **Progress**: {{completed_tasks}}/{{total_tasks}} tasks
+
+## Active Task
+- **Task**: {{current_task}}
+- **Status**: {{task_status}} <!-- pending | in_progress | blocked | debugging | done -->
+- **Attempts**: {{attempt_count}}/5
+
+## Debug Session (if active)
+- **Issue**: {{debug_issue}}
+- **Hypothesis**: {{current_hypothesis}}
+- **Attempt**: {{debug_attempt}}/5
+- **Last Error**: {{last_error}}
+- **Browser Verified**: {{browser_verified}} <!-- false | true -->
+
+## Context Budget
+- **Used**: {{context_percent}}%
+- **Quality**: {{quality_level}} <!-- peak | good | degrading | poor -->
+- **Action**: {{recommended_action}} <!-- continue | checkpoint-soon | checkpoint-now -->
+
+## Recent Decisions
+<!-- Last 5 decisions, newest first -->
+1. {{decision_1}}
+2. {{decision_2}}
+3. {{decision_3}}
+
+## Blockers
+<!-- Current blockers requiring user input -->
+- {{blocker_1}}
+
+## Next Action
+> {{next_action_description}}
+
+---
+*Last updated: {{timestamp}}*

package/commands/do.md

@@ -1,130 +0,0 @@
----
-name: ctx:do
-description: Execute current phase or run a quick task
-args: "[task]"
----
-
-<objective>
-Execute the current phase's plan, OR run a quick task if an argument is provided.
-</objective>
-
-<process>
-
-<step name="check_mode">
-If argument provided (e.g., `/ctx:do "fix the login bug"`):
-  → Quick Task Mode
-
-If no argument:
-  → Phase Execution Mode
-</step>
-
-<!-- QUICK TASK MODE -->
-<step name="quick_task" condition="argument provided">
-Quick task mode - bypass full workflow:
-
-1. Read the task description
-2. Load relevant context from memory
-3. Execute the task directly
-4. Create atomic git commit
-5. Update memory with what was done
-
-```
-## Quick Task
-
-**Task:** {task description}
-**Status:** In Progress
-
-Executing without full planning workflow...
-```
-
-Skip to `complete_task` step.
-</step>
-
-<!-- PHASE EXECUTION MODE -->
-<step name="load_phase">
-Load current phase from `.ctx/ROADMAP.md`:
-
-1. Find phase with status "in_progress" or first "pending"
-2. Load `.ctx/phases/{phase-id}/PLAN.md`
-3. Load `.ctx/phases/{phase-id}/PROGRESS.md`
-
-If no phase found:
-```
-No phase to execute. Run `/ctx:plan <goal>` first.
-```
-</step>
-
-<step name="load_context">
-JIT context loading:
-
-1. Load relevant facts from memory
-2. Load file index for files mentioned in plan
-3. Retrieve only needed files (not entire codebase)
-
-Target: Minimal context for current task.
-</step>
-
-<step name="execute_tasks">
-For each task in PLAN.md:
-
-1. **Start task**
-   - Update PROGRESS.md: task status → "in_progress"
-   - Load task-specific files
-
-2. **Execute**
-   - Implement the task
-   - Follow deviation rules:
-     - Bug in existing code → Auto-fix, document
-     - Missing validation → Auto-add, document
-     - Blocking issue → Auto-fix, document
-     - Architectural decision → STOP, ask user
-
-3. **Commit**
-   - Atomic git commit for the task
-   - Message: "ctx: {task title}"
-
-4. **Update progress**
-   - Mark task complete in PROGRESS.md
-   - Extract facts to memory
-   - Check context budget
-
-5. **Context check**
-   - If context > 50%: trigger auto-checkpoint
-   - Signal user if split recommended
-</step>
-
-<step name="complete_task">
-After task/phase completion:
-
-```
-## Task Complete
-
-**Task:** {description}
-**Files changed:** {list}
-**Commit:** {hash}
-
-**Context:** {percentage}%
-{If > 50%: "Consider `/ctx:pause` to checkpoint."}
-
-**Next:** {next task or "Run `/ctx:verify` to validate"}
-```
-</step>
-
-</process>
-
-<deviation_rules>
-| Rule | Trigger | Action |
-|------|---------|--------|
-| 1 | Bug in existing code | Auto-fix, document in commit |
-| 2 | Missing validation | Auto-add, document |
-| 3 | Blocking issue | Auto-fix, document |
-| 4 | Architectural decision | **STOP** - ask user |
-</deviation_rules>
-
-<success_criteria>
-- [ ] Task executed successfully
-- [ ] Atomic git commit created
-- [ ] PROGRESS.md updated
-- [ ] Memory updated with facts
-- [ ] Context budget monitored
-</success_criteria>

package/commands/forget.md

@@ -1,58 +0,0 @@
----
-name: ctx:forget
-description: Remove a fact from memory
-args: "<id>"
----
-
-<objective>
-Remove a specific fact from CTX memory by its ID.
-</objective>
-
-<process>
-
-<step name="find_fact">
-Search all memory tiers for the fact ID.
-
-If not found:
-```
-Fact "{id}" not found in memory.
-Use `/ctx:recall {query}` to find fact IDs.
-```
-</step>
-
-<step name="confirm">
-Show the fact before removal:
-
-```
-## Forget Fact
-
-**ID:** {id}
-**Content:** {fact}
-**Category:** {category}
-**Stored:** {timestamp}
-
-Are you sure you want to remove this fact?
-This cannot be undone.
-```
-</step>
-
-<step name="remove">
-Delete the fact from its memory tier.
-
-```
-## Fact Forgotten
-
-**ID:** {id}
-**Content:** {fact}
-
-Removed from {tier} memory.
-```
-</step>
-
-</process>
-
-<success_criteria>
-- [ ] Fact located by ID
-- [ ] Confirmation shown
-- [ ] Fact removed from correct tier
-</success_criteria>