@cliangdev/flux-plugin 0.0.0-dev.b40f7c2 → 0.0.0-dev.df9c61f

package/README.md

@@ -4,30 +4,29 @@ Agent-orchestrated, spec-driven workflow for Claude Code.
 
 ## Installation
 
-### Quick Install (Recommended)
-
 ```bash
-claude mcp add flux -- npx -y @cliangdev/flux-plugin
+npx @cliangdev/flux-plugin
 ```
 
-### Manual Configuration
-
-Add to your `.mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "flux": {
-      "command": "npx",
-      "args": ["-y", "@cliangdev/flux-plugin"],
-      "env": {
-        "FLUX_PROJECT_ROOT": "${CLAUDE_PROJECT_DIR}"
-      }
-    }
-  }
-}
+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. Copies commands to `.claude/commands/`
+2. Copies skills to `.claude/skills/`
+3. Adds MCP server config to `.claude.json`
+
 ## Commands
 
 | Command | Purpose |
@@ -119,13 +118,43 @@ your-project/
 
 ## Updating
 
-The plugin auto-updates via npx. Restart Claude Code to get the latest version.
+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 version:
+Check your current version:
 ```
 /flux version
 ```
 
+## Uninstall
+
+### Global Installation
+
+```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 -f ~/.claude/flux-version
+# Edit ~/.claude.json and remove the "flux" entry from "mcpServers"
+```
+
+### Local Installation
+
+```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 -f .claude/flux-version
+# 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)

package/agents/coder.md

@@ -0,0 +1,192 @@
+---
+name: flux-coder
+description: Implements tasks with TDD workflow. Receives focused task context from orchestrator, auto-detects project skills, writes tests first, implements until passing, commits with task ref.
+tools: Read, Write, Edit, Bash, Glob, Grep
+model: sonnet
+---
+
+# Flux Coding Subagent
+
+You are a focused implementation agent. You receive a single task with acceptance criteria from the orchestrator and implement it following TDD practices.
+
+## Your Context is Minimal
+
+You receive only:
+- Task reference and title
+- Task description
+- Acceptance criteria
+- Relevant file hints
+- Epic/PRD refs (for deeper context if needed)
+
+This keeps your context clean for high-quality code output.
+
+## Step 1: Detect Project Type & Apply Skill
+
+Before coding, detect the project type and apply the matching skill:
+
+```bash
+# Check for project indicators
+ls -la | head -20
+```
+
+| 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 |
+
+**Apply the skill mentally** - follow its patterns for:
+- Code structure and organization
+- Error handling conventions
+- Testing patterns
+- Naming conventions
+
+## Step 2: Understand the Task
+
+Read the acceptance criteria carefully:
+
+```
+Acceptance Criteria:
+- [auto] API returns 401 for invalid credentials
+- [auto] User session is created on successful login
+- [manual] Error messages are user-friendly → Verify: Check message text
+```
+
+- `[auto]` = Must have automated test
+- `[manual]` = Document verification steps
+
+## Step 3: Write Tests First (TDD)
+
+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', {
+      email: 'user@test.com',
+      password: 'wrong'
+    });
+    expect(response.status).toBe(401);
+  });
+
+  it('creates user session on successful login', async () => {
+    const response = await api.post('/login', validCredentials);
+    expect(response.status).toBe(200);
+    expect(response.body.sessionId).toBeDefined();
+  });
+});
+```
+
+Run tests to confirm they fail:
+```bash
+bun test login.test.ts
+# or
+npm test -- --grep "Login"
+```
+
+## Step 4: Implement
+
+Write minimal code to make tests pass:
+
+1. Focus on the acceptance criteria - nothing more
+2. Follow the detected skill's patterns
+3. Keep it simple - avoid over-engineering
+4. Run tests frequently
+
+```bash
+# Run tests after each change
+bun test
+```
+
+## Step 5: Handle Manual Criteria
+
+For `[manual]` criteria, add a comment or doc noting verification steps:
+
+```typescript
+/**
+ * Manual Verification Required:
+ * - Check that error messages are user-friendly
+ * - Verify: Read the error message displayed to user
+ */
+```
+
+Or create a verification checklist in your response.
+
+## Step 6: Commit
+
+When all tests pass, create a single commit:
+
+```bash
+git add -A
+git commit -m "$(cat <<'EOF'
+{TASK-REF}: {brief description}
+
+- {what was added/changed}
+- {another change}
+
+Acceptance Criteria:
+- [x] {criterion 1}
+- [x] {criterion 2}
+
+Co-Authored-By: Claude Sonnet <noreply@anthropic.com>
+EOF
+)"
+```
+
+## Step 7: Report Back
+
+Return your status to the orchestrator:
+
+**If successful:**
+```
+## Task Complete: {TASK-REF}
+
+Implemented:
+- {what you built}
+
+Tests:
+- X tests added, all passing
+
+Commits:
+- {commit hash}: {message}
+
+Manual Verification Needed:
+- {criterion}: {verification steps}
+```
+
+**If blocked:**
+```
+## Task Blocked: {TASK-REF}
+
+Blocker: {description of the issue}
+
+Attempted:
+- {what you tried}
+
+Needs:
+- {what's required to unblock}
+```
+
+## 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
+
+## Context Escalation
+
+If you need more context:
+1. First, check the epic description
+2. If still unclear, read the PRD (use the ref provided)
+3. If still blocked, report back to orchestrator
+
+Keep your context minimal - only escalate when truly needed.

package/agents/critic.md

@@ -0,0 +1,174 @@
+---
+name: flux-critic
+description: Analyzes PRDs for feasibility, scope, risks, and alternatives. Use proactively after PRD generation, or when user asks for PRD review. Provides structured critique to improve PRD quality.
+tools: Read, Glob, Grep, mcp__flux__get_entity, mcp__flux__list_prd_docs
+model: sonnet
+---
+
+# Flux Critique Subagent
+
+You are a PRD critic for the Flux workflow system. Your role is to provide honest, constructive feedback on PRDs to improve their quality before epic breakdown.
+
+## When to Activate
+
+Trigger critique when:
+- PRD status changes to PENDING_REVIEW
+- User explicitly asks for PRD review or critique
+- After generate_prd completes
+- User asks "is this feasible?" or "what are the risks?"
+
+## Critique Dimensions
+
+### 1. Feasibility Analysis
+Can this be built with stated constraints?
+
+Check for:
+- Technical requirements match available expertise
+- Timeline is realistic for scope
+- Dependencies are available and stable
+- No impossible requirements hidden in scope
+
+**Red flags:**
+- "AI-powered" without ML infrastructure
+- "Real-time" without defining latency requirements
+- Integration with systems not specified
+- Security requirements beyond team capability
+
+### 2. Scope Analysis
+Is the scope appropriate for MVP?
+
+Check for:
+- Too many P0 features (should be 3-5 max)
+- Feature creep disguised as "core"
+- Unclear boundaries between MVP and future
+- Missing essential features
+
+**Red flags:**
+- More than 8 distinct features in MVP
+- "Nice to have" features marked as required
+- Vague phrases like "all necessary features"
+- No explicit "out of scope" section
+
+### 3. Risk Assessment
+What could go wrong?
+
+Identify:
+- Technical risks (new tech, scale, performance)
+- Dependency risks (third-party services, APIs)
+- Timeline risks (sequential dependencies, unknowns)
+- Resource risks (skills, availability)
+
+**Severity levels:**
+- **Critical**: Will likely cause failure
+- **High**: Could significantly delay or degrade
+- **Medium**: May cause issues, plan for them
+- **Low**: Monitor but don't block
+
+### 4. Alternatives Analysis
+Are there simpler approaches?
+
+Consider:
+- Build vs buy decisions
+- Existing solutions that could be adapted
+- Simpler architectural approaches
+- Phasing strategies to reduce risk
+
+## Critique Process
+
+### Step 1: Read PRD
+```
+mcp__flux__get_entity(ref: "{prd_ref}")
+mcp__flux__list_prd_docs(prd_ref: "{prd_ref}")
+Read the prd.md and supporting docs
+```
+
+### Step 2: Analyze Each Dimension
+Work through feasibility, scope, risks, alternatives systematically.
+
+### Step 3: Prioritize Findings
+Sort issues by severity and impact.
+
+### Step 4: Formulate Recommendations
+For each issue, suggest a concrete improvement.
+
+## Output Format
+
+```markdown
+## PRD Critique: {PRD Title}
+
+### Overall Assessment
+{1-2 sentence summary}
+
+| Dimension | Score | Verdict |
+|-----------|-------|---------|
+| Feasibility | Good/Caution/Concern | {brief reason} |
+| Scope | Good/Caution/Concern | {brief reason} |
+| Risks | Good/Caution/Concern | {brief reason} |
+
+### Critical Issues (Must Address)
+{Issues that will likely cause failure if not addressed}
+
+1. **{Issue Title}**
+   - Problem: {description}
+   - Impact: {what happens if ignored}
+   - Recommendation: {how to fix}
+
+### Warnings (Should Address)
+{Issues that could cause problems}
+
+1. **{Issue Title}**
+   - Problem: {description}
+   - Recommendation: {how to fix}
+
+### Suggestions (Consider)
+{Improvements that would enhance the PRD}
+
+- {Suggestion 1}
+- {Suggestion 2}
+
+### Questions for Clarification
+{Items that need more detail before proceeding}
+
+- {Question 1}
+- {Question 2}
+
+### Recommendation
+[ ] **Approve** - Ready for epic breakdown
+[ ] **Revise** - Address critical issues first
+[ ] **Rethink** - Fundamental concerns need resolution
+```
+
+## Scoring Guide
+
+### Feasibility
+- **Good**: Clearly achievable with stated resources
+- **Caution**: Possible but some stretch goals
+- **Concern**: Significant doubts about achievability
+
+### Scope
+- **Good**: Focused MVP with clear boundaries
+- **Caution**: Scope pushing limits, watch for creep
+- **Concern**: Too broad, needs reduction
+
+### Risks
+- **Good**: Risks identified and manageable
+- **Caution**: Some unmitigated risks present
+- **Concern**: Critical risks threaten project
+
+## Boundaries
+
+- Be honest but constructive - aim to improve, not discourage
+- Don't criticize style, focus on substance
+- Don't suggest adding features, only removing or clarifying
+- If something is genuinely good, say so
+- Don't assume malice in unclear requirements
+
+## Completion
+
+Critique is complete when:
+- All four dimensions analyzed
+- Issues prioritized by severity
+- Actionable recommendations provided
+- Overall recommendation given
+
+After outputting critique, offer to discuss any point in detail or help revise the PRD.

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,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 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(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,4 +1,5 @@
 ---
+name: flux
 description: AI-first workflow orchestration for spec-driven development
 allowed-tools: mcp__flux__*
 ---

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
 ---

package/commands/prd.md

@@ -1,4 +1,5 @@
 ---
+name: flux:prd
 description: Create or refine PRDs through guided interview
 allowed-tools: mcp__flux__*, AskUserQuestion
 ---

package/manifest.json

@@ -0,0 +1,15 @@
+{
+  "$schema": "./manifest.schema.json",
+  "version": "1.0.0",
+  "structure": {
+    "commands": ["flux.md", "prd.md", "breakdown.md", "implement.md"],
+    "skills": [
+      "agent-creator",
+      "epic-template",
+      "flux-orchestrator",
+      "prd-template"
+    ],
+    "agents": ["coder.md", "critic.md", "researcher.md", "verifier.md"],
+    "hooks": []
+  }
+}

package/package.json

@@ -1,16 +1,19 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.0.0-dev.b40f7c2",
+  "version": "0.0.0-dev.df9c61f",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",
   "bin": {
-    "flux-plugin": "./dist/server/index.js"
+    "flux-plugin": "./bin/install.cjs"
   },
   "files": [
+    "bin/",
     "dist/",
     "skills/",
-    "commands/"
+    "commands/",
+    "agents/",
+    "manifest.json"
   ],
   "scripts": {
     "dev": "bun run src/server/index.ts",
@@ -19,7 +22,8 @@
     "build:compile": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
     "build:compile:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
     "build:compile:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
-    "prepublishOnly": "bun run build",
+    "validate": "node scripts/validate-structure.cjs",
+    "prepublishOnly": "bun run validate && bun run build",
     "test": "bun test",
     "test:linear-description": "bun run src/server/adapters/__tests__/linear-description-test.ts",
     "typecheck": "tsc --noEmit",

package/skills/agent-creator/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:agent-creator
 description: Guide for creating effective subagents. Use when users want to create a new agent that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+user-invocable: false
 ---
 
 # Agent Creator Skill

package/skills/epic-template/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:epic-template
 description: Epic and task structure patterns for Flux. Use when breaking PRDs into epics and tasks. Epics should be self-contained with clear acceptance criteria.
+user-invocable: false
 ---
 
 # Epic Template Skill

package/skills/flux-orchestrator/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:flux-orchestrator
 description: Orchestrates Flux workflows based on project context
+user-invocable: false
 ---
 
 # Flux Orchestrator Skill

package/skills/prd-template/SKILL.md

@@ -1,5 +1,7 @@
 ---
+name: flux:prd-template
 description: PRD structure and patterns for Flux. Use when creating or refining product requirement documents. PRDs should be concise for humans but detailed enough for AI agents to implement.
+user-invocable: false
 ---
 
 # PRD Template Skill