ctx-cc 2.2.0 → 3.0.0

package/commands/help.md

@@ -4,16 +4,16 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 2.2 command reference.
+Display the CTX 2.3 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 2.2 Command Reference
+# CTX 2.3 Command Reference
 
 **CTX** (Continuous Task eXecution) - Smart workflow orchestration for Claude Code.
-8 commands. PRD-driven. Smart routing. Debug loop until 100% fixed.
+8 commands. PRD-driven. Design-first. Smart routing. Debug loop until 100% fixed.
 
 ## Quick Start
 
@@ -24,7 +24,17 @@ Output ONLY the reference content below. Do NOT add project-specific analysis.
 4. /ctx pause          Checkpoint when needed
 ```
 
-## What's New in 2.2
+## What's New in 2.3
+
+- **Design System Integration** - Full brand + UI design workflow
+- **ctx-designer Agent** - WCAG 2.2 AA, W3C tokens, Figma MCP, Gemini
+- **Story Types** - feature, brand, design, fix, refactor
+- **3 Options Pattern** - Always present A/B/C for design decisions
+- **Visual Approval Gates** - Mood board → Direction → Prototype → Final
+- **BRAND_KIT.md** - Visual foundation with W3C design tokens
+- **EAA 2025 Ready** - European Accessibility Act compliance
+
+## What's in 2.2
 
 - **Front-Loaded Approach** - Gather ALL info upfront, execute autonomously
 - **PRD.json** - Requirements contract with user stories
@@ -131,6 +141,47 @@ Loop (max 5 attempts):
 | Substantive | Real code, not stub? | No TODOs, no placeholders |
 | Wired | Imported and used? | Trace imports |
 
+## Design Workflow
+
+CTX handles visual work with dedicated agents and approval gates.
+
+### Story Types
+| Type | Agent | Purpose |
+|------|-------|---------|
+| feature | ctx-executor | Standard implementation |
+| brand | ctx-designer | BRAND_KIT.md + tokens |
+| design | ctx-designer | UI components/pages |
+| fix | ctx-debugger | Bug fixes |
+| refactor | ctx-executor | Code improvements |
+
+### Design Approval Gates
+```
+Mood Board → Direction (A/B/C) → Prototype → Final
+```
+Each gate requires user approval before proceeding.
+
+### 3 Options Pattern
+All design decisions present:
+- **Option A**: Conservative (safe, proven)
+- **Option B**: Balanced (recommended)
+- **Option C**: Bold (distinctive)
+
+### WCAG 2.2 AA Compliance
+| Criterion | Requirement |
+|-----------|-------------|
+| 2.4.11 | Focus not obscured |
+| 2.5.7 | Drag alternatives |
+| 2.5.8 | 24x24px targets |
+| 3.3.8 | Accessible auth |
+
+### W3C Design Tokens
+```
+tokens/
+├── primitive.tokens.json  # Raw values
+├── semantic.tokens.json   # Purpose aliases
+└── component.tokens.json  # Component-specific
+```
+
 ## Key Design Principles
 
 ### Atomic Planning (2-3 Tasks Max)
@@ -151,13 +202,14 @@ Prevents context degradation. Big work = multiple phases.
 | 30-50% | Good | Continue |
 | 50%+ | Degrading | Auto-checkpoint |
 
-## 5 Specialized Agents
+## 6 Specialized Agents
 
 | Agent | When spawned |
 |-------|--------------|
 | ctx-researcher | During planning (ArguSeek + ChunkHound) |
 | ctx-planner | After research |
-| ctx-executor | During execution |
+| ctx-executor | During execution (feature stories) |
+| ctx-designer | During execution (brand/design stories) |
 | ctx-debugger | When debugging |
 | ctx-verifier | During verification |
 
@@ -166,6 +218,8 @@ Prevents context degradation. Big work = multiple phases.
 - **ArguSeek**: Web research during planning
 - **ChunkHound**: Semantic code search (`uv tool install chunkhound`)
 - **Playwright/DevTools**: Browser verification for UI
+- **Figma MCP**: Design context extraction and screenshots
+- **Gemini Design**: Image generation and UI code generation
 
 ## Directory Structure
 
@@ -178,21 +232,48 @@ Prevents context degradation. Big work = multiple phases.
 ├── phases/{story_id}/  # Per-story data
 │   ├── RESEARCH.md   # ArguSeek + ChunkHound results
 │   ├── PLAN.md       # Tasks mapped to acceptance criteria
-│   └── VERIFY.md     # Verification report
+│   ├── VERIFY.md     # Verification report
+│   ├── MOOD_BOARD.md # Design references (design stories)
+│   └── DESIGN_BRIEF.md # Design decisions (design stories)
 ├── checkpoints/      # Auto-checkpoints
 ├── debug/            # Debug screenshots
 └── verify/           # Verification screenshots
+
+project/
+├── BRAND_KIT.md      # Visual foundation (brand stories)
+└── tokens/           # W3C design tokens
+    ├── primitive.tokens.json
+    ├── semantic.tokens.json
+    └── component.tokens.json
 ```
 
 ## PRD.json Structure
 
 ```json
 {
+  "brand": {
+    "hasBrandKit": false,
+    "personality": ["professional", "modern"],
+    "euMarket": true
+  },
+  "design": {
+    "wcagLevel": "AA",
+    "eaaCompliance": true,
+    "tokenFormat": "w3c"
+  },
   "stories": [
     {
       "id": "S001",
-      "title": "User login",
-      "acceptanceCriteria": ["User can log in with email", "..."],
+      "type": "brand",
+      "title": "Establish brand kit",
+      "acceptanceCriteria": ["BRAND_KIT.md exists", "tokens/ populated"],
+      "passes": false
+    },
+    {
+      "id": "S002",
+      "type": "design",
+      "title": "Login page",
+      "acceptanceCriteria": ["WCAG 2.2 AA compliant", "All states implemented"],
       "passes": false
     }
   ],
@@ -211,5 +292,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 2.2 - PRD-driven, story-verified, debug loop until 100% fixed*
+*CTX 2.3 - PRD-driven, design-first, story-verified, debug loop until 100% fixed*
 </reference>

package/commands/init.md

@@ -1,15 +1,16 @@
 ---
 name: ctx:init
-description: Initialize CTX project with STATE.md, PRD.json, and secure credentials
+description: Initialize CTX project with STATE.md, PRD.json, design context, and secure credentials
 ---
 
 <objective>
-Initialize a new CTX 2.2 project. Front-loads ALL information gathering so execution runs autonomously with minimal interruption.
+Initialize a new CTX 2.3 project. Front-loads ALL information gathering so execution runs autonomously with minimal interruption.
 
 Creates:
 - `.ctx/STATE.md` - Execution state
-- `.ctx/PRD.json` - Requirements contract
+- `.ctx/PRD.json` - Requirements contract with design context
 - `.ctx/.env` - Secure credentials (gitignored)
+- `BRAND_KIT.md` - Visual foundation (if design work needed)
 </objective>
 
 <philosophy>
@@ -21,10 +22,13 @@ Creates:
 3. Credentials for testing → .ctx/.env
 4. URLs and endpoints → .ctx/.env
 5. Constitution/rules → PRD.json constitution
+6. Design context → PRD.json brand/design sections
+7. Visual requirements → Brand personality, mood, inspirations
 
 **Then execute autonomously:**
 - Minimal user interruption during execution
 - Only ask user for architecture decisions (Rule 4)
+- Only ask user for design approvals at gates
 - Use stored credentials for browser verification
 - Deliver complete, verified project
 </philosophy>
@@ -192,7 +196,57 @@ DATABASE_URL=
 - Warn user: "Credentials stored in .ctx/.env - NEVER commit this file"
 - Verify .gitignore is in place before proceeding
 
-## Step 10: Link STATE.md to PRD
+## Step 10: Gather Design Context
+
+**"Does this project need visual/UI work?"**
+
+If yes, gather brand context:
+
+**Brand Personality:**
+- "What 3-5 adjectives describe the desired brand feel?"
+- "Any brands you admire visually?" (inspirations)
+- "Any visual styles to AVOID?" (anti-inspirations)
+
+**Existing Assets:**
+- "Do you have existing brand assets?" (logo, colors, fonts)
+- "Figma file link?" (optional but recommended)
+
+**Accessibility Requirements:**
+- "Target market includes EU?" (EAA 2025 compliance)
+- "WCAG level needed?" (default: 2.2 AA)
+
+**Mode Support:**
+- "Dark mode needed?" (light-only or light+dark)
+
+Store in PRD.json `brand` section:
+```json
+{
+  "brand": {
+    "hasBrandKit": false,
+    "personality": ["professional", "trustworthy", "modern"],
+    "visualMood": "Clean, minimal, with subtle warmth",
+    "inspirations": ["Stripe", "Linear"],
+    "antiInspirations": ["flashy", "cluttered"],
+    "existingAssets": ["logo.svg"],
+    "darkModeRequired": true,
+    "euMarket": true
+  },
+  "design": {
+    "wcagLevel": "AA",
+    "eaaCompliance": true,
+    "tokenFormat": "w3c",
+    "figmaFileKey": null,
+    "breakpoints": { "mobile": 375, "tablet": 768, "desktop": 1440 }
+  }
+}
+```
+
+**Story Type Assignment:**
+- If no brand kit exists and UI work needed → Create brand story first (type: "brand")
+- For each UI component/page → Create design story (type: "design")
+- For backend/logic work → Create feature story (type: "feature")
+
+## Step 11: Link STATE.md to PRD
 Update STATE.md to reference current story:
 - **Current Story**: S001 - {{title}}
 
@@ -202,15 +256,15 @@ The user will run `/ctx` to begin the research + planning phase.
 
 <output_format>
 ```
-[CTX 2.2] Initialized
+[CTX 2.3] Initialized
 
 Project: {{name}}
 Stack: {{language}} + {{framework}}
 Directory: .ctx/
 
 PRD: {{story_count}} stories
-  S001: {{story_1_title}} ⬜
-  S002: {{story_2_title}} ⬜
+  S001: [{{type}}] {{story_1_title}} ⬜
+  S002: [{{type}}] {{story_2_title}} ⬜
   ...
 
 Constitution:
@@ -218,6 +272,14 @@ Constitution:
   Always: {{count}}
   Never: {{count}}
 
+Design Context:
+  Brand Kit: {{exists | needs creation}}
+  Personality: {{adjectives}}
+  WCAG Level: 2.2 {{level}}
+  EAA 2025: {{required | not required}}
+  Dark Mode: {{yes | no}}
+  Figma: {{linked | not linked}}
+
 Credentials:
   App URL: {{configured | not set}}
   Test User: {{configured | not set}}
@@ -228,6 +290,8 @@ Integrations:
   ArguSeek: ready
   ChunkHound: {{indexed | not found}}
   Browser Testing: {{ready | needs credentials}}
+  Figma MCP: {{ready | not configured}}
+  Gemini Design: {{ready | not configured}}
 
 Ready for autonomous execution.
 Next: Run /ctx to start planning for S001
@@ -241,6 +305,9 @@ Next: Run /ctx to start planning for S001
 - [ ] PRD.json created with user stories
 - [ ] Constitution defined (user or defaults)
 - [ ] All stories have acceptance criteria
+- [ ] Stories assigned correct type (feature/brand/design)
+- [ ] Design context gathered (if UI work needed)
+- [ ] Brand story created first (if no BRAND_KIT.md)
 - [ ] .ctx/.env created with credentials (if provided)
 - [ ] ChunkHound index attempted
 - [ ] Status set to "initializing"

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>