@cliangdev/flux-plugin 0.2.0-dev.e34d43b → 0.2.0-dev.edce79d

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

@@ -21,7 +21,21 @@ Check if arguments were provided:
 
 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/implement.md

@@ -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