@cliangdev/flux-plugin 0.1.0 → 0.2.0

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/commands/prd.md

@@ -1,4 +1,5 @@
 ---
+name: flux:prd
 description: Create or refine PRDs through guided interview
 allowed-tools: mcp__flux__*, AskUserQuestion
 ---

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;
@@ -22481,7 +22480,6 @@ var config2 = {
 };
 
 // src/server/db/index.ts
-import { Database } from "bun:sqlite";
 import { existsSync as existsSync2, mkdirSync } from "node:fs";
 
 // src/server/utils/logger.ts
@@ -22584,6 +22582,44 @@ CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
 CREATE INDEX IF NOT EXISTS idx_criteria_parent ON acceptance_criteria(parent_type, parent_id);
 `;
 
+// src/server/db/sqlite.ts
+var isBun = typeof process !== "undefined" && !!process.versions?.bun;
+var DatabaseImpl;
+if (isBun) {
+  const bunSqlite = "bun:" + "sqlite";
+  const { Database: BunDatabase } = await import(bunSqlite);
+  DatabaseImpl = BunDatabase;
+} else {
+  const BetterSqlite3 = (await import("better-sqlite3")).default;
+
+  class BetterSqlite3Wrapper {
+    db;
+    constructor(path) {
+      this.db = new BetterSqlite3(path);
+    }
+    query(sql) {
+      const stmt = this.db.prepare(sql);
+      return {
+        get: (...params) => stmt.get(...params),
+        all: (...params) => stmt.all(...params),
+        run: (...params) => {
+          stmt.run(...params);
+        }
+      };
+    }
+    exec(sql) {
+      this.db.exec(sql);
+    }
+    run(sql) {
+      this.db.exec(sql);
+    }
+    close() {
+      this.db.close();
+    }
+  }
+  DatabaseImpl = BetterSqlite3Wrapper;
+}
+
 // src/server/db/ids.ts
 function generateId(prefix = "") {
   const timestamp = Date.now().toString(36);
@@ -22686,7 +22722,7 @@ function initDb() {
     mkdirSync(config2.fluxPath, { recursive: true });
   }
   logger.info(`Opening database: ${config2.dbPath}`);
-  db = new Database(config2.dbPath);
+  db = new DatabaseImpl(config2.dbPath);
   db.run("PRAGMA foreign_keys = ON");
   db.exec(SCHEMA);
   logger.info("Database initialized successfully");
@@ -83874,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) {
@@ -84025,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()
     };
@@ -84064,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) {
@@ -84092,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);
@@ -84114,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);
@@ -84139,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) }
@@ -85431,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) {
@@ -85516,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`);
@@ -85605,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
 };
@@ -86184,14 +86325,7 @@ var getStatsTool = {
   handler: handler8
 };
 // src/version.ts
-import { readFileSync as readFileSync6 } from "node:fs";
-import { dirname as dirname2, join as join2 } from "node:path";
-import { fileURLToPath } from "node:url";
-var __filename2 = fileURLToPath(import.meta.url);
-var __dirname2 = dirname2(__filename2);
-var packageJsonPath = join2(__dirname2, "..", "package.json");
-var packageJson = JSON.parse(readFileSync6(packageJsonPath, "utf-8"));
-var VERSION = packageJson.version;
+var VERSION = "0.1.0";
 
 // src/server/tools/get-version.ts
 var inputSchema10 = exports_external.object({});
@@ -86208,15 +86342,15 @@ var getVersionTool = {
   handler: handler9
 };
 // src/server/tools/init-project.ts
-import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
-import { dirname as dirname3, join as join3 } from "node:path";
+import { existsSync as existsSync8, mkdirSync as mkdirSync4, readFileSync as readFileSync6, writeFileSync as writeFileSync4 } from "node:fs";
+import { dirname as dirname2, join as join2 } from "node:path";
 function getStatusLineBinaryPath() {
-  const thisDir = dirname3(new URL(import.meta.url).pathname);
-  return join3(thisDir, "..", "..", "..", "bin", "flux-status");
+  const thisDir = dirname2(new URL(import.meta.url).pathname);
+  return join2(thisDir, "..", "..", "..", "bin", "flux-status");
 }
 function setupClaudeSettings(projectRoot) {
-  const claudeDir = join3(projectRoot, ".claude");
-  const settingsPath = join3(claudeDir, "settings.local.json");
+  const claudeDir = join2(projectRoot, ".claude");
+  const settingsPath = join2(claudeDir, "settings.local.json");
   const statusBinaryPath = getStatusLineBinaryPath();
   if (!existsSync8(statusBinaryPath)) {
     return;
@@ -86227,7 +86361,7 @@ function setupClaudeSettings(projectRoot) {
   let settings = {};
   if (existsSync8(settingsPath)) {
     try {
-      settings = JSON.parse(readFileSync7(settingsPath, "utf-8"));
+      settings = JSON.parse(readFileSync6(settingsPath, "utf-8"));
     } catch {
       settings = {};
     }
@@ -86393,7 +86527,7 @@ var queryEntitiesTool = {
   handler: handler11
 };
 // src/server/tools/render-status.ts
-import { existsSync as existsSync9, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:fs";
 
 // src/utils/display.ts
 function renderProgressBar(percentage, width) {
@@ -86506,7 +86640,7 @@ function getProjectInfo() {
     return null;
   }
   try {
-    const content = readFileSync8(config2.projectJsonPath, "utf-8");
+    const content = readFileSync7(config2.projectJsonPath, "utf-8");
     const project = JSON.parse(content);
     return {
       name: project.name || "Unnamed Project",

package/manifest.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "./manifest.schema.json",
+  "version": "1.0.0",
+  "structure": {
+    "commands": ["flux.md", "prd.md", "breakdown.md", "implement.md"],
+    "skills": [
+      "agent-creator",
+      "epic-template",
+      "flux-orchestrator",
+      "prd-template"
+    ],
+    "agents": ["coder.md", "critic.md", "researcher.md", "verifier.md"],
+    "hooks": []
+  }
+}

package/package.json

@@ -1,32 +1,38 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",
   "bin": {
-    "flux-plugin": "./dist/server/index.js"
+    "flux-plugin": "./bin/install.cjs"
   },
   "files": [
+    "bin/",
     "dist/",
     "skills/",
-    "commands/"
+    "commands/",
+    "agents/",
+    "manifest.json"
   ],
   "scripts": {
     "dev": "bun run src/server/index.ts",
-    "build": "bun build src/server/index.ts --outdir dist/server --target node",
+    "build": "bun build src/server/index.ts --outdir dist/server --target node --external better-sqlite3",
     "postbuild": "node -e \"const fs=require('fs');const f='dist/server/index.js';const c=fs.readFileSync(f,'utf-8');if(!c.startsWith('#!/usr/bin/env node')){fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)}\"",
     "build:compile": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
     "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",
-    "prepublishOnly": "bun run build",
+    "validate": "node scripts/validate-structure.cjs",
+    "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",
@@ -47,12 +53,14 @@
   "license": "MIT",
   "devDependencies": {
     "@biomejs/biome": "^2.3.11",
+    "@types/better-sqlite3": "^7.6.13",
     "@types/bun": "^1.3.6",
     "typescript": "^5.0.0"
   },
   "dependencies": {
     "@linear/sdk": "^70.0.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
+    "better-sqlite3": "^12.6.2",
     "chalk": "^5.4.1",
     "zod": "^4.3.5"
   },

package/skills/agent-creator/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:agent-creator
 description: Guide for creating effective subagents. Use when users want to create a new agent that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+user-invocable: false
 ---
 
 # Agent Creator Skill

package/skills/epic-template/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:epic-template
 description: Epic and task structure patterns for Flux. Use when breaking PRDs into epics and tasks. Epics should be self-contained with clear acceptance criteria.
+user-invocable: false
 ---
 
 # Epic Template Skill