ctx-cc 1.0.0 → 2.1.0

package/commands/plan.md

@@ -1,139 +1,93 @@
 ---
 name: ctx:plan
-description: Research + Plan a phase automatically with ArguSeek and ChunkHound
-args: "<goal>"
+description: Force research + planning phase regardless of current state
+args: goal (optional - new goal to plan for)
 ---
 
 <objective>
-Research and plan a phase for the given goal. Automatically uses ArguSeek for web research and ChunkHound for semantic code search.
+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>
 
-<process>
-
-<step name="validate_init">
-Check `.ctx/` exists. If not:
-```
-CTX not initialized. Run `/ctx:init` first.
+<usage>
 ```
-</step>
-
-<step name="create_phase">
-Create phase directory:
+/ctx plan                    # Re-plan current phase goal
+/ctx plan "add user auth"    # Plan for new goal
 ```
-.ctx/phases/{phase-id}/
-├── RESEARCH.md
-├── PLAN.md
-├── PROGRESS.md
-└── VERIFY.md
+</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}
 
-Generate phase-id from goal (slugified, e.g., "add-user-auth").
-</step>
-
-<step name="research_arguseek">
-Generate ArguSeek research queries based on goal and tech stack:
-
-1. Best practices for {goal} in {techStack}
-2. Security considerations for {goal}
-3. Common pitfalls when implementing {goal}
-4. Performance optimization for {goal}
-
-Execute via MCP:
-```
-Use mcp__arguseek__research_iteratively with each query
-```
+Research:
+  ArguSeek: {n} findings
+  ChunkHound: {n} relevant files
 
-Format results into RESEARCH.md.
-</step>
+Plan Created:
+  Tasks: {count} (atomic)
+  Files: .ctx/phases/{id}/PLAN.md
 
-<step name="research_chunkhound">
-If ChunkHound is available, search for relevant existing code:
+Tasks:
+  1. {task_1_title}
+  2. {task_2_title}
+  3. {task_3_title} (if exists)
 
-```bash
-chunkhound search "{goal keywords}"
+Ready to execute. Run /ctx to start.
 ```
+</output_format>
 
-Find:
-- Existing implementations to reuse
-- Related code patterns
-- Entry points to modify
-- Files that will be affected
-
-Add to RESEARCH.md under "## Codebase Analysis".
-</step>
-
-<step name="generate_plan">
-Based on research, create PLAN.md:
-
-```markdown
-# Phase: {goal}
-
-## Research Summary
-{key findings from ArguSeek + ChunkHound}
-
-## Tasks
-
-### Task 1: {title}
-- **Files:** {files to create/modify}
-- **Context estimate:** {small/medium/large}
-- **Dependencies:** {other tasks}
-
-### Task 2: {title}
-...
-
-## Verification Criteria
-- [ ] {criterion 1}
-- [ ] {criterion 2}
-
-## Context Budget
-- Estimated total: {percentage}%
-- Split point: After Task {n} if needed
-```
-</step>
-
-<step name="verify_plan">
-Goal-backward verification:
-- "Will these tasks achieve the goal?"
-- Check for missing steps
-- Validate dependencies
-- Ensure verification criteria are testable
-</step>
-
-<step name="present_plan">
-Show the plan to user:
-
-```
-## Phase Plan: {goal}
-
-**Tasks:** {count}
-**Context estimate:** {percentage}%
-**Split recommended:** {yes/no, after task N}
-
-### Tasks:
-1. {task 1} ({small/medium/large})
-2. {task 2} ({small/medium/large})
-...
-
-### Verification:
-- {criterion 1}
-- {criterion 2}
-
-Proceed with `/ctx:do` to execute.
-```
-</step>
-
-</process>
-
-<output>
-Summary of research findings and generated plan with task breakdown.
-</output>
-
-<success_criteria>
-- [ ] Phase directory created
-- [ ] ArguSeek research executed (if available)
-- [ ] ChunkHound search executed (if available)
-- [ ] RESEARCH.md written with findings
-- [ ] PLAN.md written with tasks
-- [ ] Context budget estimated
-- [ ] Verification criteria defined
-</success_criteria>
+<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/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/commands/status.md

@@ -1,95 +1,78 @@
 ---
 name: ctx:status
-description: Full status report
+description: Read-only status check - see state without triggering action
 ---
 
 <objective>
-Display comprehensive project status including phase, progress, context usage, and todos.
+Display current project status without triggering any workflow action.
+Pure inspection - read STATE.md and report.
 </objective>
 
-<process>
-
-<step name="gather_status">
-Collect status from all CTX components:
-
-1. **Project** - Name, tech stack
-2. **Phase** - Current phase, progress
-3. **Context** - Usage percentage
-4. **Memory** - Fact counts
-5. **Todos** - Pending count
-6. **Integrations** - ArguSeek, ChunkHound status
-</step>
-
-<step name="display">
+<workflow>
+## Step 1: Check Project Exists
+If `.ctx/STATE.md` doesn't exist:
 ```
-## CTX Status
-
-### Project
-**Name:** {project name}
-**Tech:** {language} + {framework}
-**Initialized:** {date}
-
-### Current Phase
-**Phase:** {phase name} ({phase number}/{total})
-**Goal:** {goal}
-**Progress:** {percentage}% ({completed}/{total} tasks)
-**Status:** {pending/in_progress/complete}
-
-### Context Budget
-**Current:** {percentage}%
-**Quality:** {Peak/Good/Degrading/Poor}
-**Recommendation:** {Continue/Consider checkpoint/Checkpoint now}
-
+[CTX] No project found. Run /ctx init to start.
 ```
-{context bar visualization}
-[████████████░░░░░░░░] 45%
+
+## 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}                     │
+└─────────────────────────────────────────┘
 
-### Memory
-| Tier | Facts |
-|------|-------|
-| Working | {count} |
-| Episodic | {count} |
-| Semantic | {count} |
+Phase: {phase_id} - {phase_goal}
+Progress: {completed}/{total} tasks [{progress_bar}]
 
-### Todos
-**Pending:** {count}
-**In Progress:** {count}
-**Completed:** {count}
+Current Task: {task_name}
+Task Status: {pending|in_progress|blocked|debugging}
 
-### Integrations
-| Tool | Status |
-|------|--------|
-| ArguSeek | {available/unavailable} |
-| ChunkHound | {indexed/not indexed/unavailable} |
+{If debugging:}
+Debug Session:
+  Issue: {debug_issue}
+  Attempt: {n}/5
+  Last Error: {error_summary}
 
-### Last Checkpoint
-**ID:** {id or "None"}
-**Created:** {timestamp or "N/A"}
+Context Budget:
+  Used: {percent}% ({quality_level})
+  Action: {continue|checkpoint-soon|checkpoint-now}
 
----
+Last Checkpoint: {timestamp or "none"}
 
-**Quick Actions:**
-- Continue work: `/ctx:do`
-- Verify phase: `/ctx:verify`
-- Save state: `/ctx:pause`
-- View phases: `/ctx:phase list`
+Next Action: Run /ctx to {recommended_action}
 ```
-</step>
-
-</process>
+</output_format>
 
-<context_quality>
-| Usage | Quality | Action |
-|-------|---------|--------|
-| 0-30% | Peak | Continue |
-| 30-50% | Good | Continue |
-| 50-70% | Degrading | Consider checkpoint |
-| 70%+ | Poor | Checkpoint now |
-</context_quality>
+<key_principle>
+This command is READ-ONLY. It never:
+- Modifies STATE.md
+- Triggers any agent
+- Starts any workflow action
 
-<success_criteria>
-- [ ] All status components displayed
-- [ ] Context budget clearly shown
-- [ ] Next actions suggested
-</success_criteria>
+It only inspects and reports.
+</key_principle>

package/commands/verify.md

@@ -1,151 +1,121 @@
 ---
 name: ctx:verify
-description: Three-level verification of current phase
+description: Force three-level verification regardless of current state
 ---
 
 <objective>
-Verify the current phase implementation using three-level verification plus anti-pattern scanning.
+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>
 
-<process>
-
-<step name="load_phase">
-Load current phase from `.ctx/ROADMAP.md`.
-Load verification criteria from `.ctx/phases/{phase-id}/PLAN.md`.
-
-If no phase:
+<usage>
 ```
-No phase to verify. Run `/ctx:plan <goal>` first.
+/ctx verify              # Verify current phase
+/ctx verify --browser    # Force browser verification even for non-UI
 ```
-</step>
+</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 name="three_level_verification">
-For each artifact in the phase:
+## 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}
 ```
-Question: Is the file on disk?
-Check: Glob for the file path
-Pass: File exists
-Fail: File missing
-```
+- Pass: File found
+- Fail: File missing
 
 ### Level 2: SUBSTANTIVE
+Check for stubs/placeholders:
+```bash
+grep -n "TODO" {file}
+grep -n "not implemented" {file}
 ```
-Question: Is it real code, not a stub?
-Check:
-  - No "// TODO" comments in new code
-  - No empty function bodies
-  - No placeholder returns (return null, return {})
-  - No "not implemented" comments
-Pass: Real, complete implementation
-Fail: Stub or placeholder detected
-```
+- Pass: Real, complete code
+- Fail: Stub detected
 
 ### Level 3: WIRED
+Trace imports from entry point:
+```bash
+grep -r "import.*{module}" --include="*.ts"
 ```
-Question: Is it imported and used?
-Check:
-  - Grep for imports of the file
-  - Trace call paths from entry points
-  - Verify the code is reachable
-Pass: Connected to the application
-Fail: Orphan code (exists but unused)
+- 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>
 ```
-</step>
-
-<step name="anti_pattern_scan">
-Scan for common anti-patterns:
-
-| Pattern | Search | Severity |
-|---------|--------|----------|
-| TODO comments | `// TODO`, `# TODO` | Warning |
-| Empty catch | `catch.*\{\s*\}` | Error |
-| Console-only errors | `console.error` without throw | Warning |
-| Placeholder returns | `return null`, `return {}` | Error |
-| Hardcoded secrets | API keys, passwords | Critical |
-| Debug code | `console.log`, `debugger` | Warning |
-</step>
-
-<step name="goal_gap_analysis">
-Check if phase goal is achieved:
-
-1. Re-read the original goal
-2. Compare against what was built
-3. Identify any gaps
-
-```
-Goal: {original goal}
-Built: {what was implemented}
-Gaps: {missing pieces, if any}
-```
-</step>
-
-<step name="generate_report">
-Write `.ctx/phases/{phase-id}/VERIFY.md`:
+[CTX Verify] Phase: {id} - {goal}
 
-```markdown
-# Verification Report
+Three-Level Check:
+  ✓ Exists: {pass}/{total}
+  ✓ Substantive: {pass}/{total}
+  ✓ Wired: {pass}/{total}
 
-## Phase: {name}
-## Date: {timestamp}
+Anti-Pattern Scan:
+  Warnings: {count}
+  Errors: {count}
 
-## Three-Level Results
+{If browser:}
+Browser Verification:
+  URL: {url}
+  Status: PASS/FAIL
+  Screenshot: .ctx/verify/phase-{id}.png
 
-| Artifact | Exists | Substantive | Wired | Status |
-|----------|--------|-------------|-------|--------|
-| {file1}  | ✓      | ✓           | ✓     | PASS   |
-| {file2}  | ✓      | ✓           | ✗     | FAIL   |
-
-## Anti-Pattern Scan
-
-| Pattern | Count | Files | Severity |
-|---------|-------|-------|----------|
-| TODO    | 2     | auth.ts, login.ts | Warning |
-
-## Goal Gap Analysis
-
-**Goal:** {goal}
-**Status:** {Achieved / Partially Achieved / Not Achieved}
-**Gaps:** {list or "None"}
-
-## Overall: {PASS / FAIL}
-
-{If FAIL: List what needs to be fixed}
-```
-</step>
-
-<step name="output_summary">
-Display verification summary:
-
-```
-## Verification: {phase name}
-
-**Three-Level Check:**
-  - Exists: {pass/fail count}
-  - Substantive: {pass/fail count}
-  - Wired: {pass/fail count}
-
-**Anti-Patterns:** {count} found
-**Goal Gaps:** {count or "None"}
-
-**Overall:** {PASS ✓ / FAIL ✗}
+Overall: {PASS / FAIL}
 
 {If FAIL:}
-**Action Required:**
-  - {list of fixes needed}
+Fixes Required:
+  1. {fix_1}
+  2. {fix_2}
 
 {If PASS:}
-**Next:** Run `/ctx:phase next` or `/ctx:ship`
+Phase verified. Run /ctx to continue.
 ```
-</step>
-
-</process>
+</output_format>
 
-<success_criteria>
-- [ ] All artifacts checked at three levels
-- [ ] Anti-pattern scan completed
-- [ ] Goal gap analysis done
-- [ ] VERIFY.md written
-- [ ] Clear pass/fail determination
-</success_criteria>
+<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,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "1.0.0",
-  "description": "CTX - Smart Context Management for Claude Code. The GSD Killer.",
+  "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",
     "claude-code",