ctx-cc 1.0.0

package/commands/phase-next.md

@@ -0,0 +1,67 @@
+---
+name: ctx:phase-next
+description: Move to the next phase in the roadmap
+---
+
+<objective>
+Complete current phase and move to the next one.
+</objective>
+
+<process>
+
+<step name="check_current">
+Load current phase from `.ctx/ROADMAP.md`.
+
+If current phase not verified:
+```
+⚠ Current phase not verified.
+   Run `/ctx:verify` first to ensure phase is complete.
+```
+</step>
+
+<step name="complete_current">
+1. Mark current phase as "complete" in ROADMAP.md
+2. Update completion timestamp
+3. Archive phase state to memory
+</step>
+
+<step name="activate_next">
+1. Find next "pending" phase
+2. Mark it as "in_progress"
+3. Load phase details
+
+If no next phase:
+```
+## All Phases Complete!
+
+No more phases in the roadmap.
+
+**Options:**
+  - `/ctx:ship` - Run final audit
+  - `/ctx:phase add <name>` - Add more phases
+```
+</step>
+
+<step name="output">
+```
+## Phase Transition
+
+**Completed:** {previous phase}
+**Now Active:** {next phase}
+
+**Phase Goal:** {goal}
+**Tasks:** {count from PLAN.md or "Not planned yet"}
+
+**Next:**
+  - If not planned: `/ctx:plan {goal}`
+  - If planned: `/ctx:do`
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Previous phase marked complete
+- [ ] Next phase activated
+- [ ] Clear guidance on next steps
+</success_criteria>

package/commands/plan.md

@@ -0,0 +1,139 @@
+---
+name: ctx:plan
+description: Research + Plan a phase automatically with ArguSeek and ChunkHound
+args: "<goal>"
+---
+
+<objective>
+Research and plan a phase for the given goal. Automatically uses ArguSeek for web research and ChunkHound for semantic code search.
+</objective>
+
+<process>
+
+<step name="validate_init">
+Check `.ctx/` exists. If not:
+```
+CTX not initialized. Run `/ctx:init` first.
+```
+</step>
+
+<step name="create_phase">
+Create phase directory:
+```
+.ctx/phases/{phase-id}/
+├── RESEARCH.md
+├── PLAN.md
+├── PROGRESS.md
+└── VERIFY.md
+```
+
+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
+```
+
+Format results into RESEARCH.md.
+</step>
+
+<step name="research_chunkhound">
+If ChunkHound is available, search for relevant existing code:
+
+```bash
+chunkhound search "{goal keywords}"
+```
+
+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>

package/commands/recall.md

@@ -0,0 +1,72 @@
+---
+name: ctx:recall
+description: Query memory for relevant facts
+args: "<query>"
+---
+
+<objective>
+Search CTX memory for facts matching the query. Returns relevant information from all memory tiers.
+</objective>
+
+<process>
+
+<step name="search_memory">
+Search across all memory tiers:
+
+1. **Working memory** - Current session facts
+2. **Episodic memory** - Cross-session facts
+3. **Semantic memory** - Permanent knowledge
+
+Match by:
+- Keyword matching
+- Category filtering
+- Relevance scoring
+</step>
+
+<step name="rank_results">
+Rank results by:
+1. Recency (newer facts first)
+2. Relevance to query
+3. Importance (manual > auto-extracted)
+</step>
+
+<step name="display">
+```
+## Memory Recall: "{query}"
+
+### Results ({count} found)
+
+**From Episodic Memory:**
+1. [{id}] {fact} ({timestamp})
+2. [{id}] {fact} ({timestamp})
+
+**From Semantic Memory:**
+3. [{id}] {fact} (permanent)
+
+**From Working Memory:**
+4. [{id}] {fact} (current session)
+
+---
+To forget a fact: `/ctx:forget {id}`
+```
+
+If no results:
+```
+## Memory Recall: "{query}"
+
+No matching facts found.
+
+**Tips:**
+- Try broader keywords
+- Check `/ctx:status` for memory stats
+- Use `/ctx:remember` to add facts
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] All memory tiers searched
+- [ ] Results ranked by relevance
+- [ ] IDs provided for management
+</success_criteria>

package/commands/remember.md

@@ -0,0 +1,68 @@
+---
+name: ctx:remember
+description: Force-remember an important fact
+args: "<fact>"
+---
+
+<objective>
+Manually add a fact to CTX memory. Use for important information that should persist across sessions.
+</objective>
+
+<process>
+
+<step name="validate">
+Check `.ctx/memory/` exists. Create if not.
+</step>
+
+<step name="categorize">
+Determine fact category:
+- **decision**: Architectural or design decisions
+- **pattern**: Code patterns to follow
+- **constraint**: Limitations or requirements
+- **context**: Project-specific context
+- **preference**: User preferences
+</step>
+
+<step name="store">
+Add to appropriate memory tier:
+
+1. **Working memory** (current session): `.ctx/memory/working/`
+2. **Episodic memory** (cross-session): `.ctx/memory/episodic/`
+3. **Semantic memory** (permanent): `.ctx/memory/semantic/`
+
+For manual `/ctx:remember`, store in **episodic** by default.
+
+Format:
+```json
+{
+  "id": "{uuid}",
+  "content": "{fact}",
+  "category": "{category}",
+  "timestamp": "{iso-8601}",
+  "source": "manual"
+}
+```
+</step>
+
+<step name="confirm">
+```
+## Fact Remembered
+
+**ID:** {short-id}
+**Category:** {category}
+**Content:** {fact}
+**Stored in:** Episodic memory
+
+This fact will be available in future sessions.
+To query: `/ctx:recall {keywords}`
+To remove: `/ctx:forget {id}`
+```
+</step>
+
+</process>
+
+<success_criteria>
+- [ ] Fact stored in memory
+- [ ] ID assigned for retrieval
+- [ ] Category determined
+</success_criteria>

package/commands/resume.md

@@ -0,0 +1,108 @@
+---
+name: ctx:resume
+description: Resume from last checkpoint
+args: "[checkpoint-id]"
+---
+
+<objective>
+Resume work from a checkpoint. Restores context efficiently (~2-3k tokens instead of full reload).
+</objective>
+
+<process>
+
+<step name="find_checkpoint">
+If checkpoint-id provided:
+  Load `.ctx/checkpoints/{checkpoint-id}/`
+
+If no checkpoint-id:
+  Load most recent checkpoint from `.ctx/checkpoints/`
+
+If no checkpoints exist:
+```
+No checkpoints found.
+
+**Options:**
+- Start fresh with `/ctx:init`
+- Check `.ctx/` exists
+```
+</step>
+
+<step name="load_state">
+Load checkpoint state:
+
+1. **HANDOFF.md** - Read for context
+2. **state.json** - Parse current state
+3. **working-memory.json** - Load recent facts
+4. **file-index.json** - Know relevant files
+</step>
+
+<step name="restore_context">
+Build minimal context:
+
+1. Load semantic memory (permanent facts)
+2. Load recent episodic memory (relevant to phase)
+3. Load working memory from checkpoint
+4. Identify files to read (from file-index)
+
+Target: ~2-3k tokens for full context restoration.
+</step>
+
+<step name="verify_sync">
+Check for changes since checkpoint:
+
+```bash
+git status
+git log --oneline {checkpoint-commit}..HEAD
+```
+
+If changes found:
+```
+⚠ Changes detected since checkpoint:
+  - {files changed}
+
+These will be incorporated into current state.
+```
+</step>
+
+<step name="output">
+```
+## Session Resumed
+
+**Checkpoint:** {id}
+**Created:** {timestamp}
+**Phase:** {phase name}
+**Progress:** {percentage}%
+
+**Context Restored:** ~{token count} tokens
+
+**Where We Left Off:**
+{handoff summary}
+
+**Next Task:**
+{next task from plan}
+
+**Ready to continue.** Run `/ctx:do` to proceed.
+```
+</step>
+
+</process>
+
+<context_budget>
+| Component | Tokens |
+|-----------|--------|
+| Semantic facts | ~1,000 |
+| Recent decisions | ~500 |
+| Patterns | ~300 |
+| Task state | ~200 |
+| File identifiers | ~500 |
+| **Total** | **~2,500** |
+
+vs. Naive reload: 50,000+ tokens
+</context_budget>
+
+<success_criteria>
+- [ ] Checkpoint loaded correctly
+- [ ] Context restored efficiently
+- [ ] Sync with git verified
+- [ ] Clear next steps provided
+</success_criteria>

package/commands/ship.md

@@ -0,0 +1,119 @@
+---
+name: ctx:ship
+description: Final audit before shipping
+---
+
+<objective>
+Run final audit to ensure project is ready to ship. Checks all phases, todos, and verification status.
+</objective>
+
+<process>
+
+<step name="check_phases">
+Load `.ctx/ROADMAP.md` and check all phases:
+
+```
+## Phase Status
+
+| Phase | Status | Verified |
+|-------|--------|----------|
+| {name} | {complete/incomplete} | {yes/no} |
+```
+
+If any phase is incomplete:
+```
+⚠ Phase "{name}" is not complete.
+   Run `/ctx:do` to finish, then `/ctx:verify`.
+```
+</step>
+
+<step name="check_todos">
+Load `.ctx/todos/` and check for pending items:
+
+```
+## Pending Todos
+
+{count} todos remaining:
+  - [ ] {todo 1}
+  - [ ] {todo 2}
+```
+
+If todos exist:
+```
+⚠ {count} pending todos found.
+   Complete them or explicitly defer with rationale.
+```
+</step>
+
+<step name="run_final_verification">
+Run `/ctx:verify` on each completed phase:
+
+For each phase, check:
+- Three-level verification passes
+- No anti-patterns (or documented exceptions)
+- Goal gaps resolved
+</step>
+
+<step name="check_integrations">
+Verify integration points:
+
+1. **Dependencies** - All imports resolve
+2. **Tests** - Test suite passes (if exists)
+3. **Build** - Project builds without errors
+4. **Lint** - No linting errors
+
+```bash
+# Attempt to run common checks
+npm test 2>/dev/null || echo "No npm test"
+npm run build 2>/dev/null || echo "No build script"
+npm run lint 2>/dev/null || echo "No lint script"
+```
+</step>
+
+<step name="generate_ship_report">
+Create summary:
+
+```
+## Ship Readiness Report
+
+### Phases
+| Phase | Complete | Verified |
+|-------|----------|----------|
+{table}
+
+### Todos
+- Pending: {count}
+- Completed: {count}
+
+### Checks
+- [ ] All phases complete: {yes/no}
+- [ ] All verifications pass: {yes/no}
+- [ ] No pending todos: {yes/no}
+- [ ] Build passes: {yes/no}
+- [ ] Tests pass: {yes/no}
+
+### Overall: {READY TO SHIP ✓ / NOT READY ✗}
+
+{If not ready:}
+**Blockers:**
+  1. {blocker}
+  2. {blocker}
+
+{If ready:}
+**Recommendation:** Safe to deploy.
+```
+</step>
+
+</process>
+
+<output>
+Ship readiness report with clear pass/fail and any blockers.
+</output>
+
+<success_criteria>
+- [ ] All phases checked
+- [ ] All todos reviewed
+- [ ] Final verification run
+- [ ] Build/test status checked
+- [ ] Clear ship/no-ship recommendation
+</success_criteria>

package/commands/status.md

@@ -0,0 +1,95 @@
+---
+name: ctx:status
+description: Full status report
+---
+
+<objective>
+Display comprehensive project status including phase, progress, context usage, and todos.
+</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">
+```
+## 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}
+
+```
+{context bar visualization}
+[████████████░░░░░░░░] 45%
+```
+
+### Memory
+| Tier | Facts |
+|------|-------|
+| Working | {count} |
+| Episodic | {count} |
+| Semantic | {count} |
+
+### Todos
+**Pending:** {count}
+**In Progress:** {count}
+**Completed:** {count}
+
+### Integrations
+| Tool | Status |
+|------|--------|
+| ArguSeek | {available/unavailable} |
+| ChunkHound | {indexed/not indexed/unavailable} |
+
+### Last Checkpoint
+**ID:** {id or "None"}
+**Created:** {timestamp or "N/A"}
+
+---
+
+**Quick Actions:**
+- Continue work: `/ctx:do`
+- Verify phase: `/ctx:verify`
+- Save state: `/ctx:pause`
+- View phases: `/ctx:phase list`
+```
+</step>
+
+</process>
+
+<context_quality>
+| Usage | Quality | Action |
+|-------|---------|--------|
+| 0-30% | Peak | Continue |
+| 30-50% | Good | Continue |
+| 50-70% | Degrading | Consider checkpoint |
+| 70%+ | Poor | Checkpoint now |
+</context_quality>
+
+<success_criteria>
+- [ ] All status components displayed
+- [ ] Context budget clearly shown
+- [ ] Next actions suggested
+</success_criteria>