ctx-cc 2.1.0 → 2.3.0

package/commands/plan.md

@@ -1,73 +1,104 @@
 ---
 name: ctx:plan
-description: Force research + planning phase regardless of current state
-args: goal (optional - new goal to plan for)
+description: Force research + planning phase for current PRD story
+args: story_id (optional - specific story to plan, defaults to current)
 ---
 
 <objective>
-Force enter planning mode. Runs research (ArguSeek + ChunkHound) and creates atomic plan.
-Use when you want to explicitly plan rather than let smart router decide.
+Force enter planning mode for a PRD story. Reads acceptance criteria from PRD.json,
+runs research (ArguSeek + ChunkHound), and creates atomic plan to satisfy the story.
 </objective>
 
 <usage>
 ```
-/ctx plan                    # Re-plan current phase goal
-/ctx plan "add user auth"    # Plan for new goal
+/ctx plan           # Plan for current story (from PRD.json)
+/ctx plan S003      # Plan for specific story
 ```
 </usage>
 
 <workflow>
 ## Step 1: Validate Project
-If `.ctx/STATE.md` doesn't exist:
+If `.ctx/STATE.md` or `.ctx/PRD.json` doesn't exist:
 - Error: "No project found. Run /ctx init first."
 
-## Step 2: Determine Goal
-If goal argument provided:
-- Use provided goal
-- Create new phase if needed
+## Step 2: Load Story from PRD
+Read `.ctx/PRD.json`:
 
-If no goal argument:
-- Use current phase goal from STATE.md
-- If no current phase, ask user for goal
+If story_id argument provided:
+- Find story with matching id
+- Error if not found
+
+If no argument:
+- Use `metadata.currentStory` from PRD.json
+- If null, use first story where `passes: false`
+
+**Story data provides:**
+- `title` → Phase goal
+- `description` → Context for research
+- `acceptanceCriteria` → Verification checklist
 
 ## Step 3: Research Phase
-Spawn **ctx-researcher** agent:
+Spawn **ctx-researcher** agent with story context:
 
 1. **ArguSeek Research**
-   - Best practices for goal
+   - Best practices for story goal
    - Security considerations
-   - Common pitfalls
+   - Common pitfalls for acceptance criteria
    - Performance patterns
 
 2. **ChunkHound Analysis** (if available)
-   - Semantic search for related code
+   - Semantic search for story-related code
    - Pattern detection
    - Entry point mapping
 
-3. **Output**: `.ctx/phases/{id}/RESEARCH.md`
+3. **Output**: `.ctx/phases/{story_id}/RESEARCH.md`
 
 ## Step 4: Planning Phase
 Spawn **ctx-planner** agent:
 
 1. Read RESEARCH.md
-2. Define verification criteria
+2. Map acceptance criteria to verification steps
 3. Break into **2-3 atomic tasks** (strict limit)
-4. Assign execution order
-
-Output: `.ctx/phases/{id}/PLAN.md`
+4. Each task contributes to passing acceptance criteria
+5. Assign execution order
+
+Output: `.ctx/phases/{story_id}/PLAN.md`
+
+**Plan Format:**
+```yaml
+story: S001
+title: "{{story_title}}"
+acceptanceCriteria:
+  - criterion: "{{criterion_1}}"
+    tasks: [1]
+  - criterion: "{{criterion_2}}"
+    tasks: [1, 2]
+tasks:
+  - id: 1
+    title: "{{task_title}}"
+    criteria: ["{{criterion_1}}", "{{criterion_2}}"]
+```
 
 ## Step 5: Update State
 Update STATE.md:
 - Status: "executing"
-- Current phase: {id}
-- Phase goal: {goal}
+- Current Story: {story_id} - {title}
+- Phase goal: {story_title}
 - Total tasks: {count}
 - Completed: 0
+
+Update PRD.json:
+- `metadata.currentStory`: {story_id}
 </workflow>
 
 <output_format>
 ```
-[CTX Plan] Goal: {goal}
+[CTX Plan] Story: {story_id} - {title}
+
+Acceptance Criteria:
+  ✓ {criterion_1}
+  ✓ {criterion_2}
+  ✓ {criterion_3}
 
 Research:
   ArguSeek: {n} findings
@@ -75,12 +106,11 @@ Research:
 
 Plan Created:
   Tasks: {count} (atomic)
-  Files: .ctx/phases/{id}/PLAN.md
+  Files: .ctx/phases/{story_id}/PLAN.md
 
 Tasks:
-  1. {task_1_title}
-  2. {task_2_title}
-  3. {task_3_title} (if exists)
+  1. {task_1_title} → [criteria 1, 2]
+  2. {task_2_title} → [criteria 2, 3]
 
 Ready to execute. Run /ctx to start.
 ```
@@ -88,6 +118,8 @@ Ready to execute. Run /ctx to start.
 
 <guardrails>
 - Plans are ALWAYS atomic: 2-3 tasks maximum
-- If goal requires more, split into multiple phases
+- Each task must map to at least one acceptance criterion
+- If story requires more tasks, ask user to split into smaller stories
 - Research runs even if ChunkHound unavailable (ArguSeek only)
+- Story acceptance criteria = verification checklist
 </guardrails>

package/commands/verify.md

@@ -1,11 +1,10 @@
 ---
 name: ctx:verify
-description: Force three-level verification regardless of current state
+description: Force verification of current story against PRD acceptance criteria
 ---
 
 <objective>
-Force verification of current phase. Runs three-level check + anti-pattern scan + browser verification.
-Use when you want to verify work before smart router would normally trigger it.
+Verify current story against PRD.json acceptance criteria. Runs three-level check + anti-pattern scan + browser verification. On success, marks story as `passes: true` in PRD.json.
 </objective>
 
 <usage>
@@ -17,17 +16,21 @@ Use when you want to verify work before smart router would normally trigger it.
 
 <workflow>
 ## Step 1: Validate Project
-If `.ctx/STATE.md` doesn't exist:
+If `.ctx/STATE.md` or `.ctx/PRD.json` doesn't exist:
 - Error: "No project found. Run /ctx init first."
 
-If no current phase:
-- Error: "No phase to verify. Run /ctx plan first."
+If no current story (all `passes: true`):
+- Info: "All stories verified! PRD complete."
 
 ## Step 2: Load Context
 Read:
+- `.ctx/PRD.json` - current story and acceptance criteria
 - `.ctx/STATE.md` - current state
-- `.ctx/phases/{id}/PLAN.md` - verification criteria
-- Original phase goal
+- `.ctx/phases/{story_id}/PLAN.md` - task-to-criteria mapping
+
+**Key data:**
+- `story.acceptanceCriteria` → What to verify
+- `plan.tasks[].criteria` → How tasks map to criteria
 
 ## Step 3: Three-Level Verification
 Spawn **ctx-verifier** agent:
@@ -75,18 +78,61 @@ If phase involves UI or `--browser` flag:
 4. Take screenshot proof
 5. Save to `.ctx/verify/phase-{id}.png`
 
-## Step 6: Generate Report
-Write `.ctx/phases/{id}/VERIFY.md`
+## Step 6: Verify Acceptance Criteria
+For each criterion in story.acceptanceCriteria:
+- Check if criterion is satisfied
+- Map to three-level results
+- Document evidence
+
+## Step 7: Generate Report
+Write `.ctx/phases/{story_id}/VERIFY.md`:
+```yaml
+story: S001
+title: "{{story_title}}"
+result: PASS|FAIL
+criteria:
+  - criterion: "{{criterion_1}}"
+    status: PASS|FAIL
+    evidence: "{{what proved it}}"
+  - criterion: "{{criterion_2}}"
+    status: PASS|FAIL
+    evidence: "{{what proved it}}"
+timestamp: "{{ISO8601}}"
+```
+
+## Step 8: Update PRD.json
+If ALL criteria pass:
+```json
+{
+  "stories[current].passes": true,
+  "stories[current].verifiedAt": "{{timestamp}}",
+  "metadata.passedStories": "{{increment}}",
+  "metadata.currentStory": "{{next_unpassed_story_id or null}}"
+}
+```
 
-## Step 7: Update State
+If ANY criterion fails:
+- Keep `passes: false`
+- Add failure notes to `stories[current].notes`
+
+## Step 9: Update STATE.md
 Based on results:
-- **PASS**: Log success, ready for next phase
-- **FAIL**: Create fix tasks, set status = "executing"
+- **PASS**:
+  - Set status to "initializing" for next story
+  - Update current story reference
+- **FAIL**:
+  - Create fix tasks
+  - Set status = "debugging" or "executing"
 </workflow>
 
 <output_format>
 ```
-[CTX Verify] Phase: {id} - {goal}
+[CTX Verify] Story: {story_id} - {title}
+
+Acceptance Criteria:
+  ✓ {criterion_1} - PASS
+  ✓ {criterion_2} - PASS
+  ✗ {criterion_3} - FAIL: {reason}
 
 Three-Level Check:
   ✓ Exists: {pass}/{total}
@@ -101,17 +147,21 @@ Anti-Pattern Scan:
 Browser Verification:
   URL: {url}
   Status: PASS/FAIL
-  Screenshot: .ctx/verify/phase-{id}.png
+  Screenshot: .ctx/verify/story-{id}.png
 
 Overall: {PASS / FAIL}
 
 {If FAIL:}
 Fixes Required:
-  1. {fix_1}
+  1. {fix_1} → [criterion 3]
   2. {fix_2}
 
 {If PASS:}
-Phase verified. Run /ctx to continue.
+✓ Story {story_id} verified!
+PRD Progress: {passed}/{total} stories ({percent}%)
+
+Next Story: {next_story_id} - {next_title}
+Run /ctx to start planning.
 ```
 </output_format>
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "2.1.0",
-  "description": "CTX 2.0 (Continuous Task eXecution) - Smart workflow orchestration for Claude Code. 4 commands, debug loop, 100% verified.",
+  "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",

package/src/install.js

@@ -28,9 +28,9 @@ function printBanner() {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝
 `));
-  console.log(`  ${bold('CTX 2.1')} ${dim(`v${VERSION}`)}`);
-  console.log('  Continuous Task eXecution for Claude Code.');
-  console.log('  8 commands. Smart routing. Debug loop.\n');
+  console.log(`  ${bold('CTX 2.2')} ${dim(`v${VERSION}`)}`);
+  console.log('  PRD-driven workflow orchestration for Claude Code.');
+  console.log('  8 commands. Story-verified. Debug loop.\n');
 }
 
 function copyDir(src, dest) {

package/templates/BRAND_KIT.md

@@ -0,0 +1,265 @@
+# Brand Kit - {{project_name}}
+
+**Created:** {{timestamp}}
+**Approved:** {{approval_date}}
+**Version:** 1.0
+**Token Format:** W3C Design Tokens (DTCG)
+
+---
+
+## Brand Essence
+
+### Mission
+{{mission_statement}}
+
+### Personality
+{{personality_adjectives}}
+
+### Target Audience
+{{target_audience}}
+
+### Visual Mood
+{{visual_mood_description}}
+
+---
+
+## Token Architecture
+
+### Three-Tier Structure
+```
+tokens/
+├── primitive.tokens.json   # Raw values (colors, sizes)
+├── semantic.tokens.json    # Purpose-based aliases + modes
+└── component.tokens.json   # Component-specific tokens
+```
+
+### Mode Support
+- Light mode (default)
+- Dark mode
+{{additional_modes}}
+
+---
+
+## Color System
+
+### Primitive Colors
+| Token | Light Mode | Dark Mode |
+|-------|------------|-----------|
+| gray-50 | #FAFAFA | #171717 |
+| gray-100 | #F4F4F5 | #27272A |
+| gray-200 | #E4E4E7 | #3F3F46 |
+| gray-300 | #D4D4D8 | #52525B |
+| gray-400 | #A1A1AA | #71717A |
+| gray-500 | #71717A | #A1A1AA |
+| gray-600 | #52525B | #D4D4D8 |
+| gray-700 | #3F3F46 | #E4E4E7 |
+| gray-800 | #27272A | #F4F4F5 |
+| gray-900 | #18181B | #FAFAFA |
+| {{primary_color_name}} | {{primary_light}} | {{primary_dark}} |
+
+### Semantic Colors
+| Token | References | Usage |
+|-------|------------|-------|
+| background-primary | {gray-50} | Page backgrounds |
+| background-surface | {gray-100} | Cards, modals |
+| text-primary | {gray-900} | Body text |
+| text-secondary | {gray-600} | Captions, hints |
+| interactive | {{{primary_color}}} | CTAs, links |
+| interactive-hover | {{{primary_hover}}} | Hover states |
+
+### State Colors
+| State | Color | Hex |
+|-------|-------|-----|
+| success | green-500 | #22C55E |
+| warning | amber-500 | #F59E0B |
+| error | red-500 | #EF4444 |
+| info | blue-500 | #3B82F6 |
+
+### Accessibility Compliance
+| Combination | Ratio | WCAG 2.2 |
+|-------------|-------|----------|
+| text-primary on background | {{ratio_1}} | AA Pass |
+| text-secondary on background | {{ratio_2}} | AA Pass |
+| interactive on background | {{ratio_3}} | AA Pass |
+
+---
+
+## Typography
+
+### Font Stack
+| Role | Font Family | Fallback |
+|------|-------------|----------|
+| Heading | {{heading_font}} | system-ui, sans-serif |
+| Body | {{body_font}} | system-ui, sans-serif |
+| Mono | {{mono_font}} | ui-monospace, monospace |
+
+### Type Scale (Desktop)
+| Level | Size | Line Height | Weight | Letter Spacing |
+|-------|------|-------------|--------|----------------|
+| display | 48px | 1.1 | 700 | -0.02em |
+| h1 | 36px | 1.2 | 600 | -0.01em |
+| h2 | 28px | 1.3 | 600 | 0 |
+| h3 | 22px | 1.4 | 500 | 0 |
+| body-lg | 18px | 1.6 | 400 | 0 |
+| body | 16px | 1.5 | 400 | 0 |
+| body-sm | 14px | 1.5 | 400 | 0 |
+| caption | 12px | 1.4 | 400 | 0.01em |
+
+### Responsive Scale
+| Level | Mobile | Tablet | Desktop |
+|-------|--------|--------|---------|
+| display | 32px | 40px | 48px |
+| h1 | 28px | 32px | 36px |
+| h2 | 22px | 24px | 28px |
+
+---
+
+## Spacing & Layout
+
+### Base Scale (4px grid)
+| Token | Value | Usage |
+|-------|-------|-------|
+| space-0 | 0px | Reset |
+| space-1 | 4px | Tight inline |
+| space-2 | 8px | Related elements |
+| space-3 | 12px | Form gaps |
+| space-4 | 16px | Default gap |
+| space-6 | 24px | Section padding |
+| space-8 | 32px | Card padding |
+| space-12 | 48px | Section gaps |
+| space-16 | 64px | Page sections |
+| space-24 | 96px | Hero spacing |
+
+### Border Radius
+| Token | Value | Usage |
+|-------|-------|-------|
+| radius-sm | 4px | Small elements |
+| radius-md | 8px | Default |
+| radius-lg | 12px | Cards |
+| radius-full | 9999px | Pills, avatars |
+
+### Breakpoints
+| Token | Value | Target |
+|-------|-------|--------|
+| breakpoint-sm | 640px | Mobile landscape |
+| breakpoint-md | 768px | Tablet |
+| breakpoint-lg | 1024px | Desktop |
+| breakpoint-xl | 1280px | Large desktop |
+
+---
+
+## Motion
+
+### Duration
+| Token | Value | Usage |
+|-------|-------|-------|
+| duration-instant | 0ms | No animation |
+| duration-fast | 100ms | Micro-interactions |
+| duration-normal | 200ms | Standard transitions |
+| duration-slow | 300ms | Emphasis |
+| duration-slower | 500ms | Page transitions |
+
+### Easing
+| Token | Value | Usage |
+|-------|-------|-------|
+| ease-linear | linear | Progress bars |
+| ease-in | cubic-bezier(0.4, 0, 1, 1) | Exit animations |
+| ease-out | cubic-bezier(0, 0, 0.2, 1) | Enter animations |
+| ease-in-out | cubic-bezier(0.4, 0, 0.2, 1) | Standard |
+| ease-bounce | cubic-bezier(0.34, 1.56, 0.64, 1) | Playful |
+
+### Common Animations
+| Token | Duration | Easing | Usage |
+|-------|----------|--------|-------|
+| transition-colors | 150ms | ease-out | Hover states |
+| transition-transform | 200ms | ease-out | Scale/move |
+| transition-opacity | 200ms | ease-in-out | Fade |
+| transition-all | 200ms | ease-in-out | Complex |
+
+---
+
+## Accessibility Requirements
+
+### WCAG 2.2 Level AA (Required)
+- [x] 1.4.3 Contrast (Minimum) - 4.5:1 text
+- [x] 1.4.11 Non-text Contrast - 3:1 UI components
+- [x] 2.4.11 Focus Not Obscured (Minimum)
+- [x] 2.5.7 Dragging Movements - alternatives provided
+- [x] 2.5.8 Target Size (Minimum) - 24x24px minimum
+- [x] 3.3.8 Accessible Authentication (Minimum)
+
+### EAA 2025 Compliance (EU Markets)
+European Accessibility Act enforcement: June 28, 2025
+- All WCAG 2.2 AA criteria
+- EN 301 549 v3.2.1 alignment
+
+---
+
+## Visual Guidelines
+
+### Do's
+- Use semantic tokens, not primitives, in components
+- Maintain 4px grid alignment
+- Test all color combinations for contrast
+- Provide alternatives to dragging interactions
+- Ensure 24x24px minimum touch targets
+- Use focus-visible for keyboard focus states
+
+### Don'ts
+- Don't use color alone to convey information
+- Don't use hardcoded values (use tokens)
+- Don't skip focus states
+- Don't obscure focused elements with overlays
+- Don't require cognitive function tests for auth
+- Don't disable paste in password fields
+
+---
+
+## Asset Locations
+
+```
+project/
+├── BRAND_KIT.md              # This document
+├── tokens/
+│   ├── primitive.tokens.json # Raw values
+│   ├── semantic.tokens.json  # Semantic + modes
+│   └── component.tokens.json # Component tokens
+├── brand-assets/
+│   ├── tokens.css            # CSS custom properties
+│   ├── tokens.scss           # SCSS variables
+│   ├── tokens.js             # JS constants
+│   ├── tailwind.config.js    # Tailwind theme
+│   └── style-dictionary.config.json
+├── design-references/
+│   └── [screenshots]
+└── logo/
+    ├── logo-primary.svg
+    ├── logo-light.svg
+    └── logo-dark.svg
+```
+
+---
+
+## Export Commands
+
+```bash
+# Using Style Dictionary
+npx style-dictionary build --config style-dictionary.config.json
+
+# Or run /ctx with design token update
+```
+
+---
+
+## Approval History
+
+| Date | Approved By | Notes |
+|------|-------------|-------|
+| {{mood_board_date}} | {{user}} | Mood board approved |
+| {{direction_date}} | {{user}} | Direction selected: Option {{option}} |
+| {{final_date}} | {{user}} | Final brand kit approved |
+
+---
+
+**This document is the source of truth for all visual decisions.**
+**All design work MUST reference this kit.**