ctx-cc 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
-# CTX 2.1 - Continuous Task eXecution
+# CTX 2.3 - Continuous Task eXecution
 
-> Smart workflow orchestration for Claude Code. 8 commands. Smart routing. Debug loop until 100% fixed.
+> Smart workflow orchestration for Claude Code. PRD-driven. Design-first. 8 commands. Debug loop until 100% fixed.
 
 ## Installation
 
@@ -15,10 +15,15 @@ npx ctx-cc --project    # Install to .claude in current directory
 npx ctx-cc --force      # Overwrite existing installation
 ```
 
-## Why CTX 2.1?
+## Why CTX 2.3?
 
-| Feature | Before | CTX 2.1 |
+| Feature | Before | CTX 2.3 |
 |---------|--------|---------|
+| Requirements | Ad-hoc goals | **PRD.json with stories** |
+| Design | Manual workflow | **Full design system** |
+| Accessibility | Manual checks | **WCAG 2.2 AA + EAA 2025** |
+| Tokens | Custom formats | **W3C Design Tokens** |
+| Verification | Task-based | **Acceptance criteria** |
 | Commands | 12-27 | **8** (organized) |
 | Router | Manual | **Smart (auto-routing)** |
 | Debug | Manual | **Loop until 100% fixed** |
@@ -29,12 +34,63 @@ npx ctx-cc --force      # Overwrite existing installation
 ## Quick Start
 
 ```
-1. /ctx init           Initialize project
-2. /ctx                Smart router does the rest
+1. /ctx init           Gather ALL info upfront (requirements + credentials)
+2. /ctx                Autonomous execution with minimal interruption
 3. /ctx pause          Checkpoint when needed
 ```
 
-That's it. `/ctx` reads STATE.md and knows what to do next.
+**The Flow:**
+```
+/ctx init → Gather everything → /ctx → Autonomous loop → Delivered!
+```
+
+## Front-Loaded Approach
+
+CTX gathers EVERYTHING at initialization:
+- **Requirements** → PRD.json stories
+- **Acceptance criteria** → How to verify each story
+- **Test credentials** → .ctx/.env (gitignored)
+- **Constitution** → Rules for autonomous decisions
+- **Design context** → Brand personality, inspirations, accessibility needs
+
+Then executes autonomously:
+- Only interrupts for architecture decisions (Rule 4)
+- Only interrupts for design approvals at gates
+- Uses stored credentials for browser testing
+- Loops through stories until all pass
+
+## Design System (New in 2.3)
+
+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 + W3C tokens |
+| design | ctx-designer | UI components/pages |
+
+### 3 Options Pattern
+All design decisions present three options:
+- **Option A**: Conservative (safe, proven)
+- **Option B**: Balanced (recommended)
+- **Option C**: Bold (distinctive)
+
+### Design Approval Gates
+```
+Mood Board → Direction (A/B/C) → Prototype → Final
+```
+Each gate requires user approval before proceeding.
+
+### WCAG 2.2 AA + EAA 2025
+| Criterion | Requirement |
+|-----------|-------------|
+| 2.4.11 | Focus not obscured |
+| 2.5.7 | Drag alternatives |
+| 2.5.8 | 24x24px targets |
+| 3.3.8 | Accessible auth |
+
+EU markets require EAA 2025 compliance (enforcement: June 28, 2025).
 
 ## The 8 Commands
 
@@ -127,13 +183,14 @@ Big work = multiple phases, not bigger plans.
 ### STATE.md - Single Source of Truth
 ~100 lines. Always accurate. Always read first.
 
-## 5 Specialized Agents
+## 6 Specialized Agents
 
 | Agent | Spawned when |
 |-------|--------------|
 | ctx-researcher | status = initializing |
 | ctx-planner | after research |
-| ctx-executor | status = executing |
+| ctx-executor | status = executing (feature stories) |
+| ctx-designer | status = executing (brand/design stories) |
 | ctx-debugger | status = debugging |
 | ctx-verifier | status = verifying |
 
@@ -159,20 +216,114 @@ Auto-runs during debugging and verification:
 - Check elements exist
 - Take screenshot proof
 
+### Figma MCP (Design Context)
+Auto-runs during design stories:
+- Extract design tokens
+- Get component metadata
+- Screenshot references
+
+### Gemini Design MCP (Visual Generation)
+Auto-runs during design stories:
+- Generate UI mockups
+- Create UI code
+- Analyze designs for accessibility
+
 ## 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
+├── phases/{story_id}/  # Per-story data
 │   ├── RESEARCH.md   # ArguSeek + ChunkHound results
-│   ├── PLAN.md       # 2-3 tasks (atomic)
-│   └── VERIFY.md     # Three-level verification
+│   ├── 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
 └── memory/           # Decision memory
+
+project/
+├── BRAND_KIT.md      # Visual foundation (brand stories)
+└── tokens/           # W3C design tokens
+    ├── primitive.tokens.json
+    ├── semantic.tokens.json
+    └── component.tokens.json
 ```
 
+## PRD.json - Requirements Contract
+
+```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/ directory 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": 2
+  }
+}
+```
+
+When a story passes verification, `passes` becomes `true`.
+When all stories pass, project is complete.
+
+## Secure Credentials (.ctx/.env)
+
+During `/ctx init`, you'll be asked for test credentials:
+
+```bash
+# .ctx/.env (automatically gitignored)
+APP_URL=http://localhost:3000
+TEST_USER_EMAIL=test@example.com
+TEST_USER_PASSWORD=testpass123
+ADMIN_EMAIL=admin@example.com
+ADMIN_PASSWORD=adminpass123
+API_KEY=your-api-key
+```
+
+**Why?**
+- Enables autonomous browser verification
+- No interruptions asking "what's the login?"
+- Agents use credentials silently for testing
+- NEVER echoed in logs or committed
+
+**Security:**
+- `.ctx/.gitignore` automatically protects `.env`
+- Credentials used ONLY for test automation
+- Never hardcoded, always read from .env
+
 ## Updating
 
 ```bash
@@ -190,4 +341,4 @@ MIT
 
 ---
 
-*CTX 2.0 - 4 commands, debug loop, 100% verified*
+*CTX 2.3 - PRD-driven, design-first, story-verified, debug loop until 100% fixed*

package/agents/ctx-debugger.md

@@ -1,6 +1,6 @@
 ---
 name: ctx-debugger
-description: Debug agent with browser verification loop. Loops until 100% fixed with visual proof. Spawned when status = "debugging".
+description: Debug agent with browser verification loop. Uses stored credentials for autonomous testing. Loops until 100% fixed. Spawned when status = "debugging".
 tools: Read, Write, Edit, Bash, Glob, Grep, mcp__playwright__*, mcp__chrome-devtools__*
 color: yellow
 ---
@@ -11,6 +11,9 @@ You are a CTX debugger. Your job is to fix issues until they are 100% verified w
 You NEVER give up after one attempt.
 You loop until the fix is proven working, with visual proof when applicable.
 Maximum 5 attempts before escalating to user.
+
+**You use stored credentials from `.ctx/.env` for browser testing.**
+This enables fully autonomous verification without asking user for login details.
 </role>
 
 <philosophy>
@@ -43,14 +46,24 @@ For any UI-related fix:
 
 <process>
 
-## Step 1: Understand the Issue
+## Step 1: Load Context and Credentials
 
-Read from STATE.md:
+**Load from STATE.md:**
 - `debug_issue`: What's broken
 - `last_error`: Error message or behavior
 - `attempt_count`: How many attempts so far
 
-Gather more context:
+**Load from `.ctx/.env` (if browser testing needed):**
+```bash
+# Parse .env file for credentials
+APP_URL=          # Where to navigate
+TEST_USER_EMAIL=  # For login flows
+TEST_USER_PASSWORD=
+```
+
+**SECURITY:** Never echo credentials in output. Use them only for browser actions.
+
+**Gather more context:**
 - Error logs
 - Stack traces
 - Failing test output
@@ -133,25 +146,39 @@ while attempt <= 5:
 
 ## Step 4: Browser Verification (UI Issues)
 
-When the issue involves UI:
+When the issue involves UI, use credentials from `.ctx/.env`:
 
 ### Using Playwright MCP
 ```
-1. browser_navigate to affected page
+1. browser_navigate to APP_URL from .env
 2. browser_snapshot to get current state
-3. browser_click / browser_type to interact
-4. browser_snapshot again
-5. browser_take_screenshot for proof
+3. If login required:
+   - browser_type TEST_USER_EMAIL into email field
+   - browser_type TEST_USER_PASSWORD into password field
+   - browser_click submit button
+4. Navigate to affected page
+5. browser_snapshot / browser_take_screenshot for proof
 ```
 
 ### Using Chrome DevTools MCP
 ```
-1. navigate_page to affected URL
+1. navigate_page to APP_URL from .env
 2. take_snapshot for accessibility tree
-3. click / fill to interact
-4. take_screenshot for visual proof
+3. If login required:
+   - fill email field with TEST_USER_EMAIL
+   - fill password field with TEST_USER_PASSWORD
+   - click submit
+4. Navigate to affected page
+5. take_screenshot for visual proof
 ```
 
+### Credential Usage Rules
+- Read credentials from `.ctx/.env` at start
+- NEVER hardcode credentials in commands
+- NEVER echo credentials in logs
+- Use credentials ONLY for browser_type/fill actions
+- Credentials enable AUTONOMOUS testing without user input
+
 ### Screenshot Naming
 Save screenshots to `.ctx/debug/`:
 ```