@cliangdev/flux-plugin 0.0.0-dev.0da1574

package/commands/flux.md

@@ -0,0 +1,156 @@
+---
+name: flux
+description: AI-first workflow orchestration for spec-driven development
+allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion, Read, Write
+---
+
+# Flux Command
+
+You are the Flux orchestrator. Detect project state and guide the user to the appropriate next action.
+
+## Subcommands
+
+- `/flux version` - Show plugin version (call `get_version`)
+- `/flux linear` - Connect to Linear (delegate to `/flux:linear`)
+
+## Main Flow
+
+### Step 1: Get Project Context
+
+Call `get_project_context` to check project state.
+
+### Step 2: Route Based on State
+
+**If `initialized: false`:**
+→ Guide through initialization (see Initialization Flow below)
+
+**If `initialized: true`:**
+→ Call `render_status` with `{view: "summary"}` to show current state
+→ Determine next action based on workflow state (see Workflow States)
+
+## Initialization Flow
+
+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."
+
+### Step 2: Collect Project Details
+
+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 |
+
+## Guidelines
+
+- 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/implement.md

@@ -0,0 +1,315 @@
+---
+name: flux:implement
+description: Implement epics and tasks with orchestrator/subagent architecture
+allowed-tools: mcp__flux__*, Read, Bash, Task, AskUserQuestion
+---
+
+# Implementation Workflow
+
+You are the Flux implementation orchestrator. Your job is to coordinate implementation across epics and tasks, delegating coding work to specialized subagents while maintaining clean context.
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                  ORCHESTRATOR (You)                      │
+│  • Hold PRD/epic/task context                           │
+│  • Determine work assignment                            │
+│  • Manage dependencies                                  │
+│  • Spawn coding subagents                               │
+│  • Track progress and status                            │
+└─────────────┬───────────────────────────┬───────────────┘
+              │                           │
+              ▼                           ▼
+┌─────────────────────┐     ┌─────────────────────┐
+│   CODING SUBAGENT   │     │   CODING SUBAGENT   │
+│   (Task A)          │     │   (Task B)          │
+│                     │     │                     │
+│   • Minimal context │     │   • Minimal context │
+│   • Task + AC only  │     │   • Task + AC only  │
+│   • TDD workflow    │     │   • TDD workflow    │
+│   • Auto-detect     │     │   • Auto-detect     │
+│     skill           │     │     skill           │
+└─────────────────────┘     └─────────────────────┘
+```
+
+## Scope
+
+The orchestrator accepts any combination of PRDs, epics, or tasks:
+
+```
+/flux:implement                         → Pick next available task
+/flux:implement FP-P3                   → Implement entire PRD
+/flux:implement FP-P3 FP-P4             → Implement multiple PRDs
+/flux:implement FP-E14                  → Implement specific epic
+/flux:implement FP-E14 FP-E15 FP-E16    → Implement multiple epics
+/flux:implement FP-T31                  → Implement specific task
+/flux:implement FP-T31 FP-T32 FP-T33    → Implement multiple tasks
+/flux:implement FP-P3 FP-E20 FP-T99     → Mixed: PRD + epic + task
+/flux:implement tag:phase-3             → All PRDs with tag
+```
+
+The orchestrator resolves all refs to tasks, builds a dependency-ordered queue, and assigns work to subagents.
+
+## Pre-checks
+
+1. Call `get_project_context` to ensure Flux is initialized
+2. Parse arguments and resolve to tasks:
+   - 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
+   - Task ref(s): Use directly
+   - Mixed refs: Resolve each, deduplicate, merge
+   - `tag:{name}`: Query PRDs by tag → expand all
+
+## Workflow
+
+### Step 1: Gather Context
+
+Resolve all refs to a unified task list:
+
+```typescript
+// Collect all tasks from various input types
+const allTasks = []
+
+for (const ref of inputRefs) {
+  if (ref.startsWith('tag:')) {
+    // Tag → PRDs → Epics → Tasks
+    const prds = query_entities({ type: 'prd', tag: ref.slice(4) })
+    for (const prd of prds) {
+      const epics = query_entities({ type: 'epic', prd_ref: prd.ref })
+      for (const epic of epics) {
+        allTasks.push(...getTasks(epic.ref))
+      }
+    }
+  } else if (ref.includes('-P')) {
+    // PRD → Epics → Tasks
+    const epics = query_entities({ type: 'epic', prd_ref: ref })
+    for (const epic of epics) {
+      allTasks.push(...getTasks(epic.ref))
+    }
+  } else if (ref.includes('-E')) {
+    // Epic → Tasks
+    allTasks.push(...getTasks(ref))
+  } else if (ref.includes('-T')) {
+    // Task directly
+    allTasks.push(get_entity({ ref, include: ['criteria'] }))
+  }
+}
+
+// Deduplicate by ref
+const taskQueue = dedupe(allTasks)
+```
+
+### Step 2: Build Work Queue
+
+Order tasks by:
+1. Epic dependencies (foundational epics first)
+2. Task dependencies within epics
+3. Priority (HIGH → MEDIUM → LOW)
+
+```
+Work Queue:
+1. FP-T31 (FP-E14, no deps, HIGH)
+2. FP-T32 (FP-E14, no deps, MEDIUM)
+3. FP-T33 (FP-E14, depends on T31, HIGH)
+...
+```
+
+### Step 3: Check for Parallelization
+
+Identify tasks that can run in parallel:
+- Different repos (no file conflicts)
+- No dependencies between them
+- Independent epics
+
+```
+Parallel Groups:
+- Group A: FP-T31, FP-T32 (same epic, no deps)
+- Group B: FP-T45 (different repo)
+```
+
+### Step 4: Spawn Coding Subagents
+
+For each task (or parallel group), spawn a coding subagent:
+
+```typescript
+// Single task
+Task({
+  subagent_type: "flux:flux-coder",
+  prompt: buildCoderPrompt(task),
+  description: `Implement ${task.ref}`
+})
+
+// Parallel tasks (different repos)
+Task({
+  subagent_type: "flux:flux-coder",
+  prompt: buildCoderPrompt(taskA),
+  run_in_background: true
+})
+Task({
+  subagent_type: "flux:flux-coder",
+  prompt: buildCoderPrompt(taskB),
+  run_in_background: true
+})
+```
+
+### Step 5: Monitor Progress
+
+For background agents:
+1. Check output files periodically
+2. Wait for all parallel tasks to complete before dependent tasks
+3. Update status as tasks complete
+
+### Step 6: Epic Completion
+
+When all tasks in an epic are COMPLETED:
+1. Mark epic as COMPLETED
+2. Notify user of manual verification items
+3. Proceed to next epic or suggest PR
+
+## Coding Subagent Prompt Template
+
+When spawning a coding subagent, provide this context:
+
+```markdown
+# Task: {task.ref} - {task.title}
+
+## Description
+{task.description}
+
+## Acceptance Criteria
+{task.criteria.map(c => `- ${c.criteria}`).join('\n')}
+
+## Context
+- Epic: {epic.ref} - {epic.title}
+- PRD: {prd.ref} (read if more context needed)
+
+## Workflow
+1. Auto-detect project type and apply matching skill
+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)
+
+## Files to Focus On
+{relevantFiles}
+```
+
+## Skill Auto-Detection
+
+The coding subagent detects project type and applies matching skills:
+
+| 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 |
+
+Detection happens at subagent spawn time by checking project root files.
+
+## Status Management
+
+### Task Status Flow
+```
+PENDING → IN_PROGRESS → COMPLETED
+                     ↘ BLOCKED (if issues)
+```
+
+### Update Commands
+```typescript
+// When starting task
+update_status({ ref: taskRef, status: 'IN_PROGRESS' })
+
+// When task complete
+update_status({ ref: taskRef, status: 'COMPLETED' })
+mark_criteria_met({ criteria_id: criterionId })  // for each AC
+
+// When epic complete
+update_status({ ref: epicRef, status: 'COMPLETED' })
+```
+
+## Commit Convention
+
+Each task = one commit with this format:
+
+```
+{TASK-REF}: {brief description}
+
+- {bullet point of what changed}
+- {another change}
+
+Acceptance Criteria:
+- [x] {criterion 1}
+- [x] {criterion 2}
+```
+
+Example:
+```
+FP-T31: Add breakdown command file
+
+- Created commands/breakdown.md with YAML frontmatter
+- Added epic/task breakdown workflow
+- Included confidence-based autonomy
+
+Acceptance Criteria:
+- [x] [auto] Command file exists with proper YAML frontmatter
+```
+
+## Example: Mixed Scope Implementation
+
+```
+/flux:implement FP-P3 FP-E20 FP-T99
+
+Resolving refs...
+
+Scope:
+- FP-P3: 4 epics, 19 tasks
+- FP-E20: 5 tasks
+- FP-T99: 1 task
+
+Work Queue (25 tasks, deduplicated):
+├── FP-E14 (4 tasks) ─┐
+├── FP-E15 (3 tasks) ─┼── FP-P3
+├── FP-E16 (9 tasks) ─┤
+├── FP-E17 (3 tasks) ─┘
+├── FP-E20 (5 tasks) ←── standalone epic
+└── FP-T99 (1 task)  ←── standalone task
+
+Parallelization:
+- FP-E14 tasks: sequential (same repo)
+- FP-E20 tasks: parallel with FP-E14 (different repo)
+
+Starting implementation...
+```
+
+## Error Handling
+
+If a subagent reports BLOCKED:
+1. Log the blocker reason
+2. Skip dependent tasks
+3. Continue with independent tasks
+4. Report blockers to user at end
+
+```
+## Implementation Summary
+
+Completed: 15 tasks
+Blocked: 2 tasks
+  - FP-T45: Missing API credentials
+  - FP-T46: Depends on FP-T45
+
+Action needed: Resolve blockers, then run `/flux:implement FP-T45`
+```
+
+## Guidelines
+
+- **Keep orchestrator lean**: Only hold high-level context
+- **Subagents are disposable**: Each task gets fresh context
+- **Parallelize when safe**: Different repos = parallel
+- **Fail fast**: Report blockers immediately
+- **One commit per task**: Keep history clean
+- **TDD always**: Tests before implementation

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