@cliangdev/flux-plugin 0.0.0-dev.991d9a8 → 0.0.0-dev.aedd289

package/bin/install.cjs

@@ -5,30 +5,23 @@ const path = require("path");
 const os = require("os");
 const readline = require("readline");
 
-// Parse args first to check for serve command
 const args = process.argv.slice(2);
 
-// Check for "serve" subcommand - starts MCP server
 if (args[0] === "serve") {
-	// Dynamic import to load ESM server
 	import("../dist/server/index.js").catch((err) => {
 		console.error("Failed to start Flux MCP server:", err.message);
 		process.exit(1);
 	});
 } else {
-	// Run installer
 	runInstaller();
 }
 
 function runInstaller() {
-	// Colors
 	const cyan = "\x1b[36m";
 	const green = "\x1b[32m";
 	const yellow = "\x1b[33m";
 	const dim = "\x1b[2m";
 	const reset = "\x1b[0m";
-
-	// Get version from package.json
 	const pkg = require("../package.json");
 
 	const banner = `
@@ -49,7 +42,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 
 	console.log(banner);
 
-	// Show help
 	if (hasHelp) {
 		console.log(`  ${yellow}Usage:${reset} npx @cliangdev/flux-plugin [options]
 
@@ -71,9 +63,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		process.exit(0);
 	}
 
-	/**
-	 * Recursively copy directory
-	 */
 	function copyDir(src, dest) {
 		fs.mkdirSync(dest, { recursive: true });
 		const entries = fs.readdirSync(src, { withFileTypes: true });
@@ -90,9 +79,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		}
 	}
 
-	/**
-	 * Read JSON file, return empty object if doesn't exist
-	 */
 	function readJson(filePath) {
 		if (fs.existsSync(filePath)) {
 			try {
@@ -104,58 +90,53 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		return {};
 	}
 
-	/**
-	 * Write JSON file with formatting
-	 */
 	function writeJson(filePath, data) {
 		fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n");
 	}
 
-	/**
-	 * Install to specified directory
-	 */
 	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`);
 
-		// Create directories
 		fs.mkdirSync(claudeDir, { recursive: true });
 
-		// Copy commands
 		const commandsSrc = path.join(src, "commands");
 		if (fs.existsSync(commandsSrc)) {
 			const commandsDest = path.join(claudeDir, "commands");
-			fs.mkdirSync(commandsDest, { recursive: true });
+			const fluxSubDir = path.join(commandsDest, "flux");
+			fs.mkdirSync(fluxSubDir, { recursive: true });
 
-			// Copy each command as a directory (flux.md -> commands/flux/COMMAND.md)
 			const commandFiles = fs.readdirSync(commandsSrc);
 			for (const file of commandFiles) {
 				if (file.endsWith(".md")) {
 					const name = file.replace(".md", "");
-					const destDir = path.join(commandsDest, name);
-					fs.mkdirSync(destDir, { recursive: true });
-					fs.copyFileSync(
-						path.join(commandsSrc, file),
-						path.join(destDir, "COMMAND.md")
-					);
-					console.log(`  ${green}✓${reset} Installed command: /${name}`);
+					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}`);
+					}
 				}
 			}
 		}
 
-		// Copy skills
 		const skillsSrc = path.join(src, "skills");
 		if (fs.existsSync(skillsSrc)) {
 			const skillsDest = path.join(claudeDir, "skills");
 			fs.mkdirSync(skillsDest, { recursive: true });
 
-			// Copy each skill directory
 			const skillDirs = fs.readdirSync(skillsSrc, { withFileTypes: true });
 			for (const dir of skillDirs) {
 				if (dir.isDirectory()) {
@@ -168,29 +149,44 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 			}
 		}
 
-		// Configure MCP server
-		const claudeJsonPath = isGlobal
+		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(), ".claude.json");
+			: path.join(process.cwd(), ".mcp.json");
 
-		const claudeJson = readJson(claudeJsonPath);
+		const mcpConfig = readJson(mcpConfigPath);
 
-		if (!claudeJson.mcpServers) {
-			claudeJson.mcpServers = {};
+		if (!mcpConfig.mcpServers) {
+			mcpConfig.mcpServers = {};
 		}
 
-		// Add or update flux MCP server
-		claudeJson.mcpServers.flux = {
+		mcpConfig.mcpServers.flux = {
 			command: "npx",
-			args: ["-y", "@cliangdev/flux-plugin", "serve"],
+			args: ["-y", `@cliangdev/flux-plugin@${pkg.version}`, "serve"],
 		};
 
-		writeJson(claudeJsonPath, claudeJson);
+		writeJson(mcpConfigPath, mcpConfig);
 		console.log(
-			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.claude.json"}`
+			`  ${green}✓${reset} Configured MCP server in ${isGlobal ? "~/.claude.json" : "./.mcp.json"}`
 		);
 
-		// Write version file for update checking
 		const versionFile = path.join(claudeDir, "flux-version");
 		fs.writeFileSync(versionFile, pkg.version);
 
@@ -207,9 +203,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 `);
 	}
 
-	/**
-	 * Prompt for install location
-	 */
 	function promptLocation() {
 		const rl = readline.createInterface({
 			input: process.stdin,
@@ -229,7 +222,6 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 		});
 	}
 
-	// Main
 	if (hasGlobal && hasLocal) {
 		console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
 		process.exit(1);

package/commands/flux.md

@@ -1,113 +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/linear.md

@@ -0,0 +1,171 @@
+---
+name: flux:linear
+description: Connect Flux project to Linear for issue tracking
+allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion
+---
+
+# Linear Integration Setup
+
+Connect a Flux project to Linear using the interactive configuration flow.
+
+## How Interactive Mode Works
+
+The `configure_linear` tool supports progressive discovery:
+
+| Call | Response |
+|------|----------|
+| `{interactive: true}` | Returns `{step: "select_team", teams: [...], user: {...}}` |
+| `{interactive: true, teamId: "xxx"}` | Returns `{step: "select_project", projects: [...], team: {...}}` |
+| `{teamId: "xxx", projectName: "..."}` | Creates new project and configures |
+| `{teamId: "xxx", existingProjectId: "..."}` | Uses existing project and configures |
+
+## Flow
+
+### Step 1: Verify Project
+
+Call `get_project_context`.
+
+- If `initialized: false` → Tell user to run `/flux` first, then exit.
+- If `adapter.type === "linear"` and config exists → Already configured, show info and exit.
+- Otherwise → Continue to Step 2.
+
+### Step 2: Fetch Teams
+
+**IMPORTANT**: Call `configure_linear` with ONLY `interactive: true`. Do NOT pass teamId, projectName, or any other params.
+
+```json
+{"interactive": true}
+```
+
+This is the ONLY parameter needed for the first call. The tool will return available teams.
+
+**If error** (e.g., "Linear API key not found"):
+```
+Linear API key required.
+
+1. Get your key: Linear → Settings → API → Personal API keys
+2. Set it: export LINEAR_API_KEY=lin_api_xxx
+3. Run /flux:linear again
+```
+Then exit.
+
+**If success**, response will be:
+```json
+{
+  "step": "select_team",
+  "user": {"name": "...", "email": "..."},
+  "teams": [
+    {"id": "team-abc", "name": "Engineering", "key": "ENG"},
+    {"id": "team-def", "name": "Product", "key": "PROD"}
+  ]
+}
+```
+
+Display: "Connected as {user.name} ({user.email})"
+
+Use AskUserQuestion to let user select a team:
+```json
+{
+  "questions": [{
+    "question": "Which Linear team should Flux use?",
+    "header": "Team",
+    "options": [
+      {"label": "Engineering (ENG)", "description": "team-abc"},
+      {"label": "Product (PROD)", "description": "team-def"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+Note: Put the team ID in the description field so you can retrieve it from the response.
+
+### Step 3: Fetch Projects
+
+Call `configure_linear` with:
+```json
+{"interactive": true, "teamId": "<selected_team_id>"}
+```
+
+Response will be:
+```json
+{
+  "step": "select_project",
+  "team": {"id": "...", "name": "...", "key": "..."},
+  "projects": [
+    {"id": "proj-123", "name": "Q1 Sprint", "state": "started"},
+    {"id": "proj-456", "name": "Backlog", "state": "planned"}
+  ]
+}
+```
+
+Use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Which project should Flux sync to?",
+    "header": "Project",
+    "options": [
+      {"label": "Create New Project", "description": "new"},
+      {"label": "Q1 Sprint", "description": "proj-123"},
+      {"label": "Backlog", "description": "proj-456"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+### Step 4: Configure
+
+**If user selected "Create New Project":**
+
+Ask for project name, then call:
+```json
+{
+  "teamId": "<team_id>",
+  "projectName": "<user_provided_name>"
+}
+```
+
+**If user selected existing project:**
+
+Call:
+```json
+{
+  "teamId": "<team_id>",
+  "existingProjectId": "<project_id>"
+}
+```
+
+### Step 5: Success
+
+Response will include:
+```json
+{
+  "success": true,
+  "team": "Engineering",
+  "project": {"id": "...", "name": "..."},
+  "labels": {...},
+  "view": {"created": "...", "setup_hint": "..."}
+}
+```
+
+Display:
+```
+Linear connected!
+
+Team: {team}
+Project: {project.name}
+
+All PRDs, epics, and tasks will sync to Linear.
+Run /flux:prd to create your first PRD.
+```
+
+If `view.setup_hint` exists, show it as a tip.
+
+## Key Points
+
+- Always use `{"interactive": true}` (boolean) not a string
+- The response `step` field tells you what stage you're at
+- Use AskUserQuestion for team/project selection
+- Store the selected IDs from previous responses to use in next calls