ctx-cc 2.0.0 → 2.2.0

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>

package/commands/phase.md

@@ -0,0 +1,149 @@
+---
+name: ctx:phase
+description: Phase management - list, add, next, skip
+args: subcommand (list|add|next|skip)
+---
+
+<objective>
+Manage project phases explicitly. CRUD operations for the phase roadmap.
+</objective>
+
+<usage>
+```
+/ctx phase list              # Show all phases with status
+/ctx phase add "goal"        # Add new phase to roadmap
+/ctx phase next              # Mark current complete, move to next
+/ctx phase skip              # Skip current phase (mark skipped)
+```
+</usage>
+
+<subcommands>
+
+## /ctx phase list
+
+Show all phases with their status.
+
+**Output:**
+```
+[CTX Phases]
+
+  #   Status      Goal
+  ─────────────────────────────────────────
+  1   ✓ complete  Set up project structure
+  2   ● current   Add user authentication
+  3   ○ pending   Implement dashboard
+  4   ○ pending   Add API endpoints
+
+Current: Phase 2 - Add user authentication
+Progress: 1/3 tasks complete
+```
+
+**Status indicators:**
+- `✓` complete - Phase verified and done
+- `●` current - Currently active phase
+- `○` pending - Not yet started
+- `⊘` skipped - Explicitly skipped
+
+---
+
+## /ctx phase add "goal"
+
+Add a new phase to the end of the roadmap.
+
+**Process:**
+1. Generate phase ID (increment)
+2. Create `.ctx/phases/{id}/` directory
+3. Update STATE.md with new phase in roadmap
+4. Do NOT start planning yet (user runs `/ctx plan` when ready)
+
+**Output:**
+```
+[CTX Phase] Added phase {id}
+
+Goal: {goal}
+Status: pending
+
+Roadmap now has {n} phases.
+Run /ctx plan "{goal}" when ready to plan this phase.
+```
+
+---
+
+## /ctx phase next
+
+Mark current phase complete and move to the next.
+
+**Process:**
+1. Verify current phase is complete (all tasks done)
+2. If not complete, warn user
+3. Mark current phase as "complete"
+4. Set next pending phase as "current"
+5. Update STATE.md
+
+**Output (success):**
+```
+[CTX Phase] Completed phase {id}: {goal}
+
+Moving to phase {next_id}: {next_goal}
+Run /ctx to start planning.
+```
+
+**Output (not ready):**
+```
+[CTX Phase] Cannot complete phase {id}
+
+Remaining tasks:
+  - {task_1}
+  - {task_2}
+
+Run /ctx to continue, or /ctx phase skip to skip.
+```
+
+---
+
+## /ctx phase skip
+
+Skip the current phase without completing it.
+
+**Process:**
+1. Mark current phase as "skipped"
+2. Log reason (optional prompt)
+3. Move to next phase
+4. Update STATE.md
+
+**Output:**
+```
+[CTX Phase] Skipped phase {id}: {goal}
+
+Moving to phase {next_id}: {next_goal}
+Run /ctx to start planning.
+```
+
+</subcommands>
+
+<state_management>
+Phases are tracked in STATE.md:
+
+```markdown
+## Phases
+| ID | Status | Goal |
+|----|--------|------|
+| 1 | complete | Set up project structure |
+| 2 | current | Add user authentication |
+| 3 | pending | Implement dashboard |
+```
+
+And in individual directories:
+```
+.ctx/phases/
+├── 1/
+│   ├── RESEARCH.md
+│   ├── PLAN.md
+│   └── VERIFY.md
+├── 2/
+│   ├── RESEARCH.md
+│   └── PLAN.md
+└── 3/
+    (empty until planned)
+```
+</state_management>

package/commands/plan.md

@@ -0,0 +1,125 @@
+---
+name: ctx:plan
+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 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           # Plan for current story (from PRD.json)
+/ctx plan S003      # Plan for specific story
+```
+</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."
+
+## Step 2: Load Story from PRD
+Read `.ctx/PRD.json`:
+
+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 with story context:
+
+1. **ArguSeek Research**
+   - Best practices for story goal
+   - Security considerations
+   - Common pitfalls for acceptance criteria
+   - Performance patterns
+
+2. **ChunkHound Analysis** (if available)
+   - Semantic search for story-related code
+   - Pattern detection
+   - Entry point mapping
+
+3. **Output**: `.ctx/phases/{story_id}/RESEARCH.md`
+
+## Step 4: Planning Phase
+Spawn **ctx-planner** agent:
+
+1. Read RESEARCH.md
+2. Map acceptance criteria to verification steps
+3. Break into **2-3 atomic tasks** (strict limit)
+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 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] Story: {story_id} - {title}
+
+Acceptance Criteria:
+  ✓ {criterion_1}
+  ✓ {criterion_2}
+  ✓ {criterion_3}
+
+Research:
+  ArguSeek: {n} findings
+  ChunkHound: {n} relevant files
+
+Plan Created:
+  Tasks: {count} (atomic)
+  Files: .ctx/phases/{story_id}/PLAN.md
+
+Tasks:
+  1. {task_1_title} → [criteria 1, 2]
+  2. {task_2_title} → [criteria 2, 3]
+
+Ready to execute. Run /ctx to start.
+```
+</output_format>
+
+<guardrails>
+- Plans are ALWAYS atomic: 2-3 tasks maximum
+- 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/status.md

@@ -0,0 +1,78 @@
+---
+name: ctx:status
+description: Read-only status check - see state without triggering action
+---
+
+<objective>
+Display current project status without triggering any workflow action.
+Pure inspection - read STATE.md and report.
+</objective>
+
+<workflow>
+## Step 1: Check Project Exists
+If `.ctx/STATE.md` doesn't exist:
+```
+[CTX] No project found. Run /ctx init to start.
+```
+
+## Step 2: Read State
+Load `.ctx/STATE.md` and extract:
+- Project name and tech stack
+- Current status (initializing/executing/debugging/verifying/paused)
+- Current phase and goal
+- Task progress
+- Debug session info (if active)
+- Context budget usage
+
+## Step 3: Read Phase Data
+If phase exists, also load:
+- `.ctx/phases/{id}/PLAN.md` - task list
+- `.ctx/phases/{id}/RESEARCH.md` - research summary (if exists)
+- `.ctx/phases/{id}/VERIFY.md` - verification results (if exists)
+
+## Step 4: Calculate Metrics
+- Tasks completed vs total
+- Context usage percentage
+- Time since last checkpoint
+</workflow>
+
+<output_format>
+```
+┌─────────────────────────────────────────┐
+│  CTX Status                             │
+├─────────────────────────────────────────┤
+│  Project:  {name}                       │
+│  Stack:    {tech_stack}                 │
+│  Status:   {status}                     │
+└─────────────────────────────────────────┘
+
+Phase: {phase_id} - {phase_goal}
+Progress: {completed}/{total} tasks [{progress_bar}]
+
+Current Task: {task_name}
+Task Status: {pending|in_progress|blocked|debugging}
+
+{If debugging:}
+Debug Session:
+  Issue: {debug_issue}
+  Attempt: {n}/5
+  Last Error: {error_summary}
+
+Context Budget:
+  Used: {percent}% ({quality_level})
+  Action: {continue|checkpoint-soon|checkpoint-now}
+
+Last Checkpoint: {timestamp or "none"}
+
+Next Action: Run /ctx to {recommended_action}
+```
+</output_format>
+
+<key_principle>
+This command is READ-ONLY. It never:
+- Modifies STATE.md
+- Triggers any agent
+- Starts any workflow action
+
+It only inspects and reports.
+</key_principle>