ctx-cc 3.4.0 → 3.4.1

package/commands/map-codebase.md

@@ -1,169 +1,68 @@
 ---
 name: ctx:map-codebase
-description: Comprehensive codebase analysis using 4 parallel mapper agents. Run before starting a new project on existing code.
+description: Analyze codebase with parallel mapper agents to produce .ctx/codebase/ documents
+argument-hint: "[--refresh]"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+  - TaskOutput
 ---
 
 <objective>
-Analyze an existing codebase comprehensively using 4 specialized parallel agents.
+Analyze existing codebase using parallel ctx-*-mapper agents to produce structured codebase documents.
 
-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
+Each mapper agent explores a focus area and **writes documents directly** to `.ctx/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
 
-## 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
+Output: .ctx/codebase/ folder with 5 structured documents about the codebase state.
+</objective>
 
-Recommendations:
-  1. Address security issues before new features
-  2. Improve test coverage to 80%
-  3. Refactor auth module
+<execution_context>
+@~/.claude/ctx/workflows/map-codebase.md
+</execution_context>
 
-Saved to: .ctx/codebase/
+<context>
+Flags: $ARGUMENTS (--refresh to force re-analysis)
 
-Next: Run /ctx init to start project with this context
-```
-</output_format>
+**This command can run:**
+- Before /ctx:init (brownfield codebases) - creates codebase map first
+- After /ctx:init (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
 
 <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
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
 </when_to_use>
+
+<process>
+1. Check if .ctx/codebase/ already exists (offer to refresh or skip)
+2. Create .ctx/codebase/ directory structure
+3. Spawn 4 parallel mapper agents:
+   - ctx-tech-mapper → writes TECH.md
+   - ctx-arch-mapper → writes ARCH.md
+   - ctx-quality-mapper → writes QUALITY.md
+   - ctx-concerns-mapper → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 4 documents exist with line counts
+6. Create SUMMARY.md with synthesis
+7. Offer next steps (typically: /ctx:init)
+</process>
+
+<success_criteria>
+- [ ] .ctx/codebase/ directory created
+- [ ] All 4 codebase documents written by mapper agents
+- [ ] SUMMARY.md created with key findings
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ctx-cc",
-  "version": "3.4.0",
+  "version": "3.4.1",
   "description": "CTX 3.3 (Continuous Task eXecution) - AI that learns your preferences. Learning system, predictive planning, self-healing deployments (Sentry/LogRocket), voice control for hands-free development.",
   "keywords": [
     "claude",
@@ -30,7 +30,8 @@
     "commands/",
     "agents/",
     "references/",
-    "templates/"
+    "templates/",
+    "workflows/"
   ],
   "engines": {
     "node": ">=18.0.0"

package/src/install.js

@@ -162,6 +162,14 @@ export async function install(options) {
     console.log(green(`  ✓`) + ` Installed templates (${count} files)`);
   }
 
+  // Copy workflows
+  const srcWorkflows = path.join(packageRoot, 'workflows');
+  const destWorkflows = path.join(ctxDir, 'workflows');
+  if (fs.existsSync(srcWorkflows)) {
+    const count = copyDir(srcWorkflows, destWorkflows);
+    console.log(green(`  ✓`) + ` Installed workflows (${count} files)`);
+  }
+
   // Write VERSION file
   fs.writeFileSync(path.join(ctxDir, 'VERSION'), VERSION);
   console.log(green(`  ✓`) + ` Wrote VERSION (${VERSION})`);

package/workflows/ctx-router.md

@@ -0,0 +1,241 @@
+<purpose>
+Smart router for CTX - understands natural language, detects intent, and routes to the right workflow.
+
+Users don't need to memorize commands. They describe what they want, CTX routes automatically.
+</purpose>
+
+<intent_detection>
+Parse the user's message to detect intent. Check patterns in order:
+
+| Pattern | Intent | Action |
+|---------|--------|--------|
+| "build", "create", "make", "start new", "I want to..." + "app/project/feature" | new-project | Route to init flow |
+| "fix", "bug", "broken", "not working", "error", "crash", "fails" | debug | Route to debug flow |
+| "test", "QA", "check", "accessible", "works?", "validate" | qa | Route to QA flow |
+| "study", "analyze", "understand", "learn", "explore", "what is this", "deeply study" | analyze | Route to map-codebase flow |
+| "improve", "optimize", "better", "enhance", "upgrade", "refactor" | improve | Analyze + suggest improvements |
+| "review", "audit", "security", "ready", "before deploy" | review | Verify flow |
+| "deploy", "ship", "publish", "release", "push", "launch" | ship | Ship flow |
+| "status", "progress", "where", "what's next", "current" | status | Status report |
+| "help", "how", "what can", "commands", "guide" | help | Show help |
+| "continue", "next", "go", "do it" | continue | Read STATE.md and continue |
+
+Store detected intent for routing.
+</intent_detection>
+
+<process>
+
+<step name="verify_ctx_structure" priority="first">
+**MANDATORY FIRST STEP - Execute before anything else:**
+
+```bash
+test -d .ctx && echo "exists" || echo "missing"
+```
+
+Store result:
+- If "exists": CTX is initialized, load state
+- If "missing": CTX not initialized, may need setup
+</step>
+
+<step name="detect_intent">
+Parse user message and detect intent using patterns above.
+
+Output detected intent for routing decision.
+</step>
+
+<step name="route_no_ctx">
+**If NO .ctx/ folder (new user):**
+
+Route by detected intent:
+
+### Intent: new-project
+
+```
+Welcome to CTX!
+
+I understood: "{{user_request}}"
+
+You want to build something new. Let's set it up!
+```
+
+Execute /ctx:init inline (don't tell user to run it separately).
+
+### Intent: analyze (study/explore)
+
+```
+Welcome to CTX!
+
+I understood: "{{user_request}}"
+
+Let me analyze this codebase first.
+```
+
+**Step 1: Create structure**
+
+```bash
+mkdir -p .ctx/codebase
+```
+
+**Step 2: Spawn 4 mapper agents in parallel**
+
+Read model profile (default to "balanced"):
+```bash
+MODEL_PROFILE="haiku"
+```
+
+Spawn all 4 agents with a SINGLE message containing multiple Task calls:
+
+```
+Task(prompt="Analyze this codebase for technology stack. Write comprehensive analysis to: .ctx/codebase/TECH.md. Include languages, frameworks, dependencies, versions, build tools. Return confirmation with line count when complete.", subagent_type="ctx-tech-mapper", model="haiku", run_in_background=true, description="Map tech stack")
+
+Task(prompt="Analyze this codebase architecture. Write comprehensive analysis to: .ctx/codebase/ARCH.md. Include architectural pattern, layer structure, module boundaries, entry points, data flow. Return confirmation with line count when complete.", subagent_type="ctx-arch-mapper", model="haiku", run_in_background=true, description="Map architecture")
+
+Task(prompt="Analyze this codebase for quality patterns. Write comprehensive analysis to: .ctx/codebase/QUALITY.md. Include test coverage, linting, type safety, documentation, code smells. Return confirmation with line count when complete.", subagent_type="ctx-quality-mapper", model="haiku", run_in_background=true, description="Map quality")
+
+Task(prompt="Analyze this codebase for concerns and risks. Write comprehensive analysis to: .ctx/codebase/CONCERNS.md. Include security issues, technical debt, performance problems, operational risks. Return confirmation with line count when complete.", subagent_type="ctx-concerns-mapper", model="haiku", run_in_background=true, description="Map concerns")
+```
+
+**Step 3: Wait for completion**
+
+Use TaskOutput to wait for all 4 agents to complete.
+
+**Step 4: Verify output**
+
+```bash
+ls -la .ctx/codebase/
+wc -l .ctx/codebase/*.md
+```
+
+**Step 5: Create summary**
+
+Read all 4 documents and create SUMMARY.md:
+
+```bash
+cat .ctx/codebase/TECH.md .ctx/codebase/ARCH.md .ctx/codebase/QUALITY.md .ctx/codebase/CONCERNS.md
+```
+
+Write `.ctx/codebase/SUMMARY.md` with key findings from each document.
+
+**Step 6: Report**
+
+```
+[CTX] Codebase Mapped
+
+Tech: {{stack}}
+Architecture: {{pattern}}
+Quality: {{assessment}}
+Concerns: {{count}} identified
+
+Files: .ctx/codebase/
+
+---
+
+Next Up:
+
+/ctx:init - Initialize project with this context
+
+---
+```
+
+### Intent: debug
+
+```
+Welcome to CTX!
+
+I understood: "{{problem_description}}"
+
+Let me analyze the codebase and investigate.
+```
+
+First map codebase (same as analyze), then spawn debugger agent.
+
+### Intent: help or unknown
+
+```
+Welcome to CTX!
+
+What would you like to do?
+
+  "Build something new"  -> I'll set up your project
+  "Fix a bug"            -> I'll debug the issue
+  "Study the codebase"   -> I'll analyze everything
+  "Test the app"         -> I'll run full QA
+
+Just describe what you want!
+```
+</step>
+
+<step name="route_with_ctx">
+**If .ctx/ folder EXISTS:**
+
+### Load state first
+
+```bash
+cat .ctx/STATE.md
+cat .ctx/config.json 2>/dev/null || echo "{}"
+```
+
+Extract:
+- `status`: Current workflow status
+- `currentPhase`: Active phase
+- `profile`: Model profile (quality/balanced/budget)
+
+### Route by Intent + State
+
+| Intent | Action |
+|--------|--------|
+| new-project | Warn project exists, offer to add phase |
+| analyze | Run map-codebase (refresh) |
+| debug | Spawn debugger with context |
+| qa | Spawn QA agent |
+| status | Show status from STATE.md |
+| continue | Resume from STATE.md status |
+
+### Status Report Format
+
+```
+[CTX] Status
+
+Project: {{name}}
+Status: {{status}}
+Profile: {{profile}}
+
+Progress: [{{progress_bar}}] {{completed}}/{{total}} phases
+
+Current: {{current_phase}}
+Next: {{next_action}}
+
+---
+
+To continue: /ctx or describe what you want to do
+
+---
+```
+</step>
+
+</process>
+
+<research_integration>
+**When to use ArguSeek:**
+
+For debug, improve, and review intents, research BEFORE spawning agents:
+
+```
+mcp__arguseek__research_iteratively({
+  query: "{{tech_stack}} {{problem_or_goal}} best practices solutions 2025"
+})
+```
+
+Include research findings in agent prompts.
+</research_integration>
+
+<success_criteria>
+- [ ] .ctx structure checked first
+- [ ] Intent detected from user message
+- [ ] Correct flow routed
+- [ ] ArguSeek called for research-worthy intents
+- [ ] Task() agents spawned with full context
+- [ ] STATE.md created/updated
+- [ ] Clear "Next Up" shown
+- [ ] User knows to run /ctx to continue
+</success_criteria>