@cliangdev/flux-plugin 0.1.0 → 0.2.0-dev.359209a

package/commands/linear.md

@@ -0,0 +1,172 @@
+---
+name: flux:linear
+description: Connect Flux project to Linear for issue tracking
+allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion
+---
+
+# Linear Integration Setup
+
+Connect a Flux project to Linear using the interactive configuration flow.
+
+## How Interactive Mode Works
+
+The `configure_linear` tool supports progressive discovery:
+
+| Call | Response |
+|------|----------|
+| `{interactive: true}` | Returns `{step: "select_team", teams: [...], user: {...}}` |
+| `{interactive: true, teamId: "xxx"}` | Returns `{step: "select_project", projects: [...], team: {...}}` |
+| `{teamId: "xxx", projectName: "..."}` | Creates new project and configures |
+| `{teamId: "xxx", existingProjectId: "..."}` | Uses existing project and configures |
+
+## Flow
+
+### Step 1: Verify Project & Fetch Teams
+
+Call `configure_linear` with `{interactive: true}`.
+
+- If error with `code: "PROJECT_NOT_INITIALIZED"` → Tell user to run `/flux` first, then exit.
+- If error about Linear API key → Show instructions (see Step 2 error handling).
+- If success with `step: "already_configured"` → Already configured, show info and exit.
+- Otherwise → Continue with team selection (response contains teams list).
+
+### Step 2: Fetch Teams
+
+**IMPORTANT**: Call `configure_linear` with ONLY `interactive: true`. Do NOT pass teamId, projectName, or any other params.
+
+```json
+{"interactive": true}
+```
+
+This is the ONLY parameter needed for the first call. The tool will return available teams.
+
+**If error** (e.g., "Linear API key not found"):
+```
+Linear API key required.
+
+1. Get your key: Linear → Settings → API → Personal API keys
+2. Set it: export LINEAR_API_KEY=lin_api_xxx
+3. Run /flux:linear again
+```
+Then exit.
+
+**If success**, response will be:
+```json
+{
+  "step": "select_team",
+  "user": {"name": "...", "email": "..."},
+  "teams": [
+    {"id": "team-abc", "name": "Engineering", "key": "ENG"},
+    {"id": "team-def", "name": "Product", "key": "PROD"}
+  ]
+}
+```
+
+Display: "Connected as {user.name} ({user.email})"
+
+Use AskUserQuestion to let user select a team:
+```json
+{
+  "questions": [{
+    "question": "Which Linear team should Flux use?",
+    "header": "Team",
+    "options": [
+      {"label": "Engineering (ENG)", "description": "team-abc"},
+      {"label": "Product (PROD)", "description": "team-def"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+Note: Put the team ID in the description field so you can retrieve it from the response.
+
+### Step 3: Fetch Projects
+
+Call `configure_linear` with:
+```json
+{"interactive": true, "teamId": "<selected_team_id>"}
+```
+
+Response will be:
+```json
+{
+  "step": "select_project",
+  "team": {"id": "...", "name": "...", "key": "..."},
+  "projects": [
+    {"id": "proj-123", "name": "Q1 Sprint", "state": "started"},
+    {"id": "proj-456", "name": "Backlog", "state": "planned"}
+  ]
+}
+```
+
+Use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Which project should Flux sync to?",
+    "header": "Project",
+    "options": [
+      {"label": "Create New Project", "description": "new"},
+      {"label": "Q1 Sprint", "description": "proj-123"},
+      {"label": "Backlog", "description": "proj-456"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+### Step 4: Configure
+
+**If user selected "Create New Project":**
+
+Ask for project name, then call:
+```json
+{
+  "teamId": "<team_id>",
+  "projectName": "<user_provided_name>"
+}
+```
+
+**If user selected existing project:**
+
+Call:
+```json
+{
+  "teamId": "<team_id>",
+  "existingProjectId": "<project_id>"
+}
+```
+
+### Step 5: Success
+
+Response will include:
+```json
+{
+  "success": true,
+  "team": "Engineering",
+  "project": {"id": "...", "name": "..."},
+  "labels": {...},
+  "view": {"created": "...", "setup_hint": "..."}
+}
+```
+
+Display:
+```
+Linear connected!
+
+Team: {team}
+Project: {project.name}
+
+All PRDs, epics, and tasks will sync to Linear.
+Run /flux:prd to create your first PRD.
+```
+
+If `view.setup_hint` exists, show it as a tip.
+
+## Key Points
+
+- Always use `{"interactive": true}` (boolean) not a string
+- The response `step` field tells you what stage you're at
+- Use AskUserQuestion for team/project selection
+- Store the selected IDs from previous responses to use in next calls