ctx-cc 2.3.0 → 3.1.0

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>

package/commands/map.md

@@ -0,0 +1,88 @@
+---
+name: ctx:map
+description: Build or rebuild the repository map for intelligent code understanding
+---
+
+<objective>
+Build a token-optimized map of the codebase that enables all CTX agents to understand project structure, symbols, and dependencies.
+
+This is the foundation for intelligent code operations.
+</objective>
+
+<usage>
+```
+/ctx map              # Build/rebuild repository map
+/ctx map --expand     # Generate expanded map (8k tokens)
+/ctx map --stats      # Show map statistics only
+/ctx map --refresh    # Force full rebuild (ignore cache)
+```
+</usage>
+
+<workflow>
+
+## Step 1: Check Existing Map
+
+Read `.ctx/REPO-MAP.json` if exists:
+- If fresh (< 1 hour old) and no git changes: Skip rebuild, show stats
+- If stale or files changed: Incremental update
+- If `--refresh` flag: Full rebuild
+
+Check git for changes:
+```bash
+git diff --name-only HEAD~10 2>/dev/null || echo "no-git"
+```
+
+## Step 2: Spawn Mapper Agent
+
+Spawn `ctx-mapper` agent to build the map:
+- Pass project root
+- Pass token budget (2000 default, 8000 if --expand)
+- Pass list of changed files (for incremental)
+
+## Step 3: Validate Output
+
+Ensure mapper produced:
+- `.ctx/REPO-MAP.json` - Valid JSON
+- `.ctx/REPO-MAP.md` - Non-empty markdown
+- `.ctx/repo-map-cache.json` - Cache file
+
+## Step 4: Report Results
+
+</workflow>
+
+<output_format>
+```
+[CTX] Repository Map
+
+Project: {{name}}
+Stack: {{stack}}
+
+Statistics:
+  Files: {{file_count}}
+  Symbols: {{symbol_count}}
+  Lines: {{line_count}}
+  Languages: {{language_breakdown}}
+
+Entry Points:
+  {{entry_points}}
+
+Top Referenced:
+  1. {{symbol}} ({{refs}} refs)
+  2. {{symbol}} ({{refs}} refs)
+  3. {{symbol}} ({{refs}} refs)
+
+Map Tokens: {{token_count}}/{{budget}}
+Cache: {{cache_status}}
+
+Saved to: .ctx/REPO-MAP.md
+```
+</output_format>
+
+<integration>
+The repository map is automatically:
+- Loaded by ctx-researcher before research
+- Loaded by ctx-planner before planning
+- Loaded by ctx-executor before execution
+- Used to identify relevant files for any task
+- Updated incrementally when files change
+</integration>

package/commands/profile.md

@@ -0,0 +1,131 @@
+---
+name: ctx:profile
+description: Switch between model profiles (quality/balanced/budget) for cost optimization
+---
+
+<objective>
+Switch between pre-configured model profiles to optimize for quality or cost.
+
+Profiles control which models are used for each phase of the CTX workflow.
+</objective>
+
+<usage>
+```
+/ctx profile                 # Show current profile
+/ctx profile quality         # Use best models (highest cost)
+/ctx profile balanced        # Use balanced models (default)
+/ctx profile budget          # Use fastest models (lowest cost)
+```
+</usage>
+
+<profiles>
+
+## Quality Profile
+**Use when**: Critical production code, complex architecture, security-sensitive
+
+| Phase | Model | Why |
+|-------|-------|-----|
+| Research | Opus | Deep understanding needed |
+| Discussion | Opus | Nuanced question formulation |
+| Planning | Opus | Best architectural decisions |
+| Execution | Opus | Highest quality code |
+| Debugging | Opus | Complex root cause analysis |
+| Verification | Sonnet | Good enough for checks |
+| Mapping | Sonnet | Reliable parsing |
+| Quick | Sonnet | Still good quality |
+
+**Estimated cost**: ~3x balanced profile
+
+## Balanced Profile (Default)
+**Use when**: Most development work, good balance of speed and quality
+
+| Phase | Model | Why |
+|-------|-------|-----|
+| Research | Opus | Worth investing in understanding |
+| Discussion | Sonnet | Good enough for questions |
+| Planning | Opus | Worth investing in architecture |
+| Execution | Sonnet | Good code quality |
+| Debugging | Sonnet | Reliable debugging |
+| Verification | Haiku | Fast checks sufficient |
+| Mapping | Haiku | Fast parsing |
+| Quick | Haiku | Speed prioritized |
+
+**Estimated cost**: Baseline
+
+## Budget Profile
+**Use when**: Prototyping, learning, non-critical code, cost-sensitive
+
+| Phase | Model | Why |
+|-------|-------|-----|
+| Research | Sonnet | Acceptable understanding |
+| Discussion | Sonnet | Good enough |
+| Planning | Sonnet | Acceptable plans |
+| Execution | Sonnet | Decent code |
+| Debugging | Sonnet | Usually works |
+| Verification | Haiku | Fast is fine |
+| Mapping | Haiku | Fast parsing |
+| Quick | Haiku | Maximum speed |
+
+**Estimated cost**: ~0.4x balanced profile (60% savings)
+
+</profiles>
+
+<workflow>
+
+## Step 1: Read Current Config
+
+Read `.ctx/config.json`:
+- If doesn't exist: Copy from template, set balanced as default
+- Get current `activeProfile`
+
+## Step 2: Handle Command
+
+If no argument:
+- Show current profile and routing table
+
+If profile name provided:
+- Validate: must be `quality`, `balanced`, or `budget`
+- Update `activeProfile` in config.json
+- Show new routing table
+
+## Step 3: Update Config
+
+Write updated config to `.ctx/config.json`
+
+</workflow>
+
+<output_format>
+```
+[CTX] Model Profile: {{profile}}
+
+Current Routing:
+  Research:     {{model}} ({{costTier}})
+  Discussion:   {{model}} ({{costTier}})
+  Planning:     {{model}} ({{costTier}})
+  Execution:    {{model}} ({{costTier}})
+  Debugging:    {{model}} ({{costTier}})
+  Verification: {{model}} ({{costTier}})
+  Mapping:      {{model}} ({{costTier}})
+  Quick:        {{model}} ({{costTier}})
+
+Estimated Cost: {{multiplier}}x baseline
+
+Saved to: .ctx/config.json
+```
+</output_format>
+
+<integration>
+All CTX agents check config.json before spawning subagents:
+1. Determine task type (research, planning, etc.)
+2. Look up routing table for model
+3. Use Task tool with `model` parameter
+
+Example:
+```
+Task(
+  prompt: "Research authentication patterns",
+  subagent_type: "ctx-researcher",
+  model: "opus"  // from config routing
+)
+```
+</integration>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "2.3.0",
-  "description": "CTX 2.3 (Continuous Task eXecution) - PRD-driven, design-first workflow orchestration for Claude Code. WCAG 2.2 AA, W3C tokens, story-verified, debug loop until 100% fixed.",
+  "version": "3.1.0",
+  "description": "CTX 3.1 (Continuous Task eXecution) - Intelligent workflow orchestration for Claude Code. Task parallelization, pre-commit review, criteria auto-generation, smart handoff, issue tracker sync (Linear/Jira/GitHub).",
   "keywords": [
     "claude",
     "claude-code",

package/templates/config.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://ctx.dev/schemas/config.json",
+  "version": "3.1",
+
+  "models": {
+    "architect": {
+      "id": "claude-opus-4",
+      "description": "Best reasoning, use for critical decisions",
+      "costTier": "high"
+    },
+    "default": {
+      "id": "claude-sonnet-4",
+      "description": "Balanced performance and cost",
+      "costTier": "medium"
+    },
+    "fast": {
+      "id": "claude-haiku-4",
+      "description": "Quick tasks, lower cost",
+      "costTier": "low"
+    }
+  },
+
+  "routing": {
+    "research": "architect",
+    "discussion": "default",
+    "planning": "architect",
+    "execution": "default",
+    "debugging": "default",
+    "verification": "fast",
+    "mapping": "fast",
+    "quick": "fast",
+    "review": "default",
+    "parallelizer": "fast",
+    "criteria": "default",
+    "handoff": "fast"
+  },
+
+  "profiles": {
+    "quality": {
+      "description": "Best results, higher cost (~3x)",
+      "routing": {
+        "research": "architect",
+        "discussion": "architect",
+        "planning": "architect",
+        "execution": "architect",
+        "debugging": "architect",
+        "verification": "default",
+        "mapping": "default",
+        "quick": "default",
+        "review": "architect",
+        "parallelizer": "default",
+        "criteria": "architect",
+        "handoff": "default"
+      }
+    },
+    "balanced": {
+      "description": "Good results, moderate cost (default)",
+      "routing": {
+        "research": "architect",
+        "discussion": "default",
+        "planning": "architect",
+        "execution": "default",
+        "debugging": "default",
+        "verification": "fast",
+        "mapping": "fast",
+        "quick": "fast",
+        "review": "default",
+        "parallelizer": "fast",
+        "criteria": "default",
+        "handoff": "fast"
+      }
+    },
+    "budget": {
+      "description": "Acceptable results, lowest cost (~0.4x)",
+      "routing": {
+        "research": "default",
+        "discussion": "default",
+        "planning": "default",
+        "execution": "default",
+        "debugging": "default",
+        "verification": "fast",
+        "mapping": "fast",
+        "quick": "fast",
+        "review": "fast",
+        "parallelizer": "fast",
+        "criteria": "fast",
+        "handoff": "fast"
+      }
+    }
+  },
+
+  "activeProfile": "balanced",
+
+  "git": {
+    "autoCommit": true,
+    "commitPerTask": true,
+    "commitMessageFormat": "[CTX] {title}\n\nStory: {storyId} - {storyTitle}\nCriterion: {criterion}\n\nCo-Authored-By: Claude <noreply@anthropic.com>",
+    "signOff": false,
+    "gpgSign": false,
+    "pushOnComplete": false
+  },
+
+  "context": {
+    "mapTokenBudget": 2000,
+    "mapTokenBudgetExpanded": 8000,
+    "prepareHandoffThreshold": 0.4,
+    "checkpointThreshold": 0.5,
+    "spawnFreshThreshold": 0.6,
+    "forceCheckpointThreshold": 0.7
+  },
+
+  "parallelization": {
+    "enabled": true,
+    "maxParallelTasks": 3,
+    "requireDependencyAnalysis": true,
+    "fileLocking": true
+  },
+
+  "review": {
+    "enabled": true,
+    "beforeCommit": true,
+    "blockOnCritical": true,
+    "blockOnHigh": true,
+    "warnOnMedium": true,
+    "autoFix": false,
+    "checks": {
+      "typeErrors": true,
+      "importResolution": true,
+      "circularDeps": true,
+      "security": true,
+      "bestPractices": true,
+      "consoleLogs": true,
+      "emptyBlocks": true
+    }
+  },
+
+  "criteria": {
+    "autoSuggest": true,
+    "minCriteria": 5,
+    "maxCriteria": 15,
+    "categories": ["happy_path", "validation", "error_states", "security", "performance"]
+  },
+
+  "debug": {
+    "maxAttempts": 10,
+    "persistSessions": true,
+    "screenshotOnFailure": true,
+    "autoResume": true
+  },
+
+  "integrations": {
+    "linear": {
+      "enabled": false,
+      "apiKey": "env:LINEAR_API_KEY",
+      "teamId": null,
+      "projectId": null,
+      "syncOnCreate": true,
+      "syncOnVerify": true,
+      "closeOnComplete": true,
+      "statusMapping": {
+        "pending": "Todo",
+        "executing": "In Progress",
+        "verifying": "In Review",
+        "complete": "Done"
+      }
+    },
+    "jira": {
+      "enabled": false,
+      "baseUrl": null,
+      "email": "env:JIRA_EMAIL",
+      "apiToken": "env:JIRA_API_TOKEN",
+      "projectKey": null,
+      "issueType": "Story",
+      "syncOnCreate": true,
+      "syncOnVerify": true,
+      "transitionMapping": {
+        "executing": "In Progress",
+        "verifying": "In Review",
+        "complete": "Done"
+      }
+    },
+    "github": {
+      "enabled": false,
+      "repository": null,
+      "token": "env:GITHUB_TOKEN",
+      "syncIssues": true,
+      "closeOnComplete": true,
+      "createPROnComplete": false,
+      "labels": {
+        "feature": "enhancement",
+        "bug": "bug",
+        "design": "design"
+      }
+    },
+    "slack": {
+      "enabled": false,
+      "webhookUrl": "env:SLACK_WEBHOOK_URL",
+      "notifyOnPhaseComplete": false,
+      "notifyOnVerifyFail": true,
+      "notifyOnHandoff": false
+    }
+  },
+
+  "ui": {
+    "showTokenUsage": true,
+    "showModelInfo": true,
+    "showWaveProgress": true,
+    "verboseOutput": false
+  }
+}