ctx-cc 1.0.0 → 2.1.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/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>