ctx-cc 2.3.0 → 3.1.0

package/commands/ctx.md

@@ -1,55 +1,84 @@
 ---
 name: ctx
-description: Smart router - reads STATE.md and does the right thing
+description: Smart router - reads STATE.md, config.json, and does the right thing. Uses model profiles for cost optimization.
 ---
 
 <objective>
-CTX 2.0 Smart Router - One command that always knows what to do next.
+CTX 3.0 Smart Router - One command that always knows what to do next.
 
-Read STATE.md, understand current context, and execute the appropriate action.
+Read STATE.md, load config.json, use appropriate model profile, and execute the right action.
 </objective>
 
 <workflow>
+## Step 0: Load Configuration
+
+Read `.ctx/config.json` for:
+- Active profile (quality/balanced/budget)
+- Model routing table
+- Git settings (autoCommit, commitPerTask)
+- Integration settings
+
+If config.json doesn't exist:
+- Copy from templates/config.json
+- Set balanced as default profile
+
 ## Step 1: Read State
+
 Read `.ctx/STATE.md` to understand current situation.
 
 If STATE.md doesn't exist:
 - Output: "No CTX project found. Run `/ctx init` to start."
 - Stop.
 
+Also check for:
+- `.ctx/REPO-MAP.md` - Codebase understanding
+- `.ctx/codebase/SUMMARY.md` - Deep codebase analysis
+- `.ctx/phases/{story_id}/CONTEXT.md` - Locked decisions
+
 ## Step 2: Route Based on State
 
 ### If status = "initializing"
 Route to: **Research Phase**
-1. Use ArguSeek to research the project goal
-2. Use ChunkHound for semantic code search (if existing codebase)
+1. Check if REPO-MAP exists, if not run ctx-mapper
+2. Use ArguSeek to research the project goal
 3. Create atomic plan (2-3 tasks max)
 4. Update STATE.md with plan
-5. Set status = "executing"
+5. Set status = "discussing"
+
+### If status = "discussing"
+Route to: **Discussion Phase**
+1. Spawn ctx-discusser agent
+2. Ask targeted questions about gray areas
+3. Lock decisions in CONTEXT.md
+4. Set status = "executing"
 
 ### If status = "executing"
 Route to: **Execute Current Task**
 1. Read current task from STATE.md
-2. Spawn ctx-executor agent
-3. Execute task with deviation handling:
+2. Load REPO-MAP for context
+3. Spawn ctx-executor agent (uses git-native workflow)
+4. Execute task with deviation handling:
    - Auto-fix: bugs, validation, deps (95%)
    - Ask user: architecture decisions only (5%)
-4. After task:
+5. After task:
    - Run verification (build, tests, lint)
+   - Auto-commit if config allows
    - If passes: mark done, update STATE.md
    - If fails: set status = "debugging"
 
 ### If status = "debugging"
-Route to: **Debug Loop**
+Route to: **Persistent Debug Loop**
 1. Spawn ctx-debugger agent
-2. Loop until fixed (max 5 attempts):
+2. Check for existing debug session (resume if exists)
+3. Loop until fixed (max 10 attempts):
    - Analyze error
    - Form hypothesis
    - Apply fix
    - Verify (build + tests + browser if UI)
+   - Record in persistent state
    - Take screenshot proof if browser test
-3. If fixed: set status = "executing", continue
-4. If 5 attempts fail: escalate to user
+4. If fixed: set status = "executing", continue
+5. If max attempts: escalate with full report
 
 ### If status = "verifying"
 Route to: **Three-Level Verification**
@@ -69,39 +98,83 @@ Route to: **Resume**
 3. Set status to previous state
 4. Continue workflow
 
-## Step 3: Context Budget Check
+## Step 3: Model Selection
+
+Based on current action and active profile:
+
+| Action | quality | balanced | budget |
+|--------|---------|----------|--------|
+| Research | opus | opus | sonnet |
+| Discussion | opus | sonnet | sonnet |
+| Planning | opus | opus | sonnet |
+| Execution | opus | sonnet | sonnet |
+| Debugging | opus | sonnet | sonnet |
+| Verification | sonnet | haiku | haiku |
+| Mapping | sonnet | haiku | haiku |
+
+Use Task tool with `model` parameter from routing table.
+
+## Step 4: Context Budget Check
+
 After every action:
 - Calculate context usage
+- If > 40%: Prepare handoff notes
 - If > 50%: Auto-checkpoint, warn user
+- If > 60%: Create HANDOFF.md, spawn fresh agent
 - If > 70%: Force checkpoint
 
-## Step 4: Update State
+## Step 5: Git-Native Commit
+
+If task completed successfully AND config.git.autoCommit = true:
+1. Stage modified files
+2. Create commit with CTX format
+3. Record commit hash in STATE.md
+
+## Step 6: Update State
+
 Always update STATE.md after any action:
 - Current status
 - Progress
+- Recent commits
 - Recent decisions
 - Next action
+- Context usage
 </workflow>
 
 <state_transitions>
 ```
-initializing → executing (after plan created)
+initializing → discussing (after research)
+discussing → executing (after decisions locked)
 executing → debugging (if verification fails)
 executing → verifying (if all tasks done)
 debugging → executing (if fix works)
-debugging → ESCALATE (if 5 attempts fail)
+debugging → ESCALATE (if max attempts fail)
 verifying → executing (if anti-patterns found)
 verifying → COMPLETE (if all passes)
 paused → (previous state)
 ```
 </state_transitions>
 
+<new_commands>
+## New in CTX 3.0
+
+| Command | Purpose |
+|---------|---------|
+| `/ctx map` | Build repository map (REPO-MAP.md) |
+| `/ctx map-codebase` | Deep codebase analysis (4 parallel agents) |
+| `/ctx discuss [story]` | Run discussion phase for story |
+| `/ctx profile [name]` | Switch model profile |
+| `/ctx debug --resume` | Resume previous debug session |
+</new_commands>
+
 <context_budget>
 | Usage | Quality | Action |
 |-------|---------|--------|
 | 0-30% | Peak | Continue |
-| 30-50% | Good | Continue |
-| 50-70% | Degrading | Auto-checkpoint |
+| 30-40% | Good | Continue |
+| 40-50% | Good | Prepare handoff |
+| 50-60% | Degrading | Auto-checkpoint |
+| 60-70% | Degrading | Create HANDOFF.md |
 | 70%+ | Poor | Force checkpoint |
 </context_budget>
 
@@ -109,7 +182,9 @@ paused → (previous state)
 After routing, output:
 ```
 [CTX] Status: {{status}}
+[CTX] Profile: {{profile}} ({{costTier}})
 [CTX] Action: {{action_taken}}
+[CTX] Commit: {{commit_hash}} (if auto-committed)
 [CTX] Next: {{next_action}}
 [CTX] Context: {{percent}}% ({{quality}})
 ```

package/commands/discuss.md

@@ -0,0 +1,101 @@
+---
+name: ctx:discuss
+description: Capture implementation decisions before planning. Resolves ambiguities and locks decisions.
+---
+
+<objective>
+Identify gray areas in a story and capture implementation decisions BEFORE planning.
+
+This prevents wasted work from misaligned assumptions.
+</objective>
+
+<usage>
+```
+/ctx discuss              # Discuss current story from PRD.json
+/ctx discuss S002         # Discuss specific story
+/ctx discuss --review     # Review existing decisions
+```
+</usage>
+
+<workflow>
+
+## Step 1: Load Story
+
+If story ID provided:
+- Read that story from `.ctx/PRD.json`
+
+If no story ID:
+- Read `metadata.currentStory` from PRD.json
+- Use that story
+
+If no PRD.json:
+- Output: "No PRD found. Run `/ctx init` first."
+- Stop
+
+## Step 2: Check Existing Discussion
+
+If `.ctx/phases/{story_id}/CONTEXT.md` exists:
+- If `--review` flag: Show existing decisions
+- Otherwise: Ask "Discussion exists. Redo? (will overwrite)"
+
+## Step 3: Spawn Discusser Agent
+
+Spawn `ctx-discusser` agent with:
+- Story details from PRD.json
+- Project context from STATE.md
+- Repo map from REPO-MAP.md (if exists)
+
+Agent will:
+1. Analyze story for gray areas
+2. Formulate targeted questions
+3. Ask user via AskUserQuestion
+4. Write CONTEXT.md with decisions
+
+## Step 4: Validate Output
+
+Ensure:
+- `.ctx/phases/{story_id}/CONTEXT.md` exists
+- Contains all required sections
+- No unresolved questions (or explicitly noted)
+
+## Step 5: Update State
+
+Update `.ctx/STATE.md`:
+- Set discussion status to complete
+- Add key decisions to "Recent Decisions"
+- Set next action to "Run /ctx plan"
+
+</workflow>
+
+<output_format>
+```
+[CTX] Discussion: Story {id} - {title}
+
+Questions Asked: {{count}}
+Decisions Captured: {{count}}
+
+Key Decisions:
+  - Auth: {{decision}}
+  - UI: {{decision}}
+  - Data: {{decision}}
+  ...
+
+Saved to: .ctx/phases/{story_id}/CONTEXT.md
+
+Next: Run /ctx plan (or /ctx to auto-route)
+```
+</output_format>
+
+<when_to_use>
+**Always use before planning when:**
+- Story has UI components (layout decisions needed)
+- Story involves new data models (schema decisions)
+- Story has security implications (auth, encryption)
+- Story touches external integrations
+- Story requirements are vague
+
+**Can skip when:**
+- Story is purely technical (refactor, optimization)
+- All decisions are already documented
+- Story is a simple bug fix with clear solution
+</when_to_use>

package/commands/integrate.md

@@ -0,0 +1,422 @@
+---
+name: ctx:integrate
+description: Setup and manage issue tracker integrations (Linear, Jira, GitHub Issues). Sync stories between PRD.json and external tools.
+---
+
+<objective>
+Connect CTX to external issue trackers for bidirectional story sync.
+
+When integrated:
+- Stories in PRD.json sync to issue tracker
+- Status updates reflect in both systems
+- Verification pass → close issue
+- Verification fail → add comment with details
+</objective>
+
+<usage>
+```
+/ctx integrate                    # Show current integrations
+/ctx integrate linear             # Setup Linear integration
+/ctx integrate jira               # Setup Jira integration
+/ctx integrate github             # Setup GitHub Issues integration
+/ctx integrate --sync             # Force sync all stories
+/ctx integrate --disconnect       # Remove integration
+```
+</usage>
+
+<supported_integrations>
+
+## Linear
+
+**Best for**: Startups, modern teams, API-first workflows
+
+**Features**:
+- Automatic story → issue sync
+- Status mapping (CTX status → Linear status)
+- Label sync (story type → Linear labels)
+- Cycle/sprint assignment
+- Comment sync on verify fail
+
+**Setup**:
+```bash
+/ctx integrate linear
+```
+
+Prompts for:
+1. API Key (from Linear settings)
+2. Team ID (workspace identifier)
+3. Default project (optional)
+4. Status mapping preferences
+
+**Config** (`.ctx/config.json`):
+```json
+{
+  "integrations": {
+    "linear": {
+      "enabled": true,
+      "apiKey": "env:LINEAR_API_KEY",
+      "teamId": "TEAM-123",
+      "projectId": "PROJECT-456",
+      "syncOnCreate": true,
+      "syncOnVerify": true,
+      "statusMapping": {
+        "pending": "Todo",
+        "executing": "In Progress",
+        "verifying": "In Review",
+        "complete": "Done"
+      },
+      "typeLabels": {
+        "feature": "feature",
+        "bug": "bug",
+        "design": "design"
+      }
+    }
+  }
+}
+```
+
+## Jira
+
+**Best for**: Enterprise, existing Jira workflows
+
+**Features**:
+- Story → Issue sync
+- Custom field mapping
+- Sprint assignment
+- Transition on status change
+- Attachment support (screenshots)
+
+**Setup**:
+```bash
+/ctx integrate jira
+```
+
+Prompts for:
+1. Jira URL (https://your-domain.atlassian.net)
+2. API Token (from Atlassian account)
+3. Project Key (e.g., "PROJ")
+4. Issue type (Story, Task, etc.)
+
+**Config**:
+```json
+{
+  "integrations": {
+    "jira": {
+      "enabled": true,
+      "baseUrl": "https://your-domain.atlassian.net",
+      "email": "env:JIRA_EMAIL",
+      "apiToken": "env:JIRA_API_TOKEN",
+      "projectKey": "PROJ",
+      "issueType": "Story",
+      "syncOnCreate": true,
+      "syncOnVerify": true,
+      "customFields": {
+        "acceptanceCriteria": "customfield_10001"
+      },
+      "transitionMapping": {
+        "executing": "In Progress",
+        "verifying": "In Review",
+        "complete": "Done"
+      }
+    }
+  }
+}
+```
+
+## GitHub Issues
+
+**Best for**: Open source, GitHub-centric workflows
+
+**Features**:
+- Story → Issue sync
+- Label management
+- Milestone assignment
+- Link to commits/PRs
+- Close on verify pass
+
+**Setup**:
+```bash
+/ctx integrate github
+```
+
+Prompts for:
+1. Repository (owner/repo format)
+2. GitHub token (uses existing gh auth if available)
+3. Label preferences
+
+**Config**:
+```json
+{
+  "integrations": {
+    "github": {
+      "enabled": true,
+      "repository": "owner/repo",
+      "token": "env:GITHUB_TOKEN",
+      "syncOnCreate": true,
+      "syncOnVerify": true,
+      "closeOnComplete": true,
+      "labels": {
+        "feature": "enhancement",
+        "bug": "bug",
+        "design": "design"
+      },
+      "milestoneFromPhase": true
+    }
+  }
+}
+```
+
+</supported_integrations>
+
+<workflow>
+
+## Step 1: Check Existing Integration
+
+```bash
+cat .ctx/config.json | jq '.integrations'
+```
+
+If integration exists, show status:
+```
+[CTX] Integration Status
+
+Linear: ✅ Connected
+  Team: Engineering
+  Stories synced: 12
+  Last sync: 2 minutes ago
+
+GitHub: ❌ Not configured
+Jira: ❌ Not configured
+```
+
+## Step 2: Setup New Integration
+
+### For Linear:
+```
+[CTX] Linear Integration Setup
+
+1. Get your API key from: https://linear.app/settings/api
+
+2. Enter API Key: **********************
+
+3. Fetching teams...
+   Found teams:
+   [1] Engineering (ENG)
+   [2] Product (PRD)
+
+   Select team: 1
+
+4. Fetching projects...
+   Found projects:
+   [1] CTX Development
+   [2] Website Redesign
+   [3] No project (team inbox)
+
+   Select default project: 1
+
+5. Status mapping:
+   CTX "executing" → Linear "In Progress" ✓
+   CTX "verifying" → Linear "In Review" ✓
+   CTX "complete" → Linear "Done" ✓
+
+   Use these mappings? [Y/n]: y
+
+✅ Linear integration configured!
+
+Saved to: .ctx/config.json
+API key stored in: .ctx/.env (gitignored)
+
+Run `/ctx integrate --sync` to sync existing stories.
+```
+
+### For Jira:
+```
+[CTX] Jira Integration Setup
+
+1. Enter your Jira URL: https://mycompany.atlassian.net
+
+2. Enter email for API access: user@company.com
+
+3. Get API token from: https://id.atlassian.com/manage-profile/security/api-tokens
+   Enter API Token: **********************
+
+4. Fetching projects...
+   Found projects:
+   [1] PROJ - Main Project
+   [2] OPS - Operations
+
+   Select project: 1
+
+5. Issue type for stories:
+   [1] Story
+   [2] Task
+   [3] Bug
+
+   Select: 1
+
+✅ Jira integration configured!
+```
+
+### For GitHub:
+```
+[CTX] GitHub Issues Integration Setup
+
+1. Enter repository (owner/repo): myorg/myrepo
+
+2. Checking GitHub authentication...
+   ✅ Found existing gh auth
+
+3. Fetching repository info...
+   ✅ Repository found: My Repo
+   ✅ Issues enabled
+
+4. Labels to create/use:
+   - "ctx:feature" for feature stories
+   - "ctx:bug" for bug stories
+   - "ctx:design" for design stories
+
+   Create missing labels? [Y/n]: y
+
+✅ GitHub integration configured!
+```
+
+## Step 3: Sync Stories
+
+When `/ctx integrate --sync` runs:
+
+```
+[CTX] Syncing stories to Linear...
+
+Story S001 - User Authentication
+  → Creating issue in Linear...
+  → Issue created: ENG-123
+  → Syncing acceptance criteria...
+  ✅ Synced
+
+Story S002 - Dashboard UI
+  → Creating issue in Linear...
+  → Issue created: ENG-124
+  ✅ Synced
+
+Story S003 - API Refactor
+  → Issue already exists: ENG-100
+  → Updating status...
+  ✅ Updated
+
+Summary:
+  Created: 2 issues
+  Updated: 1 issue
+  Errors: 0
+```
+
+## Step 4: Ongoing Sync
+
+### On Story Create (via /ctx init or edit PRD.json)
+```
+if config.integrations.linear.syncOnCreate:
+  create_linear_issue(story)
+  store_issue_id_in_prd(story.id, issue.id)
+```
+
+### On Status Change
+```
+if status changed to "executing":
+  update_issue_status("In Progress")
+
+if status changed to "complete":
+  update_issue_status("Done")
+  if config.closeOnComplete:
+    close_issue()
+```
+
+### On Verify Fail
+```
+if verification fails:
+  add_comment(issue, {
+    title: "Verification Failed",
+    body: verification_report,
+    attachments: screenshots
+  })
+```
+
+### On Verify Pass
+```
+if verification passes:
+  add_comment(issue, {
+    title: "✅ Verification Passed",
+    body: summary,
+    commits: related_commits
+  })
+  close_issue()
+```
+
+</workflow>
+
+<prd_integration>
+
+## PRD.json with Issue Tracking
+
+```json
+{
+  "stories": [
+    {
+      "id": "S001",
+      "title": "User Authentication",
+      "type": "feature",
+      "acceptanceCriteria": [...],
+      "passes": false,
+      "external": {
+        "linear": {
+          "issueId": "ENG-123",
+          "url": "https://linear.app/team/issue/ENG-123"
+        }
+      }
+    }
+  ]
+}
+```
+
+The `external` field tracks linked issues across integrations.
+
+</prd_integration>
+
+<commands>
+
+## Integration Commands
+
+| Command | Action |
+|---------|--------|
+| `/ctx integrate` | Show all integrations status |
+| `/ctx integrate linear` | Setup Linear |
+| `/ctx integrate jira` | Setup Jira |
+| `/ctx integrate github` | Setup GitHub Issues |
+| `/ctx integrate --sync` | Force sync all stories |
+| `/ctx integrate --sync S001` | Sync specific story |
+| `/ctx integrate --disconnect linear` | Remove Linear integration |
+| `/ctx integrate --test` | Test connection |
+
+</commands>
+
+<output_format>
+```
+[CTX] Integration: {{provider}}
+
+Status: {{connected|disconnected|error}}
+{{details}}
+
+Last sync: {{timestamp}}
+Stories synced: {{count}}
+
+{{action_result}}
+```
+</output_format>
+
+<security>
+## Credential Security
+
+- API keys stored in `.ctx/.env` (gitignored)
+- Config references via `env:VARIABLE_NAME`
+- Never log or display full tokens
+- Support for environment variables
+- Prompt for re-auth if token expired
+</security>