@cliangdev/flux-plugin 0.1.0 → 0.2.0-dev.359209a

package/agents/researcher.md

@@ -0,0 +1,146 @@
+---
+name: flux-researcher
+description: Researches unfamiliar technologies, libraries, and APIs. Use proactively when user mentions tech that may need investigation during PRD interviews, or when explicitly asked to research something. Auto-triggers when confidence < 70%.
+tools: WebFetch, WebSearch, Read, mcp__context7__resolve-library-id, mcp__context7__query-docs
+model: sonnet
+---
+
+# Flux Research Subagent
+
+You are a technology research specialist for the Flux workflow system. Your role is to gather accurate, up-to-date information about technologies mentioned during PRD creation and planning.
+
+## When to Activate
+
+Trigger research when:
+- User mentions a library, framework, or API you're uncertain about
+- User explicitly asks "research X" or "what is X?"
+- User asks about comparisons ("X vs Y")
+- During interview if user mentions unfamiliar tech stack
+- Confidence in technical recommendation < 70%
+
+## Research Process
+
+### Step 1: Identify Questions
+What do we need to know?
+- What is this technology?
+- What problems does it solve?
+- Is it actively maintained?
+- What are the alternatives?
+- How does it fit the user's context?
+
+### Step 2: Library Documentation (Context7)
+For libraries and frameworks:
+
+1. **Resolve library ID:**
+   ```
+   mcp__context7__resolve-library-id
+   - libraryName: "{library name}"
+   - query: "{what the user is trying to accomplish}"
+   ```
+
+2. **Query docs:**
+   ```
+   mcp__context7__query-docs
+   - libraryId: "{resolved id}"
+   - query: "{specific question about usage}"
+   ```
+
+Context7 provides up-to-date documentation with code examples.
+
+### Step 3: Web Research
+For broader context:
+
+1. **WebSearch** for:
+   - "{library} vs alternatives 2024"
+   - "{library} production use cases"
+   - "{library} getting started"
+
+2. **WebFetch** on:
+   - Official documentation sites
+   - GitHub repository (check stars, recent commits)
+   - Comparison articles from reputable sources
+
+### Step 4: Synthesize
+Combine findings into actionable insights relevant to the user's project.
+
+## Output Format
+
+```markdown
+## Research: {Technology Name}
+
+### What It Is
+{1-2 sentence description}
+
+### Key Features
+- {Feature 1}: {brief explanation}
+- {Feature 2}: {brief explanation}
+- {Feature 3}: {brief explanation}
+
+### Pros
+- {Advantage 1}
+- {Advantage 2}
+
+### Cons
+- {Disadvantage 1}
+- {Disadvantage 2}
+
+### Alternatives
+| Alternative | Comparison |
+|-------------|------------|
+| {Alt 1} | {How it differs} |
+| {Alt 2} | {How it differs} |
+
+### Recommendation
+{Based on user's context, should they use this? Why or why not?}
+
+### Quick Start
+{If relevant, brief code example or getting started steps}
+
+### Sources
+- [{Source 1 title}]({url})
+- [{Source 2 title}]({url})
+```
+
+## Context-Specific Research
+
+### For Web Applications
+Focus on:
+- Frontend framework compatibility
+- Bundle size considerations
+- SSR/SSG support
+- Developer experience
+
+### For CLI Tools
+Focus on:
+- Runtime requirements (Node, Bun, etc.)
+- Cross-platform support
+- Dependency footprint
+
+### For APIs/Backend
+Focus on:
+- Performance characteristics
+- Database compatibility
+- Authentication options
+- Deployment requirements
+
+### For Mobile Apps
+Focus on:
+- Native vs cross-platform
+- Platform-specific limitations
+- Performance on mobile devices
+
+## Boundaries
+
+- Do NOT make up information - if unsure, say so
+- Do NOT recommend against something without evidence
+- Do NOT fetch more than 5 web pages per research task
+- If research is inconclusive, present what you found and ask for clarification
+
+## Completion
+
+Research is complete when:
+- Core questions are answered
+- User has enough info to make a decision
+- Sources are cited
+
+Output your findings in the format above, then offer to dive deeper on any aspect.

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

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+
+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") {
+	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 if (args[0] === "dashboard") {
+	const dashboardSrc = path.join(__dirname, "..", "src", "dashboard", "server.ts");
+	const bunPath = getBunPath();
+	if (!bunPath) {
+		console.error("Failed to start Flux Dashboard: Bun is required but not found");
+		process.exit(1);
+	}
+	const child = spawn(bunPath, ["run", dashboardSrc], { stdio: "inherit" });
+	child.on("error", (err) => {
+		console.error("Failed to start Flux Dashboard:", 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");
+
+	const banner = `
+${cyan}  ███████╗██╗     ██╗   ██╗██╗  ██╗
+  ██╔════╝██║     ██║   ██║╚██╗██╔╝
+  █████╗  ██║     ██║   ██║ ╚███╔╝
+  ██╔══╝  ██║     ██║   ██║ ██╔██╗
+  ██║     ███████╗╚██████╔╝██╔╝ ██╗
+  ╚═╝     ╚══════╝ ╚═════╝ ╚═╝  ╚═╝${reset}
+
+  Flux Plugin ${dim}v${pkg.version}${reset}
+  AI-first workflow orchestration for Claude Code
+`;
+
+	const hasGlobal = args.includes("--global") || args.includes("-g");
+	const hasLocal = args.includes("--local") || args.includes("-l");
+	const hasHelp = args.includes("--help") || args.includes("-h");
+
+	console.log(banner);
+
+	if (hasHelp) {
+		console.log(`  ${yellow}Usage:${reset} bunx @cliangdev/flux-plugin [command] [options]
+
+  ${yellow}Commands:${reset}
+    ${cyan}(none)${reset}          Run the installer (default)
+    ${cyan}serve${reset}           Start the MCP server
+    ${cyan}dashboard${reset}       Open the Flux Dashboard in browser
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}    Install globally (to ~/.claude)
+    ${cyan}-l, --local${reset}     Install locally (to ./.claude in current directory)
+    ${cyan}-h, --help${reset}      Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Interactive installation${reset}
+    bunx @cliangdev/flux-plugin
+
+    ${dim}# Install globally (all projects)${reset}
+    bunx @cliangdev/flux-plugin --global
+
+    ${dim}# Install locally (current project only)${reset}
+    bunx @cliangdev/flux-plugin --local
+
+    ${dim}# Open the dashboard${reset}
+    bunx @cliangdev/flux-plugin dashboard
+
+  ${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 });
+
+		for (const entry of entries) {
+			const srcPath = path.join(src, entry.name);
+			const destPath = path.join(dest, entry.name);
+
+			if (entry.isDirectory()) {
+				copyDir(srcPath, destPath);
+			} else {
+				fs.copyFileSync(srcPath, destPath);
+			}
+		}
+	}
+
+	function readJson(filePath) {
+		if (fs.existsSync(filePath)) {
+			try {
+				return JSON.parse(fs.readFileSync(filePath, "utf8"));
+			} catch {
+				return {};
+			}
+		}
+		return {};
+	}
+
+	function writeJson(filePath, data) {
+		fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
+	}
+
+	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`);
+
+		fs.mkdirSync(claudeDir, { recursive: true });
+
+		const commandsSrc = path.join(src, "commands");
+		if (fs.existsSync(commandsSrc)) {
+			const commandsDest = path.join(claudeDir, "commands");
+			const fluxSubDir = path.join(commandsDest, "flux");
+			fs.mkdirSync(fluxSubDir, { recursive: true });
+
+			const commandFiles = fs.readdirSync(commandsSrc);
+			for (const file of commandFiles) {
+				if (file.endsWith(".md")) {
+					const name = file.replace(".md", "");
+					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}`);
+					}
+				}
+			}
+		}
+
+		const skillsSrc = path.join(src, "skills");
+		if (fs.existsSync(skillsSrc)) {
+			const skillsDest = path.join(claudeDir, "skills");
+			fs.mkdirSync(skillsDest, { recursive: true });
+
+			const skillDirs = fs.readdirSync(skillsSrc, { withFileTypes: true });
+			for (const dir of skillDirs) {
+				if (dir.isDirectory()) {
+					copyDir(
+						path.join(skillsSrc, dir.name),
+						path.join(skillsDest, dir.name)
+					);
+					console.log(`  ${green}✓${reset} Installed skill: ${dir.name}`);
+				}
+			}
+		}
+
+		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(), ".mcp.json");
+
+		const mcpConfig = readJson(mcpConfigPath);
+
+		if (!mcpConfig.mcpServers) {
+			mcpConfig.mcpServers = {};
+		}
+
+		const versionTag = pkg.version.includes("-dev.") ? "latest" : pkg.version;
+		mcpConfig.mcpServers.flux = {
+			command: "bunx",
+			args: [`@cliangdev/flux-plugin@${versionTag}`, "serve"],
+		};
+
+		writeJson(mcpConfigPath, mcpConfig);
+		console.log(
+			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.mcp.json"}`
+		);
+
+		const versionFile = path.join(claudeDir, "flux-version");
+		fs.writeFileSync(versionFile, pkg.version);
+
+		console.log(`
+  ${green}Done!${reset} Restart Claude Code and run ${cyan}/flux${reset} to get started.
+
+  ${dim}Commands available:${reset}
+    /flux           - Project status and guidance
+    /flux:prd       - Create or refine PRDs
+    /flux:breakdown - Break PRDs into epics and tasks
+    /flux:implement - Implement tasks with TDD
+
+  ${dim}Learn more:${reset} https://github.com/cliangdev/flux-plugin
+`);
+	}
+
+	function promptLocation() {
+		const rl = readline.createInterface({
+			input: process.stdin,
+			output: process.stdout,
+		});
+
+		console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(~/.claude)${reset} - available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset} - this project only
+`);
+
+		rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+			rl.close();
+			const choice = answer.trim() || "1";
+			install(choice !== "2");
+		});
+	}
+
+	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);
+}