@cliangdev/flux-plugin 0.2.0 → 0.3.0

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
@@ -32,7 +36,7 @@ The installer automatically:
 | Command | Purpose |
 |---------|---------|
 | `/flux` | Smart entry point - shows status and guides you to the next step |
-| `/flux:prd` | Create product requirements through guided interview |
+| `/flux:prd` | Create PRDs through discovery, research, and guided writing |
 | `/flux:breakdown` | Break PRDs into epics and tasks with acceptance criteria |
 | `/flux:implement` | Implement tasks with TDD workflow |
 
@@ -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:
@@ -139,7 +143,7 @@ Check your current version:
 
 ```bash
 rm -rf ~/.claude/commands/flux.md ~/.claude/commands/flux
-rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-template
+rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-writer
 rm -f ~/.claude/flux-version
 # Edit ~/.claude.json and remove the "flux" entry from "mcpServers"
 ```
@@ -148,7 +152,7 @@ rm -f ~/.claude/flux-version
 
 ```bash
 rm -rf .claude/commands/flux.md .claude/commands/flux
-rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-template
+rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-writer
 rm -f .claude/flux-version
 # Edit .claude.json and remove the "flux" entry from "mcpServers"
 ```

package/agents/coder.md

@@ -20,30 +20,41 @@ You receive only:
 
 This keeps your context clean for high-quality code output.
 
-## Step 1: Detect Project Type & Apply Skill
+## Step 1: Apply Project Skill
 
-Before coding, detect the project type and apply the matching skill:
+The orchestrator should provide a **Project Skill** section in your prompt with patterns to follow. If provided, strictly follow those patterns for:
+- Code structure and organization
+- Error handling conventions
+- Testing patterns
+- Naming conventions
+
+### Fallback: Discover Skill Yourself
+
+If no skill was provided in your prompt, discover and load it:
 
 ```bash
-# Check for project indicators
+# 1. Detect project type
 ls -la | head -20
+
+# 2. Check for matching skill in .claude/skills/
+ls .claude/skills/ 2>/dev/null
 ```
 
-| File Found | Project Type | Skill to Apply |
-|------------|--------------|----------------|
-| `pom.xml` | Java/Spring Boot | `springboot-patterns` |
-| `build.gradle` | Java/Gradle | `springboot-patterns` |
-| `tsconfig.json` | TypeScript | `typescript-patterns` |
-| `package.json` + `react` | React | `ui-patterns` |
-| `go.mod` | Go | Go idioms |
-| `Cargo.toml` | Rust | Rust idioms |
-| `requirements.txt` / `pyproject.toml` | Python | Python idioms |
+| File Found | Project Type | Skill Search Pattern |
+|------------|--------------|---------------------|
+| `go.mod` | Go | `golang*`, `go-*` |
+| `tsconfig.json` | TypeScript | `typescript*`, `ts-*` |
+| `pom.xml` / `build.gradle` | Java/Spring | `java*`, `spring*` |
+| `package.json` + react | React | `react*`, `ui-*` |
+| `Cargo.toml` | Rust | `rust*` |
+| `requirements.txt` | Python | `python*`, `py-*` |
 
-**Apply the skill mentally** - follow its patterns for:
-- Code structure and organization
-- Error handling conventions
-- Testing patterns
-- Naming conventions
+```bash
+# 3. Read matching skill
+cat .claude/skills/{matched-skill}/SKILL.md
+```
+
+**Apply the loaded skill patterns** - if no matching skill exists, use general best practices for that language.
 
 ## Step 2: Understand the Task
 
@@ -61,10 +72,11 @@ Acceptance Criteria:
 
 ## Step 3: Write Tests First (TDD)
 
+### 3.1 Tests for Acceptance Criteria
+
 For each `[auto]` criterion, write a failing test:
 
 ```typescript
-// Example for TypeScript
 describe('Login API', () => {
   it('returns 401 for invalid credentials', async () => {
     const response = await api.post('/login', {
@@ -82,6 +94,34 @@ describe('Login API', () => {
 });
 ```
 
+### 3.2 Tests for Critical Components
+
+Beyond acceptance criteria, also test:
+
+- **Core business logic**: Functions that make important decisions
+- **Data transformations**: Parsing, validation, mapping functions
+- **Error paths**: Edge cases and failure scenarios
+- **Integration points**: API handlers, database operations
+- **Utilities used in multiple places**: Shared helpers and utils
+
+```typescript
+describe('SessionManager', () => {
+  it('expires sessions after TTL', async () => {
+    const session = await sessionManager.create(userId);
+    await advanceTime(SESSION_TTL + 1000);
+    expect(await sessionManager.isValid(session.id)).toBe(false);
+  });
+
+  it('handles concurrent session creation', async () => {
+    const results = await Promise.all([
+      sessionManager.create(userId),
+      sessionManager.create(userId),
+    ]);
+    expect(results[0].id).not.toBe(results[1].id);
+  });
+});
+```
+
 Run tests to confirm they fail:
 ```bash
 bun test login.test.ts
@@ -103,6 +143,81 @@ Write minimal code to make tests pass:
 bun test
 ```
 
+## Code Quality Standards
+
+### Write Clean, Modular, Testable Code
+
+**Modularity**
+- Small, focused functions that do one thing well
+- Clear separation of concerns (business logic vs I/O vs presentation)
+- Dependencies injected, not hardcoded - makes testing easy
+- Extract reusable logic into well-named helper functions
+
+```typescript
+// ✅ Good: Modular, testable
+function validateCredentials(email: string, password: string): ValidationResult {
+  if (!isValidEmail(email)) return { valid: false, error: 'Invalid email' };
+  if (password.length < 8) return { valid: false, error: 'Password too short' };
+  return { valid: true };
+}
+
+async function login(credentials: Credentials, userRepo: UserRepository) {
+  const validation = validateCredentials(credentials.email, credentials.password);
+  if (!validation.valid) throw new ValidationError(validation.error);
+  return userRepo.findByEmail(credentials.email);
+}
+
+// ❌ Bad: Monolithic, hard to test
+async function login(email: string, password: string) {
+  // validation mixed with business logic mixed with database calls
+  const db = getDatabase();
+  if (!email.includes('@')) throw new Error('bad email');
+  const user = await db.query('SELECT * FROM users WHERE email = ?', [email]);
+  // ... more mixed concerns
+}
+```
+
+**Testability**
+- Pure functions where possible (same input → same output)
+- Side effects isolated and explicit
+- Avoid global state
+- Use interfaces/types for dependencies
+
+### No Unnecessary Comments
+
+Let code be self-documenting. Comments should explain **why**, not **what**.
+
+```typescript
+// ❌ Bad: Comments that restate the code
+// Check if user is admin
+if (user.role === 'admin') {
+  // Grant admin access
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Code explains itself
+if (user.role === 'admin') {
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Comment explains non-obvious "why"
+// Rate limit bypass for internal services to prevent cascade failures
+if (request.source === 'internal') {
+  skipRateLimit = true;
+}
+```
+
+**When to comment:**
+- Non-obvious business rules or edge cases
+- Workarounds for external bugs/limitations
+- Performance optimizations that sacrifice readability
+- Public API documentation (JSDoc for library interfaces)
+
+**Never comment:**
+- What the code does (let naming convey this)
+- Obvious operations
+- Commented-out code (delete it, git has history)
+
 ## Step 5: Handle Manual Criteria
 
 For `[manual]` criteria, add a comment or doc noting verification steps:
@@ -174,13 +289,23 @@ Needs:
 
 ## Boundaries
 
-- **DO** focus only on the assigned task
-- **DO** write tests before implementation
-- **DO** follow detected skill patterns
-- **DON'T** refactor unrelated code
-- **DON'T** add features not in acceptance criteria
-- **DON'T** skip tests for `[auto]` criteria
-- **DON'T** make commits without running tests
+**DO:**
+- Focus only on the assigned task
+- Apply project skill patterns from your prompt (or discover them from `.claude/skills/`)
+- Write tests before implementation
+- Test critical components beyond just acceptance criteria
+- Write clean, modular, testable code
+- Use clear naming that makes code self-documenting
+
+**DON'T:**
+- Ignore provided skill patterns - they contain project-specific conventions
+- Refactor unrelated code
+- Add features not in acceptance criteria
+- Skip tests for `[auto]` criteria
+- Make commits without running tests
+- Add comments that restate what code does
+- Add unnecessary JSDoc/docstrings for simple functions
+- Leave commented-out code
 
 ## Context Escalation
 

package/bin/install.cjs

@@ -4,22 +4,58 @@ 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 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");
@@ -43,7 +79,12 @@ ${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 [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)
@@ -52,17 +93,126 @@ ${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
+
+    ${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 });
@@ -177,9 +327,10 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			mcpConfig.mcpServers = {};
 		}
 
+		const versionTag = pkg.version.includes("-dev.") ? "latest" : pkg.version;
 		mcpConfig.mcpServers.flux = {
-			command: "npx",
-			args: ["-y", `@cliangdev/flux-plugin@${pkg.version}`, "serve"],
+			command: "bunx",
+			args: [`@cliangdev/flux-plugin@${versionTag}`, "serve"],
 		};
 
 		writeJson(mcpConfigPath, mcpConfig);
@@ -222,14 +373,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/breakdown.md

@@ -16,12 +16,26 @@ Check if arguments were provided:
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
-2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+2. If query successful but no approved PRDs found:
    - If no approved PRDs, tell user: "No approved PRDs found. Approve a PRD first or run `/flux:prd` to create one."
-   - If multiple approved PRDs, use AskUserQuestion to let user select which one
+   - If multiple approved PRDs, use AskUserQuestion to let user select:
+     ```json
+     {
+       "questions": [{
+         "question": "Which PRD would you like to break down?",
+         "header": "Select PRD",
+         "options": [
+           {"label": "{PRD-1 title}", "description": "{ref} - {brief description}"},
+           {"label": "{PRD-2 title}", "description": "{ref} - {brief description}"}
+         ],
+         "multiSelect": false
+       }]
+     }
+     ```
+     Note: Dynamically populate options from the query results.
 
 3. If ref provided, call `get_entity` with the ref
    - Verify status is APPROVED
@@ -78,9 +92,21 @@ Which approach do you prefer?
 
 1. Get PRD entity with `get_entity` including `include: ['epics']`
 2. Read full PRD content from `folder_path + '/prd.md'` using Read tool
-3. If PRD already has epics, inform user:
-   - "This PRD already has {count} epics. Continue adding more or start fresh?"
-   - Use AskUserQuestion with options: "Add more epics", "View existing", "Start fresh (delete existing)"
+3. If PRD already has epics, inform user and use AskUserQuestion:
+   ```json
+   {
+     "questions": [{
+       "question": "This PRD already has {count} epics. What would you like to do?",
+       "header": "Epics",
+       "options": [
+         {"label": "Add more epics", "description": "Keep existing epics and add new ones"},
+         {"label": "View existing", "description": "See current epic structure before deciding"},
+         {"label": "Start fresh", "description": "Delete existing epics and recreate from scratch"}
+       ],
+       "multiSelect": false
+     }]
+   }
+   ```
 
 ### Step 2: Analyze & Identify Epics
 
@@ -142,9 +168,20 @@ Ready to create these epics?
 ```
 
 Use AskUserQuestion only when uncertain:
-- Create all epics (Recommended)
-- Modify structure first
-- Add/remove epics
+```json
+{
+  "questions": [{
+    "question": "Ready to create these epics?",
+    "header": "Confirm",
+    "options": [
+      {"label": "Create all epics (Recommended)", "description": "Proceed with the proposed structure"},
+      {"label": "Modify structure first", "description": "Adjust epic boundaries or dependencies"},
+      {"label": "Add/remove epics", "description": "Change the number of epics"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
 ### Step 4: Create Epics
 

package/commands/dashboard.md

@@ -0,0 +1,29 @@
+---
+name: flux:dashboard
+description: Open the Flux Dashboard to visualize PRDs, epics, and tasks
+allowed-tools: Bash
+---
+
+# Flux Dashboard
+
+Launch the Flux Dashboard web interface to visualize project status.
+
+## Instructions
+
+Run the dashboard server:
+
+```bash
+bunx @cliangdev/flux-plugin dashboard
+```
+
+This will:
+1. Start the dashboard server on port 3333 (or next available)
+2. Open the dashboard in the default browser
+
+The dashboard shows:
+- All PRDs with their epics and tasks
+- Status indicators and progress
+- Dependency graph visualization
+- Detailed views for each entity
+
+Tell the user the dashboard is starting and they can close it with Ctrl+C when done.