@cliangdev/flux-plugin 0.1.0 → 0.2.0-dev.359209a

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
 ---
@@ -15,12 +16,26 @@ Check if arguments were provided:
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
-2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+2. If query successful but no approved PRDs found:
    - 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
+   - If multiple approved PRDs, use AskUserQuestion to let user select:
+     ```json
+     {
+       "questions": [{
+         "question": "Which PRD would you like to break down?",
+         "header": "Select PRD",
+         "options": [
+           {"label": "{PRD-1 title}", "description": "{ref} - {brief description}"},
+           {"label": "{PRD-2 title}", "description": "{ref} - {brief description}"}
+         ],
+         "multiSelect": false
+       }]
+     }
+     ```
+     Note: Dynamically populate options from the query results.
 
 3. If ref provided, call `get_entity` with the ref
    - Verify status is APPROVED
@@ -77,9 +92,21 @@ Which approach do you prefer?
 
 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)"
+3. If PRD already has epics, inform user and use AskUserQuestion:
+   ```json
+   {
+     "questions": [{
+       "question": "This PRD already has {count} epics. What would you like to do?",
+       "header": "Epics",
+       "options": [
+         {"label": "Add more epics", "description": "Keep existing epics and add new ones"},
+         {"label": "View existing", "description": "See current epic structure before deciding"},
+         {"label": "Start fresh", "description": "Delete existing epics and recreate from scratch"}
+       ],
+       "multiSelect": false
+     }]
+   }
+   ```
 
 ### Step 2: Analyze & Identify Epics
 
@@ -141,9 +168,20 @@ Ready to create these epics?
 ```
 
 Use AskUserQuestion only when uncertain:
-- Create all epics (Recommended)
-- Modify structure first
-- Add/remove epics
+```json
+{
+  "questions": [{
+    "question": "Ready to create these epics?",
+    "header": "Confirm",
+    "options": [
+      {"label": "Create all epics (Recommended)", "description": "Proceed with the proposed structure"},
+      {"label": "Modify structure first", "description": "Adjust epic boundaries or dependencies"},
+      {"label": "Add/remove epics", "description": "Change the number of epics"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
 ### Step 4: Create Epics
 

package/commands/dashboard.md

@@ -0,0 +1,29 @@
+---
+name: flux:dashboard
+description: Open the Flux Dashboard to visualize PRDs, epics, and tasks
+allowed-tools: Bash
+---
+
+# Flux Dashboard
+
+Launch the Flux Dashboard web interface to visualize project status.
+
+## Instructions
+
+Run the dashboard server:
+
+```bash
+bunx @cliangdev/flux-plugin dashboard
+```
+
+This will:
+1. Start the dashboard server on port 3333 (or next available)
+2. Open the dashboard in the default browser
+
+The dashboard shows:
+- All PRDs with their epics and tasks
+- Status indicators and progress
+- Dependency graph visualization
+- Detailed views for each entity
+
+Tell the user the dashboard is starting and they can close it with Ctrl+C when done.

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
@@ -61,8 +61,100 @@ The orchestrator resolves all refs to tasks, builds a dependency-ordered queue,
    - Mixed refs: Resolve each, deduplicate, merge
    - `tag:{name}`: Query PRDs by tag → expand all
 
+2. Git state check (REQUIRED before any implementation):
+   - Run `git status` to check for uncommitted changes
+   - If dirty working tree: Ask user whether to commit, stash, or abort
+   - Never proceed with uncommitted changes
+
 ## Workflow
 
+### Step 0: Git Branch Setup
+
+**Always start from latest main with a fresh branch.** This ensures clean PRs and avoids merge conflicts.
+
+#### 0.1 Ensure Clean State
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If output is non-empty, use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "You have uncommitted changes. How would you like to proceed?",
+    "header": "Git Status",
+    "options": [
+      {"label": "Commit them first", "description": "Stage and commit current changes before starting"},
+      {"label": "Stash them", "description": "Stash changes temporarily, restore after implementation"},
+      {"label": "Abort implementation", "description": "Stop here and handle changes manually"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+#### 0.2 Create Feature Branch from Latest Main
+
+```bash
+# Fetch latest and create branch
+git fetch origin main
+git checkout -b {branch-name} origin/main
+```
+
+#### 0.3 Branch Naming Convention
+
+| Scope | Branch Name | Example |
+|-------|-------------|---------|
+| `tag:xxx` | `feat/tag-{tag}` | `feat/tag-phase-3` |
+| Single PRD | `feat/{prd-ref}` | `feat/FLUX-P3` |
+| Multiple PRDs | `feat/{first-prd-ref}` | `feat/FLUX-P3` |
+| Single Epic | `feat/{epic-ref}` | `feat/FLUX-E14` |
+| Multiple Epics | `feat/{first-epic-ref}` | `feat/FLUX-E14` |
+| Single Task | `feat/{task-ref}` | `feat/FLUX-T31` |
+| Multiple Tasks | `feat/{first-task-ref}` | `feat/FLUX-T31` |
+| No args (next task) | `feat/{task-ref}` | `feat/FLUX-T42` |
+| Mixed refs | `feat/{highest-level-ref}` | `feat/FLUX-P3` (PRD > Epic > Task) |
+
+**Priority for mixed refs**: Use the highest-level entity (PRD > Epic > Task). If multiple of the same level, use the first one alphabetically.
+
+#### 0.4 Handle Existing Branch
+
+If the branch already exists:
+```bash
+# Check if branch exists
+git rev-parse --verify feat/FLUX-P3 2>/dev/null
+```
+
+If branch exists, use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Branch 'feat/FLUX-P3' already exists. What would you like to do?",
+    "header": "Branch",
+    "options": [
+      {"label": "Continue on existing (Recommended)", "description": "Resume work on the existing branch"},
+      {"label": "Delete and recreate", "description": "Start fresh from latest main"},
+      {"label": "Use different name", "description": "Create a new branch with a different name"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+#### Example Output
+
+```
+Git Setup:
+✓ Working tree clean
+✓ Fetched origin/main
+✓ Created branch: feat/tag-phase-3
+  └── Based on: origin/main (abc1234)
+
+Ready to implement 3 PRDs (tag: phase-3)
+```
+
 ### Step 1: Gather Context
 
 Resolve all refs to a unified task list:
@@ -184,31 +276,87 @@ When spawning a coding subagent, provide this context:
 - Epic: {epic.ref} - {epic.title}
 - PRD: {prd.ref} (read if more context needed)
 
+## Project Skill (APPLY THESE PATTERNS)
+{skillContent || "No project-specific skill found. Use general best practices for this language."}
+
 ## Workflow
-1. Auto-detect project type and apply matching skill
+1. Apply the project skill patterns above (if provided)
 2. Write tests for each [auto] criterion FIRST
-3. Implement until all tests pass
-4. For [manual] criteria, document verification steps
-5. Commit with message: "{task.ref}: {brief description}"
-6. Report back: COMPLETED or BLOCKED (with reason)
+3. Write tests for critical components (business logic, data transformations, error paths)
+4. Implement until all tests pass
+5. For [manual] criteria, document verification steps
+6. Commit with message: "{task.ref}: {brief description}"
+7. Report back: COMPLETED or BLOCKED (with reason)
+
+## Code Quality Requirements
+- Write clean, modular, testable code
+- Small focused functions with clear separation of concerns
+- Inject dependencies for testability
+- NO unnecessary comments - let code be self-documenting
+- Comments only for non-obvious "why", never for "what"
+- No commented-out code
 
 ## Files to Focus On
 {relevantFiles}
 ```
 
-## Skill Auto-Detection
+**Note:** The orchestrator MUST discover and include skill content before spawning. See "Skill Discovery & Application" section above.
+
+## Skill Discovery & Application
+
+Before spawning a coding subagent, discover and load relevant project skills.
+
+### Step 1: Detect Project Type
+
+Check for project indicator files:
+
+```bash
+ls -la | head -20
+```
+
+| File Found | Project Type |
+|------------|--------------|
+| `go.mod` | Go |
+| `tsconfig.json` | TypeScript |
+| `pom.xml` / `build.gradle` | Java/Spring |
+| `package.json` + react | React |
+| `Cargo.toml` | Rust |
+| `requirements.txt` / `pyproject.toml` | Python |
+
+### Step 2: Search for Matching Skills
+
+Check `.claude/skills/` for project-specific skills:
+
+```bash
+# List available skills
+ls .claude/skills/ 2>/dev/null || echo "No skills directory"
+```
+
+**Skill matching patterns:**
+
+| Project Type | Skill Search Patterns |
+|--------------|----------------------|
+| Go | `golang*`, `go-*`, `go_*` |
+| TypeScript | `typescript*`, `ts-*`, `ts_*` |
+| Java/Spring | `java*`, `spring*`, `springboot*` |
+| React | `react*`, `ui-*`, `frontend*` |
+| Rust | `rust*` |
+| Python | `python*`, `py-*` |
+
+### Step 3: Load Skill Content
+
+If a matching skill is found, read its content:
+
+```bash
+# Read skill content
+cat .claude/skills/{skill-name}/SKILL.md
+```
 
-The coding subagent detects project type and applies matching skills:
+### Step 4: Pass Skill to Subagent
 
-| Detection | Skill | Patterns Applied |
-|-----------|-------|------------------|
-| `pom.xml` | `springboot-patterns` | DDD, transactions, Java style |
-| `tsconfig.json` | `typescript-patterns` | Async/await, typed errors |
-| `package.json` + React | `ui-patterns` | Components, Tailwind, dark mode |
-| `go.mod` | Go patterns | Error handling, interfaces |
-| `Cargo.toml` | Rust patterns | Result types, ownership |
+Include the skill content in the coding subagent prompt (see template below).
 
-Detection happens at subagent spawn time by checking project root files.
+**Important:** If no matching skill is found, the subagent falls back to general best practices for that language.
 
 ## Status Management
 
@@ -312,3 +460,5 @@ Action needed: Resolve blockers, then run `/flux:implement FP-T45`
 - **Fail fast**: Report blockers immediately
 - **One commit per task**: Keep history clean
 - **TDD always**: Tests before implementation
+- **Test critical components**: Not just acceptance criteria - test business logic, transformations, error paths
+- **Clean code**: Modular, testable, self-documenting - no unnecessary comments