ctx-cc 2.2.0 → 2.3.0

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/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/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "2.2.0",
-  "description": "CTX 2.2 (Continuous Task eXecution) - PRD-driven workflow orchestration for Claude Code. Story-verified, debug loop until 100% fixed.",
+  "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.",
   "keywords": [
     "claude",
     "claude-code",