ctx-cc 2.0.0 → 2.2.0

package/commands/verify.md

@@ -0,0 +1,171 @@
+---
+name: ctx:verify
+description: Force verification of current story against PRD acceptance criteria
+---
+
+<objective>
+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>
+```
+/ctx verify              # Verify current phase
+/ctx verify --browser    # Force browser verification even for non-UI
+```
+</usage>
+
+<workflow>
+## Step 1: Validate Project
+If `.ctx/STATE.md` or `.ctx/PRD.json` doesn't exist:
+- Error: "No project found. Run /ctx init 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/{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:
+
+### Level 1: EXISTS
+For each artifact in plan:
+```bash
+ls {file_path}
+```
+- Pass: File found
+- Fail: File missing
+
+### Level 2: SUBSTANTIVE
+Check for stubs/placeholders:
+```bash
+grep -n "TODO" {file}
+grep -n "not implemented" {file}
+```
+- Pass: Real, complete code
+- Fail: Stub detected
+
+### Level 3: WIRED
+Trace imports from entry point:
+```bash
+grep -r "import.*{module}" --include="*.ts"
+```
+- Pass: Code is imported and used
+- Fail: Orphan code (exists but unused)
+
+## Step 4: Anti-Pattern Scan
+Search for common issues:
+| Pattern | Severity |
+|---------|----------|
+| `// TODO` | Warning |
+| Empty catch blocks | Error |
+| `console.log` (debug) | Warning |
+| Placeholder returns | Error |
+
+## Step 5: Browser Verification (if UI)
+If phase involves UI or `--browser` flag:
+
+1. Navigate to affected page
+2. Take snapshot
+3. Check expected elements
+4. Take screenshot proof
+5. Save to `.ctx/verify/phase-{id}.png`
+
+## 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}}"
+}
+```
+
+If ANY criterion fails:
+- Keep `passes: false`
+- Add failure notes to `stories[current].notes`
+
+## Step 9: Update STATE.md
+Based on results:
+- **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] Story: {story_id} - {title}
+
+Acceptance Criteria:
+  ✓ {criterion_1} - PASS
+  ✓ {criterion_2} - PASS
+  ✗ {criterion_3} - FAIL: {reason}
+
+Three-Level Check:
+  ✓ Exists: {pass}/{total}
+  ✓ Substantive: {pass}/{total}
+  ✓ Wired: {pass}/{total}
+
+Anti-Pattern Scan:
+  Warnings: {count}
+  Errors: {count}
+
+{If browser:}
+Browser Verification:
+  URL: {url}
+  Status: PASS/FAIL
+  Screenshot: .ctx/verify/story-{id}.png
+
+Overall: {PASS / FAIL}
+
+{If FAIL:}
+Fixes Required:
+  1. {fix_1} → [criterion 3]
+  2. {fix_2}
+
+{If PASS:}
+✓ Story {story_id} verified!
+PRD Progress: {passed}/{total} stories ({percent}%)
+
+Next Story: {next_story_id} - {next_title}
+Run /ctx to start planning.
+```
+</output_format>
+
+<key_principle>
+Verification is STRICT. Better to catch issues now than in production.
+A failing verification saves debugging time later.
+</key_principle>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ctx-cc",
-  "version": "2.0.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.0')} ${dim(`v${VERSION}`)}`);
-  console.log('  Continuous Task eXecution for Claude Code.');
-  console.log('  4 commands. Debug loop. 100% verified.\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
+# ===========================================
+