@cliangdev/flux-plugin 0.1.0

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@cliangdev/flux-plugin",
+  "version": "0.1.0",
+  "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
+  "type": "module",
+  "main": "./dist/server/index.js",
+  "bin": {
+    "flux-plugin": "./dist/server/index.js"
+  },
+  "files": [
+    "dist/",
+    "skills/",
+    "commands/"
+  ],
+  "scripts": {
+    "dev": "bun run src/server/index.ts",
+    "build": "bun build src/server/index.ts --outdir dist/server --target node",
+    "postbuild": "node -e \"const fs=require('fs');const f='dist/server/index.js';const c=fs.readFileSync(f,'utf-8');if(!c.startsWith('#!/usr/bin/env node')){fs.writeFileSync(f,'#!/usr/bin/env node\\n'+c)}\"",
+    "build:compile": "bun build --compile --outfile bin/flux-server src/server/index.ts && bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "build:compile:server": "bun build --compile --outfile bin/flux-server src/server/index.ts",
+    "build:compile:status": "bun build --compile --outfile bin/flux-status src/status-line/index.ts",
+    "prepublishOnly": "bun run build",
+    "test": "bun test",
+    "test:linear-description": "bun run src/server/adapters/__tests__/linear-description-test.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "verify-release": "bun run scripts/verify-release.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/cliangdev/flux-plugin.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "workflow",
+    "orchestration",
+    "ai",
+    "productivity",
+    "task-management"
+  ],
+  "author": "Chris Liang <chris@cliangdev.com>",
+  "license": "MIT",
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@types/bun": "^1.3.6",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "@linear/sdk": "^70.0.0",
+    "@modelcontextprotocol/sdk": "^1.25.2",
+    "chalk": "^5.4.1",
+    "zod": "^4.3.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/agent-creator/SKILL.md

@@ -0,0 +1,310 @@
+---
+description: Guide for creating effective subagents. Use when users want to create a new agent that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.
+---
+
+# Agent Creator Skill
+
+This skill guides the creation of well-designed Claude Code subagents following Anthropic's best practices.
+
+## When to Use This Skill
+
+- User wants to create a new subagent
+- User needs to automate a repetitive workflow
+- User wants to add domain-specific expertise to Claude
+- User is building agents for a plugin
+
+## Core Principles (from Anthropic)
+
+### 1. Start Simple
+"Find the simplest solution possible, and only increase complexity when needed."
+
+**Complexity ladder:**
+1. Single optimized prompt (try this first)
+2. Prompt chaining (fixed sequence of steps)
+3. Routing (classify input → specialized handler)
+4. Orchestrator-workers (dynamic delegation)
+5. Full autonomous agent (only if truly needed)
+
+### 2. When Agents Excel
+- Open-ended problems where steps are unpredictable
+- Tasks requiring dynamic tool selection
+- Work that benefits from iterative refinement
+- Multi-step processes with branching logic
+
+### 3. When to Avoid Agents
+- Fixed, predictable workflows → use prompt chaining
+- Single-domain tasks → use a focused prompt
+- Tasks with clear evaluation criteria → use evaluator-optimizer pattern
+
+## Subagent Architecture Patterns
+
+### Pattern 1: Specialist Agent
+Single-purpose expert for a specific domain.
+
+```markdown
+---
+name: {domain}-specialist
+description: Expert in {domain}. Use when {trigger condition}.
+tools: {minimal required tools}
+model: sonnet
+---
+
+You are an expert in {domain}.
+
+When invoked:
+1. {First action}
+2. {Second action}
+3. {Output format}
+
+Focus on: {core responsibilities}
+Avoid: {out of scope items}
+```
+
+**Use when:** Task requires deep expertise in one area.
+
+### Pattern 2: Workflow Agent
+Orchestrates a multi-step process with defined stages.
+
+```markdown
+---
+name: {workflow}-workflow
+description: Runs the {workflow} process. Use when {trigger}.
+tools: {tools for all stages}
+model: sonnet
+---
+
+You orchestrate the {workflow} process.
+
+## Workflow Stages
+
+### Stage 1: {Name}
+{What to do}
+{Success criteria}
+
+### Stage 2: {Name}
+{What to do}
+{Success criteria}
+
+### Stage 3: {Name}
+{What to do}
+{Success criteria}
+
+## Completion
+{How to know when done}
+{What to output}
+```
+
+**Use when:** Task has predictable stages but needs intelligent execution within each.
+
+### Pattern 3: Evaluator Agent
+Reviews and provides structured feedback.
+
+```markdown
+---
+name: {domain}-reviewer
+description: Reviews {what} for {criteria}. Use proactively after {trigger}.
+tools: Read, Grep, Glob
+model: inherit
+---
+
+You are a {domain} reviewer ensuring {quality standard}.
+
+## Review Checklist
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Output Format
+Organize feedback by priority:
+1. **Critical** (must fix)
+2. **Warning** (should fix)
+3. **Suggestion** (consider)
+```
+
+**Use when:** Clear evaluation criteria exist and feedback improves outcomes.
+
+### Pattern 4: Research Agent
+Gathers and synthesizes information.
+
+```markdown
+---
+name: {domain}-researcher
+description: Researches {topic area}. Use when encountering unfamiliar {domain}.
+tools: Read, Glob, Grep, WebFetch, WebSearch
+model: sonnet
+---
+
+You are a research specialist for {domain}.
+
+When asked to research:
+1. Identify key questions to answer
+2. Search for authoritative sources
+3. Synthesize findings into actionable insights
+4. Cite sources
+
+## Output Format
+### Summary
+{1-2 sentence overview}
+
+### Key Findings
+- {Finding 1}
+- {Finding 2}
+
+### Recommendations
+{How to apply findings}
+
+### Sources
+- {Source 1}
+- {Source 2}
+```
+
+**Use when:** Tasks require gathering external information.
+
+## Best Practices
+
+### 1. Write Detailed Descriptions
+The `description` field determines when Claude delegates to the subagent.
+
+**Good:**
+```yaml
+description: Expert code reviewer for TypeScript. Use proactively after writing or modifying any .ts or .tsx files. Focuses on type safety, best practices, and potential bugs.
+```
+
+**Bad:**
+```yaml
+description: Reviews code
+```
+
+### 2. Limit Tool Access
+Grant only the tools the agent needs. Less is more.
+
+| Agent Type | Typical Tools |
+|------------|---------------|
+| Read-only analyzer | `Read`, `Grep`, `Glob` |
+| Code modifier | `Read`, `Edit`, `Grep`, `Glob` |
+| Build/test runner | `Bash`, `Read`, `Glob` |
+| Research agent | `WebFetch`, `WebSearch`, `Read` |
+
+### 3. Choose the Right Model
+
+| Model | Use When |
+|-------|----------|
+| `haiku` | Fast, simple tasks; exploration; high-volume |
+| `sonnet` | Balanced capability; most agents |
+| `opus` | Complex reasoning; critical decisions |
+| `inherit` | Match parent conversation |
+
+### 4. Make Agents Proactive
+Add "use proactively" to description for autonomous invocation:
+
+```yaml
+description: Test runner that executes after code changes. Use proactively when files in src/ are modified.
+```
+
+### 5. Define Clear Completion Criteria
+Every agent should know when it's done:
+
+```markdown
+## Completion
+You are done when:
+- All tests pass
+- Coverage > 80%
+- No linting errors
+
+Output a summary of what was accomplished.
+```
+
+### 6. Handle Edge Cases
+Document what the agent should NOT do:
+
+```markdown
+## Boundaries
+- Do NOT modify files outside src/
+- Do NOT run commands that could affect production
+- If unsure, ask for clarification instead of guessing
+```
+
+## Creating an Agent: Interview Flow
+
+When helping create an agent, ask:
+
+1. **Purpose**: "What task should this agent handle?"
+2. **Trigger**: "When should it be invoked? (after code changes, on request, etc.)"
+3. **Tools**: "What capabilities does it need? (read files, edit, run commands, web search)"
+4. **Autonomy**: "Should it act proactively or wait to be called?"
+5. **Output**: "What should it produce when done?"
+
+Then generate the appropriate pattern.
+
+## File Locations
+
+| Scope | Location | Use Case |
+|-------|----------|----------|
+| User | `~/.claude/agents/` | Personal agents across all projects |
+| Project | `.claude/agents/` | Shared with team via version control |
+| Plugin | `{plugin}/agents/` | Distributed with plugin |
+
+## Example: Creating a Research Subagent
+
+**User request:** "I need an agent that researches technologies when I mention something unfamiliar"
+
+**Generated agent:**
+
+```markdown
+---
+name: tech-researcher
+description: Researches unfamiliar technologies, libraries, and APIs. Use proactively when user mentions tech that may need investigation, or when explicitly asked to research something.
+tools: WebFetch, WebSearch, Read
+model: sonnet
+---
+
+You are a technology research specialist.
+
+## When to Activate
+- User mentions a library, framework, or API you're uncertain about
+- User explicitly asks "research X" or "what is X?"
+- Confidence in technical recommendation < 70%
+
+## Research Process
+1. **Identify** the core questions to answer
+2. **Search** using WebSearch for recent, authoritative sources
+3. **Deep dive** using WebFetch on official docs, GitHub repos
+4. **Synthesize** findings relevant to user's context
+
+## Output Format
+
+### {Technology Name}
+
+**What it is:** {1-sentence description}
+
+**Key features:**
+- {Feature 1}
+- {Feature 2}
+
+**Relevance to your project:**
+{How this applies to what user is building}
+
+**Recommendations:**
+{Should they use it? Alternatives?}
+
+**Sources:**
+- [{Source title}]({url})
+```
+
+## Validation Checklist
+
+Before finalizing an agent, verify:
+
+- [ ] Description clearly states when to use it
+- [ ] Tools are minimal and appropriate
+- [ ] Model matches complexity needs
+- [ ] Prompt includes clear instructions
+- [ ] Output format is defined
+- [ ] Completion criteria are specified
+- [ ] Edge cases and boundaries are documented
+
+## References
+
+- [Building Effective Agents](https://www.anthropic.com/engineering/building-effective-agents) - Anthropic's agent design principles
+- [Claude Code Subagents](https://code.claude.com/docs/en/sub-agents) - Official subagent documentation
+- [Awesome Claude Code Subagents](https://github.com/VoltAgent/awesome-claude-code-subagents) - Community examples

package/skills/epic-template/SKILL.md

@@ -0,0 +1,156 @@
+---
+description: Epic and task structure patterns for Flux. Use when breaking PRDs into epics and tasks. Epics should be self-contained with clear acceptance criteria.
+---
+
+# Epic Template Skill
+
+Epics are **self-contained work packages** that can be implemented independently.
+
+## Epic Structure
+
+```markdown
+## {Epic Title}
+
+**Goal**: {One sentence: what does completing this epic achieve?}
+
+**Scope**:
+- IN: {What's included}
+- OUT: {What's explicitly excluded}
+
+**Tasks**:
+1. {Task title} - {brief description}
+2. {Task title} - {brief description}
+
+**Acceptance Criteria**:
+- [ ] {Testable criterion 1}
+- [ ] {Testable criterion 2}
+
+**Dependencies**: {Other epics this depends on, or "None"}
+```
+
+## Task Structure
+
+```markdown
+### {Task Title}
+
+{1-2 sentences: what needs to be done}
+
+**Acceptance Criteria**:
+- [ ] {Specific, testable criterion}
+- [ ] {Specific, testable criterion}
+
+**Files**: {Key files to create/modify, if known}
+```
+
+## Guidelines
+
+### Epic Sizing
+- **Too small**: "Add login button" → merge into larger epic
+- **Right size**: "User Authentication" (3-7 tasks, 1-3 days work)
+- **Too big**: "Build entire frontend" → split into multiple epics
+
+### Task Sizing
+- One task = one commit
+- Should take 30min - 4hrs
+- Has clear "done" state
+
+### Dependency Order
+- Order epics so dependencies come first
+- Mark blocking dependencies explicitly
+- Prefer parallel-safe epics when possible
+
+### Test Type Convention
+
+Mark each acceptance criterion with its test type as a prefix:
+- **`[auto]`** - Verified by automated test (unit, integration, e2e)
+- **`[manual]`** - Requires human verification (include steps)
+
+For manual criteria, add verification steps after `→ Verify:`:
+```
+[manual] Dashboard displays correctly on mobile → Verify: Open on phone, check layout
+```
+
+Examples:
+- `[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`
+
+Prefer `[auto]` wherever possible - automated tests are more reliable and repeatable.
+
+## Breaking Down PRDs
+
+### Step 1: Identify Epics
+Read PRD features and group into logical work packages:
+- Each P0 feature often maps to 1-2 epics
+- Shared infrastructure (auth, database setup) = separate epic
+- UI and backend for same feature can be same or separate epic
+
+### Step 2: Order by Dependencies
+```
+Epic 1: Project Setup (no deps)
+Epic 2: Database Schema (depends on 1)
+Epic 3: User Auth (depends on 2)
+Epic 4: Core Feature A (depends on 3)
+Epic 5: Core Feature B (depends on 3)  ← can parallel with 4
+```
+
+### Step 3: Break into Tasks
+For each epic, create 3-7 tasks:
+- Start with data/schema tasks
+- Then business logic
+- Then API/interface
+- Finally integration/wiring
+
+### Example Breakdown
+
+**PRD Feature**:
+> **User Authentication**: Users can sign up and log in
+> - Sign up with email, password, name
+> - Login returns JWT
+> - Forgot password flow
+
+**Epic**:
+```markdown
+## User Authentication
+
+**Goal**: Users can create accounts and authenticate.
+
+**Scope**:
+- IN: Sign up, login, JWT tokens, forgot password
+- OUT: OAuth, 2FA, session management
+
+**Tasks**:
+1. Create users table schema
+2. Implement sign up endpoint
+3. Implement login endpoint with JWT
+4. Add forgot password email flow
+5. Create auth middleware
+
+**Acceptance Criteria**:
+- [ ] User can sign up with email/password/name
+- [ ] User can login and receive JWT
+- [ ] Invalid credentials return 401
+- [ ] Forgot password sends reset email
+
+**Dependencies**: Database Setup epic
+```
+
+## MCP Integration
+
+When breaking down:
+
+1. Create epic: `create_epic` with prd_ref, title, description
+2. Add criteria: `add_criteria` for each acceptance criterion
+3. Create tasks: `create_task` with epic_ref, title, description
+4. Add task criteria: `add_criteria` for each task criterion
+5. Add dependencies: `add_dependency` between epics if needed
+
+## Workflow
+
+1. **Read PRD** → Understand features and scope
+2. **Draft epics** → Group features into work packages
+3. **Review with user** → Confirm epic structure
+4. **Create in MCP** → Use tools to persist
+5. **Break into tasks** → Detail each epic
+6. **Set dependencies** → Order the work

package/skills/flux-orchestrator/SKILL.md

@@ -0,0 +1,130 @@
+---
+description: Orchestrates Flux workflows based on project context
+---
+
+# Flux Orchestrator Skill
+
+This skill is automatically active when working in a Flux project. It provides context about available tools and workflow patterns.
+
+## Available MCP Tools
+
+### Query Tools
+- `get_project_context` - Check if project initialized, get name/vision/prefix
+- `get_stats` - Get PRD/epic/task counts by status
+- `get_entity` - Fetch entity by ref with optional includes (criteria, tasks, dependencies)
+- `query_entities` - Search entities by type, status, parent ref
+
+### Mutation Tools
+- `init_project` - Initialize new .flux/ directory with project.json and database
+- `create_prd` - Create a new PRD
+- `create_epic` - Create an epic linked to a PRD
+- `create_task` - Create a task linked to an epic
+- `update_entity` - Update any entity's fields
+- `update_status` - Update entity status with validation
+- `delete_entity` - Delete entity with cascade
+
+### Relationship Tools
+- `add_dependency` - Add dependency between epics or tasks
+- `remove_dependency` - Remove a dependency
+- `add_criteria` - Add acceptance criterion to epic or task
+- `mark_criteria_met` - Mark criterion as satisfied
+
+## Workflow States
+
+The Flux project progresses through these states:
+
+1. **Uninitialized** - No .flux/ directory
+   - Action: Run `/flux` to initialize
+
+2. **No PRDs** - Project initialized but empty
+   - Action: Run `/flux:prd` to create first PRD
+
+3. **PRD Draft** - PRD created but needs review
+   - Action: Review and submit for approval or refine
+
+4. **PRD Pending Review** - PRD submitted for review
+   - Action: Run critique agent, then approve or revise
+
+5. **PRD Reviewed** - Critique complete
+   - Action: Address feedback, then approve or revise to DRAFT
+
+6. **PRD Approved** - Ready for epic breakdown
+   - Action: Run `/flux:breakdown` to create epics
+
+7. **Breakdown Ready** - Epics and tasks created
+   - Action: Run `/flux:implement` to start coding
+
+8. **Implementation In Progress** - Tasks IN_PROGRESS
+   - Action: Continue implementing current task
+
+9. **Complete** - All tasks COMPLETED
+    - Action: Review and create PR
+
+## Entity References
+
+All entities have a reference format: `{PREFIX}-{TYPE}{NUMBER}`
+
+- PRD: `MSA-P1`, `MSA-P2`
+- Epic: `MSA-E1`, `MSA-E2`
+- Task: `MSA-T1`, `MSA-T2`
+
+The prefix is generated from the project name during initialization.
+
+## Status Values
+
+### PRD Statuses (6-stage workflow)
+- `DRAFT` - Initial state, being created/refined
+- `PENDING_REVIEW` - Submitted for critique
+- `REVIEWED` - Critique complete, awaiting approval
+- `APPROVED` - Ready for epic breakdown
+- `BREAKDOWN_READY` - Epics and tasks created
+- `COMPLETED` - All epics done
+
+### Valid PRD Transitions
+```
+DRAFT → PENDING_REVIEW
+PENDING_REVIEW → REVIEWED | DRAFT (revise)
+REVIEWED → APPROVED | DRAFT (revise)
+APPROVED → BREAKDOWN_READY
+BREAKDOWN_READY → COMPLETED
+```
+
+### Epic/Task Statuses
+- `PENDING` - Not started
+- `IN_PROGRESS` - Currently being worked on
+- `COMPLETED` - Done
+
+## Confidence-Based Autonomy
+
+The orchestrator uses confidence levels to determine autonomy:
+
+| Confidence | Behavior | Example |
+|------------|----------|---------|
+| > 80% | Auto-execute, inform user | "I'm creating the epic structure..." |
+| 50-80% | Suggest action, wait for confirmation | "Ready to break down into tasks. Proceed?" |
+| < 50% | Ask clarifying question | "Should we research this technology first?" |
+
+### Confidence Indicators
+- **High confidence (>80%)**: Clear next step, no ambiguity, user has been responsive
+- **Medium confidence (50-80%)**: Reasonable next step, some uncertainty
+- **Low confidence (<50%)**: Multiple valid paths, unclear requirements, unfamiliar tech
+
+## Available Subagents
+
+### Research Agent
+- **Trigger**: Unfamiliar technology mentioned, confidence < 70%
+- **Purpose**: Gather information about libraries, frameworks, APIs
+- **Tools**: Context7, WebSearch, WebFetch
+
+### Critique Agent
+- **Trigger**: PRD status becomes PENDING_REVIEW
+- **Purpose**: Analyze feasibility, scope, risks
+- **Output**: Structured critique with recommendations
+
+## Best Practices
+
+1. **Check context first** - Always call `get_project_context` before taking actions
+2. **Use refs, not IDs** - Tools accept human-readable refs like `MSA-E1`
+3. **Validate status transitions** - Use `update_status` which enforces valid transitions
+4. **Include related data** - Use `include` parameter to fetch nested entities in one call
+5. **Handle errors gracefully** - Tools return errors with codes, display user-friendly messages