@cliangdev/flux-plugin 0.2.0-dev.dc5e2c4 → 0.2.0-dev.e8f7aab

package/README.md

@@ -36,7 +36,7 @@ The installer automatically:
 | Command | Purpose |
 |---------|---------|
 | `/flux` | Smart entry point - shows status and guides you to the next step |
-| `/flux:prd` | Create product requirements through guided interview |
+| `/flux:prd` | Create PRDs through discovery, research, and guided writing |
 | `/flux:breakdown` | Break PRDs into epics and tasks with acceptance criteria |
 | `/flux:implement` | Implement tasks with TDD workflow |
 
@@ -143,7 +143,7 @@ Check your current version:
 
 ```bash
 rm -rf ~/.claude/commands/flux.md ~/.claude/commands/flux
-rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-template
+rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-writer
 rm -f ~/.claude/flux-version
 # Edit ~/.claude.json and remove the "flux" entry from "mcpServers"
 ```
@@ -152,7 +152,7 @@ rm -f ~/.claude/flux-version
 
 ```bash
 rm -rf .claude/commands/flux.md .claude/commands/flux
-rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-template
+rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-writer
 rm -f .claude/flux-version
 # Edit .claude.json and remove the "flux" entry from "mcpServers"
 ```

package/agents/coder.md

@@ -20,30 +20,41 @@ You receive only:
 
 This keeps your context clean for high-quality code output.
 
-## Step 1: Detect Project Type & Apply Skill
+## Step 1: Apply Project Skill
 
-Before coding, detect the project type and apply the matching skill:
+The orchestrator should provide a **Project Skill** section in your prompt with patterns to follow. If provided, strictly follow those patterns for:
+- Code structure and organization
+- Error handling conventions
+- Testing patterns
+- Naming conventions
+
+### Fallback: Discover Skill Yourself
+
+If no skill was provided in your prompt, discover and load it:
 
 ```bash
-# Check for project indicators
+# 1. Detect project type
 ls -la | head -20
+
+# 2. Check for matching skill in .claude/skills/
+ls .claude/skills/ 2>/dev/null
 ```
 
-| File Found | Project Type | Skill to Apply |
-|------------|--------------|----------------|
-| `pom.xml` | Java/Spring Boot | `springboot-patterns` |
-| `build.gradle` | Java/Gradle | `springboot-patterns` |
-| `tsconfig.json` | TypeScript | `typescript-patterns` |
-| `package.json` + `react` | React | `ui-patterns` |
-| `go.mod` | Go | Go idioms |
-| `Cargo.toml` | Rust | Rust idioms |
-| `requirements.txt` / `pyproject.toml` | Python | Python idioms |
+| File Found | Project Type | Skill Search Pattern |
+|------------|--------------|---------------------|
+| `go.mod` | Go | `golang*`, `go-*` |
+| `tsconfig.json` | TypeScript | `typescript*`, `ts-*` |
+| `pom.xml` / `build.gradle` | Java/Spring | `java*`, `spring*` |
+| `package.json` + react | React | `react*`, `ui-*` |
+| `Cargo.toml` | Rust | `rust*` |
+| `requirements.txt` | Python | `python*`, `py-*` |
 
-**Apply the skill mentally** - follow its patterns for:
-- Code structure and organization
-- Error handling conventions
-- Testing patterns
-- Naming conventions
+```bash
+# 3. Read matching skill
+cat .claude/skills/{matched-skill}/SKILL.md
+```
+
+**Apply the loaded skill patterns** - if no matching skill exists, use general best practices for that language.
 
 ## Step 2: Understand the Task
 
@@ -61,10 +72,11 @@ Acceptance Criteria:
 
 ## Step 3: Write Tests First (TDD)
 
+### 3.1 Tests for Acceptance Criteria
+
 For each `[auto]` criterion, write a failing test:
 
 ```typescript
-// Example for TypeScript
 describe('Login API', () => {
   it('returns 401 for invalid credentials', async () => {
     const response = await api.post('/login', {
@@ -82,6 +94,34 @@ describe('Login API', () => {
 });
 ```
 
+### 3.2 Tests for Critical Components
+
+Beyond acceptance criteria, also test:
+
+- **Core business logic**: Functions that make important decisions
+- **Data transformations**: Parsing, validation, mapping functions
+- **Error paths**: Edge cases and failure scenarios
+- **Integration points**: API handlers, database operations
+- **Utilities used in multiple places**: Shared helpers and utils
+
+```typescript
+describe('SessionManager', () => {
+  it('expires sessions after TTL', async () => {
+    const session = await sessionManager.create(userId);
+    await advanceTime(SESSION_TTL + 1000);
+    expect(await sessionManager.isValid(session.id)).toBe(false);
+  });
+
+  it('handles concurrent session creation', async () => {
+    const results = await Promise.all([
+      sessionManager.create(userId),
+      sessionManager.create(userId),
+    ]);
+    expect(results[0].id).not.toBe(results[1].id);
+  });
+});
+```
+
 Run tests to confirm they fail:
 ```bash
 bun test login.test.ts
@@ -103,6 +143,81 @@ Write minimal code to make tests pass:
 bun test
 ```
 
+## Code Quality Standards
+
+### Write Clean, Modular, Testable Code
+
+**Modularity**
+- Small, focused functions that do one thing well
+- Clear separation of concerns (business logic vs I/O vs presentation)
+- Dependencies injected, not hardcoded - makes testing easy
+- Extract reusable logic into well-named helper functions
+
+```typescript
+// ✅ Good: Modular, testable
+function validateCredentials(email: string, password: string): ValidationResult {
+  if (!isValidEmail(email)) return { valid: false, error: 'Invalid email' };
+  if (password.length < 8) return { valid: false, error: 'Password too short' };
+  return { valid: true };
+}
+
+async function login(credentials: Credentials, userRepo: UserRepository) {
+  const validation = validateCredentials(credentials.email, credentials.password);
+  if (!validation.valid) throw new ValidationError(validation.error);
+  return userRepo.findByEmail(credentials.email);
+}
+
+// ❌ Bad: Monolithic, hard to test
+async function login(email: string, password: string) {
+  // validation mixed with business logic mixed with database calls
+  const db = getDatabase();
+  if (!email.includes('@')) throw new Error('bad email');
+  const user = await db.query('SELECT * FROM users WHERE email = ?', [email]);
+  // ... more mixed concerns
+}
+```
+
+**Testability**
+- Pure functions where possible (same input → same output)
+- Side effects isolated and explicit
+- Avoid global state
+- Use interfaces/types for dependencies
+
+### No Unnecessary Comments
+
+Let code be self-documenting. Comments should explain **why**, not **what**.
+
+```typescript
+// ❌ Bad: Comments that restate the code
+// Check if user is admin
+if (user.role === 'admin') {
+  // Grant admin access
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Code explains itself
+if (user.role === 'admin') {
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Comment explains non-obvious "why"
+// Rate limit bypass for internal services to prevent cascade failures
+if (request.source === 'internal') {
+  skipRateLimit = true;
+}
+```
+
+**When to comment:**
+- Non-obvious business rules or edge cases
+- Workarounds for external bugs/limitations
+- Performance optimizations that sacrifice readability
+- Public API documentation (JSDoc for library interfaces)
+
+**Never comment:**
+- What the code does (let naming convey this)
+- Obvious operations
+- Commented-out code (delete it, git has history)
+
 ## Step 5: Handle Manual Criteria
 
 For `[manual]` criteria, add a comment or doc noting verification steps:
@@ -174,13 +289,23 @@ Needs:
 
 ## Boundaries
 
-- **DO** focus only on the assigned task
-- **DO** write tests before implementation
-- **DO** follow detected skill patterns
-- **DON'T** refactor unrelated code
-- **DON'T** add features not in acceptance criteria
-- **DON'T** skip tests for `[auto]` criteria
-- **DON'T** make commits without running tests
+**DO:**
+- Focus only on the assigned task
+- Apply project skill patterns from your prompt (or discover them from `.claude/skills/`)
+- Write tests before implementation
+- Test critical components beyond just acceptance criteria
+- Write clean, modular, testable code
+- Use clear naming that makes code self-documenting
+
+**DON'T:**
+- Ignore provided skill patterns - they contain project-specific conventions
+- Refactor unrelated code
+- Add features not in acceptance criteria
+- Skip tests for `[auto]` criteria
+- Make commits without running tests
+- Add comments that restate what code does
+- Add unnecessary JSDoc/docstrings for simple functions
+- Leave commented-out code
 
 ## Context Escalation
 

package/bin/install.cjs

@@ -21,6 +21,19 @@ if (args[0] === "serve") {
 		process.exit(1);
 	});
 	child.on("close", (code) => process.exit(code || 0));
+} else if (args[0] === "dashboard") {
+	const dashboardSrc = path.join(__dirname, "..", "src", "dashboard", "server.ts");
+	const bunPath = getBunPath();
+	if (!bunPath) {
+		console.error("Failed to start Flux Dashboard: Bun is required but not found");
+		process.exit(1);
+	}
+	const child = spawn(bunPath, ["run", dashboardSrc], { stdio: "inherit" });
+	child.on("error", (err) => {
+		console.error("Failed to start Flux Dashboard:", err.message);
+		process.exit(1);
+	});
+	child.on("close", (code) => process.exit(code || 0));
 } else {
 	runInstaller();
 }
@@ -66,7 +79,12 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
 	console.log(banner);
 
 	if (hasHelp) {
-		console.log(`  ${yellow}Usage:${reset} bunx @cliangdev/flux-plugin [options]
+		console.log(`  ${yellow}Usage:${reset} bunx @cliangdev/flux-plugin [command] [options]
+
+  ${yellow}Commands:${reset}
+    ${cyan}(none)${reset}          Run the installer (default)
+    ${cyan}serve${reset}           Start the MCP server
+    ${cyan}dashboard${reset}       Open the Flux Dashboard in browser
 
   ${yellow}Options:${reset}
     ${cyan}-g, --global${reset}    Install globally (to ~/.claude)
@@ -83,6 +101,9 @@ ${cyan}  ███████╗██╗     ██╗   ██╗██╗
     ${dim}# Install locally (current project only)${reset}
     bunx @cliangdev/flux-plugin --local
 
+    ${dim}# Open the dashboard${reset}
+    bunx @cliangdev/flux-plugin dashboard
+
   ${yellow}Note:${reset} This plugin requires Bun. Install from https://bun.sh
 `);
 		process.exit(0);

package/commands/breakdown.md

@@ -16,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
@@ -78,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
 
@@ -142,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

@@ -6,27 +6,78 @@ 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.
+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
+
+## Available Commands
+
+| 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 |
+
+## Subcommand Routing
+
+When user provides arguments, route to the appropriate command:
+
+| 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)
 
-## Subcommands
+## Main Flow
 
-- `/flux version` - Show plugin version (call `get_version`)
-- `/flux linear` - Connect to Linear (delegate to `/flux:linear`)
+### Step 0: Check for Subcommands
 
-## Main Flow
+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: Get Project Context
+### Step 1: Check Project State
 
-Call `get_project_context` to check project state.
+If no subcommand, call `render_status` with `{view: "summary"}` to show current state.
 
-### Step 2: Route Based on State
+### Step 2: Route Based on Response
 
-**If `initialized: false`:**
+**If error with `code: "PROJECT_NOT_INITIALIZED"`:**
 → 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)
+**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
 
 ## Initialization Flow
 
@@ -148,9 +199,38 @@ When determining actions:
 | 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
 
 - 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