@cliangdev/flux-plugin 0.0.0-dev.45a9640 → 0.0.0-dev.46408d1

package/bin/install.cjs

@@ -179,7 +179,7 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 
 		mcpConfig.mcpServers.flux = {
 			command: "npx",
-			args: ["-y", "@cliangdev/flux-plugin", "serve"],
+			args: ["-y", `@cliangdev/flux-plugin@${pkg.version}`, "serve"],
 		};
 
 		writeJson(mcpConfigPath, mcpConfig);

package/commands/flux.md

@@ -1,113 +1,156 @@
 ---
 name: flux
 description: AI-first workflow orchestration for spec-driven development
-allowed-tools: mcp__flux__*
+allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion, Read, Write
 ---
 
-# Flux Orchestrator
+# Flux Command
+
+You are the Flux orchestrator. Detect project state and guide the user to the appropriate next action.
+
+## Subcommands
 
-You are the Flux orchestrator. Your job is to detect the project state and guide the user through the appropriate workflow.
+- `/flux version` - Show plugin version (call `get_version`)
+- `/flux linear` - Connect to Linear (delegate to `/flux:linear`)
 
-## Step 0: Check for Version Subcommand
+## Main Flow
+
+### Step 1: Get Project Context
 
-First, check if the user requested version information:
-- `/flux version` - Show version information
+Call `get_project_context` to check project state.
 
-If the argument is "version":
+### Step 2: Route Based on State
 
-1. Call the `get_version` MCP tool
-2. Display the version information in a friendly format:
-   ```
-   Flux Plugin v{version}
-   Package: @cliangdev/{name}
-   ```
-3. Exit (do not proceed to project state check)
+**If `initialized: false`:**
+→ Guide through initialization (see Initialization Flow below)
 
-## Step 1: Check Project State
+**If `initialized: true`:**
+→ Call `render_status` with `{view: "summary"}` to show current state
+→ Determine next action based on workflow state (see Workflow States)
 
-If no subcommand was provided, call the `get_project_context` MCP tool to check if this is a Flux project.
+## Initialization Flow
 
-## Step 2: Handle Result
+Use the `AskUserQuestion` tool for all questions during initialization.
 
-### If `initialized: false` (New Project)
+### Step 1: Confirm Initialization
 
-This is a new project. Guide the user through initialization:
+Use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "No Flux project found. Would you like to initialize one?",
+    "header": "Initialize",
+    "options": [
+      {"label": "Yes", "description": "Create a new Flux project in this directory"},
+      {"label": "No", "description": "Cancel initialization"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
-1. Ask: "No Flux project found in this directory. Would you like to initialize one?"
-   - If no, end with: "Run `/flux` when you're ready to set up Flux."
+If "No", exit with: "Run `/flux` when you're ready to set up Flux."
 
-2. Ask: "What is the name of this project?"
-   - Wait for response
+### Step 2: Collect Project Details
 
-3. Ask: "Brief vision - what does this project do? (one sentence)"
-   - Wait for response
+Use AskUserQuestion with text input (user will select "Other" to type):
+- Ask for project name
+- Ask for project vision (brief description)
 
-4. Call `init_project` tool with the name and vision
+### Step 3: Select Storage Backend
 
-5. Display success message:
-   ```
-   Flux project initialized!
+Use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Where should Flux store data?",
+    "header": "Storage",
+    "options": [
+      {"label": "Local (Recommended)", "description": "SQLite database in .flux/ - offline-first, no setup required"},
+      {"label": "Linear", "description": "Sync with Linear for team collaboration and issue tracking"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
-   Project: {name}
-   Vision: {vision}
-   Reference prefix: {ref_prefix}
+### Step 4: Ask About Tool Permissions
 
-   Created:
-   - .flux/project.json
-   - .flux/flux.db
+Use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Add Flux tools to allow list? This prevents permission prompts for Flux operations.",
+    "header": "Permissions",
+    "options": [
+      {"label": "Yes (Recommended)", "description": "Allow all Flux MCP tools without prompting"},
+      {"label": "No", "description": "Ask for permission each time"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
-   Next: Run /flux:prd to start planning your first PRD.
-   ```
+If "Yes", update the settings file:
 
-### If Project Exists (Initialized)
+1. Read `.claude/settings.local.json` (create if doesn't exist)
+2. Parse JSON (or start with `{"permissions": {"allow": []}}` if empty/missing)
+3. Add `"mcp__plugin_flux_flux__*"` to `permissions.allow` array if not already present
+4. Write back to `.claude/settings.local.json`
 
-This is an existing Flux project. Show status and suggest next action:
+Example result:
+```json
+{
+  "permissions": {
+    "allow": ["mcp__plugin_flux_flux__*"]
+  }
+}
+```
 
-1. Call `get_stats` to get entity counts
-
-2. Display status summary:
-   ```
-   Project: {name}
-   Vision: {vision}
-
-   Status:
-   - PRDs: {total} ({draft} draft, {pending_review} in review, {approved} approved)
-   - Epics: {total} ({pending} pending, {in_progress} active, {completed} done)
-   - Tasks: {total} ({pending} pending, {in_progress} active, {completed} done)
-   ```
-
-3. Determine and suggest next action based on state:
-
-   **If no PRDs exist:**
-   > "No PRDs yet. Run `/flux:prd` to create your first product requirements document."
-
-   **If PRDs exist with DRAFT status:**
-   > "You have draft PRDs. Review them and run `/flux:prd refine` or submit for review."
-
-   **If PRDs in PENDING_REVIEW:**
-   > "PRDs pending review. The critique agent will analyze feasibility and risks."
-
-   **If PRDs in REVIEWED status:**
-   > "Critique complete. Review feedback, then approve or revise the PRD."
-
-   **If PRDs APPROVED but no epics:**
-   > "PRDs approved! Run `/flux:breakdown` to break them into epics and tasks."
-
-   **If PRDs BREAKDOWN_READY with epics/tasks:**
-   > "Ready to implement! Run `/flux:implement` to start working on tasks."
-
-   **If tasks exist with PENDING status:**
-   > "Tasks ready. Run `/flux:implement` to start working."
-
-   **If tasks IN_PROGRESS:**
-   > "Implementation in progress. Run `/flux:implement` to continue."
-
-   **If all tasks COMPLETED:**
-   > "All tasks complete! Review your work and create a PR."
+Confirm to user: "Flux tools added to allow list. No more permission prompts for Flux operations."
+
+### Step 5: Initialize Project
+
+Call `init_project` with collected values:
+- `name`: project name
+- `vision`: project vision
+- `adapter`: "local" or "linear"
+
+### Step 6: Next Steps
+
+Display success message, then:
+
+- **If Local**: "Project initialized! Run `/flux:prd` to create your first PRD."
+- **If Linear**: "Project initialized! Now run `/flux:linear` to connect to Linear."
+
+## Workflow States
+
+Detect current state and suggest the appropriate next action:
+
+| State | Detection | Next Action |
+|-------|-----------|-------------|
+| No PRDs | `prds.total == 0` | `/flux:prd` to create first PRD |
+| Draft PRDs | PRDs in DRAFT | Review and refine or submit for review |
+| Pending Review | PRDs in PENDING_REVIEW | Critique agent will analyze |
+| Reviewed | PRDs in REVIEWED | Address feedback, approve or revise |
+| Approved | PRDs in APPROVED, no epics | `/flux:breakdown` to create epics |
+| Breakdown Ready | PRDs in BREAKDOWN_READY | `/flux:implement` to start coding |
+| In Progress | Tasks IN_PROGRESS | Continue with `/flux:implement` |
+| Complete | All tasks COMPLETED | Create PR |
+
+## Confidence-Based Autonomy
+
+When determining actions:
+
+| Confidence | Behavior |
+|------------|----------|
+| > 80% | Auto-execute, inform user |
+| 50-80% | Suggest action, wait for confirmation |
+| < 50% | Ask clarifying question |
 
 ## Guidelines
 
-- Be concise - users want quick status, not essays
-- One question at a time during initialization
-- Show actionable next steps
-- Use the MCP tools, don't read filesystem directly
+- Use `AskUserQuestion` tool for all user choices during initialization
+- Be concise - show status and one clear next action
+- Use `render_status` for visual project overview
+- Apply confidence-based autonomy for decisions

package/commands/linear.md

@@ -0,0 +1,171 @@
+---
+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
+
+Call `get_project_context`.
+
+- If `initialized: false` → Tell user to run `/flux` first, then exit.
+- If `adapter.type === "linear"` and config exists → Already configured, show info and exit.
+- Otherwise → Continue to Step 2.
+
+### 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

package/dist/server/index.js

@@ -1,4 +1,3 @@
-#!/usr/bin/env node
 import { createRequire } from "node:module";
 var __create = Object.create;
 var __getProtoOf = Object.getPrototypeOf;
@@ -83911,6 +83910,18 @@ var PRD_STATUSES_WITH_LABELS = {
   COMPLETED: null,
   ARCHIVED: null
 };
+var FLUX_MILESTONE_LABEL_PREFIX = "flux:milestone:";
+function getMilestoneLabel(tag) {
+  return `${FLUX_MILESTONE_LABEL_PREFIX}${tag}`;
+}
+function extractTagFromLabels(labels) {
+  for (const label of labels) {
+    if (label.startsWith(FLUX_MILESTONE_LABEL_PREFIX)) {
+      return label.substring(FLUX_MILESTONE_LABEL_PREFIX.length);
+    }
+  }
+  return;
+}
 
 // src/server/adapters/linear/mappers/epic.ts
 function toLinearEpicState(status) {
@@ -84062,6 +84073,7 @@ class LinearAdapter {
       title: issue2.title,
       description: issue2.description,
       status: toFluxPrdStatusFromIssue(issue2.stateName, issue2.labels),
+      tag: extractTagFromLabels(issue2.labels),
       createdAt: issue2.createdAt.toISOString(),
       updatedAt: issue2.updatedAt.toISOString()
     };
@@ -84101,13 +84113,17 @@ class LinearAdapter {
     return issue2.labels.includes(this.config.defaultLabels.task);
   }
   async createPrd(input) {
-    const prdLabelId = await this.getLabelId(this.config.defaultLabels.prd);
+    const labelIds = [await this.getLabelId(this.config.defaultLabels.prd)];
+    if (input.tag) {
+      const tagLabelId = await this.getOrCreateLabel(getMilestoneLabel(input.tag));
+      labelIds.push(tagLabelId);
+    }
     const createResult = await this.client.execute(() => this.client.client.createIssue({
       title: input.title,
       description: input.description,
       teamId: this.config.teamId,
       projectId: this.config.projectId,
-      labelIds: [prdLabelId]
+      labelIds
     }));
     const rawIssue = await this.client.execute(() => createResult.issue);
     if (!rawIssue) {
@@ -84129,7 +84145,10 @@ class LinearAdapter {
       updatePayload.description = input.description;
     if (input.status !== undefined) {
       updatePayload.stateId = await this.getStateId(toLinearPrdIssueState(input.status));
-      updatePayload.labelIds = await this.buildPrdLabelIds(issue2.labels, input.status);
+    }
+    if (input.status !== undefined || input.tag !== undefined) {
+      const currentStatus = toFluxPrdStatusFromIssue(issue2.stateName, issue2.labels);
+      updatePayload.labelIds = await this.buildPrdLabelIdsWithTag(issue2.labels, input.status ?? currentStatus, input.tag !== undefined ? input.tag : extractTagFromLabels(issue2.labels));
     }
     await this.client.execute(() => issue2._raw.update(updatePayload));
     const updated = await this.fetchIssue(ref);
@@ -84151,6 +84170,23 @@ class LinearAdapter {
     }
     return labelIds;
   }
+  async buildPrdLabelIdsWithTag(currentLabels, newStatus, newTag) {
+    const statusLabels = getAllStatusLabels();
+    const newStatusLabel = getStatusLabelForPrdStatus(newStatus);
+    const labelsToKeep = currentLabels.filter((l) => !statusLabels.includes(l) && !l.startsWith(FLUX_MILESTONE_LABEL_PREFIX));
+    if (newStatusLabel) {
+      labelsToKeep.push(newStatusLabel);
+    }
+    if (newTag) {
+      labelsToKeep.push(getMilestoneLabel(newTag));
+    }
+    const labelIds = [];
+    for (const labelName of labelsToKeep) {
+      const id = await this.getOrCreateLabel(labelName);
+      labelIds.push(id);
+    }
+    return labelIds;
+  }
   async getOrCreateLabel(labelName) {
     try {
       return await this.getLabelId(labelName);
@@ -84176,9 +84212,18 @@ class LinearAdapter {
     const limit = pagination?.limit ?? 50;
     const offset = pagination?.offset ?? 0;
     const linearFilter = {
-      labels: { name: { eq: this.config.defaultLabels.prd } },
       project: { id: { eq: this.config.projectId } }
     };
+    if (filters?.tag) {
+      linearFilter.labels = {
+        and: [
+          { name: { eq: this.config.defaultLabels.prd } },
+          { name: { eq: getMilestoneLabel(filters.tag) } }
+        ]
+      };
+    } else {
+      linearFilter.labels = { name: { eq: this.config.defaultLabels.prd } };
+    }
     if (filters?.status) {
       linearFilter.state = {
         name: { eq: toLinearPrdIssueState(filters.status) }
@@ -85468,14 +85513,20 @@ function clearAdapterCache() {
 var LINEAR_API_KEY_ENV = "LINEAR_API_KEY";
 var inputSchema = exports_external.object({
   apiKey: exports_external.string().optional(),
-  teamId: exports_external.string().min(1, "Team ID is required"),
+  teamId: exports_external.string().optional(),
   projectName: exports_external.string().optional(),
   existingProjectId: exports_external.string().optional(),
   prdLabel: exports_external.string().optional().default("prd"),
   epicLabel: exports_external.string().optional().default("epic"),
-  taskLabel: exports_external.string().optional().default("task")
-}).refine((data) => data.projectName || data.existingProjectId, {
-  message: "Either projectName or existingProjectId must be provided"
+  taskLabel: exports_external.string().optional().default("task"),
+  interactive: exports_external.boolean().optional().default(false)
+}).refine((data) => {
+  if (data.interactive) {
+    return true;
+  }
+  return data.teamId && data.teamId.length > 0 && (data.projectName || data.existingProjectId);
+}, {
+  message: "teamId and either projectName or existingProjectId are required (unless interactive mode)"
 });
 function resolveApiKey(inputApiKey) {
   if (inputApiKey) {
@@ -85553,19 +85604,72 @@ async function createDefaultView(client, teamId, projectId, projectName, labels)
     };
   }
 }
+async function listTeams(client) {
+  const teamsResult = await client.teams();
+  return teamsResult.nodes.map((team) => ({
+    id: team.id,
+    name: team.name,
+    key: team.key
+  }));
+}
+async function listProjects(client, teamId) {
+  const projectsResult = await client.projects({
+    filter: {
+      accessibleTeams: { some: { id: { eq: teamId } } },
+      state: { nin: ["canceled"] }
+    }
+  });
+  return projectsResult.nodes.map((project) => ({
+    id: project.id,
+    name: project.name,
+    description: project.description ?? null,
+    state: project.state,
+    updatedAt: project.updatedAt.toISOString()
+  }));
+}
 async function handler(input) {
   const parsed = inputSchema.parse(input);
   const { apiKey, source: apiKeySource } = resolveApiKey(parsed.apiKey);
   const client = new LinearClient({ apiKey });
+  let viewerName;
+  let viewerEmail;
   try {
     const viewer = await client.viewer;
     if (!viewer) {
       throw new Error("Invalid API key");
     }
+    viewerName = viewer.name;
+    viewerEmail = viewer.email;
   } catch (error48) {
     const message = error48 instanceof Error ? error48.message : String(error48);
     throw new Error(`Invalid Linear API key (source: ${apiKeySource}): ${message}`);
   }
+  if (parsed.interactive && !parsed.teamId) {
+    const teams = await listTeams(client);
+    return {
+      step: "select_team",
+      user: { name: viewerName, email: viewerEmail },
+      api_key_source: apiKeySource,
+      teams
+    };
+  }
+  if (parsed.interactive && parsed.teamId && !parsed.projectName && !parsed.existingProjectId) {
+    const team2 = await client.team(parsed.teamId);
+    if (!team2) {
+      throw new Error(`Team ${parsed.teamId} not found`);
+    }
+    const projects = await listProjects(client, parsed.teamId);
+    return {
+      step: "select_project",
+      user: { name: viewerName, email: viewerEmail },
+      api_key_source: apiKeySource,
+      team: { id: team2.id, name: team2.name, key: team2.key },
+      projects
+    };
+  }
+  if (!parsed.teamId) {
+    throw new Error("teamId is required");
+  }
   const team = await client.team(parsed.teamId);
   if (!team) {
     throw new Error(`Team ${parsed.teamId} not found`);
@@ -85642,7 +85746,7 @@ async function handler(input) {
 }
 var configureLinearTool = {
   name: "configure_linear",
-  description: "Configure Linear integration for the Flux project. " + "API Key Resolution (priority order): 1) LINEAR_API_KEY environment variable (recommended), 2) Existing .flux/linear-config.json, 3) apiKey parameter (not recommended - visible in logs). " + "Required: teamId (Linear team ID), and either projectName (to create new) or existingProjectId (to use existing). " + "Optional: apiKey, prdLabel (default 'prd'), epicLabel (default 'epic'), taskLabel (default 'task'). " + "Creates a Linear Project, ensures labels exist, creates 'Flux' custom view for new projects, saves config to .flux/linear-config.json. " + "Returns {success, message, api_key_source, team, project, labels, view}. " + "Setup: export LINEAR_API_KEY=lin_api_xxx before running.",
+  description: "Configure Linear integration for the Flux project. " + "Use interactive mode for guided setup: " + "1) Call with {interactive: true} to get list of teams. " + "2) Call with {interactive: true, teamId: '...'} to get list of projects. " + "3) Call with full params to configure. " + "API Key Resolution (priority order): 1) LINEAR_API_KEY environment variable (recommended), 2) Existing .flux/linear-config.json, 3) apiKey parameter (not recommended - visible in logs). " + "Required (non-interactive): teamId (Linear team ID), and either projectName (to create new) or existingProjectId (to use existing). " + "Optional: apiKey, prdLabel (default 'prd'), epicLabel (default 'epic'), taskLabel (default 'task'). " + "Creates a Linear Project, ensures labels exist, creates 'Flux' custom view for new projects, saves config to .flux/linear-config.json. " + "Returns {success, message, api_key_source, team, project, labels, view} on final configuration. " + "Setup: export LINEAR_API_KEY=lin_api_xxx before running.",
   inputSchema,
   handler
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.0.0-dev.45a9640",
+  "version": "0.0.0-dev.46408d1",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",
@@ -23,14 +23,16 @@
     "build:compile:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
     "build:compile:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
     "validate": "node scripts/validate-structure.cjs",
-    "prepublishOnly": "bun run validate && bun run build",
+    "test:integration": "bun test scripts/__tests__/integration.test.ts --timeout 120000",
+    "prepublishOnly": "bun run validate && bun run build && bun run test:integration",
     "test": "bun test",
     "test:linear-description": "bun run src/server/adapters/__tests__/linear-description-test.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "verify-release": "bun run scripts/verify-release.ts"
+    "verify-release": "bun run scripts/verify-release.ts",
+    "release": "./scripts/release.sh"
   },
   "repository": {
     "type": "git",

package/skills/flux-orchestrator/SKILL.md

@@ -6,18 +6,20 @@ user-invocable: false
 
 # Flux Orchestrator Skill
 
-This skill is automatically active when working in a Flux project. It provides context about available tools and workflow patterns.
+This skill is automatically active when working in a Flux project. It provides context about available tools, workflow patterns, and integration options.
 
 ## Available MCP Tools
 
 ### Query Tools
-- `get_project_context` - Check if project initialized, get name/vision/prefix
+- `get_project_context` - Check if project initialized, get name/vision/adapter type
 - `get_stats` - Get PRD/epic/task counts by status
 - `get_entity` - Fetch entity by ref with optional includes (criteria, tasks, dependencies)
 - `query_entities` - Search entities by type, status, parent ref
+- `render_status` - Get formatted project status with progress bars
 
 ### Mutation Tools
 - `init_project` - Initialize new .flux/ directory with project.json and database
+- `configure_linear` - Configure Linear integration (supports interactive mode)
 - `create_prd` - Create a new PRD
 - `create_epic` - Create an epic linked to a PRD
 - `create_task` - Create a task linked to an epic
@@ -31,102 +33,82 @@ This skill is automatically active when working in a Flux project. It provides c
 - `add_criteria` - Add acceptance criterion to epic or task
 - `mark_criteria_met` - Mark criterion as satisfied
 
-## Workflow States
+## Available Commands
 
-The Flux project progresses through these states:
+| Command | Purpose |
+|---------|---------|
+| `/flux` | Project init, status, and workflow routing |
+| `/flux:linear` | Connect project to Linear (interactive setup) |
+| `/flux:prd` | Create or refine PRDs |
+| `/flux:breakdown` | Break approved PRD into epics and tasks |
+| `/flux:implement` | Implement tasks with TDD workflow |
 
-1. **Uninitialized** - No .flux/ directory
-   - Action: Run `/flux` to initialize
+## Workflow States
 
-2. **No PRDs** - Project initialized but empty
-   - Action: Run `/flux:prd` to create first PRD
+```
+Uninitialized → Initialized → PRD Draft → Pending Review → Reviewed → Approved → Breakdown Ready → In Progress → Complete
+                     ↓
+              (optional) Linear Connected
+```
 
-3. **PRD Draft** - PRD created but needs review
-   - Action: Review and submit for approval or refine
+### PRD Status Transitions
+```
+DRAFT → PENDING_REVIEW → REVIEWED → APPROVED → BREAKDOWN_READY → COMPLETED
+          ↓                 ↓
+        DRAFT (revise)    DRAFT (revise)
+```
 
-4. **PRD Pending Review** - PRD submitted for review
-   - Action: Run critique agent, then approve or revise
+### Epic/Task Statuses
+- `PENDING` → `IN_PROGRESS` → `COMPLETED`
+
+## Backend Adapters
 
-5. **PRD Reviewed** - Critique complete
-   - Action: Address feedback, then approve or revise to DRAFT
+Flux supports multiple backends via the adapter pattern:
 
-6. **PRD Approved** - Ready for epic breakdown
-   - Action: Run `/flux:breakdown` to create epics
+| Adapter | Storage | Use Case |
+|---------|---------|----------|
+| `local` | SQLite (.flux/flux.db) | Default, offline-first |
+| `linear` | Linear API | Team collaboration, issue tracking |
 
-7. **Breakdown Ready** - Epics and tasks created
-   - Action: Run `/flux:implement` to start coding
+### Switching to Linear
 
-8. **Implementation In Progress** - Tasks IN_PROGRESS
-   - Action: Continue implementing current task
+Use `configure_linear` with interactive mode:
+1. `{interactive: true}` → returns teams list
+2. `{interactive: true, teamId: "..."}` → returns projects list
+3. `{teamId: "...", projectName/existingProjectId: "..."}` → configures
 
-9. **Complete** - All tasks COMPLETED
-    - Action: Review and create PR
+Or run `/flux:linear` for guided setup.
 
 ## Entity References
 
-All entities have a reference format: `{PREFIX}-{TYPE}{NUMBER}`
+Format: `{PREFIX}-{TYPE}{NUMBER}`
 
 - PRD: `MSA-P1`, `MSA-P2`
 - Epic: `MSA-E1`, `MSA-E2`
 - Task: `MSA-T1`, `MSA-T2`
 
-The prefix is generated from the project name during initialization.
-
-## Status Values
-
-### PRD Statuses (6-stage workflow)
-- `DRAFT` - Initial state, being created/refined
-- `PENDING_REVIEW` - Submitted for critique
-- `REVIEWED` - Critique complete, awaiting approval
-- `APPROVED` - Ready for epic breakdown
-- `BREAKDOWN_READY` - Epics and tasks created
-- `COMPLETED` - All epics done
-
-### Valid PRD Transitions
-```
-DRAFT → PENDING_REVIEW
-PENDING_REVIEW → REVIEWED | DRAFT (revise)
-REVIEWED → APPROVED | DRAFT (revise)
-APPROVED → BREAKDOWN_READY
-BREAKDOWN_READY → COMPLETED
-```
-
-### Epic/Task Statuses
-- `PENDING` - Not started
-- `IN_PROGRESS` - Currently being worked on
-- `COMPLETED` - Done
-
-## Confidence-Based Autonomy
-
-The orchestrator uses confidence levels to determine autonomy:
-
-| Confidence | Behavior | Example |
-|------------|----------|---------|
-| > 80% | Auto-execute, inform user | "I'm creating the epic structure..." |
-| 50-80% | Suggest action, wait for confirmation | "Ready to break down into tasks. Proceed?" |
-| < 50% | Ask clarifying question | "Should we research this technology first?" |
-
-### Confidence Indicators
-- **High confidence (>80%)**: Clear next step, no ambiguity, user has been responsive
-- **Medium confidence (50-80%)**: Reasonable next step, some uncertainty
-- **Low confidence (<50%)**: Multiple valid paths, unclear requirements, unfamiliar tech
-
 ## Available Subagents
 
-### Research Agent
-- **Trigger**: Unfamiliar technology mentioned, confidence < 70%
-- **Purpose**: Gather information about libraries, frameworks, APIs
+### Research Agent (`flux:flux-researcher`)
+- **Trigger**: Unfamiliar technology, confidence < 70%
 - **Tools**: Context7, WebSearch, WebFetch
 
-### Critique Agent
-- **Trigger**: PRD status becomes PENDING_REVIEW
-- **Purpose**: Analyze feasibility, scope, risks
-- **Output**: Structured critique with recommendations
+### Critique Agent (`flux:flux-critic`)
+- **Trigger**: PRD submitted for review
+- **Output**: Feasibility analysis, risks, recommendations
+
+### Coder Agent (`flux:flux-coder`)
+- **Trigger**: Task implementation
+- **Workflow**: TDD - write tests, implement, verify
+
+### Verifier Agent (`flux:flux-verifier`)
+- **Trigger**: After implementation
+- **Purpose**: Verify acceptance criteria coverage
 
 ## Best Practices
 
-1. **Check context first** - Always call `get_project_context` before taking actions
-2. **Use refs, not IDs** - Tools accept human-readable refs like `MSA-E1`
-3. **Validate status transitions** - Use `update_status` which enforces valid transitions
-4. **Include related data** - Use `include` parameter to fetch nested entities in one call
-5. **Handle errors gracefully** - Tools return errors with codes, display user-friendly messages
+1. **Check context first** - Call `get_project_context` before actions
+2. **Use refs, not IDs** - Tools accept `MSA-E1` format
+3. **Use render_status** - For visual project overview
+4. **Validate transitions** - `update_status` enforces valid transitions
+5. **Include related data** - Use `include` param to fetch nested entities