ctx-cc 3.4.0 → 3.4.2

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.2",
   "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/references/ui-brand.md

@@ -0,0 +1,256 @@
+<ui_patterns>
+
+Visual patterns for user-facing CTX output. All workflows @-reference this file.
+
+## Stage Banners
+
+Use for major workflow transitions. 55-character width.
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► {STAGE NAME}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Stage names (uppercase):**
+- `ANALYZING CODEBASE`
+- `MAPPING COMPLETE`
+- `INITIALIZING PROJECT`
+- `RESEARCHING`
+- `PLANNING PHASE {N}`
+- `EXECUTING`
+- `VERIFYING`
+- `PHASE {N} COMPLETE ✓`
+- `DEBUG MODE`
+- `QA TESTING`
+- `SHIP READY 🚀`
+
+---
+
+## Checkpoint Boxes
+
+User action required. 55-character width.
+
+```
+╔═══════════════════════════════════════════════════════╗
+║  CHECKPOINT: {Type}                                   ║
+╚═══════════════════════════════════════════════════════╝
+
+{Content}
+
+───────────────────────────────────────────────────────
+→ {ACTION PROMPT}
+───────────────────────────────────────────────────────
+```
+
+**Types:**
+- `CHECKPOINT: Approval Required` → `→ Type "approved" or describe issues`
+- `CHECKPOINT: Decision Required` → `→ Select an option`
+- `CHECKPOINT: Action Required` → `→ Type "done" when complete`
+
+---
+
+## Status Symbols
+
+```
+✓  Complete / Passed / Verified
+✗  Failed / Missing / Blocked
+◆  In Progress / Active
+○  Pending / Queued
+⚡ Auto-completed
+⚠  Warning / Attention needed
+🚀 Ship ready (only in banner)
+```
+
+---
+
+## Progress Bars
+
+**Percentage-based:**
+```
+Progress: ████████░░ 80%
+```
+
+**For agent spawning:**
+```
+Mapping:  [████████████████████] TECH     ✓ 12s
+          [████████████████████] ARCH     ✓ 15s
+          [████████████████░░░░] QUALITY  ◆ ...
+          [░░░░░░░░░░░░░░░░░░░░] CONCERNS ○
+```
+
+**Task count:**
+```
+Tasks: 2/4 complete
+Phases: 1/5 complete
+```
+
+---
+
+## Spawning Indicators
+
+When spawning agents, show activity:
+
+```
+◆ Spawning 4 mappers in parallel...
+  → ctx-tech-mapper
+  → ctx-arch-mapper
+  → ctx-quality-mapper
+  → ctx-concerns-mapper
+
+✓ ctx-tech-mapper complete: TECH.md (156 lines)
+✓ ctx-arch-mapper complete: ARCH.md (203 lines)
+✓ ctx-quality-mapper complete: QUALITY.md (178 lines)
+✓ ctx-concerns-mapper complete: CONCERNS.md (145 lines)
+```
+
+---
+
+## Summary Boxes
+
+For displaying analysis results:
+
+```
+┌─────────────────────────────────────────────────────┐
+│  CODEBASE SUMMARY                                   │
+├─────────────────────────────────────────────────────┤
+│  Tech:         TypeScript, Next.js 14, Prisma      │
+│  Architecture: Modular monolith                    │
+│  Quality:      67% coverage, 12 lint warnings      │
+│  Concerns:     3 security, 5 tech debt items       │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Next Up Block
+
+Always at end of major completions.
+
+```
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+**{Action}** — {one-line description}
+
+`{copy-paste command}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+───────────────────────────────────────────────────────
+
+**Also available:**
+- `/ctx:alternative-1` — description
+- `/ctx:alternative-2` — description
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Error Box
+
+```
+╔═══════════════════════════════════════════════════════╗
+║  ERROR                                                ║
+╚═══════════════════════════════════════════════════════╝
+
+{Error description}
+
+**To fix:** {Resolution steps}
+```
+
+---
+
+## Warning Box
+
+```
+┌─────────────────────────────────────────────────────┐
+│  ⚠ WARNING                                          │
+├─────────────────────────────────────────────────────┤
+│  {Warning message}                                  │
+└─────────────────────────────────────────────────────┘
+```
+
+---
+
+## Tables
+
+For structured data display:
+
+```
+| Phase | Status | Tasks | Progress |
+|-------|--------|-------|----------|
+| 1     | ✓      | 5/5   | 100%     |
+| 2     | ◆      | 2/4   | 50%      |
+| 3     | ○      | 0/3   | 0%       |
+```
+
+For concerns/issues:
+
+```
+| Severity | Count | Category        |
+|----------|-------|-----------------|
+| Critical | 0     | —               |
+| High     | 2     | Security        |
+| Medium   | 5     | Tech Debt       |
+| Low      | 8     | Code Quality    |
+```
+
+---
+
+## Welcome Banner
+
+First-time users:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► WELCOME
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+I understood: "{user_request}"
+
+{Brief explanation of what will happen next}
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Completion Banner
+
+End of workflow:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ CTX ► {STAGE} COMPLETE ✓
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+{Summary of what was accomplished}
+
+Files: {list of created/modified files}
+
+───────────────────────────────────────────────────────
+
+## ▶ Next Up
+
+{Next action recommendation}
+
+───────────────────────────────────────────────────────
+```
+
+---
+
+## Anti-Patterns (AVOID)
+
+- Varying box/banner widths (use 55 chars consistently)
+- Mixing banner styles (`===`, `---`, `***`)
+- Skipping `CTX ►` prefix in banners
+- Random emoji (only use defined symbols above)
+- Missing Next Up block after completions
+- Plain text output without structure
+- Inconsistent indentation
+- Missing progress indicators during long operations
+
+</ui_patterns>

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})`);