ctx-cc 2.1.0 → 2.2.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.2.0",
+  "description": "CTX 2.2 (Continuous Task eXecution) - PRD-driven workflow orchestration for Claude Code. 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/PRD.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://ctx.dev/schemas/prd.json",
+  "version": "2.0",
+  "project": {
+    "name": "{{project_name}}",
+    "description": "{{project_description}}",
+    "stack": "{{tech_stack}}",
+    "created": "{{timestamp}}"
+  },
+  "context": {
+    "problem": "{{what_problem_are_we_solving}}",
+    "targetUser": "{{who_is_this_for}}",
+    "successLooksLike": "{{how_will_we_know_its_done}}",
+    "outOfScope": [
+      "{{what_we_are_NOT_building}}"
+    ],
+    "assumptions": [
+      "{{assumption_1}}",
+      "{{assumption_2}}"
+    ],
+    "risks": [
+      "{{risk_1}}"
+    ]
+  },
+  "constitution": {
+    "principles": [
+      "Code quality over speed",
+      "Test before ship",
+      "No secrets in code"
+    ],
+    "always": [
+      "Run tests before committing",
+      "Use TypeScript strict mode",
+      "Handle errors explicitly"
+    ],
+    "never": [
+      "Commit secrets or credentials",
+      "Skip error handling",
+      "Leave TODO comments in production"
+    ],
+    "askFirst": [
+      "Database schema changes",
+      "New dependencies",
+      "API contract changes"
+    ]
+  },
+  "testing": {
+    "requiresBrowser": false,
+    "requiresLogin": false,
+    "requiresAdmin": false,
+    "requiresAPI": false,
+    "notes": "{{testing_notes}}"
+  },
+  "stories": [
+    {
+      "id": "S001",
+      "title": "{{story_title}}",
+      "description": "{{story_description}}",
+      "acceptanceCriteria": [
+        "{{criterion_1}}",
+        "{{criterion_2}}",
+        "{{criterion_3}}"
+      ],
+      "priority": 1,
+      "phase": 1,
+      "passes": false,
+      "verifiedAt": null,
+      "notes": ""
+    }
+  ],
+  "metadata": {
+    "totalStories": 0,
+    "passedStories": 0,
+    "currentStory": null,
+    "lastUpdated": "{{timestamp}}"
+  }
+}

package/templates/STATE.md

@@ -8,11 +8,21 @@
 - **Stack**: {{tech_stack}}
 - **Status**: {{status}} <!-- initializing | planning | executing | debugging | verifying | paused -->
 
+## PRD Progress
+- **Stories**: {{passed_stories}}/{{total_stories}} ({{percent}}%)
+- **Current Story**: {{story_id}} - {{story_title}}
+
 ## Current Phase
-- **ID**: {{phase_id}}
-- **Goal**: {{phase_goal}}
+- **ID**: {{phase_id}} (maps to story {{story_id}})
+- **Goal**: {{story_title}}
 - **Progress**: {{completed_tasks}}/{{total_tasks}} tasks
 
+## Acceptance Criteria (from PRD)
+<!-- Current story's acceptance criteria -->
+- [ ] {{criterion_1}}
+- [ ] {{criterion_2}}
+- [ ] {{criterion_3}}
+
 ## Active Task
 - **Task**: {{current_task}}
 - **Status**: {{task_status}} <!-- pending | in_progress | blocked | debugging | done -->

package/templates/ctx.gitignore

@@ -0,0 +1,19 @@
+# CTX Secrets - NEVER COMMIT
+.env
+*.env
+.env.*
+!.env.example
+
+# Credential files
+credentials.json
+secrets.json
+*.secrets
+*.pem
+*.key
+
+# Debug screenshots may contain sensitive data
+debug/*.png
+debug/*.jpg
+
+# Checkpoint data may contain state
+checkpoints/*.json

package/templates/env.template

@@ -0,0 +1,61 @@
+# CTX Test Credentials
+# Generated by /ctx init
+# WARNING: DO NOT COMMIT THIS FILE
+
+# ===========================================
+# APP CONFIGURATION
+# ===========================================
+
+# Local development URL
+APP_URL=http://localhost:3000
+
+# Staging/preview URL (optional)
+STAGING_URL=
+
+# Production URL (optional - for smoke tests)
+PRODUCTION_URL=
+
+# ===========================================
+# TEST USER CREDENTIALS
+# ===========================================
+
+# Primary test user (for normal user flows)
+TEST_USER_EMAIL=
+TEST_USER_PASSWORD=
+
+# Admin user (for admin features)
+ADMIN_EMAIL=
+ADMIN_PASSWORD=
+
+# Secondary test user (for multi-user tests)
+TEST_USER_2_EMAIL=
+TEST_USER_2_PASSWORD=
+
+# ===========================================
+# API KEYS & TOKENS
+# ===========================================
+
+# Primary API key (if applicable)
+API_KEY=
+
+# OAuth tokens (if applicable)
+OAUTH_CLIENT_ID=
+OAUTH_CLIENT_SECRET=
+
+# Third-party service keys
+# STRIPE_TEST_KEY=
+# SENDGRID_API_KEY=
+# AWS_ACCESS_KEY_ID=
+# AWS_SECRET_ACCESS_KEY=
+
+# ===========================================
+# DATABASE (if direct DB testing needed)
+# ===========================================
+
+DATABASE_URL=
+
+# ===========================================
+# CUSTOM SECRETS
+# Add project-specific secrets below
+# ===========================================
+