@cliangdev/flux-plugin 0.1.0 → 0.2.0-dev.dc5e2c4

package/skills/flux-orchestrator/SKILL.md

@@ -1,21 +1,25 @@
 ---
+name: flux:flux-orchestrator
 description: Orchestrates Flux workflows based on project context
+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
@@ -29,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

package/skills/prd-template/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:prd-template
 description: PRD structure and patterns for Flux. Use when creating or refining product requirement documents. PRDs should be concise for humans but detailed enough for AI agents to implement.
+user-invocable: false
 ---
 
 # PRD Template Skill

package/src/__tests__/version.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, test } from "bun:test";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+describe("version module", () => {
+  test("VERSION is exported from src/version.ts", async () => {
+    // Dynamic import to get the VERSION constant
+    const versionModule = await import("../version.js");
+
+    expect(versionModule.VERSION).toBeDefined();
+    expect(typeof versionModule.VERSION).toBe("string");
+  });
+
+  test("VERSION equals package.json version", async () => {
+    // Read package.json version
+    const packageJsonPath = join(process.cwd(), "package.json");
+    expect(existsSync(packageJsonPath)).toBe(true);
+
+    const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf-8"));
+    const packageVersion = packageJson.version;
+
+    expect(packageVersion).toBeDefined();
+    expect(typeof packageVersion).toBe("string");
+
+    // Import VERSION and compare
+    const versionModule = await import("../version.js");
+    expect(versionModule.VERSION).toBe(packageVersion);
+  });
+
+  test("VERSION is a valid semver format", async () => {
+    const versionModule = await import("../version.js");
+
+    // Basic semver format check (e.g., "0.1.0", "1.2.3-beta.1")
+    const semverPattern = /^\d+\.\d+\.\d+(-[\w.]+)?$/;
+    expect(semverPattern.test(versionModule.VERSION)).toBe(true);
+  });
+});

package/src/server/__tests__/config.test.ts

@@ -0,0 +1,163 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  realpathSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+
+describe("config", () => {
+  const originalEnv = process.env.FLUX_PROJECT_ROOT;
+  const originalCwd = process.cwd();
+  // Use os.tmpdir() to get the real temp path (handles /tmp -> /private/tmp on macOS)
+  const TEST_DIR = `${realpathSync(tmpdir())}/flux-config-test-${Date.now()}`;
+  const NESTED_DIR = `${TEST_DIR}/subdir/nested`;
+
+  beforeEach(async () => {
+    // Clean up any previous test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+
+    // Create test directory structure
+    mkdirSync(NESTED_DIR, { recursive: true });
+
+    // Clear the config cache before each test
+    const { config } = await import("../config.js");
+    config.clearCache();
+  });
+
+  afterEach(async () => {
+    // Restore original env
+    if (originalEnv !== undefined) {
+      process.env.FLUX_PROJECT_ROOT = originalEnv;
+    } else {
+      delete process.env.FLUX_PROJECT_ROOT;
+    }
+
+    // Restore original cwd
+    process.chdir(originalCwd);
+
+    // Clear the config cache
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Clean up test directory
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true });
+    }
+  });
+
+  test("uses env var when properly set", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/some/valid/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectRoot).toBe("/some/valid/path");
+  });
+
+  test("ignores unresolved template variable and walks up directories", async () => {
+    // Create a .flux folder at TEST_DIR
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // Simulate Claude Code passing unresolved template variable
+    // biome-ignore lint/suspicious/noTemplateCurlyInString: intentionally testing literal template string
+    process.env.FLUX_PROJECT_ROOT = "${CLAUDE_PROJECT_DIR}";
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR, not use the literal "${CLAUDE_PROJECT_DIR}"
+    expect(config.projectRoot).not.toContain("${");
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("walks up directories to find .flux folder", async () => {
+    // Create a .flux folder at TEST_DIR (parent of NESTED_DIR)
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to nested directory
+    process.chdir(NESTED_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should walk up and find TEST_DIR
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("falls back to cwd when no .flux folder found", async () => {
+    // No .flux folder anywhere in TEST_DIR hierarchy
+    // No env var set
+    delete process.env.FLUX_PROJECT_ROOT;
+
+    // Change to test directory (which has no .flux)
+    process.chdir(TEST_DIR);
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // Should fall back to cwd
+    expect(config.projectRoot).toBe(TEST_DIR);
+  });
+
+  test("projectExists returns true when project.json exists", async () => {
+    mkdirSync(`${TEST_DIR}/.flux`, { recursive: true });
+    writeFileSync(
+      `${TEST_DIR}/.flux/project.json`,
+      JSON.stringify({ name: "test" }),
+    );
+
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(true);
+  });
+
+  test("projectExists returns false when project.json does not exist", async () => {
+    // No .flux folder
+    process.env.FLUX_PROJECT_ROOT = TEST_DIR;
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    expect(config.projectExists).toBe(false);
+  });
+
+  test("caches project root for performance", async () => {
+    process.env.FLUX_PROJECT_ROOT = "/first/path";
+
+    const { config } = await import("../config.js");
+    config.clearCache();
+
+    // First call caches the value
+    expect(config.projectRoot).toBe("/first/path");
+
+    // Changing env var should not affect cached value
+    process.env.FLUX_PROJECT_ROOT = "/second/path";
+    expect(config.projectRoot).toBe("/first/path");
+
+    // After clearing cache, should use new env var
+    config.clearCache();
+    expect(config.projectRoot).toBe("/second/path");
+  });
+});

package/src/server/adapters/__tests__/a-client-linear.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, test } from "bun:test";
+import { LinearApiError, LinearClient } from "../linear/client.js";
+
+const config = {
+  apiKey: "lin_api_test123",
+  teamId: "TEAM-123",
+  projectId: "proj_container",
+  defaultLabels: { prd: "prd", epic: "epic", task: "task" },
+};
+
+describe("LinearClient", () => {
+  describe("constructor", () => {
+    test("creates client with valid config", () => {
+      const client = new LinearClient(config);
+
+      expect(client).toBeDefined();
+      expect(client.client).toBeDefined();
+    });
+
+    test("accepts custom retry options", () => {
+      const client = new LinearClient(config, {
+        maxRetries: 5,
+        baseDelay: 500,
+      });
+
+      expect(client).toBeDefined();
+    });
+  });
+
+  describe("execute - retry logic", () => {
+    test("returns result on successful operation", async () => {
+      const client = new LinearClient(config);
+      let callCount = 0;
+      const operation = () => {
+        callCount++;
+        return Promise.resolve({ data: "success" });
+      };
+
+      const result = await client.execute(operation);
+
+      expect(result).toEqual({ data: "success" });
+      expect(callCount).toBe(1);
+    });
+
+    test("retries on network error and succeeds", async () => {
+      const client = new LinearClient(config, { maxRetries: 3, baseDelay: 10 });
+      let attempts = 0;
+      const operation = () => {
+        attempts++;
+        if (attempts < 3) {
+          const error: any = new Error("Network error");
+          error.code = "ECONNRESET";
+          return Promise.reject(error);
+        }
+        return Promise.resolve({ data: "success" });
+      };
+
+      const result = await client.execute(operation);
+
+      expect(result).toEqual({ data: "success" });
+      expect(attempts).toBe(3);
+    });
+
+    test("retries on rate limit error (429) and succeeds", async () => {
+      const client = new LinearClient(config, { maxRetries: 3, baseDelay: 10 });
+      let attempts = 0;
+      const operation = () => {
+        attempts++;
+        if (attempts < 2) {
+          const error: any = new Error("Rate limited");
+          error.status = 429;
+          return Promise.reject(error);
+        }
+        return Promise.resolve({ data: "success" });
+      };
+
+      const result = await client.execute(operation);
+
+      expect(result).toEqual({ data: "success" });
+      expect(attempts).toBe(2);
+    });
+
+    test("throws LinearApiError after max retries exhausted (rate limit)", async () => {
+      const client = new LinearClient(config, { maxRetries: 2, baseDelay: 10 });
+      const operation = () => {
+        const error: any = new Error("Rate limited");
+        error.status = 429;
+        return Promise.reject(error);
+      };
+
+      await expect(client.execute(operation)).rejects.toThrow(LinearApiError);
+      await expect(client.execute(operation)).rejects.toThrow(
+        "Rate limited after 2 retries",
+      );
+    });
+
+    test("throws LinearApiError after max retries exhausted (network error)", async () => {
+      const client = new LinearClient(config, { maxRetries: 2, baseDelay: 10 });
+      const operation = () => {
+        const error: any = new Error("Connection failed");
+        error.code = "ECONNREFUSED";
+        return Promise.reject(error);
+      };
+
+      await expect(client.execute(operation)).rejects.toThrow(LinearApiError);
+      await expect(client.execute(operation)).rejects.toThrow(
+        "Network error after 2 retries",
+      );
+    });
+
+    test("throws immediately on unauthorized error (401)", async () => {
+      const client = new LinearClient(config);
+      const operation = () => {
+        const error: any = new Error("Unauthorized");
+        error.status = 401;
+        return Promise.reject(error);
+      };
+
+      await expect(client.execute(operation)).rejects.toThrow(LinearApiError);
+      await expect(client.execute(operation)).rejects.toThrow(
+        "Unauthorized: Invalid API key",
+      );
+    });
+
+    test("throws immediately on other API errors", async () => {
+      const client = new LinearClient(config);
+      let callCount = 0;
+      const operation = () => {
+        callCount++;
+        const error: any = new Error("Bad request");
+        error.status = 400;
+        return Promise.reject(error);
+      };
+
+      await expect(client.execute(operation)).rejects.toThrow(LinearApiError);
+      expect(callCount).toBe(1); // No retries for non-retryable errors
+    });
+  });
+
+  describe("LinearApiError", () => {
+    test("creates error with all properties", () => {
+      const originalError = new Error("Original error");
+      const error = new LinearApiError(
+        "Test error message",
+        "TEST_CODE",
+        500,
+        originalError,
+      );
+
+      expect(error).toBeInstanceOf(Error);
+      expect(error.name).toBe("LinearApiError");
+      expect(error.message).toBe("Test error message");
+      expect(error.code).toBe("TEST_CODE");
+      expect(error.statusCode).toBe(500);
+      expect(error.originalError).toBe(originalError);
+    });
+
+    test("creates error without optional fields", () => {
+      const error = new LinearApiError("Test error", "TEST_CODE");
+
+      expect(error.message).toBe("Test error");
+      expect(error.code).toBe("TEST_CODE");
+      expect(error.statusCode).toBeUndefined();
+      expect(error.originalError).toBeUndefined();
+    });
+  });
+
+  describe("exponential backoff", () => {
+    test("applies exponential backoff with jitter", async () => {
+      const client = new LinearClient(config, {
+        maxRetries: 3,
+        baseDelay: 100,
+      });
+      const startTime = Date.now();
+      let attempts = 0;
+
+      const operation = () => {
+        attempts++;
+        if (attempts <= 3) {
+          const error: any = new Error("Rate limited");
+          error.status = 429;
+          return Promise.reject(error);
+        }
+        return Promise.resolve({ data: "success" });
+      };
+
+      const result = await client.execute(operation);
+
+      const elapsed = Date.now() - startTime;
+
+      // Expected delays: ~100ms, ~200ms, ~400ms (with jitter ±10%)
+      // Total: ~700ms minimum
+      expect(elapsed).toBeGreaterThanOrEqual(630); // 700ms - 10% jitter
+      expect(result).toEqual({ data: "success" });
+    });
+  });
+});