ctx-cc 3.0.0 → 3.3.0

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>