ctx-cc 1.0.0

package/bin/ctx.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { install } from '../src/install.js';
+
+const args = process.argv.slice(2);
+const options = {
+  global: args.includes('--global') || args.includes('-g'),
+  project: args.includes('--project') || args.includes('-p'),
+  force: args.includes('--force') || args.includes('-f'),
+  help: args.includes('--help') || args.includes('-h'),
+};
+
+if (options.help) {
+  console.log(`
+\x1b[36m   ██████╗████████╗██╗  ██╗
+  ██╔════╝╚══██╔══╝╚██╗██╔╝
+  ██║        ██║    ╚███╔╝
+  ██║        ██║    ██╔██╗
+  ╚██████╗   ██║   ██╔╝ ██╗
+   ╚═════╝   ╚═╝   ╚═╝  ╚═╝\x1b[0m
+
+  \x1b[1mCTX - Smart Context Management\x1b[0m
+  The GSD Killer. 12 commands, infinite power.
+
+  \x1b[1mUsage:\x1b[0m
+    npx ctx-cc [options]
+
+  \x1b[1mOptions:\x1b[0m
+    --global, -g     Install to ~/.claude (default)
+    --project, -p    Install to .claude in current directory
+    --force, -f      Overwrite existing installation
+    --help, -h       Show this help message
+
+  \x1b[1mExamples:\x1b[0m
+    npx ctx-cc --global      Install globally
+    npx ctx-cc --project     Install for current project only
+
+  \x1b[1mAfter Installation:\x1b[0m
+    Launch Claude Code and run /ctx:help
+`);
+  process.exit(0);
+}
+
+// Default to global if no option specified
+if (!options.global && !options.project) {
+  options.global = true;
+}
+
+install(options);

package/commands/do.md

@@ -0,0 +1,130 @@
+---
+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

@@ -0,0 +1,58 @@
+---
+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>

package/commands/help.md

@@ -0,0 +1,146 @@
+---
+name: ctx:help
+description: Show CTX commands and usage guide
+---
+
+<objective>
+Display the complete CTX command reference.
+
+Output ONLY the reference content below. Do NOT add project-specific analysis or suggestions.
+</objective>
+
+<reference>
+# CTX Command Reference
+
+**CTX** (Context) is a smart context management system for Claude Code.
+12 commands. Infinite power.
+
+## Quick Start
+
+```
+1. /ctx:init              Initialize project
+2. /ctx:plan <goal>       Research + Plan automatically
+3. /ctx:do                Execute phase
+4. (repeat 2-3 for each phase)
+5. /ctx:ship              Final audit
+```
+
+## Why CTX?
+
+| Aspect | GSD | CTX |
+|--------|-----|-----|
+| Commands | 27 | 12 |
+| Context management | Manual | Automatic |
+| Research | Separate step | Auto-integrated |
+| Verification | Manual trigger | Built-in |
+| Memory | Files only | Hierarchical + JIT |
+| Resume cost | ~50k+ tokens | ~2-3k tokens |
+
+## Core Workflow
+
+**`/ctx:init`**
+Initialize project. Detects tech stack, maps codebase, creates PROJECT.md.
+
+**`/ctx:plan <goal>`**
+Research + Plan automatically. Uses ArguSeek for web research and ChunkHound for semantic code search.
+
+**`/ctx:do [task]`**
+Execute current phase, or run a quick task if argument provided.
+- `/ctx:do` - Execute current phase
+- `/ctx:do "fix the login bug"` - Quick task (bypasses workflow)
+
+**`/ctx:verify`**
+Three-level verification:
+1. Exists - Is file on disk?
+2. Substantive - Real code, not stub?
+3. Wired - Imported and used?
+
+Plus anti-pattern scan for TODOs, empty catches, placeholder returns.
+
+**`/ctx:ship`**
+Final audit before shipping. Checks all phases complete, no pending todos, verification passes.
+
+## Phase Management
+
+**`/ctx:phase add <name>`**
+Add a new phase to the roadmap.
+
+**`/ctx:phase list`**
+Show all phases with status.
+
+**`/ctx:phase next`**
+Move to the next phase.
+
+## Memory
+
+**`/ctx:remember <fact>`**
+Force-remember something important.
+
+**`/ctx:recall <query>`**
+Query memory for relevant facts.
+
+**`/ctx:forget <id>`**
+Remove a fact from memory.
+
+## Session Control
+
+**`/ctx:pause`**
+Create checkpoint with handoff notes. Safe to close session.
+
+**`/ctx:resume`**
+Resume from last checkpoint. Restores full context in ~2-3k tokens.
+
+**`/ctx:status`**
+Full status report: project, phase, progress, context usage, todos.
+
+## Integrations
+
+### ArguSeek (Web Research)
+Auto-generates research queries during `/ctx:plan`:
+- Best practices for the goal
+- Security considerations
+- Performance optimization
+- Error handling patterns
+
+### ChunkHound (Semantic Code Search)
+Auto-runs during `/ctx:plan`:
+- Semantic search for goal-relevant code
+- Pattern detection
+- Entry point mapping
+
+Install: `uv tool install chunkhound`
+
+## Directory Structure
+
+```
+.ctx/
+├── PROJECT.md          # Project definition
+├── ROADMAP.md          # Phase roadmap
+├── config.json         # Settings
+├── phases/{id}/        # Phase data
+│   ├── RESEARCH.md     # ArguSeek + ChunkHound results
+│   ├── PLAN.md         # Task breakdown
+│   ├── PROGRESS.md     # Execution state
+│   └── VERIFY.md       # Verification report
+├── memory/             # Hierarchical memory
+├── checkpoints/        # Auto-checkpoints
+└── todos/              # Task management
+```
+
+## Context Budget
+
+| Usage | Quality | Action |
+|-------|---------|--------|
+| 0-30% | Peak | Continue |
+| 30-50% | Good | Continue |
+| 50%+ | Degrading | Auto-checkpoint |
+
+## Updating CTX
+
+```
+/ctx:update
+```
+
+---
+*CTX - 12 commands, infinite power*
+</reference>

package/commands/init.md

@@ -0,0 +1,132 @@
+---
+name: ctx:init
+description: Initialize CTX project with tech detection and codebase mapping
+---
+
+<objective>
+Initialize a new CTX project. Detect tech stack, map codebase structure, create PROJECT.md and initial ROADMAP.md.
+</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:
+
+```
+.ctx/
+├── PROJECT.md
+├── ROADMAP.md
+├── config.json
+├── phases/
+├── memory/
+│   ├── working/
+│   ├── episodic/
+│   └── semantic/
+├── checkpoints/
+└── todos/
+```
+</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
+
+Use 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
+}
+```
+</step>
+
+<step name="ask_goal">
+Ask the user:
+
+"Project initialized! What's your goal for this project?"
+
+Based on their answer, create initial `.ctx/ROADMAP.md` with Phase 1.
+</step>
+
+</process>
+
+<output>
+```
+## CTX Initialized
+
+**Project:** {name}
+**Tech Stack:** {language} + {framework}
+**Integrations:**
+  - ArguSeek: {available/not available}
+  - ChunkHound: {indexed/not available}
+
+**Files Created:**
+  - .ctx/PROJECT.md
+  - .ctx/ROADMAP.md
+  - .ctx/config.json
+
+**Next:** Run `/ctx:plan <goal>` to start your first phase.
+```
+</output>
+
+<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
+</success_criteria>

package/commands/pause.md

@@ -0,0 +1,104 @@
+---
+name: ctx:pause
+description: Create checkpoint with handoff notes
+---
+
+<objective>
+Create a checkpoint of current state for seamless session resumption. Captures all context needed to continue later.
+</objective>
+
+<process>
+
+<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:
+
+```markdown
+# Checkpoint: {timestamp}
+
+## Context
+**Phase:** {phase name}
+**Task:** {current task or "between tasks"}
+**Progress:** {percentage}%
+
+## What Was Done
+- {completed item 1}
+- {completed item 2}
+
+## What's Next
+- {next task}
+- {considerations}
+
+## Key Decisions Made
+- {decision 1}
+- {decision 2}
+
+## Open Questions
+- {question if any}
+
+## Files in Progress
+- {file 1}: {state}
+- {file 2}: {state}
+```
+</step>
+
+<step name="save_checkpoint">
+Save to `.ctx/checkpoints/{checkpoint-id}/`:
+
+```
+.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:
+
+```bash
+git add .ctx/
+git commit -m "ctx: checkpoint {id} - {phase name}"
+```
+</step>
+
+<step name="output">
+```
+## Checkpoint Created
+
+**ID:** {checkpoint-id}
+**Phase:** {phase name}
+**Progress:** {percentage}%
+**Context:** {context percentage}%
+
+**Handoff Summary:**
+{brief summary}
+
+**Resume Command:**
+```
+/ctx:resume
+```
+
+Safe to close this session. State preserved.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] State fully captured
+- [ ] Handoff notes generated
+- [ ] Checkpoint saved to .ctx/checkpoints/
+- [ ] Git commit created
+- [ ] Resume instructions provided
+</success_criteria>

package/commands/phase-add.md

@@ -0,0 +1,53 @@
+---
+name: ctx:phase-add
+description: Add a new phase to the roadmap
+args: "<name>"
+---
+
+<objective>
+Add a new phase to the project roadmap.
+</objective>
+
+<process>
+
+<step name="validate">
+Check `.ctx/ROADMAP.md` exists. If not:
+```
+CTX not initialized. Run `/ctx:init` first.
+```
+</step>
+
+<step name="get_details">
+Ask user for phase details:
+
+1. **Goal**: What should this phase achieve?
+2. **Priority**: Where in the roadmap? (next, end, after phase X)
+</step>
+
+<step name="create_phase">
+1. Generate phase ID from name (slugified)
+2. Create phase directory: `.ctx/phases/{phase-id}/`
+3. Add to ROADMAP.md in specified position
+4. Set status to "pending"
+</step>
+
+<step name="output">
+```
+## Phase Added
+
+**Name:** {name}
+**ID:** {phase-id}
+**Position:** #{position} in roadmap
+**Status:** pending
+
+**Next:** Run `/ctx:plan {name}` to create the plan.
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Phase added to ROADMAP.md
+- [ ] Phase directory created
+- [ ] Position correct in roadmap
+</success_criteria>

package/commands/phase-list.md

@@ -0,0 +1,46 @@
+---
+name: ctx:phase-list
+description: Show all phases with status
+---
+
+<objective>
+Display all phases in the roadmap with their current status.
+</objective>
+
+<process>
+
+<step name="load_roadmap">
+Read `.ctx/ROADMAP.md` and parse phases.
+
+If not found:
+```
+CTX not initialized. Run `/ctx:init` first.
+```
+</step>
+
+<step name="display_phases">
+```
+## Project Phases
+
+| # | Phase | Status | Progress | Verified |
+|---|-------|--------|----------|----------|
+| 1 | {name} | complete | 100% | ✓ |
+| 2 | {name} | in_progress | 60% | - |
+| 3 | {name} | pending | 0% | - |
+
+**Current:** Phase 2 - {name}
+**Remaining:** {count} phases
+
+**Next action:**
+  - If current incomplete: `/ctx:do`
+  - If current done: `/ctx:verify` then `/ctx:phase next`
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All phases listed with accurate status
+- [ ] Current phase highlighted
+- [ ] Next action suggested
+</success_criteria>