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

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

package/commands/prd.md

@@ -1,7 +1,7 @@
 ---
 name: flux:prd
 description: Create comprehensive PRDs through discovery, research, and guided writing
-allowed-tools: mcp__flux__*, AskUserQuestion, Read, Glob, Grep, Task, WebSearch
+allowed-tools: mcp__flux__*, AskUserQuestion, Read, Write, Glob, Grep, Task, WebSearch, Bash
 ---
 
 # PRD Creation Command
@@ -216,6 +216,181 @@ Use AskUserQuestion:
 
 **Goal**: Gather technical context to make the PRD specific and implementable.
 
+#### Step 2.0: Greenfield Detection & Essential Setup
+
+**Before exploring the codebase, check if this is a greenfield project.**
+
+##### Detection
+
+Check for project indicators using Glob:
+```
+- .git directory exists?
+- package.json / go.mod / pyproject.toml / Cargo.toml / etc.?
+- src/ or lib/ directories with code files?
+```
+
+**If ALL indicators are missing → Greenfield project → Trigger setup flow**
+
+##### Essential Setup Flow
+
+When greenfield is detected, present:
+
+```
+This looks like a new project without existing setup.
+
+Before we create the PRD, let's establish the foundation:
+
+**Git Setup**
+- Initialize repository with .gitignore for {detected/chosen tech stack}
+- Create branching structure: main + develop (git flow ready)
+- Initial commit with project structure
+
+**Project Structure** (based on {project type from Phase 1})
+{Show recommended minimal structure}
+
+**Package Setup**
+- Initialize {package.json / pyproject.toml / go.mod / etc.}
+
+Proceed with this setup?
+```
+
+Use AskUserQuestion:
+- "Yes, set up essentials" (Recommended)
+- "Customize setup first"
+- "Skip - I'll set up manually"
+
+##### Essential Setup by Project Type
+
+| Project Type | Git | Structure | Package Init |
+|--------------|-----|-----------|--------------|
+| **Web App (Node)** | .gitignore (node) | `src/`, `tests/`, `public/` | package.json |
+| **Web App (Python)** | .gitignore (python) | `src/`, `tests/` | pyproject.toml |
+| **CLI Tool (Node)** | .gitignore (node) | `src/`, `bin/`, `tests/` | package.json with bin |
+| **CLI Tool (Go)** | .gitignore (go) | `cmd/`, `internal/`, `pkg/` | go.mod |
+| **API/Backend** | .gitignore (lang) | `src/`, `tests/`, `config/` | Language-specific |
+| **Library** | .gitignore (lang) | `src/`, `tests/`, `examples/` | Language-specific |
+
+##### Executing Essential Setup
+
+When user confirms, execute via Bash:
+
+```bash
+# Git initialization
+git init
+git checkout -b main
+git checkout -b develop
+
+# Create .gitignore (use appropriate template for language)
+# Create initial directory structure (mkdir -p)
+# Initialize package manager (npm init -y / go mod init / etc.)
+
+# Initial commit
+git add .
+git commit -m "Initial project setup
+
+- Initialize git with main/develop branches
+- Add .gitignore for {language}
+- Create project structure
+- Initialize {package manager}
+
+Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>"
+
+# Return to develop for feature work
+git checkout develop
+```
+
+##### Foundation PRD Offer
+
+After essential setup completes (or if user skipped), offer comprehensive setup as a tracked PRD:
+
+```
+Foundation is ready. Would you like to track additional setup as a PRD?
+
+A Foundation PRD would cover:
+- CI/CD pipeline (GitHub Actions / GitLab CI)
+- Linting & formatting (ESLint+Prettier / Biome / Ruff)
+- Testing framework setup
+- Environment configuration (.env patterns)
+- Pre-commit hooks
+
+This gets tracked in Flux so you can implement it systematically.
+```
+
+Use AskUserQuestion:
+- "Create Foundation PRD" - Creates PRD with [tag: foundation], then continues to feature PRD
+- "Skip - continue to feature PRD" (Recommended for simple projects)
+
+##### Foundation PRD Template
+
+If user wants a Foundation PRD, create it with this structure:
+
+```markdown
+# Project Foundation
+
+> **Tag**: foundation
+> **Depends on**: None
+> **Blocks**: All feature PRDs
+
+## Problem
+
+New projects without proper tooling lead to inconsistent code quality,
+manual testing overhead, and deployment friction.
+
+## Users
+
+Developers working on this codebase.
+
+## Solution
+
+Establish development infrastructure: CI/CD, code quality tools, testing
+framework, and environment management.
+
+## Features
+
+### P0: Must Have
+
+- **CI Pipeline**: Automated testing on push/PR
+  - **What**: GitHub Actions workflow for test/lint/build
+  - **Not**: Deployment pipelines, complex matrix builds
+  - **Acceptance Criteria**:
+    - [ ] Push to any branch triggers CI
+    - [ ] PR cannot merge if CI fails
+    - [ ] CI runs tests, linting, and type checking
+
+- **Code Quality**: Linting and formatting
+  - **What**: {ESLint+Prettier / Biome / Ruff} with pre-commit hooks
+  - **Not**: Custom rules beyond standard configs
+  - **Acceptance Criteria**:
+    - [ ] Lint command runs without errors
+    - [ ] Pre-commit hook prevents unlinted commits
+    - [ ] Editor integration documented
+
+- **Testing Framework**: Test infrastructure
+  - **What**: {Jest/Vitest / Pytest / Go test} with coverage
+  - **Not**: E2E tests, integration infrastructure
+  - **Acceptance Criteria**:
+    - [ ] Test command runs and reports coverage
+    - [ ] Example test demonstrates patterns
+    - [ ] Coverage threshold set (70%)
+
+### P1: Should Have
+
+- **Environment Config**: .env management
+- **Documentation**: README with setup instructions
+
+### Out of Scope
+- Deployment pipelines
+- Production infrastructure
+- Monitoring/observability
+```
+
+After creating Foundation PRD:
+1. Save it with `tag: foundation`
+2. Continue to the user's feature PRD
+3. Set feature PRD's `Depends on: {Foundation PRD ref}`
+
+---
+
 #### Step 2.1: Codebase Research
 
 Check if there's an existing codebase to analyze: