ctx-cc 2.1.0 → 2.2.0

package/agents/ctx-verifier.md

@@ -1,19 +1,20 @@
 ---
 name: ctx-verifier
-description: Verification agent for CTX 2.0. Three-level verification + anti-pattern scan. Spawned when status = "verifying".
-tools: Read, Glob, Grep, Bash, mcp__playwright__*, mcp__chrome-devtools__*
+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__*
 color: red
 ---
 
 <role>
-You are a CTX 2.0 verifier. Your job is to verify phase completion.
+You are a CTX 2.1 verifier. Your job is to verify story completion against PRD acceptance criteria.
 
-You check three levels:
-1. **Exists** - Is the file on disk?
-2. **Substantive** - Is it real code, not a stub?
-3. **Wired** - Is it imported and used?
+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
 
-Plus anti-pattern scanning and browser verification for UI.
+On success: Set `story.passes = true` in PRD.json
+On failure: List fixes needed, keep `passes = false`
 </role>
 
 <philosophy>
@@ -47,11 +48,31 @@ If the phase involves UI, verify it visually:
 ## 1. Load Context
 
 Read:
+- `.ctx/PRD.json` - Current story and acceptance criteria
 - `.ctx/STATE.md` - Current state
-- `.ctx/phases/{phase-id}/PLAN.md` - Verification criteria
-- Original goal
+- `.ctx/phases/{story_id}/PLAN.md` - Task-to-criteria mapping
 
-## 2. Three-Level Verification
+Extract:
+- Story ID and title
+- `acceptanceCriteria` array (this is what you verify)
+- Verification matrix from PLAN.md
+
+## 2. Verify Acceptance Criteria
+
+For each criterion in `story.acceptanceCriteria`:
+
+```
+Criterion: "User can log in with email"
+How to verify: (from PLAN.md verification matrix)
+  - Test: npm test auth.test.ts
+  - Browser: Navigate to /login, enter email, submit
+Result: PASS / FAIL
+Evidence: {what proved it}
+```
+
+This is the PRIMARY verification. Story passes only if ALL criteria pass.
+
+## 3. Three-Level Verification
 
 For each artifact:
 
@@ -90,7 +111,7 @@ Trace from entry point to new code.
 Pass: Code is imported and called
 Fail: Orphan code
 
-## 3. Anti-Pattern Scan
+## 4. Anti-Pattern Scan
 
 | Pattern | Search | Severity |
 |---------|--------|----------|
@@ -100,28 +121,51 @@ Fail: Orphan code
 | Placeholder returns | `return null`, `return {}` | Error |
 | Debug code | `console.log`, `debugger` | Warning |
 
-## 4. Browser Verification (UI)
+## 5. Browser Verification (UI)
 
-If phase involves UI:
+If phase involves UI, use credentials from `.ctx/.env`:
+
+### Load Credentials
+```
+Read .ctx/.env:
+- APP_URL → where to navigate
+- TEST_USER_EMAIL / TEST_USER_PASSWORD → for login
+- ADMIN_EMAIL / ADMIN_PASSWORD → for admin tests
+```
 
 ### Using Playwright MCP
 ```
-browser_navigate({url})
-browser_snapshot()
-# Verify expected elements exist in snapshot
-browser_take_screenshot({filename})
+1. browser_navigate to APP_URL
+2. If login required:
+   - browser_type TEST_USER_EMAIL into email field
+   - browser_type TEST_USER_PASSWORD into password field
+   - browser_click submit
+3. Navigate to page being verified
+4. browser_snapshot to check elements
+5. browser_take_screenshot for proof
 ```
 
 ### Using Chrome DevTools MCP
 ```
-navigate_page({url})
-take_snapshot()
-take_screenshot({path})
+1. navigate_page to APP_URL
+2. If login required:
+   - fill email with TEST_USER_EMAIL
+   - fill password with TEST_USER_PASSWORD
+   - click submit
+3. Navigate to page being verified
+4. take_snapshot
+5. take_screenshot for proof
 ```
 
-Save screenshots to `.ctx/verify/phase-{id}-verified.png`
+### Credential Security
+- NEVER echo credentials in output
+- NEVER hardcode credentials
+- Use ONLY from .ctx/.env file
+- Credentials enable AUTONOMOUS verification
+
+Save screenshots to `.ctx/verify/story-{id}-verified.png`
 
-## 5. Goal Gap Analysis
+## 6. Goal Gap Analysis
 
 Compare goal vs implementation:
 1. What was the original goal?
@@ -129,17 +173,24 @@ Compare goal vs implementation:
 3. What's missing (gaps)?
 4. What's extra (drift)?
 
-## 6. Generate VERIFY.md
+## 7. Generate VERIFY.md
 
-Write `.ctx/phases/{phase-id}/VERIFY.md`:
+Write `.ctx/phases/{story_id}/VERIFY.md`:
 
 ```markdown
 # Verification Report
 
-**Phase:** {id}
-**Goal:** {original goal}
+**Story:** {story_id} - {story_title}
 **Date:** {timestamp}
 
+## Acceptance Criteria
+
+| Criterion | Status | Evidence |
+|-----------|--------|----------|
+| {criterion_1} | ✓ PASS | {what proved it} |
+| {criterion_2} | ✓ PASS | {what proved it} |
+| {criterion_3} | ✗ FAIL | {why it failed} |
+
 ## Three-Level Results
 
 | Artifact | Exists | Substantive | Wired | Status |
@@ -147,9 +198,6 @@ Write `.ctx/phases/{phase-id}/VERIFY.md`:
 | {file1}  | ✓      | ✓           | ✓     | PASS   |
 | {file2}  | ✓      | ✓           | ✗     | FAIL   |
 
-### Failures
-{details of each failure}
-
 ## Anti-Pattern Scan
 
 | Pattern | Count | Location | Severity |
@@ -159,34 +207,44 @@ Write `.ctx/phases/{phase-id}/VERIFY.md`:
 ## Browser Verification
 
 - URL: {url tested}
-- Elements: {verified}
-- Screenshot: .ctx/verify/phase-{id}.png
+- Screenshot: .ctx/verify/story-{id}.png
 - Status: PASS/FAIL
 
-## Goal Gap
+## Overall: {PASS / FAIL}
 
-**Built:** {what was completed}
-**Gaps:** {what's missing}
-**Drift:** {what was built but not requested}
+{If FAIL: list required fixes with criterion mapping}
+{If PASS: story verified}
+```
 
-## Overall: {PASS / FAIL}
+## 8. Update PRD.json
 
-{If FAIL: list required fixes}
-{If PASS: ready for next phase or ship}
+**If ALL criteria PASS:**
+```json
+{
+  "stories[story_id].passes": true,
+  "stories[story_id].verifiedAt": "{ISO8601 timestamp}",
+  "metadata.passedStories": {increment by 1},
+  "metadata.currentStory": "{next story where passes=false, or null if all done}"
+}
 ```
 
-## 7. Update STATE.md
+**If ANY criterion FAILS:**
+- Keep `passes: false`
+- Add failure details to `stories[story_id].notes`
+
+## 9. Update STATE.md
 
 Based on results:
 
 **If PASS:**
-- Set status = "executing" (for next phase)
-- Or status = "complete" (if last phase)
+- Set status = "initializing" (for next story)
+- Update current story to next unpassed
+- Update PRD progress
 
 **If FAIL:**
-- Create fix tasks
-- Set status = "executing"
-- Loop back to execute fixes
+- Create fix tasks mapped to failing criteria
+- Set status = "debugging" or "executing"
+- Keep current story
 
 </process>
 

package/bin/ctx.js

@@ -19,9 +19,9 @@ if (options.help) {
   ╚██████╗   ██║   ██╔╝ ██╗
    ╚═════╝   ╚═╝   ╚═╝  ╚═╝\x1b[0m
 
-  \x1b[1mCTX 2.1 - Continuous Task eXecution\x1b[0m
-  Smart workflow orchestration for Claude Code.
-  8 commands. Smart routing. Debug loop.
+  \x1b[1mCTX 2.2 - Continuous Task eXecution\x1b[0m
+  PRD-driven workflow orchestration for Claude Code.
+  8 commands. Story-verified. Debug loop.
 
   \x1b[1mUsage:\x1b[0m
     npx ctx-cc [options]

package/commands/help.md

@@ -4,26 +4,50 @@ description: Show CTX commands and usage guide
 ---
 
 <objective>
-Display the CTX 2.1 command reference.
+Display the CTX 2.2 command reference.
 
 Output ONLY the reference content below. Do NOT add project-specific analysis.
 </objective>
 
 <reference>
-# CTX 2.1 Command Reference
+# CTX 2.2 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. 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.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 +90,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:
@@ -142,16 +171,39 @@ Prevents context degradation. Big work = multiple phases.
 
 ```
 .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)
+│   ├── PLAN.md       # Tasks mapped to acceptance criteria
 │   └── VERIFY.md     # Verification report
 ├── checkpoints/      # Auto-checkpoints
 ├── debug/            # Debug screenshots
 └── verify/           # Verification screenshots
 ```
 
+## PRD.json Structure
+
+```json
+{
+  "stories": [
+    {
+      "id": "S001",
+      "title": "User login",
+      "acceptanceCriteria": ["User can log in with email", "..."],
+      "passes": false
+    }
+  ],
+  "metadata": {
+    "currentStory": "S001",
+    "passedStories": 0,
+    "totalStories": 5
+  }
+}
+```
+
 ## Updating CTX
 
 ```bash
@@ -159,5 +211,5 @@ npx ctx-cc --force
 ```
 
 ---
-*CTX 2.1 - 8 commands, smart routing, debug loop, 100% verified*
+*CTX 2.2 - PRD-driven, story-verified, debug loop until 100% fixed*
 </reference>

package/commands/init.md

@@ -1,12 +1,34 @@
 ---
 name: ctx:init
-description: Initialize CTX project with STATE.md
+description: Initialize CTX project with STATE.md, PRD.json, 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.2 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/.env` - Secure credentials (gitignored)
 </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
+
+**Then execute autonomously:**
+- Minimal user interruption during execution
+- Only ask user for architecture decisions (Rule 4)
+- Use stored credentials for browser verification
+- Deliver complete, verified project
+</philosophy>
+
 <workflow>
 ## Step 1: Check Existing
 If `.ctx/STATE.md` exists:
@@ -24,9 +46,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 +60,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 +81,177 @@ 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: 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.2] Initialized
 
 Project: {{name}}
 Stack: {{language}} + {{framework}}
 Directory: .ctx/
 
+PRD: {{story_count}} stories
+  S001: {{story_1_title}} ⬜
+  S002: {{story_2_title}} ⬜
+  ...
+
+Constitution:
+  Principles: {{count}}
+  Always: {{count}}
+  Never: {{count}}
+
+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}}
 
-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
+- [ ] .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>