@cliangdev/flux-plugin 0.0.0-dev.df9c61f → 0.1.0-dev.588ae42

package/README.md

@@ -2,10 +2,14 @@
 
 Agent-orchestrated, spec-driven workflow for Claude Code.
 
+## Prerequisites
+
+This plugin requires [Bun](https://bun.sh). If you don't have Bun installed, the installer will offer to install it for you.
+
 ## Installation
 
 ```bash
-npx @cliangdev/flux-plugin
+bunx @cliangdev/flux-plugin
 ```
 
 This installs:
@@ -16,8 +20,8 @@ This installs:
 ### Options
 
 ```bash
-npx @cliangdev/flux-plugin --global   # Install to ~/.claude (all projects)
-npx @cliangdev/flux-plugin --local    # Install to ./.claude (current project)
+bunx @cliangdev/flux-plugin --global   # Install to ~/.claude (all projects)
+bunx @cliangdev/flux-plugin --local    # Install to ./.claude (current project)
 ```
 
 ### What Gets Configured
@@ -121,7 +125,7 @@ your-project/
 To update to the latest version, simply re-run the installer:
 
 ```bash
-npx @cliangdev/flux-plugin@latest --global
+bunx @cliangdev/flux-plugin@latest --global
 ```
 
 This will:

package/bin/install.cjs

@@ -4,22 +4,45 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const readline = require("readline");
+const { execSync, spawn } = require("child_process");
 
 const args = process.argv.slice(2);
 
 if (args[0] === "serve") {
-	import("../dist/server/index.js").catch((err) => {
+	const serverSrc = path.join(__dirname, "..", "src", "server", "index.ts");
+	const bunPath = getBunPath();
+	if (!bunPath) {
+		console.error("Failed to start Flux MCP server: Bun is required but not found");
+		process.exit(1);
+	}
+	const child = spawn(bunPath, ["run", serverSrc], { stdio: "inherit" });
+	child.on("error", (err) => {
 		console.error("Failed to start Flux MCP server:", err.message);
 		process.exit(1);
 	});
+	child.on("close", (code) => process.exit(code || 0));
 } else {
 	runInstaller();
 }
 
+function getBunPath() {
+	const bunDir = path.join(os.homedir(), ".bun", "bin");
+	const bunBinary = process.platform === "win32" ? "bun.exe" : "bun";
+	const localBunPath = path.join(bunDir, bunBinary);
+	if (fs.existsSync(localBunPath)) return localBunPath;
+	try {
+		execSync("bun --version", { stdio: "ignore" });
+		return "bun";
+	} catch {
+		return null;
+	}
+}
+
 function runInstaller() {
 	const cyan = "\x1b[36m";
 	const green = "\x1b[32m";
 	const yellow = "\x1b[33m";
+	const red = "\x1b[31m";
 	const dim = "\x1b[2m";
 	const reset = "\x1b[0m";
 	const pkg = require("../package.json");
@@ -43,7 +66,7 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 	console.log(banner);
 
 	if (hasHelp) {
-		console.log(`  ${yellow}Usage:${reset} npx @cliangdev/flux-plugin [options]
+		console.log(`  ${yellow}Usage:${reset} bunx @cliangdev/flux-plugin [options]
 
   ${yellow}Options:${reset}
     ${cyan}-g, --global${reset}    Install globally (to ~/.claude)
@@ -52,17 +75,123 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 
   ${yellow}Examples:${reset}
     ${dim}# Interactive installation${reset}
-    npx @cliangdev/flux-plugin
+    bunx @cliangdev/flux-plugin
 
     ${dim}# Install globally (all projects)${reset}
-    npx @cliangdev/flux-plugin --global
+    bunx @cliangdev/flux-plugin --global
 
     ${dim}# Install locally (current project only)${reset}
-    npx @cliangdev/flux-plugin --local
+    bunx @cliangdev/flux-plugin --local
+
+  ${yellow}Note:${reset} This plugin requires Bun. Install from https://bun.sh
 `);
 		process.exit(0);
 	}
 
+	function isBunInstalled() {
+		const bunDir = path.join(os.homedir(), ".bun", "bin");
+		const envPath = process.env.PATH || "";
+		const pathWithBun = envPath.includes(bunDir)
+			? envPath
+			: `${bunDir}${path.delimiter}${envPath}`;
+
+		try {
+			execSync("bun --version", {
+				stdio: "ignore",
+				env: { ...process.env, PATH: pathWithBun },
+			});
+			return true;
+		} catch {
+			return false;
+		}
+	}
+
+	function installBun() {
+		return new Promise((resolve, reject) => {
+			const platform = os.platform();
+			const installCmd = platform === "win32" ? "powershell" : "/bin/sh";
+			const installArgs = platform === "win32"
+				? ["-c", "irm bun.sh/install.ps1 | iex"]
+				: ["-c", "curl -fsSL https://bun.sh/install | bash"];
+
+			console.log(`\n  ${cyan}Installing Bun...${reset}\n`);
+
+			const child = spawn(installCmd, installArgs, {
+				stdio: "inherit",
+				shell: false,
+			});
+
+			child.on("close", (code) => {
+				if (code === 0) {
+					console.log(`\n  ${green}✓${reset} Bun installed successfully\n`);
+					resolve(true);
+				} else {
+					reject(new Error(`Installation exited with code ${code}`));
+				}
+			});
+
+			child.on("error", (err) => {
+				reject(err);
+			});
+		});
+	}
+
+	function showBunInstallInstructions() {
+		console.log(`
+  ${yellow}Bun is required but not installed.${reset}
+
+  Install Bun manually:
+
+  ${cyan}macOS/Linux:${reset}
+    curl -fsSL https://bun.sh/install | bash
+
+  ${cyan}Windows:${reset}
+    powershell -c "irm bun.sh/install.ps1 | iex"
+
+  Then restart your terminal and run this installer again.
+
+  ${dim}Learn more: https://bun.sh${reset}
+`);
+	}
+
+	async function checkBunAndContinue(callback) {
+		if (isBunInstalled()) {
+			callback();
+			return;
+		}
+
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+
+		console.log(`  ${yellow}Bun is required but not installed.${reset}\n`);
+
+		rl.question(`  Install Bun now? ${dim}[Y/n]${reset}: `, async (answer) => {
+			rl.close();
+			const shouldInstall = answer.trim().toLowerCase() !== "n";
+
+			if (shouldInstall) {
+				try {
+					await installBun();
+					if (isBunInstalled()) {
+						callback();
+					} else {
+						console.log(`  ${yellow}Please restart your terminal to use Bun, then run the installer again.${reset}\n`);
+						process.exit(0);
+					}
+				} catch (err) {
+					console.log(`\n  ${red}Failed to install Bun:${reset} ${err.message}\n`);
+					showBunInstallInstructions();
+					process.exit(1);
+				}
+			} else {
+				showBunInstallInstructions();
+				process.exit(1);
+			}
+		});
+	}
+
 	function copyDir(src, dest) {
 		fs.mkdirSync(dest, { recursive: true });
 		const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -167,24 +296,25 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			}
 		}
 
-		const claudeJsonPath = isGlobal
+		const mcpConfigPath = isGlobal
 			? path.join(os.homedir(), ".claude.json")
-			: path.join(process.cwd(), ".claude.json");
+			: path.join(process.cwd(), ".mcp.json");
 
-		const claudeJson = readJson(claudeJsonPath);
+		const mcpConfig = readJson(mcpConfigPath);
 
-		if (!claudeJson.mcpServers) {
-			claudeJson.mcpServers = {};
+		if (!mcpConfig.mcpServers) {
+			mcpConfig.mcpServers = {};
 		}
 
-		claudeJson.mcpServers.flux = {
-			command: "npx",
-			args: ["-y", "@cliangdev/flux-plugin", "serve"],
+		const versionTag = pkg.version.includes("-dev.") ? "latest" : pkg.version;
+		mcpConfig.mcpServers.flux = {
+			command: "bunx",
+			args: [`@cliangdev/flux-plugin@${versionTag}`, "serve"],
 		};
 
-		writeJson(claudeJsonPath, claudeJson);
+		writeJson(mcpConfigPath, mcpConfig);
 		console.log(
-			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.claude.json"}`
+			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.mcp.json"}`
 		);
 
 		const versionFile = path.join(claudeDir, "flux-version");
@@ -222,14 +352,18 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		});
 	}
 
-	if (hasGlobal && hasLocal) {
-		console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
-		process.exit(1);
-	} else if (hasGlobal) {
-		install(true);
-	} else if (hasLocal) {
-		install(false);
-	} else {
-		promptLocation();
+	function startInstallation() {
+		if (hasGlobal && hasLocal) {
+			console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+			process.exit(1);
+		} else if (hasGlobal) {
+			install(true);
+		} else if (hasLocal) {
+			install(false);
+		} else {
+			promptLocation();
+		}
 	}
+
+	checkBunAndContinue(startInstallation);
 }

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