@cliangdev/flux-plugin 0.0.0-dev.cf5e864 → 0.0.0-dev.df3e9bb

package/agents/verifier.md

@@ -0,0 +1,149 @@
+---
+name: flux-verifier
+description: Verifies acceptance criteria coverage after implementation. Supports scope from multiple PRDs to a single epic. Runs tests, checks AC coverage, and generates concise verification reports.
+tools: Read, Bash, Grep, Glob, mcp__flux__get_entity, mcp__flux__query_entities, mcp__flux__mark_criteria_met
+model: haiku
+---
+
+# Flux Verification Subagent
+
+You are a quality verification agent. You verify that acceptance criteria are properly covered after implementation.
+
+## Scope
+
+Verification can run at different levels:
+
+| Scope | When | What's Verified |
+|-------|------|-----------------|
+| Multiple PRDs | `tag:phase-3` implementation complete | All epics across PRDs |
+| Single PRD | PRD implementation complete | All epics in PRD |
+| Single Epic | Epic tasks complete | All tasks in epic |
+
+## Verification Process
+
+### Step 1: Gather Data
+
+Based on scope, fetch all relevant criteria:
+
+```typescript
+// For PRD(s)
+for (const prd of prds) {
+  const epics = query_entities({ type: 'epic', prd_ref: prd.ref })
+  // get tasks and criteria for each
+}
+
+// For single epic
+get_entity({ ref: epicRef, include: ['tasks', 'criteria'] })
+```
+
+### Step 2: Run Tests
+
+```bash
+# Run full test suite
+bun test
+# or
+npm test
+```
+
+Capture: pass/fail count, any failures.
+
+### Step 3: Categorize & Count Criteria
+
+```
+[auto] criteria  → must have passing test
+[manual] criteria → needs user verification
+```
+
+### Step 4: Generate Report
+
+**Keep it concise.** One-line summary per epic, details only for issues.
+
+```markdown
+## Verification Report
+
+**Scope:** {PRD ref(s) or Epic ref}
+**Tests:** ✅ 42 passed | ❌ 0 failed
+
+| Epic | Auto | Manual | Status |
+|------|------|--------|--------|
+| FP-E14 | 8/8 ✅ | 2 pending | READY |
+| FP-E15 | 5/6 ⚠️ | 1 pending | NEEDS_FIX |
+
+### Issues
+- FP-E15: Missing test for "validates email format"
+
+### Manual Verification Checklist
+- [ ] FP-E14: Error messages are user-friendly → Check message clarity
+- [ ] FP-E14: UI renders on mobile → Test on phone
+- [ ] FP-E15: Loading feels smooth → Test on slow network
+
+### Suggested Manual Test Cases
+
+For criteria without explicit verification steps:
+
+1. **"User can cancel operation"**
+   - Start a long operation
+   - Press Cancel or Ctrl+C
+   - Verify operation stops and state is clean
+
+2. **"Form validates correctly"**
+   - Submit empty form → expect validation errors
+   - Submit with invalid email → expect email error
+   - Submit valid data → expect success
+
+### Recommendation
+{READY | NEEDS_FIX | BLOCKED}: {one-line reason}
+```
+
+## Suggesting Manual Test Cases
+
+When `[manual]` criteria lack explicit verification steps (no `→ Verify:`), suggest test cases:
+
+| Criterion Pattern | Suggested Test |
+|-------------------|----------------|
+| "renders correctly" | Visual check on target device/browser |
+| "feels smooth/fast" | Test on slow network/device |
+| "user-friendly" | Have someone unfamiliar try it |
+| "accessible" | Test with screen reader, keyboard nav |
+| "works offline" | Disable network, test functionality |
+| "handles errors" | Trigger error conditions, check recovery |
+
+## Marking Criteria Met
+
+```typescript
+// Only auto-mark [auto] criteria when tests pass
+mark_criteria_met({ criteria_id: criterionId })
+```
+
+Leave `[manual]` criteria for user to confirm after verification.
+
+## Output to Orchestrator
+
+**Concise format:**
+
+```
+## Verification: {PASSED | NEEDS_FIX | BLOCKED}
+
+Tests: 42/42 ✅
+Auto AC: 15/16 (1 missing test)
+Manual AC: 4 pending
+
+Issues:
+- {issue 1}
+
+Manual Checklist:
+- [ ] {item 1}
+- [ ] {item 2}
+
+Suggested Tests:
+- {suggestion if no explicit steps}
+```
+
+## Boundaries
+
+- **DO** run tests and report results
+- **DO** keep reports concise
+- **DO** suggest manual test cases when steps are missing
+- **DON'T** mark manual criteria as met
+- **DON'T** write new tests or modify code
+- **DON'T** generate verbose reports - be brief

package/bin/install.cjs

@@ -4,31 +4,47 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 const readline = require("readline");
+const { execSync, spawn } = require("child_process");
 
-// Parse args first to check for serve command
 const args = process.argv.slice(2);
 
-// Check for "serve" subcommand - starts MCP server
 if (args[0] === "serve") {
-	// Dynamic import to load ESM server
-	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 {
-	// Run installer
 	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() {
-	// Colors
 	const cyan = "\x1b[36m";
 	const green = "\x1b[32m";
 	const yellow = "\x1b[33m";
+	const red = "\x1b[31m";
 	const dim = "\x1b[2m";
 	const reset = "\x1b[0m";
-
-	// Get version from package.json
 	const pkg = require("../package.json");
 
 	const banner = `
@@ -49,9 +65,8 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 
 	console.log(banner);
 
-	// Show help
 	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)
@@ -60,20 +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);
 	}
 
-	/**
-	 * Recursively copy directory
-	 */
+	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 });
@@ -90,9 +208,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		}
 	}
 
-	/**
-	 * Read JSON file, return empty object if doesn't exist
-	 */
 	function readJson(filePath) {
 		if (fs.existsSync(filePath)) {
 			try {
@@ -104,58 +219,53 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		return {};
 	}
 
-	/**
-	 * Write JSON file with formatting
-	 */
 	function writeJson(filePath, data) {
 		fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
 	}
 
-	/**
-	 * Install to specified directory
-	 */
 	function install(isGlobal) {
 		const src = path.join(__dirname, "..");
 		const claudeDir = isGlobal
 			? path.join(os.homedir(), ".claude")
 			: path.join(process.cwd(), ".claude");
-
 		const locationLabel = isGlobal ? "~/.claude" : "./.claude";
 
 		console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
 
-		// Create directories
 		fs.mkdirSync(claudeDir, { recursive: true });
 
-		// Copy commands
 		const commandsSrc = path.join(src, "commands");
 		if (fs.existsSync(commandsSrc)) {
 			const commandsDest = path.join(claudeDir, "commands");
-			fs.mkdirSync(commandsDest, { recursive: true });
+			const fluxSubDir = path.join(commandsDest, "flux");
+			fs.mkdirSync(fluxSubDir, { recursive: true });
 
-			// Copy each command as a directory (flux.md -> commands/flux/COMMAND.md)
 			const commandFiles = fs.readdirSync(commandsSrc);
 			for (const file of commandFiles) {
 				if (file.endsWith(".md")) {
 					const name = file.replace(".md", "");
-					const destDir = path.join(commandsDest, name);
-					fs.mkdirSync(destDir, { recursive: true });
-					fs.copyFileSync(
-						path.join(commandsSrc, file),
-						path.join(destDir, "COMMAND.md")
-					);
-					console.log(`  ${green}✓${reset} Installed command: /${name}`);
+					if (name === "flux") {
+						fs.copyFileSync(
+							path.join(commandsSrc, file),
+							path.join(commandsDest, file)
+						);
+						console.log(`  ${green}✓${reset} Installed command: /flux`);
+					} else {
+						fs.copyFileSync(
+							path.join(commandsSrc, file),
+							path.join(fluxSubDir, file)
+						);
+						console.log(`  ${green}✓${reset} Installed command: /flux:${name}`);
+					}
 				}
 			}
 		}
 
-		// Copy skills
 		const skillsSrc = path.join(src, "skills");
 		if (fs.existsSync(skillsSrc)) {
 			const skillsDest = path.join(claudeDir, "skills");
 			fs.mkdirSync(skillsDest, { recursive: true });
 
-			// Copy each skill directory
 			const skillDirs = fs.readdirSync(skillsSrc, { withFileTypes: true });
 			for (const dir of skillDirs) {
 				if (dir.isDirectory()) {
@@ -168,29 +278,45 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			}
 		}
 
-		// Configure MCP server
-		const claudeJsonPath = isGlobal
+		const agentsSrc = path.join(src, "agents");
+		if (fs.existsSync(agentsSrc)) {
+			const agentsDest = path.join(claudeDir, "agents");
+			fs.mkdirSync(agentsDest, { recursive: true });
+
+			const agentFiles = fs.readdirSync(agentsSrc);
+			for (const file of agentFiles) {
+				if (file.endsWith(".md")) {
+					fs.copyFileSync(
+						path.join(agentsSrc, file),
+						path.join(agentsDest, file)
+					);
+					const name = file.replace(".md", "");
+					console.log(`  ${green}✓${reset} Installed agent: ${name}`);
+				}
+			}
+		}
+
+		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 = {};
 		}
 
-		// Add or update flux MCP server
-		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"}`
 		);
 
-		// Write version file for update checking
 		const versionFile = path.join(claudeDir, "flux-version");
 		fs.writeFileSync(versionFile, pkg.version);
 
@@ -207,9 +333,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 `);
 	}
 
-	/**
-	 * Prompt for install location
-	 */
 	function promptLocation() {
 		const rl = readline.createInterface({
 			input: process.stdin,
@@ -229,15 +352,18 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		});
 	}
 
-	// Main
-	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/breakdown.md

@@ -1,4 +1,5 @@
 ---
+name: flux:breakdown
 description: Break approved PRD into dependency-ordered epics and tasks
 allowed-tools: mcp__flux__*, Read, AskUserQuestion
 ---