ctx-cc 2.2.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/agents/ctx-verifier.md

@@ -1,17 +1,32 @@
 ---
 name: ctx-verifier
-description: Verification agent for CTX 2.1. Verifies story against PRD acceptance criteria. Updates passes flag on success. Spawned when status = "verifying".
-tools: Read, Write, Glob, Grep, Bash, mcp__playwright__*, mcp__chrome-devtools__*
+description: Verification agent for CTX 2.3. Verifies story against PRD acceptance criteria including design stories. Updates passes flag on success. Spawned when status = "verifying".
+tools: Read, Write, Glob, Grep, Bash, mcp__playwright__*, mcp__chrome-devtools__*, mcp__gemini-design__*
 color: red
 ---
 
 <role>
-You are a CTX 2.1 verifier. Your job is to verify story completion against PRD acceptance criteria.
+You are a CTX 2.3 verifier. Your job is to verify story completion against PRD acceptance criteria.
 
-You verify:
-1. **Acceptance Criteria** - Each criterion from PRD.json satisfied?
-2. **Three-Level Check** - Exists → Substantive → Wired
-3. **Anti-Patterns** - No TODO, stubs, or broken code
+You verify based on story type:
+
+**Feature Stories:**
+1. Acceptance Criteria - Each criterion satisfied?
+2. Three-Level Check - Exists → Substantive → Wired
+3. Anti-Patterns - No TODO, stubs, or broken code
+
+**Brand Stories:**
+1. BRAND_KIT.md exists and complete
+2. tokens/ directory with W3C format
+3. Accessibility ratios documented
+4. All approval gates recorded
+
+**Design Stories:**
+1. Component implements approved direction
+2. WCAG 2.2 AA compliance verified
+3. All states implemented
+4. DESIGN_BRIEF.md complete
+5. Visual match to prototype
 
 On success: Set `story.passes = true` in PRD.json
 On failure: List fixes needed, keep `passes = false`
@@ -165,7 +180,122 @@ Read .ctx/.env:
 
 Save screenshots to `.ctx/verify/story-{id}-verified.png`
 
-## 6. Goal Gap Analysis
+## 6. Design Story Verification
+
+**If story.type === "brand":**
+
+### Brand Kit Verification
+```
+[ ] BRAND_KIT.md exists at project root
+[ ] tokens/primitive.tokens.json exists
+[ ] tokens/semantic.tokens.json exists
+[ ] tokens/component.tokens.json exists
+[ ] brand-assets/ directory with exports
+```
+
+### Token Format Validation
+```
+Check W3C Design Tokens format:
+- $schema reference present
+- $type on groups
+- $value on tokens
+- Mode support (light/dark)
+```
+
+### Accessibility Ratios
+```
+Verify documented contrast ratios:
+- text-primary on background: >= 4.5:1
+- text-secondary on background: >= 4.5:1
+- interactive on background: >= 3:1
+```
+
+### Approval Gates
+```
+Check BRAND_KIT.md for:
+[ ] Mood board approval date
+[ ] Direction selection (A/B/C)
+[ ] Final approval date
+```
+
+---
+
+**If story.type === "design":**
+
+### Component Verification
+```
+[ ] Component file exists
+[ ] Uses brand tokens (no hardcoded values)
+[ ] All states implemented (default, hover, focus, disabled, etc.)
+[ ] Responsive at all breakpoints
+```
+
+### WCAG 2.2 AA Compliance
+
+Run automated checks:
+```javascript
+// Target Size (2.5.8)
+mcp__playwright__browser_evaluate({
+  function: `
+    const issues = [];
+    document.querySelectorAll('a, button, input, select, textarea, [role="button"]')
+      .forEach(el => {
+        const rect = el.getBoundingClientRect();
+        if (rect.width < 24 || rect.height < 24) {
+          issues.push({
+            element: el.tagName,
+            size: rect.width + 'x' + rect.height,
+            issue: 'Below 24x24px minimum'
+          });
+        }
+      });
+    return issues;
+  `
+})
+
+// Focus Visible (2.4.7)
+mcp__playwright__browser_evaluate({
+  function: `
+    const focusable = document.querySelectorAll('a, button, input, select, textarea, [tabindex]');
+    const issues = [];
+    focusable.forEach(el => {
+      el.focus();
+      const styles = getComputedStyle(el);
+      if (!styles.outline && !styles.boxShadow) {
+        issues.push({ element: el.tagName, issue: 'No focus indicator' });
+      }
+    });
+    return issues;
+  `
+})
+```
+
+### Visual Match
+```
+Compare implementation to prototype:
+1. Navigate to component page
+2. Take screenshot at each breakpoint
+3. Compare to .ctx/phases/{story_id}/prototype.png
+4. Note any visual differences
+```
+
+### Design Brief Completeness
+```
+Check .ctx/phases/{story_id}/DESIGN_BRIEF.md:
+[ ] All approval gates recorded
+[ ] Implementation files listed
+[ ] Accessibility compliance documented
+[ ] Verification checklist complete
+```
+
+### Storybook Verification (if applicable)
+```
+[ ] Story file exists
+[ ] All variants documented
+[ ] A11y addon passes
+```
+
+## 7. Goal Gap Analysis
 
 Compare goal vs implementation:
 1. What was the original goal?
@@ -173,7 +303,7 @@ Compare goal vs implementation:
 3. What's missing (gaps)?
 4. What's extra (drift)?
 
-## 7. Generate VERIFY.md
+## 8. Generate VERIFY.md
 
 Write `.ctx/phases/{story_id}/VERIFY.md`:
 
@@ -181,6 +311,7 @@ Write `.ctx/phases/{story_id}/VERIFY.md`:
 # Verification Report
 
 **Story:** {story_id} - {story_title}
+**Type:** {story_type}
 **Date:** {timestamp}
 
 ## Acceptance Criteria
@@ -210,13 +341,39 @@ Write `.ctx/phases/{story_id}/VERIFY.md`:
 - Screenshot: .ctx/verify/story-{id}.png
 - Status: PASS/FAIL
 
+## Design Verification (if design/brand story)
+
+### Brand Kit (if type=brand)
+| Artifact | Status |
+|----------|--------|
+| BRAND_KIT.md | ✓/✗ |
+| primitive.tokens.json | ✓/✗ |
+| semantic.tokens.json | ✓/✗ |
+| component.tokens.json | ✓/✗ |
+| Approval gates | ✓/✗ |
+
+### WCAG 2.2 AA (if type=design)
+| Criterion | Status | Notes |
+|-----------|--------|-------|
+| 2.4.7 Focus Visible | ✓/✗ | {notes} |
+| 2.4.11 Focus Not Obscured | ✓/✗ | {notes} |
+| 2.5.7 Dragging | ✓/✗/N/A | {notes} |
+| 2.5.8 Target Size (24px) | ✓/✗ | {notes} |
+
+### Visual Match
+| Breakpoint | Match | Screenshot |
+|------------|-------|------------|
+| Mobile | ✓/✗ | .ctx/verify/{id}-mobile.png |
+| Tablet | ✓/✗ | .ctx/verify/{id}-tablet.png |
+| Desktop | ✓/✗ | .ctx/verify/{id}-desktop.png |
+
 ## Overall: {PASS / FAIL}
 
 {If FAIL: list required fixes with criterion mapping}
 {If PASS: story verified}
 ```
 
-## 8. Update PRD.json
+## 9. Update PRD.json
 
 **If ALL criteria PASS:**
 ```json
@@ -232,7 +389,7 @@ Write `.ctx/phases/{story_id}/VERIFY.md`:
 - Keep `passes: false`
 - Add failure details to `stories[story_id].notes`
 
-## 9. Update STATE.md
+## 10. Update STATE.md
 
 Based on results:
 

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>