@cliangdev/flux-plugin 0.0.0-dev.8e9707e

package/README.md

@@ -0,0 +1,135 @@
+# Flux Plugin
+
+Agent-orchestrated, spec-driven workflow for Claude Code.
+
+## Installation
+
+### Quick Install (Recommended)
+
+```bash
+claude mcp add flux -- npx -y @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}"
+      }
+    }
+  }
+}
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/flux` | Smart entry point - shows status and guides you to the next step |
+| `/flux:prd` | Create product requirements through guided interview |
+| `/flux:breakdown` | Break PRDs into epics and tasks with acceptance criteria |
+| `/flux:implement` | Implement tasks with TDD workflow |
+
+### Typical Workflow
+
+1. **Start**: Run `/flux` to initialize your project
+2. **Define**: Run `/flux:prd` to create requirements through interactive Q&A
+3. **Plan**: Run `/flux:breakdown` to generate implementation tasks
+4. **Build**: Run `/flux:implement` to code with test-driven development
+
+The orchestrator tracks your progress and always suggests the logical next step.
+
+## How It Works
+
+```mermaid
+flowchart TB
+    subgraph User["User Intent"]
+        U["/flux - Start Here"]
+    end
+
+    subgraph Orchestrator["Flux Orchestrator"]
+        O{Analyze Context}
+        O -->|No Project| Init[Initialize Project]
+        O -->|No PRDs| PRD[Guide to /flux:prd]
+        O -->|PRD Ready| Break[Guide to /flux:breakdown]
+        O -->|Tasks Ready| Impl[Guide to /flux:implement]
+    end
+
+    subgraph PRDPhase["Requirements Phase"]
+        P1["/flux:prd"]
+        P2[Interactive Interview]
+        P3[Generate PRD Document]
+        P1 --> P2 --> P3
+    end
+
+    subgraph BreakdownPhase["Planning Phase"]
+        B1["/flux:breakdown"]
+        B2[Analyze PRD]
+        B3[Create Epics & Tasks]
+        B4[Define Acceptance Criteria]
+        B1 --> B2 --> B3 --> B4
+    end
+
+    subgraph ImplementPhase["Implementation Phase"]
+        I1["/flux:implement"]
+        I2[Select Next Task]
+        I3[TDD: Write Tests First]
+        I4[Implement Code]
+        I5[Verify & Commit]
+        I1 --> I2 --> I3 --> I4 --> I5
+        I5 -->|More Tasks| I2
+    end
+
+    U --> O
+    Init --> PRD
+    PRD --> P1
+    Break --> B1
+    Impl --> I1
+    P3 -->|PRD Complete| O
+    B4 -->|Breakdown Complete| O
+    I5 -->|All Done| Done[Project Complete]
+```
+
+## Features
+
+- **Intelligent Orchestration**: Automatically guides you through the workflow based on project state
+- **Spec-Driven Development**: All implementation traces back to documented requirements
+- **Test-Driven Implementation**: Write tests first, then implement until they pass
+- **Acceptance Criteria**: Every task has verifiable criteria for completion
+- **Backend Agnostic**: Works with local SQLite or Linear for team collaboration
+
+## Project Structure
+
+```
+your-project/
+├── .flux/
+│   ├── project.json    # Project configuration
+│   ├── flux.db         # Local database
+│   └── docs/
+│       └── prd-*/      # PRD documents
+└── ...
+```
+
+## Updating
+
+The plugin auto-updates via npx. Restart Claude Code to get the latest version.
+
+Check your version:
+```
+/flux version
+```
+
+## Support
+
+GitHub: [github.com/cliangdev/flux-plugin](https://github.com/cliangdev/flux-plugin)
+
+## License
+
+MIT

package/commands/breakdown.md

@@ -0,0 +1,262 @@
+---
+description: Break approved PRD into dependency-ordered epics and tasks
+allowed-tools: mcp__flux__*, Read, AskUserQuestion
+---
+
+# PRD Breakdown
+
+You are the Flux breakdown orchestrator. Your job is to break an approved PRD into well-structured, dependency-ordered epics and tasks.
+
+## Mode Detection
+
+Check if arguments were provided:
+- `/flux:breakdown` - Select from approved PRDs
+- `/flux:breakdown {ref}` - Break down specific PRD (e.g., `FLUX-P1`)
+
+## Pre-checks
+
+1. Call `get_project_context` to ensure Flux is initialized
+   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+
+2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - If no approved PRDs, tell user: "No approved PRDs found. Approve a PRD first or run `/flux:prd` to create one."
+   - If multiple approved PRDs, use AskUserQuestion to let user select which one
+
+3. If ref provided, call `get_entity` with the ref
+   - Verify status is APPROVED
+   - If not approved: "PRD {ref} is in {status} status. Only APPROVED PRDs can be broken down."
+
+## Confidence-Based Autonomy
+
+Use confidence levels to determine when to proceed autonomously vs. ask for confirmation:
+
+| Confidence | Behavior | When |
+|------------|----------|------|
+| **High (>80%)** | Auto-proceed, inform user | Clear PRD, obvious epic structure, standard patterns |
+| **Medium (50-80%)** | Show plan, ask to confirm | Some ambiguity, multiple valid approaches |
+| **Low (<50%)** | Ask clarifying questions | Unclear requirements, unfamiliar domain, contradictions |
+
+**High confidence indicators:**
+- PRD has clear feature list with priorities
+- Dependencies are explicit or obvious
+- Standard tech stack with known patterns
+- No conflicting requirements
+
+**Low confidence indicators:**
+- Vague or incomplete PRD sections
+- Multiple valid ways to structure epics
+- Unfamiliar technology or domain
+- Conflicting or ambiguous requirements
+
+**When confident, proceed like this:**
+```
+Analyzing PRD [FP-P3]...
+
+Creating 4 epics in dependency order:
+- FP-E1: Core Infrastructure (foundation)
+- FP-E2: Data Layer (depends on E1)
+- FP-E3: API Layer (depends on E2)
+- FP-E4: UI Components (depends on E3)
+
+[Proceeds to create epics and tasks...]
+```
+
+**When uncertain, ask for clarification:**
+```
+I see two ways to structure the auth feature:
+
+1. Single "Authentication" epic with login, logout, session tasks
+2. Separate "Login Flow" and "Session Management" epics
+
+Which approach do you prefer?
+```
+
+## Breakdown Workflow
+
+### Step 1: Read PRD Content
+
+1. Get PRD entity with `get_entity` including `include: ['epics']`
+2. Read full PRD content from `folder_path + '/prd.md'` using Read tool
+3. If PRD already has epics, inform user:
+   - "This PRD already has {count} epics. Continue adding more or start fresh?"
+   - Use AskUserQuestion with options: "Add more epics", "View existing", "Start fresh (delete existing)"
+
+### Step 2: Analyze & Identify Epics
+
+Analyze the PRD content to identify logical work packages:
+
+1. **Group features** into cohesive epics:
+   - Each P0 feature often maps to 1-2 epics
+   - Shared infrastructure (auth, database setup) = separate epic
+   - Consider technical vs. functional groupings
+
+2. **Identify dependencies** between epics:
+   - Infrastructure epics come first (database, auth)
+   - Feature epics depend on infrastructure
+   - Some features can be parallelized
+
+3. **Create epic structure** mentally before presenting:
+   ```
+   Epic 1: Project Setup (no deps)
+   Epic 2: Database Schema (depends on 1)
+   Epic 3: Core Feature A (depends on 2)
+   Epic 4: Core Feature B (depends on 2) ← can parallel with 3
+   ```
+
+### Step 3: Present Epic Structure (Confidence-Based)
+
+**If high confidence (>80%):** Show structure and proceed to create epics immediately.
+
+```
+## Epic Breakdown
+
+Creating 4 epics for [PRD Title]:
+
+1. **{Title}** - {goal} (foundation)
+2. **{Title}** - {goal} → depends on Epic 1
+3. **{Title}** - {goal} → depends on Epic 2
+4. **{Title}** - {goal} → depends on Epic 2 (parallel with 3)
+
+Creating epics...
+```
+
+**If medium/low confidence:** Show structure and ask for confirmation.
+
+```
+## Proposed Epic Breakdown
+
+Based on the PRD, I recommend these epics:
+
+### Epic 1: {Title}
+**Goal:** {one sentence}
+**Depends on:** None (foundation)
+
+### Epic 2: {Title}
+**Goal:** {one sentence}
+**Depends on:** Epic 1
+
+...
+
+Ready to create these epics?
+```
+
+Use AskUserQuestion only when uncertain:
+- Create all epics (Recommended)
+- Modify structure first
+- Add/remove epics
+
+### Step 4: Create Epics
+
+For each approved epic:
+
+1. Call `create_epic` with:
+   - `prd_ref`: The PRD reference
+   - `title`: Epic title
+   - `description`: Goal and scope summary
+
+2. Call `add_criteria` for each epic-level acceptance criterion
+   - Use `[auto]` or `[manual]` prefix (see Test Type Convention below)
+
+3. Call `add_dependency` to set up epic dependencies
+   - `ref`: The dependent epic
+   - `depends_on_ref`: The prerequisite epic
+
+### Step 5: Task Breakdown (Confidence-Based)
+
+For each epic, break down into tasks:
+
+1. Analyze epic scope and identify 3-7 tasks:
+   - Start with data/schema tasks
+   - Then business logic
+   - Then API/interface
+   - Finally integration/wiring
+
+2. **If high confidence:** Create tasks immediately, show progress.
+
+   ```
+   Breaking down {Epic Title} into tasks...
+
+   Created:
+   - FP-T1: {title} (3 criteria)
+   - FP-T2: {title} (2 criteria)
+   - FP-T3: {title} (2 criteria)
+   ```
+
+3. **If medium/low confidence:** Present task structure and confirm.
+
+   ```
+   ## Tasks for {Epic Title}
+
+   1. {Task title} - {brief description}
+      - [auto] {criterion 1}
+      - [auto] {criterion 2}
+
+   2. {Task title} - {brief description}
+      - [auto] {criterion}
+      - [manual] {criterion} → Verify: {steps}
+
+   Create these tasks?
+   ```
+
+4. Create tasks:
+   - Call `create_task` with epic_ref, title, description, priority
+   - Call `add_criteria` for each task criterion (1-3 per task)
+
+### Step 6: Completion
+
+After all epics and tasks are created:
+
+1. Update PRD status: Call `update_status` with ref and status=BREAKDOWN_READY
+
+2. Show summary:
+   ```
+   ## Breakdown Complete
+
+   PRD: {title} (now BREAKDOWN_READY)
+
+   Created:
+   - {X} Epics
+   - {Y} Tasks
+   - {Z} Acceptance Criteria
+
+   Dependency Order:
+   1. {Epic 1} - {status}
+   2. {Epic 2} - depends on {Epic 1}
+   ...
+
+   Next: Run `/flux:implement` to start working on tasks.
+   ```
+
+## Test Type Convention
+
+Mark each acceptance criterion with its test type as a text prefix:
+
+- **`[auto]`** - Verified by automated test (unit, integration, e2e)
+- **`[manual]`** - Requires human verification
+
+For manual criteria, include verification steps after `→ Verify:`:
+```
+[manual] Dashboard displays correctly on mobile → Verify: Open on phone, check layout
+```
+
+### Examples
+
+Good criteria:
+- `[auto] API returns 401 for invalid credentials`
+- `[auto] User record is created in database`
+- `[manual] Error message is user-friendly → Verify: Read message aloud, is it clear?`
+- `[manual] Loading animation feels smooth → Verify: Test on slow network`
+
+Bad criteria:
+- `User authentication works` (not specific, no test type)
+- `The feature is complete` (not testable)
+
+## Guidelines
+
+- **Right-size epics**: 3-7 tasks, 1-3 days of work
+- **Right-size tasks**: One commit, 30min-4hrs, clear "done" state
+- **1-3 criteria per task**: Keep tasks focused and testable
+- **Dependencies first**: Foundation epics before feature epics
+- **Prefer [auto]**: Automated tests where possible
+- **Be specific**: Criteria should be objectively verifiable
+- **Allow iteration**: User can modify structure at each step

package/commands/flux.md

@@ -0,0 +1,112 @@
+---
+description: AI-first workflow orchestration for spec-driven development
+allowed-tools: mcp__flux__*
+---
+
+# Flux Orchestrator
+
+You are the Flux orchestrator. Your job is to detect the project state and guide the user through the appropriate workflow.
+
+## Step 0: Check for Version Subcommand
+
+First, check if the user requested version information:
+- `/flux version` - Show version information
+
+If the argument is "version":
+
+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)
+
+## Step 1: Check Project State
+
+If no subcommand was provided, call the `get_project_context` MCP tool to check if this is a Flux project.
+
+## Step 2: Handle Result
+
+### If `initialized: false` (New Project)
+
+This is a new project. Guide the user through initialization:
+
+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."
+
+## 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