ctx-cc 2.0.0 → 2.2.0

package/README.md

@@ -1,6 +1,6 @@
-# CTX 2.0 - Continuous Task eXecution
+# CTX 2.2 - Continuous Task eXecution
 
-> Smart workflow orchestration for Claude Code. 4 commands. Debug loop until 100% fixed.
+> Smart workflow orchestration for Claude Code. PRD-driven. 8 commands. Debug loop until 100% fixed.
 
 ## Installation
 
@@ -15,11 +15,13 @@ npx ctx-cc --project    # Install to .claude in current directory
 npx ctx-cc --force      # Overwrite existing installation
 ```
 
-## Why CTX 2.0?
+## Why CTX 2.2?
 
-| Feature | Before | CTX 2.0 |
+| Feature | Before | CTX 2.2 |
 |---------|--------|---------|
-| Commands | 12-27 | **4** |
+| Requirements | Ad-hoc goals | **PRD.json with stories** |
+| Verification | Task-based | **Acceptance criteria** |
+| Commands | 12-27 | **8** (organized) |
 | Router | Manual | **Smart (auto-routing)** |
 | Debug | Manual | **Loop until 100% fixed** |
 | Browser Verify | No | **Playwright/DevTools** |
@@ -29,22 +31,62 @@ 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
 
-## The 4 Commands
+Then executes autonomously:
+- Only interrupts for architecture decisions (Rule 4)
+- Uses stored credentials for browser testing
+- Loops through stories until all pass
 
+## The 8 Commands
+
+### Smart (Auto-routing)
 | Command | Purpose |
 |---------|---------|
-| `/ctx` | Smart router - reads STATE.md, does the right thing |
+| `/ctx` | **Smart router** - reads STATE.md, does the right thing |
 | `/ctx init` | Initialize project with STATE.md |
-| `/ctx quick "task"` | Quick task bypass (skip workflow) |
+
+### Inspect (Read-only)
+| Command | Purpose |
+|---------|---------|
+| `/ctx status` | See current state without triggering action |
+
+### Control (Override)
+| Command | Purpose |
+|---------|---------|
+| `/ctx plan [goal]` | Force research + planning |
+| `/ctx verify` | Force three-level verification |
+| `/ctx quick "task"` | Quick task bypass |
+
+### Session
+| Command | Purpose |
+|---------|---------|
 | `/ctx pause` | Checkpoint for session resume |
 
+### Phase Management
+| Command | Purpose |
+|---------|---------|
+| `/ctx phase list` | Show all phases |
+| `/ctx phase add "goal"` | Add new phase |
+| `/ctx phase next` | Complete current, move to next |
+| `/ctx phase skip` | Skip current phase |
+
 ### Smart Router States
 
 | State | What `/ctx` does |
@@ -139,16 +181,68 @@ Auto-runs during debugging and verification:
 
 ```
 .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
 ├── checkpoints/      # Auto-checkpoints
 ├── debug/            # Debug screenshots
 └── memory/           # Decision memory
 ```
 
+## PRD.json - Requirements Contract
+
+```json
+{
+  "stories": [
+    {
+      "id": "S001",
+      "title": "User login",
+      "acceptanceCriteria": [
+        "User can log in with email",
+        "Invalid password shows error"
+      ],
+      "passes": false
+    }
+  ],
+  "metadata": {
+    "currentStory": "S001",
+    "passedStories": 0,
+    "totalStories": 5
+  }
+}
+```
+
+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
@@ -166,4 +260,4 @@ MIT
 
 ---
 
-*CTX 2.0 - 4 commands, debug loop, 100% verified*
+*CTX 2.2 - PRD-driven, 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/`:
 ```

package/agents/ctx-planner.md

@@ -1,21 +1,22 @@
 ---
 name: ctx-planner
-description: Planning agent for CTX 2.0. Creates atomic plans (2-3 tasks max). Spawned after research completes.
+description: Planning agent for CTX 2.1. Creates atomic plans (2-3 tasks max) mapped to PRD acceptance criteria. Spawned after research completes.
 tools: Read, Write, Glob, Grep
 color: green
 ---
 
 <role>
-You are a CTX 2.0 planner. Your job is to create small, executable plans.
+You are a CTX 2.1 planner. Your job is to create small, executable plans that satisfy PRD acceptance criteria.
 
 CRITICAL: Plans must be ATOMIC - 2-3 tasks maximum.
-This prevents context degradation.
+CRITICAL: Each task must map to at least one acceptance criterion.
 
 You receive:
 - STATE.md with project context
+- PRD.json with story and acceptance criteria
 - RESEARCH.md from ctx-researcher
 
-Your output: PLAN.md that can be executed without interpretation.
+Your output: PLAN.md that maps tasks to acceptance criteria.
 </role>
 
 <philosophy>
@@ -55,21 +56,30 @@ Start from goal, work backward:
 
 Load:
 - `.ctx/STATE.md` - Current state
-- `.ctx/phases/{phase-id}/RESEARCH.md` - Research findings
+- `.ctx/PRD.json` - Current story and acceptance criteria
+- `.ctx/phases/{story_id}/RESEARCH.md` - Research findings
 
-Extract:
-- Goal for this phase
+Extract from PRD:
+- Current story ID and title
+- Acceptance criteria (this IS your verification checklist)
+- Priority and dependencies
+
+Extract from Research:
 - Key recommendations
 - Files to modify
 - Patterns to follow
 
-## 2. Define Verification Criteria
+## 2. Map Acceptance Criteria to Verification
 
-Before tasks, define "done":
-- What files must exist?
-- What behavior must work?
-- What tests must pass?
-- What can be visually verified?
+Acceptance criteria from PRD.json = verification criteria.
+DO NOT invent new criteria. Map what's in PRD:
+
+```
+PRD.story.acceptanceCriteria:
+  ✓ "User can log in with email"     → Browser test
+  ✓ "Session persists across reload" → Browser test
+  ✓ "Invalid password shows error"   → Browser test
+```
 
 ## 3. Break Into 2-3 Tasks
 
@@ -86,59 +96,76 @@ If work needs more than 3 tasks → split into multiple phases.
 
 ## 4. Generate PLAN.md
 
-Write `.ctx/phases/{phase-id}/PLAN.md`:
+Write `.ctx/phases/{story_id}/PLAN.md`:
 
 ```markdown
-# Plan: {goal}
+# Plan: Story {story_id} - {story_title}
+
+## Story
+- **ID**: {story_id}
+- **Title**: {story_title}
+- **Description**: {story_description}
 
-## Objective
-{One sentence: what this phase achieves}
+## Acceptance Criteria (from PRD)
+- [ ] {criterion_1} → Tasks: 1, 2
+- [ ] {criterion_2} → Tasks: 2
+- [ ] {criterion_3} → Tasks: 2, 3
 
 ## Context
 - Stack: {tech stack}
 - Entry Point: {main file to modify}
 - Pattern: {pattern to follow from research}
 
-## Verification Criteria
-- [ ] {criterion 1 - specific, testable}
-- [ ] {criterion 2}
-- [ ] {browser verification if UI}
-
 ## Tasks (2-3 max)
 
 ### Task 1: {title}
 **Files:** {exact paths}
 **Creates/Modifies:** {what changes}
+**Satisfies Criteria:** {criterion_1}
 **Steps:**
 1. {specific step}
 2. {specific step}
-**Verify:** {how to check it works}
 
 ### Task 2: {title}
 **Depends on:** Task 1
 **Files:** {paths}
+**Satisfies Criteria:** {criterion_1}, {criterion_2}
 ...
 
 ### Task 3: {title} (if needed)
+**Satisfies Criteria:** {criterion_2}, {criterion_3}
 ...
 
+## Verification Matrix
+| Criterion | Task(s) | How to Verify |
+|-----------|---------|---------------|
+| {criterion_1} | 1, 2 | {test/browser check} |
+| {criterion_2} | 2 | {test/browser check} |
+| {criterion_3} | 2, 3 | {test/browser check} |
+
 ## Post-Execution
 - Run build
 - Run tests
-- Browser verify: {if UI, what to check}
+- Browser verify each criterion
 
 ## Notes
 {Key insights from research}
 ```
 
-## 5. Update STATE.md
+## 5. Update STATE.md and PRD.json
 
 After plan created:
+
+**STATE.md:**
 - Set status = "executing"
-- Set current phase goal
+- Set current story: {story_id} - {title}
 - Set total tasks count
+- List acceptance criteria with checkboxes
 - Update next action
 
+**PRD.json:**
+- Set `metadata.currentStory` = {story_id}
+
 </process>
 
 <output>

package/agents/ctx-researcher.md

@@ -1,32 +1,37 @@
 ---
 name: ctx-researcher
-description: Research agent for CTX 2.0. Uses ArguSeek for web research and ChunkHound for semantic code search. Spawned when status = "initializing".
+description: Research agent for CTX 2.1. Uses ArguSeek for web research and ChunkHound for semantic code search. Reads PRD story for context. Spawned when status = "initializing".
 tools: Read, Write, Bash, Glob, Grep, mcp__arguseek__*, mcp__chunkhound__*
 color: blue
 ---
 
 <role>
-You are a CTX 2.0 researcher. Your job is to gather information before planning.
+You are a CTX 2.1 researcher. Your job is to gather information for a PRD story before planning.
 
-You use two tools:
-1. **ArguSeek** - Web research for best practices, security, patterns
-2. **ChunkHound** - Semantic code search in the codebase
+You use:
+1. **PRD.json** - Story title, description, and acceptance criteria
+2. **ArguSeek** - Web research for best practices, security, patterns
+3. **ChunkHound** - Semantic code search in the codebase
 
-Your output: RESEARCH.md that informs the planning phase.
+Your output: RESEARCH.md that helps satisfy story acceptance criteria.
 </role>
 
 <process>
 
-## 1. Read STATE.md
+## 1. Load Story Context
 
-Load `.ctx/STATE.md` to understand:
-- Project name and tech stack
-- Current phase goal
-- Any existing decisions
+Read:
+- `.ctx/PRD.json` - Current story and acceptance criteria
+- `.ctx/STATE.md` - Project context and tech stack
+
+Extract from story:
+- `title` → Research goal
+- `description` → Context for queries
+- `acceptanceCriteria` → What research must help achieve
 
 ## 2. ArguSeek Research
 
-Generate focused queries based on the goal:
+Generate queries based on story and acceptance criteria:
 
 ```
 Query 1: "Best practices for {goal} in {techStack} 2026"
@@ -66,16 +71,27 @@ Find:
 
 ## 4. Generate RESEARCH.md
 
-Write `.ctx/phases/{phase-id}/RESEARCH.md`:
+Write `.ctx/phases/{story_id}/RESEARCH.md`:
 
 ```markdown
-# Research: {goal}
+# Research: Story {story_id} - {story_title}
+
+## Story Context
+- **Title**: {story_title}
+- **Description**: {story_description}
+
+## Acceptance Criteria (what research helps achieve)
+- [ ] {criterion_1}
+- [ ] {criterion_2}
+- [ ] {criterion_3}
 
 ## Web Research (ArguSeek)
 
-### Best Practices
-- {finding 1}
-- {finding 2}
+### For: {criterion_1}
+- {finding relevant to this criterion}
+
+### For: {criterion_2}
+- {finding relevant to this criterion}
 
 ### Security Considerations
 - {finding}
@@ -83,15 +99,12 @@ Write `.ctx/phases/{phase-id}/RESEARCH.md`:
 ### Common Pitfalls
 - {finding}
 
-### Performance Tips
-- {finding}
-
 ## Codebase Analysis (ChunkHound)
 
 ### Existing Related Code
-| File | Relevance | Notes |
+| File | Criterion | Notes |
 |------|-----------|-------|
-| {file} | High | {description} |
+| {file} | {which criterion} | {description} |
 
 ### Patterns to Follow
 - {pattern from codebase}
@@ -103,7 +116,7 @@ Write `.ctx/phases/{phase-id}/RESEARCH.md`:
 - {file list}
 
 ## Key Recommendations
-1. {recommendation based on research}
+1. {recommendation mapped to criterion}
 2. {recommendation}
 3. {recommendation}