ctx-cc 2.3.0 → 3.0.0

package/agents/ctx-tech-mapper.md

@@ -0,0 +1,163 @@
+---
+name: ctx-tech-mapper
+description: Tech stack mapper for CTX 3.0. Analyzes languages, frameworks, dependencies, and versions. Part of parallel codebase mapping.
+tools: Read, Bash, Glob, Grep
+color: blue
+---
+
+<role>
+You are a CTX 3.0 tech stack mapper. You analyze:
+- Programming languages and their proportions
+- Frameworks and libraries
+- Dependencies and versions
+- Build tools and configurations
+- Runtime requirements
+
+You produce: `.ctx/codebase/TECH.md`
+</role>
+
+<process>
+
+## 1. Detect Languages
+
+Count lines by language:
+```bash
+# Use cloc if available
+cloc . --json 2>/dev/null || find . -type f \( -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.go" -o -name "*.rs" \) | head -100
+```
+
+Analyze distribution:
+- Primary language (>50%)
+- Secondary languages
+- Configuration languages (JSON, YAML, etc.)
+
+## 2. Identify Frameworks
+
+### JavaScript/TypeScript
+```bash
+# Check package.json
+cat package.json | grep -E "(react|vue|angular|next|express|fastify|nest)"
+```
+
+### Python
+```bash
+# Check requirements or pyproject
+cat requirements.txt pyproject.toml 2>/dev/null | grep -E "(django|flask|fastapi|pytest)"
+```
+
+### Go
+```bash
+# Check go.mod
+cat go.mod 2>/dev/null | grep -E "(gin|echo|fiber|chi)"
+```
+
+### Rust
+```bash
+# Check Cargo.toml
+cat Cargo.toml 2>/dev/null | grep -E "(actix|rocket|axum|tokio)"
+```
+
+## 3. Analyze Dependencies
+
+### Package Counts
+```bash
+# Node
+cat package.json | jq '.dependencies | length' 2>/dev/null
+cat package.json | jq '.devDependencies | length' 2>/dev/null
+
+# Python
+wc -l requirements.txt 2>/dev/null
+
+# Go
+grep -c "require" go.mod 2>/dev/null
+```
+
+### Outdated Check
+```bash
+# Check for outdated (if npm available)
+npm outdated 2>/dev/null | head -20
+```
+
+### Security Vulnerabilities
+```bash
+# Check for known vulnerabilities
+npm audit --json 2>/dev/null | jq '.metadata.vulnerabilities'
+```
+
+## 4. Build Configuration
+
+Look for:
+- `tsconfig.json` - TypeScript config
+- `webpack.config.js` - Webpack
+- `vite.config.ts` - Vite
+- `rollup.config.js` - Rollup
+- `Makefile` - Make
+- `Dockerfile` - Docker
+- `.github/workflows/` - CI/CD
+
+## 5. Runtime Requirements
+
+Check for:
+- Node version in `package.json` engines
+- Python version in `pyproject.toml`
+- Go version in `go.mod`
+- Docker base image
+
+</process>
+
+<output>
+Write `.ctx/codebase/TECH.md`:
+
+```markdown
+# Tech Stack Analysis
+
+## Languages
+| Language | Files | Lines | Percentage |
+|----------|-------|-------|------------|
+| TypeScript | 120 | 15,000 | 75% |
+| JavaScript | 30 | 3,000 | 15% |
+| CSS | 20 | 2,000 | 10% |
+
+Primary: **TypeScript**
+
+## Frameworks
+- **Frontend**: React 18.2, Next.js 14.0
+- **Backend**: Node.js (via Next.js API routes)
+- **Styling**: Tailwind CSS 3.4
+- **Database**: PostgreSQL via Prisma 5.0
+
+## Dependencies
+- Production: 45 packages
+- Development: 32 packages
+- Outdated: 5 packages
+- Vulnerabilities: 0 critical, 2 moderate
+
+### Key Dependencies
+| Package | Version | Purpose |
+|---------|---------|---------|
+| react | 18.2.0 | UI framework |
+| next | 14.0.4 | Full-stack framework |
+| prisma | 5.7.0 | ORM |
+| zod | 3.22.4 | Validation |
+
+## Build Tools
+- **Bundler**: Next.js (Turbopack)
+- **TypeScript**: 5.3.3 (strict mode)
+- **Linting**: ESLint 8.56
+- **Formatting**: Prettier 3.1
+
+## Runtime
+- Node.js: >=18.0.0
+- npm: >=9.0.0
+- Database: PostgreSQL 15+
+
+## CI/CD
+- GitHub Actions
+- Vercel deployment
+
+## Recommendations
+1. Update 5 outdated packages
+2. Address 2 moderate vulnerabilities
+3. Consider upgrading to Node 20 LTS
+```
+</output>

package/commands/ctx.md

@@ -1,55 +1,84 @@
 ---
 name: ctx
-description: Smart router - reads STATE.md and does the right thing
+description: Smart router - reads STATE.md, config.json, and does the right thing. Uses model profiles for cost optimization.
 ---
 
 <objective>
-CTX 2.0 Smart Router - One command that always knows what to do next.
+CTX 3.0 Smart Router - One command that always knows what to do next.
 
-Read STATE.md, understand current context, and execute the appropriate action.
+Read STATE.md, load config.json, use appropriate model profile, and execute the right action.
 </objective>
 
 <workflow>
+## Step 0: Load Configuration
+
+Read `.ctx/config.json` for:
+- Active profile (quality/balanced/budget)
+- Model routing table
+- Git settings (autoCommit, commitPerTask)
+- Integration settings
+
+If config.json doesn't exist:
+- Copy from templates/config.json
+- Set balanced as default profile
+
 ## Step 1: Read State
+
 Read `.ctx/STATE.md` to understand current situation.
 
 If STATE.md doesn't exist:
 - Output: "No CTX project found. Run `/ctx init` to start."
 - Stop.
 
+Also check for:
+- `.ctx/REPO-MAP.md` - Codebase understanding
+- `.ctx/codebase/SUMMARY.md` - Deep codebase analysis
+- `.ctx/phases/{story_id}/CONTEXT.md` - Locked decisions
+
 ## Step 2: Route Based on State
 
 ### If status = "initializing"
 Route to: **Research Phase**
-1. Use ArguSeek to research the project goal
-2. Use ChunkHound for semantic code search (if existing codebase)
+1. Check if REPO-MAP exists, if not run ctx-mapper
+2. Use ArguSeek to research the project goal
 3. Create atomic plan (2-3 tasks max)
 4. Update STATE.md with plan
-5. Set status = "executing"
+5. Set status = "discussing"
+
+### If status = "discussing"
+Route to: **Discussion Phase**
+1. Spawn ctx-discusser agent
+2. Ask targeted questions about gray areas
+3. Lock decisions in CONTEXT.md
+4. Set status = "executing"
 
 ### If status = "executing"
 Route to: **Execute Current Task**
 1. Read current task from STATE.md
-2. Spawn ctx-executor agent
-3. Execute task with deviation handling:
+2. Load REPO-MAP for context
+3. Spawn ctx-executor agent (uses git-native workflow)
+4. Execute task with deviation handling:
    - Auto-fix: bugs, validation, deps (95%)
    - Ask user: architecture decisions only (5%)
-4. After task:
+5. After task:
    - Run verification (build, tests, lint)
+   - Auto-commit if config allows
    - If passes: mark done, update STATE.md
    - If fails: set status = "debugging"
 
 ### If status = "debugging"
-Route to: **Debug Loop**
+Route to: **Persistent Debug Loop**
 1. Spawn ctx-debugger agent
-2. Loop until fixed (max 5 attempts):
+2. Check for existing debug session (resume if exists)
+3. Loop until fixed (max 10 attempts):
    - Analyze error
    - Form hypothesis
    - Apply fix
    - Verify (build + tests + browser if UI)
+   - Record in persistent state
    - Take screenshot proof if browser test
-3. If fixed: set status = "executing", continue
-4. If 5 attempts fail: escalate to user
+4. If fixed: set status = "executing", continue
+5. If max attempts: escalate with full report
 
 ### If status = "verifying"
 Route to: **Three-Level Verification**
@@ -69,39 +98,83 @@ Route to: **Resume**
 3. Set status to previous state
 4. Continue workflow
 
-## Step 3: Context Budget Check
+## Step 3: Model Selection
+
+Based on current action and active profile:
+
+| Action | quality | balanced | budget |
+|--------|---------|----------|--------|
+| Research | opus | opus | sonnet |
+| Discussion | opus | sonnet | sonnet |
+| Planning | opus | opus | sonnet |
+| Execution | opus | sonnet | sonnet |
+| Debugging | opus | sonnet | sonnet |
+| Verification | sonnet | haiku | haiku |
+| Mapping | sonnet | haiku | haiku |
+
+Use Task tool with `model` parameter from routing table.
+
+## Step 4: Context Budget Check
+
 After every action:
 - Calculate context usage
+- If > 40%: Prepare handoff notes
 - If > 50%: Auto-checkpoint, warn user
+- If > 60%: Create HANDOFF.md, spawn fresh agent
 - If > 70%: Force checkpoint
 
-## Step 4: Update State
+## Step 5: Git-Native Commit
+
+If task completed successfully AND config.git.autoCommit = true:
+1. Stage modified files
+2. Create commit with CTX format
+3. Record commit hash in STATE.md
+
+## Step 6: Update State
+
 Always update STATE.md after any action:
 - Current status
 - Progress
+- Recent commits
 - Recent decisions
 - Next action
+- Context usage
 </workflow>
 
 <state_transitions>
 ```
-initializing → executing (after plan created)
+initializing → discussing (after research)
+discussing → executing (after decisions locked)
 executing → debugging (if verification fails)
 executing → verifying (if all tasks done)
 debugging → executing (if fix works)
-debugging → ESCALATE (if 5 attempts fail)
+debugging → ESCALATE (if max attempts fail)
 verifying → executing (if anti-patterns found)
 verifying → COMPLETE (if all passes)
 paused → (previous state)
 ```
 </state_transitions>
 
+<new_commands>
+## New in CTX 3.0
+
+| Command | Purpose |
+|---------|---------|
+| `/ctx map` | Build repository map (REPO-MAP.md) |
+| `/ctx map-codebase` | Deep codebase analysis (4 parallel agents) |
+| `/ctx discuss [story]` | Run discussion phase for story |
+| `/ctx profile [name]` | Switch model profile |
+| `/ctx debug --resume` | Resume previous debug session |
+</new_commands>
+
 <context_budget>
 | Usage | Quality | Action |
 |-------|---------|--------|
 | 0-30% | Peak | Continue |
-| 30-50% | Good | Continue |
-| 50-70% | Degrading | Auto-checkpoint |
+| 30-40% | Good | Continue |
+| 40-50% | Good | Prepare handoff |
+| 50-60% | Degrading | Auto-checkpoint |
+| 60-70% | Degrading | Create HANDOFF.md |
 | 70%+ | Poor | Force checkpoint |
 </context_budget>
 
@@ -109,7 +182,9 @@ paused → (previous state)
 After routing, output:
 ```
 [CTX] Status: {{status}}
+[CTX] Profile: {{profile}} ({{costTier}})
 [CTX] Action: {{action_taken}}
+[CTX] Commit: {{commit_hash}} (if auto-committed)
 [CTX] Next: {{next_action}}
 [CTX] Context: {{percent}}% ({{quality}})
 ```

package/commands/discuss.md

@@ -0,0 +1,101 @@
+---
+name: ctx:discuss
+description: Capture implementation decisions before planning. Resolves ambiguities and locks decisions.
+---
+
+<objective>
+Identify gray areas in a story and capture implementation decisions BEFORE planning.
+
+This prevents wasted work from misaligned assumptions.
+</objective>
+
+<usage>
+```
+/ctx discuss              # Discuss current story from PRD.json
+/ctx discuss S002         # Discuss specific story
+/ctx discuss --review     # Review existing decisions
+```
+</usage>
+
+<workflow>
+
+## Step 1: Load Story
+
+If story ID provided:
+- Read that story from `.ctx/PRD.json`
+
+If no story ID:
+- Read `metadata.currentStory` from PRD.json
+- Use that story
+
+If no PRD.json:
+- Output: "No PRD found. Run `/ctx init` first."
+- Stop
+
+## Step 2: Check Existing Discussion
+
+If `.ctx/phases/{story_id}/CONTEXT.md` exists:
+- If `--review` flag: Show existing decisions
+- Otherwise: Ask "Discussion exists. Redo? (will overwrite)"
+
+## Step 3: Spawn Discusser Agent
+
+Spawn `ctx-discusser` agent with:
+- Story details from PRD.json
+- Project context from STATE.md
+- Repo map from REPO-MAP.md (if exists)
+
+Agent will:
+1. Analyze story for gray areas
+2. Formulate targeted questions
+3. Ask user via AskUserQuestion
+4. Write CONTEXT.md with decisions
+
+## Step 4: Validate Output
+
+Ensure:
+- `.ctx/phases/{story_id}/CONTEXT.md` exists
+- Contains all required sections
+- No unresolved questions (or explicitly noted)
+
+## Step 5: Update State
+
+Update `.ctx/STATE.md`:
+- Set discussion status to complete
+- Add key decisions to "Recent Decisions"
+- Set next action to "Run /ctx plan"
+
+</workflow>
+
+<output_format>
+```
+[CTX] Discussion: Story {id} - {title}
+
+Questions Asked: {{count}}
+Decisions Captured: {{count}}
+
+Key Decisions:
+  - Auth: {{decision}}
+  - UI: {{decision}}
+  - Data: {{decision}}
+  ...
+
+Saved to: .ctx/phases/{story_id}/CONTEXT.md
+
+Next: Run /ctx plan (or /ctx to auto-route)
+```
+</output_format>
+
+<when_to_use>
+**Always use before planning when:**
+- Story has UI components (layout decisions needed)
+- Story involves new data models (schema decisions)
+- Story has security implications (auth, encryption)
+- Story touches external integrations
+- Story requirements are vague
+
+**Can skip when:**
+- Story is purely technical (refactor, optimization)
+- All decisions are already documented
+- Story is a simple bug fix with clear solution
+</when_to_use>

package/commands/map-codebase.md

@@ -0,0 +1,169 @@
+---
+name: ctx:map-codebase
+description: Comprehensive codebase analysis using 4 parallel mapper agents. Run before starting a new project on existing code.
+---
+
+<objective>
+Analyze an existing codebase comprehensively using 4 specialized parallel agents.
+
+This command is essential for "brownfield" projects where CTX is being added to existing code.
+It produces documentation that informs all future planning and execution.
+</objective>
+
+<usage>
+```
+/ctx map-codebase              # Full analysis with all 4 mappers
+/ctx map-codebase --tech       # Only tech stack analysis
+/ctx map-codebase --arch       # Only architecture analysis
+/ctx map-codebase --quality    # Only quality analysis
+/ctx map-codebase --concerns   # Only concerns analysis
+/ctx map-codebase --refresh    # Force re-analysis (ignore cache)
+```
+</usage>
+
+<parallel_agents>
+
+## The 4 Mapper Agents
+
+```
+┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐
+│    TECH     │  │    ARCH     │  │   QUALITY   │  │  CONCERNS   │
+│   MAPPER    │  │   MAPPER    │  │   MAPPER    │  │   MAPPER    │
+│             │  │             │  │             │  │             │
+│ Stack       │  │ Patterns    │  │ Test cov    │  │ Security    │
+│ Frameworks  │  │ Data flow   │  │ Lint status │  │ Tech debt   │
+│ Dependencies│  │ Modules     │  │ Type safety │  │ Performance │
+│ Versions    │  │ Entry pts   │  │ Code smells │  │ Risks       │
+└─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘
+       │                │                │                │
+       ▼                ▼                ▼                ▼
+   TECH.md          ARCH.md         QUALITY.md      CONCERNS.md
+       │                │                │                │
+       └────────────────┴────────────────┴────────────────┘
+                                │
+                                ▼
+                          SUMMARY.md
+```
+
+All 4 agents run in PARALLEL for speed, then results are synthesized.
+
+</parallel_agents>
+
+<workflow>
+
+## Step 1: Check Prerequisites
+
+- Ensure we're in a git repository (or at least a code directory)
+- Check for existing analysis in `.ctx/codebase/`
+- If exists and not `--refresh`: Show cached results
+
+## Step 2: Spawn Parallel Mappers
+
+Spawn all 4 agents simultaneously using Task tool:
+
+```
+Task(subagent_type="ctx-tech-mapper", prompt="Analyze tech stack...", run_in_background=true)
+Task(subagent_type="ctx-arch-mapper", prompt="Analyze architecture...", run_in_background=true)
+Task(subagent_type="ctx-quality-mapper", prompt="Analyze quality...", run_in_background=true)
+Task(subagent_type="ctx-concerns-mapper", prompt="Analyze concerns...", run_in_background=true)
+```
+
+## Step 3: Wait for Completion
+
+Use TaskOutput to wait for all 4 mappers:
+- Each mapper writes its output to `.ctx/codebase/{TYPE}.md`
+- Collect results as they complete
+- Show progress to user
+
+## Step 4: Synthesize Results
+
+After all mappers complete, create SUMMARY.md:
+- Executive summary of findings
+- Key metrics
+- Recommendations for CTX workflow
+- Suggested first phase
+
+## Step 5: Update State
+
+- Create/update `.ctx/codebase/` directory
+- Store analysis timestamp
+- Link from STATE.md
+
+</workflow>
+
+<output_structure>
+
+```
+.ctx/codebase/
+├── TECH.md           # Tech stack analysis
+├── ARCH.md           # Architecture analysis
+├── QUALITY.md        # Quality metrics
+├── CONCERNS.md       # Security, performance, tech debt
+├── SUMMARY.md        # Executive summary
+└── metadata.json     # Analysis timestamp, versions
+```
+
+</output_structure>
+
+<output_format>
+```
+[CTX] Codebase Analysis
+
+Spawning 4 parallel mappers...
+  [■■■■■■■■■■] TECH     ✓ 12s
+  [■■■■■■■■■■] ARCH     ✓ 15s
+  [■■■■■■■■■■] QUALITY  ✓ 18s
+  [■■■■■■■■■■] CONCERNS ✓ 14s
+
+Synthesizing results...
+
+═══════════════════════════════════════════════════════
+                    CODEBASE SUMMARY
+═══════════════════════════════════════════════════════
+
+Tech Stack:
+  Language:   TypeScript (92%), JavaScript (8%)
+  Framework:  Next.js 14, React 18
+  Database:   PostgreSQL + Prisma
+  Testing:    Jest, Playwright
+
+Architecture:
+  Pattern:    Monolith with modular structure
+  Entry:      src/app/page.tsx, src/server/index.ts
+  Modules:    12 feature modules
+  API Style:  REST + Server Actions
+
+Quality:
+  Test Coverage:  67%
+  Type Safety:    Strong (strict mode)
+  Lint Status:    12 warnings, 0 errors
+  Code Smells:    3 files need attention
+
+Concerns:
+  Security:       2 medium issues (see CONCERNS.md)
+  Performance:    N+1 query in users module
+  Tech Debt:      Auth module needs refactor
+
+Recommendations:
+  1. Address security issues before new features
+  2. Improve test coverage to 80%
+  3. Refactor auth module
+
+Saved to: .ctx/codebase/
+
+Next: Run /ctx init to start project with this context
+```
+</output_format>
+
+<when_to_use>
+**Always run before:**
+- Adding CTX to an existing codebase
+- Starting major refactoring work
+- Onboarding to unfamiliar codebase
+- Security or quality audit
+
+**Can skip when:**
+- Greenfield project (no existing code)
+- Small utility or script
+- Analysis already done and code unchanged
+</when_to_use>