@cliangdev/flux-plugin 0.0.0-dev.0da1574

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,235 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("readline");
+
+const args = process.argv.slice(2);
+
+if (args[0] === "serve") {
+	import("../dist/server/index.js").catch((err) => {
+		console.error("Failed to start Flux MCP server:", err.message);
+		process.exit(1);
+	});
+} else {
+	runInstaller();
+}
+
+function runInstaller() {
+	const cyan = "\x1b[36m";
+	const green = "\x1b[32m";
+	const yellow = "\x1b[33m";
+	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} npx @cliangdev/flux-plugin [options]
+
+  ${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}
+    npx @cliangdev/flux-plugin
+
+    ${dim}# Install globally (all projects)${reset}
+    npx @cliangdev/flux-plugin --global
+
+    ${dim}# Install locally (current project only)${reset}
+    npx @cliangdev/flux-plugin --local
+`);
+		process.exit(0);
+	}
+
+	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 = {};
+		}
+
+		mcpConfig.mcpServers.flux = {
+			command: "npx",
+			args: ["-y", `@cliangdev/flux-plugin@${pkg.version}`, "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");
+		});
+	}
+
+	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();
+	}
+}

package/commands/breakdown.md

@@ -0,0 +1,263 @@
+---
+name: flux:breakdown
+description: Break approved PRD into dependency-ordered epics and tasks
+allowed-tools: mcp__flux__*, Read, AskUserQuestion
+---
+
+# PRD Breakdown
+
+You are the Flux breakdown orchestrator. Your job is to break an approved PRD into well-structured, dependency-ordered epics and tasks.
+
+## Mode Detection
+
+Check if arguments were provided:
+- `/flux:breakdown` - Select from approved PRDs
+- `/flux:breakdown {ref}` - Break down specific PRD (e.g., `FLUX-P1`)
+
+## Pre-checks
+
+1. Call `get_project_context` to ensure Flux is initialized
+   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+
+2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - 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
+
+3. If ref provided, call `get_entity` with the ref
+   - Verify status is APPROVED
+   - If not approved: "PRD {ref} is in {status} status. Only APPROVED PRDs can be broken down."
+
+## Confidence-Based Autonomy
+
+Use confidence levels to determine when to proceed autonomously vs. ask for confirmation:
+
+| Confidence | Behavior | When |
+|------------|----------|------|
+| **High (>80%)** | Auto-proceed, inform user | Clear PRD, obvious epic structure, standard patterns |
+| **Medium (50-80%)** | Show plan, ask to confirm | Some ambiguity, multiple valid approaches |
+| **Low (<50%)** | Ask clarifying questions | Unclear requirements, unfamiliar domain, contradictions |
+
+**High confidence indicators:**
+- PRD has clear feature list with priorities
+- Dependencies are explicit or obvious
+- Standard tech stack with known patterns
+- No conflicting requirements
+
+**Low confidence indicators:**
+- Vague or incomplete PRD sections
+- Multiple valid ways to structure epics
+- Unfamiliar technology or domain
+- Conflicting or ambiguous requirements
+
+**When confident, proceed like this:**
+```
+Analyzing PRD [FP-P3]...
+
+Creating 4 epics in dependency order:
+- FP-E1: Core Infrastructure (foundation)
+- FP-E2: Data Layer (depends on E1)
+- FP-E3: API Layer (depends on E2)
+- FP-E4: UI Components (depends on E3)
+
+[Proceeds to create epics and tasks...]
+```
+
+**When uncertain, ask for clarification:**
+```
+I see two ways to structure the auth feature:
+
+1. Single "Authentication" epic with login, logout, session tasks
+2. Separate "Login Flow" and "Session Management" epics
+
+Which approach do you prefer?
+```
+
+## Breakdown Workflow
+
+### Step 1: Read PRD Content
+
+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)"
+
+### Step 2: Analyze & Identify Epics
+
+Analyze the PRD content to identify logical work packages:
+
+1. **Group features** into cohesive epics:
+   - Each P0 feature often maps to 1-2 epics
+   - Shared infrastructure (auth, database setup) = separate epic
+   - Consider technical vs. functional groupings
+
+2. **Identify dependencies** between epics:
+   - Infrastructure epics come first (database, auth)
+   - Feature epics depend on infrastructure
+   - Some features can be parallelized
+
+3. **Create epic structure** mentally before presenting:
+   ```
+   Epic 1: Project Setup (no deps)
+   Epic 2: Database Schema (depends on 1)
+   Epic 3: Core Feature A (depends on 2)
+   Epic 4: Core Feature B (depends on 2) ← can parallel with 3
+   ```
+
+### Step 3: Present Epic Structure (Confidence-Based)
+
+**If high confidence (>80%):** Show structure and proceed to create epics immediately.
+
+```
+## Epic Breakdown
+
+Creating 4 epics for [PRD Title]:
+
+1. **{Title}** - {goal} (foundation)
+2. **{Title}** - {goal} → depends on Epic 1
+3. **{Title}** - {goal} → depends on Epic 2
+4. **{Title}** - {goal} → depends on Epic 2 (parallel with 3)
+
+Creating epics...
+```
+
+**If medium/low confidence:** Show structure and ask for confirmation.
+
+```
+## Proposed Epic Breakdown
+
+Based on the PRD, I recommend these epics:
+
+### Epic 1: {Title}
+**Goal:** {one sentence}
+**Depends on:** None (foundation)
+
+### Epic 2: {Title}
+**Goal:** {one sentence}
+**Depends on:** Epic 1
+
+...
+
+Ready to create these epics?
+```
+
+Use AskUserQuestion only when uncertain:
+- Create all epics (Recommended)
+- Modify structure first
+- Add/remove epics
+
+### Step 4: Create Epics
+
+For each approved epic:
+
+1. Call `create_epic` with:
+   - `prd_ref`: The PRD reference
+   - `title`: Epic title
+   - `description`: Goal and scope summary
+
+2. Call `add_criteria` for each epic-level acceptance criterion
+   - Use `[auto]` or `[manual]` prefix (see Test Type Convention below)
+
+3. Call `add_dependency` to set up epic dependencies
+   - `ref`: The dependent epic
+   - `depends_on_ref`: The prerequisite epic
+
+### Step 5: Task Breakdown (Confidence-Based)
+
+For each epic, break down into tasks:
+
+1. Analyze epic scope and identify 3-7 tasks:
+   - Start with data/schema tasks
+   - Then business logic
+   - Then API/interface
+   - Finally integration/wiring
+
+2. **If high confidence:** Create tasks immediately, show progress.
+
+   ```
+   Breaking down {Epic Title} into tasks...
+
+   Created:
+   - FP-T1: {title} (3 criteria)
+   - FP-T2: {title} (2 criteria)
+   - FP-T3: {title} (2 criteria)
+   ```
+
+3. **If medium/low confidence:** Present task structure and confirm.
+
+   ```
+   ## Tasks for {Epic Title}
+
+   1. {Task title} - {brief description}
+      - [auto] {criterion 1}
+      - [auto] {criterion 2}
+
+   2. {Task title} - {brief description}
+      - [auto] {criterion}
+      - [manual] {criterion} → Verify: {steps}
+
+   Create these tasks?
+   ```
+
+4. Create tasks:
+   - Call `create_task` with epic_ref, title, description, priority
+   - Call `add_criteria` for each task criterion (1-3 per task)
+
+### Step 6: Completion
+
+After all epics and tasks are created:
+
+1. Update PRD status: Call `update_status` with ref and status=BREAKDOWN_READY
+
+2. Show summary:
+   ```
+   ## Breakdown Complete
+
+   PRD: {title} (now BREAKDOWN_READY)
+
+   Created:
+   - {X} Epics
+   - {Y} Tasks
+   - {Z} Acceptance Criteria
+
+   Dependency Order:
+   1. {Epic 1} - {status}
+   2. {Epic 2} - depends on {Epic 1}
+   ...
+
+   Next: Run `/flux:implement` to start working on tasks.
+   ```
+
+## Test Type Convention
+
+Mark each acceptance criterion with its test type as a text prefix:
+
+- **`[auto]`** - Verified by automated test (unit, integration, e2e)
+- **`[manual]`** - Requires human verification
+
+For manual criteria, include verification steps after `→ Verify:`:
+```
+[manual] Dashboard displays correctly on mobile → Verify: Open on phone, check layout
+```
+
+### Examples
+
+Good criteria:
+- `[auto] API returns 401 for invalid credentials`
+- `[auto] User record is created in database`
+- `[manual] Error message is user-friendly → Verify: Read message aloud, is it clear?`
+- `[manual] Loading animation feels smooth → Verify: Test on slow network`
+
+Bad criteria:
+- `User authentication works` (not specific, no test type)
+- `The feature is complete` (not testable)
+
+## Guidelines
+
+- **Right-size epics**: 3-7 tasks, 1-3 days of work
+- **Right-size tasks**: One commit, 30min-4hrs, clear "done" state
+- **1-3 criteria per task**: Keep tasks focused and testable
+- **Dependencies first**: Foundation epics before feature epics
+- **Prefer [auto]**: Automated tests where possible
+- **Be specific**: Criteria should be objectively verifiable
+- **Allow iteration**: User can modify structure at each step