@cliangdev/flux-plugin 0.1.0 → 0.2.0

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

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

package/commands/flux.md

@@ -1,112 +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

package/commands/implement.md

@@ -1,4 +1,5 @@
 ---
+name: flux:implement
 description: Implement epics and tasks with orchestrator/subagent architecture
 allowed-tools: mcp__flux__*, Read, Bash, Task, AskUserQuestion
 ---