@cliangdev/flux-plugin 0.0.0-dev.1db9c6c

package/README.md

@@ -0,0 +1,159 @@
+# Flux Plugin
+
+Agent-orchestrated, spec-driven workflow for Claude Code.
+
+## Installation
+
+```bash
+npx @cliangdev/flux-plugin
+```
+
+This installs:
+- Commands (`/flux`, `/flux:prd`, `/flux:breakdown`, `/flux:implement`)
+- Skills for AI orchestration
+- MCP server for project data
+
+### Options
+
+```bash
+npx @cliangdev/flux-plugin --global   # Install to ~/.claude (all projects)
+npx @cliangdev/flux-plugin --local    # Install to ./.claude (current project)
+```
+
+### What Gets Configured
+
+The installer automatically:
+1. Creates plugin at `.claude/plugins/marketplaces/npm/flux-plugin/`
+2. Adds MCP server config to `.claude.json`
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/flux` | Smart entry point - shows status and guides you to the next step |
+| `/flux:prd` | Create product requirements through guided interview |
+| `/flux:breakdown` | Break PRDs into epics and tasks with acceptance criteria |
+| `/flux:implement` | Implement tasks with TDD workflow |
+
+### Typical Workflow
+
+1. **Start**: Run `/flux` to initialize your project
+2. **Define**: Run `/flux:prd` to create requirements through interactive Q&A
+3. **Plan**: Run `/flux:breakdown` to generate implementation tasks
+4. **Build**: Run `/flux:implement` to code with test-driven development
+
+The orchestrator tracks your progress and always suggests the logical next step.
+
+## How It Works
+
+```mermaid
+flowchart TB
+    subgraph User["User Intent"]
+        U["/flux - Start Here"]
+    end
+
+    subgraph Orchestrator["Flux Orchestrator"]
+        O{Analyze Context}
+        O -->|No Project| Init[Initialize Project]
+        O -->|No PRDs| PRD[Guide to /flux:prd]
+        O -->|PRD Ready| Break[Guide to /flux:breakdown]
+        O -->|Tasks Ready| Impl[Guide to /flux:implement]
+    end
+
+    subgraph PRDPhase["Requirements Phase"]
+        P1["/flux:prd"]
+        P2[Interactive Interview]
+        P3[Generate PRD Document]
+        P1 --> P2 --> P3
+    end
+
+    subgraph BreakdownPhase["Planning Phase"]
+        B1["/flux:breakdown"]
+        B2[Analyze PRD]
+        B3[Create Epics & Tasks]
+        B4[Define Acceptance Criteria]
+        B1 --> B2 --> B3 --> B4
+    end
+
+    subgraph ImplementPhase["Implementation Phase"]
+        I1["/flux:implement"]
+        I2[Select Next Task]
+        I3[TDD: Write Tests First]
+        I4[Implement Code]
+        I5[Verify & Commit]
+        I1 --> I2 --> I3 --> I4 --> I5
+        I5 -->|More Tasks| I2
+    end
+
+    U --> O
+    Init --> PRD
+    PRD --> P1
+    Break --> B1
+    Impl --> I1
+    P3 -->|PRD Complete| O
+    B4 -->|Breakdown Complete| O
+    I5 -->|All Done| Done[Project Complete]
+```
+
+## Features
+
+- **Intelligent Orchestration**: Automatically guides you through the workflow based on project state
+- **Spec-Driven Development**: All implementation traces back to documented requirements
+- **Test-Driven Implementation**: Write tests first, then implement until they pass
+- **Acceptance Criteria**: Every task has verifiable criteria for completion
+- **Backend Agnostic**: Works with local SQLite or Linear for team collaboration
+
+## Project Structure
+
+```
+your-project/
+├── .flux/
+│   ├── project.json    # Project configuration
+│   ├── flux.db         # Local database
+│   └── docs/
+│       └── prd-*/      # PRD documents
+└── ...
+```
+
+## Updating
+
+To update to the latest version, simply re-run the installer:
+
+```bash
+npx @cliangdev/flux-plugin@latest --global
+```
+
+This will:
+- Update commands and skills to the latest version
+- Update the MCP server configuration
+
+Check your current version:
+```
+/flux version
+```
+
+## Uninstall
+
+### Global Installation
+
+```bash
+rm -rf ~/.claude/plugins/marketplaces/npm/flux-plugin
+# Edit ~/.claude.json and remove the "flux" entry from "mcpServers"
+```
+
+### Local Installation
+
+```bash
+rm -rf .claude/plugins/marketplaces/npm/flux-plugin
+# Edit .claude.json and remove the "flux" entry from "mcpServers"
+```
+
+Note: Your project data in `.flux/` is preserved. Delete it manually if you want to remove all Flux data.
+
+## Support
+
+GitHub: [github.com/cliangdev/flux-plugin](https://github.com/cliangdev/flux-plugin)
+
+## License
+
+MIT

package/bin/install.cjs

@@ -0,0 +1,222 @@
+#!/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 pluginDir = path.join(claudeDir, "plugins", "marketplaces", "npm", "flux-plugin");
+		const locationLabel = isGlobal ? "~/.claude" : "./.claude";
+
+		console.log(`  Installing to ${cyan}${locationLabel}/plugins/marketplaces/npm/flux-plugin${reset}\n`);
+
+		fs.mkdirSync(pluginDir, { recursive: true });
+
+		const pluginConfigDir = path.join(pluginDir, ".claude-plugin");
+		fs.mkdirSync(pluginConfigDir, { recursive: true });
+		writeJson(path.join(pluginConfigDir, "plugin.json"), {
+			name: "flux-plugin",
+			description: "AI-first workflow orchestration for spec-driven development",
+			version: pkg.version,
+			author: {
+				name: "cliangdev",
+				url: "https://github.com/cliangdev/flux-plugin"
+			}
+		});
+		console.log(`  ${green}✓${reset} Created plugin config`);
+
+		const commandsSrc = path.join(src, "commands");
+		if (fs.existsSync(commandsSrc)) {
+			const commandsDest = path.join(pluginDir, "commands");
+			fs.mkdirSync(commandsDest, { recursive: true });
+
+			const commandFiles = fs.readdirSync(commandsSrc);
+			for (const file of commandFiles) {
+				if (file.endsWith(".md")) {
+					fs.copyFileSync(
+						path.join(commandsSrc, file),
+						path.join(commandsDest, file)
+					);
+					const name = file.replace(".md", "");
+					console.log(`  ${green}✓${reset} Installed command: /${name}`);
+				}
+			}
+		}
+
+		const skillsSrc = path.join(src, "skills");
+		if (fs.existsSync(skillsSrc)) {
+			const skillsDest = path.join(pluginDir, "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 claudeJsonPath = isGlobal
+			? path.join(os.homedir(), ".claude.json")
+			: path.join(process.cwd(), ".claude.json");
+
+		const claudeJson = readJson(claudeJsonPath);
+
+		if (!claudeJson.mcpServers) {
+			claudeJson.mcpServers = {};
+		}
+
+		claudeJson.mcpServers.flux = {
+			command: "npx",
+			args: ["-y", "@cliangdev/flux-plugin", "serve"],
+		};
+
+		writeJson(claudeJsonPath, claudeJson);
+		console.log(
+			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.claude.json"}`
+		);
+
+		const versionFile = path.join(pluginDir, "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