ctx-cc 2.1.0 → 2.3.0

package/commands/help.md

@@ -4,26 +4,60 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 2.1 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.1 Command Reference
+# CTX 2.3 Command Reference
 
 **CTX** (Continuous Task eXecution) - Smart workflow orchestration for Claude Code.
-8 commands. Smart routing. Debug loop until 100% fixed.
+8 commands. PRD-driven. Design-first. Smart routing. Debug loop until 100% fixed.
 
 ## Quick Start
 
 ```
-1. /ctx init           Initialize project
+1. /ctx init           Initialize project + generate PRD.json
 2. /ctx                Smart router does the right thing
 3. /ctx status         Check progress (read-only)
 4. /ctx pause          Checkpoint when needed
 ```
 
+## 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
+- **Secure Credentials** - `.ctx/.env` for test credentials (gitignored)
+- **Acceptance Criteria** - Each story has verifiable criteria
+- **`passes` Flag** - Auto-tracks story completion
+- **Story-Driven Workflow** - Plan → Execute → Verify → Next Story
+
+## Front-Loaded Philosophy
+
+```
+/ctx init gathers:
+├── Requirements → PRD.json stories
+├── Context → problem, target user, success criteria
+├── Credentials → .ctx/.env (gitignored)
+└── Constitution → rules for autonomous decisions
+
+Then /ctx runs autonomously:
+├── Only interrupts for architecture decisions
+├── Uses stored credentials for browser testing
+└── Loops until all stories pass
+```
+
 ## The 8 Commands
 
 ### Smart (Auto-routing)
@@ -66,16 +100,21 @@ Output ONLY the reference content below. Do NOT add project-specific analysis.
 
 ## Smart Router States
 
-When you run `/ctx`, it reads STATE.md and auto-routes:
+When you run `/ctx`, it reads STATE.md and PRD.json, auto-routes:
 
 | State | What happens |
 |-------|--------------|
-| initializing | Research + Plan (ArguSeek + ChunkHound) |
-| executing | Execute current task |
+| initializing | Research + Plan for current story |
+| executing | Execute tasks for current story |
 | debugging | **Debug loop until 100% fixed** |
-| verifying | Three-level verification |
+| verifying | Verify acceptance criteria → mark story as passed |
 | paused | Resume from checkpoint |
 
+**Story Flow:**
+```
+S001 → plan → execute → verify ✓ → S002 → plan → execute → verify ✓ → ...
+```
+
 ## Debug Loop
 
 When something breaks, CTX enters debug mode:
@@ -102,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)
@@ -122,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 |
 
@@ -137,19 +218,71 @@ 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
 
 ```
 .ctx/
-├── STATE.md          # Living digest - ALWAYS read first
-├── phases/{id}/      # Phase data
+├── STATE.md          # Living digest - execution state
+├── PRD.json          # Requirements contract - stories + criteria
+├── .env              # Test credentials (GITIGNORED)
+├── .gitignore        # Protects secrets
+├── phases/{story_id}/  # Per-story data
 │   ├── RESEARCH.md   # ArguSeek + ChunkHound results
-│   ├── PLAN.md       # 2-3 tasks (atomic)
-│   └── VERIFY.md     # Verification report
+│   ├── PLAN.md       # Tasks mapped to acceptance criteria
+│   ├── 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",
+      "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
+    }
+  ],
+  "metadata": {
+    "currentStory": "S001",
+    "passedStories": 0,
+    "totalStories": 5
+  }
+}
 ```
 
 ## Updating CTX
@@ -159,5 +292,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 2.1 - 8 commands, smart routing, debug loop, 100% verified*
+*CTX 2.3 - PRD-driven, design-first, story-verified, debug loop until 100% fixed*
 </reference>

package/commands/init.md

@@ -1,12 +1,38 @@
 ---
 name: ctx:init
-description: Initialize CTX project with STATE.md
+description: Initialize CTX project with STATE.md, PRD.json, design context, and secure credentials
 ---
 
 <objective>
-Initialize a new CTX 2.0 project. Creates `.ctx/` directory with STATE.md as the single source of truth.
+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 with design context
+- `.ctx/.env` - Secure credentials (gitignored)
+- `BRAND_KIT.md` - Visual foundation (if design work needed)
 </objective>
 
+<philosophy>
+## Front-Loaded Approach
+
+**Gather EVERYTHING upfront:**
+1. Project requirements → PRD.json
+2. User stories → PRD.json stories
+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>
+
 <workflow>
 ## Step 1: Check Existing
 If `.ctx/STATE.md` exists:
@@ -24,9 +50,12 @@ Scan the codebase:
 ## Step 3: Create Structure
 ```
 .ctx/
-├── STATE.md          # Living digest - ALWAYS read first
+├── STATE.md          # Living digest - execution state
+├── PRD.json          # Requirements contract - stories + acceptance criteria
+├── .env              # Credentials for testing (GITIGNORED)
+├── .gitignore        # Protects secrets
 ├── phases/           # Phase-specific data
-│   └── {phase-id}/
+│   └── {story_id}/
 │       ├── RESEARCH.md
 │       ├── PLAN.md
 │       └── VERIFY.md
@@ -35,6 +64,13 @@ Scan the codebase:
 └── archive/          # Archived states
 ```
 
+**Create `.ctx/.gitignore`:**
+```
+.env
+*.secrets
+credentials.json
+```
+
 ## Step 4: Initialize STATE.md
 Create STATE.md from template with:
 - Project name (from package.json or directory name)
@@ -49,33 +85,240 @@ chunkhound index . --output .ctx/chunks.json
 ```
 This enables semantic code search during planning.
 
-## Step 6: Prompt for Goal
+## Step 6: Gather Requirements
 Ask user: **"What do you want to build/fix/improve?"**
 
-Do NOT start planning yet. Just store the goal in STATE.md and set status to "initializing".
+Then ask follow-up questions to elicit user stories:
+- **"What are the main features/outcomes?"** (becomes stories)
+- **"How will you know each is done?"** (becomes acceptance criteria)
+- **"Any constraints or rules?"** (becomes constitution)
+
+## Step 7: Generate PRD.json
+Create PRD.json with gathered information:
+
+```json
+{
+  "$schema": "https://ctx.dev/schemas/prd.json",
+  "version": "1.0",
+  "project": {
+    "name": "{{project_name}}",
+    "description": "{{project_description}}",
+    "stack": "{{tech_stack}}",
+    "created": "{{timestamp}}"
+  },
+  "constitution": {
+    "principles": ["{{from user or defaults}}"],
+    "always": ["{{from user or defaults}}"],
+    "never": ["{{from user or defaults}}"],
+    "askFirst": ["{{from user or defaults}}"]
+  },
+  "stories": [
+    {
+      "id": "S001",
+      "title": "{{story_title}}",
+      "description": "{{story_description}}",
+      "acceptanceCriteria": ["{{criterion_1}}", "{{criterion_2}}"],
+      "priority": 1,
+      "phase": 1,
+      "passes": false,
+      "verifiedAt": null,
+      "notes": ""
+    }
+  ],
+  "metadata": {
+    "totalStories": {{count}},
+    "passedStories": 0,
+    "currentStory": "S001",
+    "lastUpdated": "{{timestamp}}"
+  }
+}
+```
+
+**Story Generation Rules:**
+- Each distinct feature/outcome = one story
+- Max 3 acceptance criteria per story (keep atomic)
+- Ordered by dependency (foundation first)
+- All stories start with `passes: false`
+
+## Step 8: Gather Credentials for Testing
+
+Ask user about testing requirements:
+
+**"Will this project need browser testing?"**
+If yes, gather:
+- **App URL** (local dev, staging, or production)
+- **Test user credentials** (email/password for login flows)
+- **Admin credentials** (if admin features exist)
+
+**"Are there external APIs or services?"**
+If yes, gather:
+- **API keys** (third-party services)
+- **Database URLs** (if direct DB testing needed)
+- **OAuth tokens** (if OAuth flows)
+
+**"Any other secrets needed for testing?"**
+- Environment-specific values
+- Feature flags
+- Test data identifiers
+
+## Step 9: Create .ctx/.env
+
+Write credentials to `.ctx/.env`:
+
+```bash
+# CTX Test Credentials - DO NOT COMMIT
+# Generated by /ctx init
+
+# App URLs
+APP_URL=http://localhost:3000
+STAGING_URL=
+
+# Test User
+TEST_USER_EMAIL=
+TEST_USER_PASSWORD=
+
+# Admin User (if applicable)
+ADMIN_EMAIL=
+ADMIN_PASSWORD=
+
+# API Keys
+API_KEY=
+
+# Database (if applicable)
+DATABASE_URL=
+
+# Other Secrets
+# Add as needed
+```
+
+**IMPORTANT:**
+- Create `.ctx/.gitignore` with `.env` entry
+- Warn user: "Credentials stored in .ctx/.env - NEVER commit this file"
+- Verify .gitignore is in place before proceeding
+
+## 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}}
+
+Do NOT start planning yet. Set status to "initializing".
 The user will run `/ctx` to begin the research + planning phase.
 </workflow>
 
 <output_format>
 ```
-[CTX 2.0] Initialized
+[CTX 2.3] Initialized
 
 Project: {{name}}
 Stack: {{language}} + {{framework}}
 Directory: .ctx/
 
+PRD: {{story_count}} stories
+  S001: [{{type}}] {{story_1_title}} ⬜
+  S002: [{{type}}] {{story_2_title}} ⬜
+  ...
+
+Constitution:
+  Principles: {{count}}
+  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}}
+  API Keys: {{count}} configured
+  ⚠️  Stored in .ctx/.env (gitignored)
+
 Integrations:
   ArguSeek: ready
   ChunkHound: {{indexed | not found}}
+  Browser Testing: {{ready | needs credentials}}
+  Figma MCP: {{ready | not configured}}
+  Gemini Design: {{ready | not configured}}
 
-Next: Run /ctx to start planning
+Ready for autonomous execution.
+Next: Run /ctx to start planning for S001
 ```
 </output_format>
 
 <success_criteria>
 - [ ] .ctx/ directory created
+- [ ] .ctx/.gitignore created (protects .env)
 - [ ] STATE.md initialized with detected info
+- [ ] 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
-- [ ] User prompted for goal
 - [ ] Status set to "initializing"
+- [ ] User warned about credential security
 </success_criteria>
+
+<security_reminders>
+**CRITICAL - Credential Security:**
+1. NEVER commit `.ctx/.env` to version control
+2. NEVER echo credentials in logs or output
+3. ALWAYS verify `.ctx/.gitignore` exists before storing secrets
+4. WARN user if `.gitignore` is missing or incomplete
+5. Use credentials ONLY for automated testing
+</security_reminders>