@cliangdev/flux-plugin 0.1.0 → 0.2.0-dev.4f12f3f

package/commands/flux.md

@@ -1,112 +1,236 @@
 ---
+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. Your job is to detect the project state and guide the user through the appropriate workflow.
+You are the Flux orchestrator - the main entry point for all Flux operations. Your job is to:
+1. Detect project state and guide users to the appropriate next action
+2. Route to specialized commands based on user input
+3. Provide intelligent suggestions based on workflow state
 
-## Step 0: Check for Version Subcommand
+## Available Commands
 
-First, check if the user requested version information:
-- `/flux version` - Show version information
+| Command | Description |
+|---------|-------------|
+| `/flux` | Show project status and suggest next action |
+| `/flux:prd` | Create or refine PRDs through guided interview |
+| `/flux:breakdown` | Break approved PRD into dependency-ordered epics and tasks |
+| `/flux:implement` | Implement tasks with TDD workflow using specialized coding agents |
+| `/flux:linear` | Connect Flux project to Linear for issue tracking |
 
-If the argument is "version":
+## Subcommand Routing
 
-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)
+When user provides arguments, route to the appropriate command:
 
-## Step 1: Check Project State
+| User Input | Action |
+|------------|--------|
+| `/flux` | Show status (see Main Flow) |
+| `/flux version` | Call `get_version` and display result |
+| `/flux status` | Call `render_status` with `{view: "full"}` |
+| `/flux prd` or `/flux prd ...` | Delegate to `/flux:prd` with any additional args |
+| `/flux breakdown` or `/flux breakdown ...` | Delegate to `/flux:breakdown` with any additional args |
+| `/flux implement` or `/flux implement ...` | Delegate to `/flux:implement` with any additional args |
+| `/flux linear` | Delegate to `/flux:linear` |
+| `/flux help` | Show available commands and their purposes |
+
+## Available MCP Tools
+
+These tools are available for programmatic access:
+
+**Entity Management:**
+- `create_prd`, `create_epic`, `create_task` - Create entities
+- `update_entity`, `update_status`, `delete_entity` - Modify entities
+- `get_entity`, `query_entities` - Retrieve entities
+
+**Project:**
+- `init_project` - Initialize new Flux project
+- `get_stats` - Get entity counts by status
+- `get_version` - Get plugin version
+- `render_status` - Visual project status with progress bars
+
+**Relationships:**
+- `add_dependency`, `remove_dependency` - Task/epic dependencies
+- `add_criteria`, `mark_criteria_met` - Acceptance criteria
+
+**Integration:**
+- `configure_linear` - Connect to Linear (interactive mode supported)
+
+## Main Flow
+
+### Step 0: Check for Subcommands
+
+First, check if the user provided arguments (e.g., `/flux prd`, `/flux implement FP-T1`).
+If so, route to the appropriate command as described in Subcommand Routing above.
+
+### Step 1: Check Project State
+
+If no subcommand, call `render_status` with `{view: "summary"}` to show current state.
+
+### Step 2: Route Based on Response
+
+**If error with `code: "PROJECT_NOT_INITIALIZED"`:**
+→ Guide through initialization (see Initialization Flow below)
 
-If no subcommand was provided, call the `get_project_context` MCP tool to check if this is a Flux project.
+**If success:**
+→ Display the rendered status
+→ Analyze workflow state and suggest the most appropriate next action (see Workflow States)
+→ If multiple actions are possible, use AskUserQuestion to let user choose
 
-## Step 2: Handle Result
+## Initialization Flow
 
-### If `initialized: false` (New Project)
+Use the `AskUserQuestion` tool for all questions during initialization.
+
+### Step 1: Confirm 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
+  }]
+}
+```
+
+If "No", exit with: "Run `/flux` when you're ready to set up Flux."
 
-This is a new project. Guide the user through initialization:
+### Step 2: Collect Project Details
 
-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."
-
-2. Ask: "What is the name of this project?"
-   - Wait for response
-
-3. Ask: "Brief vision - what does this project do? (one sentence)"
-   - Wait for response
-
-4. Call `init_project` tool with the name and vision
-
-5. Display success message:
-   ```
-   Flux project initialized!
-
-   Project: {name}
-   Vision: {vision}
-   Reference prefix: {ref_prefix}
-
-   Created:
-   - .flux/project.json
-   - .flux/flux.db
-
-   Next: Run /flux:prd to start planning your first PRD.
-   ```
-
-### If Project Exists (Initialized)
-
-This is an existing Flux project. Show status and suggest next action:
-
-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."
+Use AskUserQuestion with text input (user will select "Other" to type):
+- Ask for project name
+- Ask for project vision (brief description)
+
+### Step 3: Select Storage Backend
+
+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
+  }]
+}
+```
+
+### Step 4: Ask About Tool Permissions
+
+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
+  }]
+}
+```
+
+If "Yes", update the settings file:
+
+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`
+
+Example result:
+```json
+{
+  "permissions": {
+    "allow": ["mcp__plugin_flux_flux__*"]
+  }
+}
+```
+
+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 |
+
+## Help Output
+
+When user runs `/flux help`, display:
+
+```
+Flux - AI-first workflow orchestration
+
+Commands:
+  /flux              Show project status and next action
+  /flux:prd          Create or refine PRDs
+  /flux:breakdown    Break PRD into epics and tasks
+  /flux:implement    Implement tasks with TDD
+  /flux:linear       Connect to Linear
+
+Shortcuts:
+  /flux prd          Same as /flux:prd
+  /flux breakdown    Same as /flux:breakdown
+  /flux implement    Same as /flux:implement
+  /flux status       Show detailed project status
+  /flux version      Show plugin version
+
+Workflow:
+  1. /flux           Initialize project (first time)
+  2. /flux:prd       Create your first PRD
+  3. /flux:breakdown Break PRD into tasks
+  4. /flux:implement Start coding with TDD
+```
 
 ## 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
+- When user input matches a subcommand pattern, delegate immediately without calling render_status first

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
 ---
@@ -52,8 +53,7 @@ The orchestrator resolves all refs to tasks, builds a dependency-ordered queue,
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-2. Parse arguments and resolve to tasks:
+1. Parse arguments and resolve to tasks (if any tool returns `PROJECT_NOT_INITIALIZED` error, tell user: "Run `/flux` first to initialize the project." and exit):
    - No args: Query for next PENDING task with no blockers
    - PRD ref(s): Expand to all epics → all tasks
    - Epic ref(s): Expand to all tasks

package/commands/linear.md

@@ -0,0 +1,172 @@
+---
+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 & Fetch Teams
+
+Call `configure_linear` with `{interactive: true}`.
+
+- If error with `code: "PROJECT_NOT_INITIALIZED"` → Tell user to run `/flux` first, then exit.
+- If error about Linear API key → Show instructions (see Step 2 error handling).
+- If success with `step: "already_configured"` → Already configured, show info and exit.
+- Otherwise → Continue with team selection (response contains teams list).
+
+### 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

package/commands/prd.md

@@ -1,4 +1,5 @@
 ---
+name: flux:prd
 description: Create or refine PRDs through guided interview
 allowed-tools: mcp__flux__*, AskUserQuestion
 ---
@@ -19,8 +20,8 @@ Check if arguments were provided:
 
 ### Pre-check
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. Call `query_entities` with `type: "prd"` to verify project is initialized
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
 2. Call `get_interview` to check for any in-progress interview
    - If exists, ask: "You have an unfinished interview. Resume it or start fresh?"
@@ -95,7 +96,7 @@ Use AskUserQuestion to confirm:
 
 ## After Interview Complete
 
-The `get_project_context` call from Pre-check returns the adapter type. Use this to determine storage behavior.
+The `create_prd` response includes project context. Use it to determine storage behavior, or call `get_entity` on the created PRD to check the adapter type.
 
 ### For Local Adapter (`adapter.type === "local"`):
 

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,32 +1,36 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.1.0",
+  "version": "0.2.0-dev.4f12f3f",
   "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": [
-    "dist/",
+    "bin/install.cjs",
+    "src/",
     "skills/",
-    "commands/"
+    "commands/",
+    "agents/",
+    "manifest.json"
   ],
   "scripts": {
     "dev": "bun run src/server/index.ts",
-    "build": "bun build src/server/index.ts --outdir dist/server --target node",
-    "postbuild": "node -e \"const fs=require('fs');const f='dist/server/index.js';const c=fs.readFileSync(f,'utf-8');if(!c.startsWith('#!/usr/bin/env node')){fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)}\"",
-    "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",
+    "build": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "build:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
+    "build:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "validate": "node scripts/validate-structure.cjs",
+    "test:integration": "bun test scripts/__tests__/integration.test.ts --timeout 120000",
+    "prepublishOnly": "bun run validate && bun run test:integration",
     "test": "bun test",
     "test:linear-description": "bun run src/server/adapters/__tests__/linear-description-test.ts",
     "typecheck": "tsc --noEmit",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
     "format": "biome format --write .",
-    "verify-release": "bun run scripts/verify-release.ts"
+    "verify-release": "bun run scripts/verify-release.ts",
+    "release": "./scripts/release.sh"
   },
   "repository": {
     "type": "git",

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