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

package/manifest.json

@@ -7,7 +7,7 @@
       "agent-creator",
       "epic-template",
       "flux-orchestrator",
-      "prd-template"
+      "prd-writer"
     ],
     "agents": ["coder.md", "critic.md", "researcher.md", "verifier.md"],
     "hooks": []

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cliangdev/flux-plugin",
-  "version": "0.2.0-dev.dc5e2c4",
+  "version": "0.2.0-dev.e34d43b",
   "description": "Claude Code plugin for AI-first workflow orchestration with MCP server",
   "type": "module",
   "main": "./dist/server/index.js",

package/skills/flux-orchestrator/SKILL.md

@@ -11,11 +11,11 @@ This skill is automatically active when working in a Flux project. It provides c
 ## Available MCP Tools
 
 ### Query Tools
-- `get_project_context` - Check if project initialized, get name/vision/adapter type
 - `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
 - `render_status` - Get formatted project status with progress bars
+- `get_version` - Get Flux plugin version
 
 ### Mutation Tools
 - `init_project` - Initialize new .flux/ directory with project.json and database
@@ -39,10 +39,18 @@ This skill is automatically active when working in a Flux project. It provides c
 |---------|---------|
 | `/flux` | Project init, status, and workflow routing |
 | `/flux:linear` | Connect project to Linear (interactive setup) |
-| `/flux:prd` | Create or refine PRDs |
+| `/flux:prd` | Create PRDs through discovery, research, and guided writing |
 | `/flux:breakdown` | Break approved PRD into epics and tasks |
 | `/flux:implement` | Implement tasks with TDD workflow |
 
+## Available Skills
+
+| Skill | Purpose | Auto-loaded When |
+|-------|---------|------------------|
+| `flux:prd-writer` | PRD structure, templates, and quality guidelines | Creating or refining PRDs |
+| `flux:epic-template` | Epic/task structure and breakdown patterns | Breaking down PRDs |
+| `flux:agent-creator` | Guide for creating specialized subagents | Building new agents |
+
 ## Workflow States
 
 ```
@@ -107,7 +115,7 @@ Format: `{PREFIX}-{TYPE}{NUMBER}`
 
 ## Best Practices
 
-1. **Check context first** - Call `get_project_context` before actions
+1. **Handle PROJECT_NOT_INITIALIZED** - If any tool returns this error, direct user to run `/flux` to initialize the project
 2. **Use refs, not IDs** - Tools accept `MSA-E1` format
 3. **Use render_status** - For visual project overview
 4. **Validate transitions** - `update_status` enforces valid transitions

package/skills/prd-writer/SKILL.md

@@ -0,0 +1,577 @@
+---
+name: flux:prd-writer
+description: Comprehensive guide for creating PRDs that are concise for humans and detailed enough for AI implementation. Use when creating, refining, or reviewing product requirement documents. This skill drives the entire PRD creation workflow.
+user-invocable: false
+---
+
+# PRD Writer Skill
+
+This skill guides the creation of **Product Requirement Documents** that serve two audiences:
+1. **Humans** - who need to understand and approve the vision
+2. **AI Agents** - who need unambiguous specifications to implement
+
+## Core Principle: Specification as Contract
+
+A PRD is a contract between the product vision and the implementation. Every feature must have:
+- **Clear scope** - What's in, what's out
+- **Testable criteria** - How do we know it works?
+- **Edge cases** - What could go wrong?
+
+---
+
+## PRD Scoping: Right-Sizing Your PRDs
+
+### The Golden Rule
+
+**One PRD = One implementable unit that delivers standalone value.**
+
+A well-scoped PRD should:
+- Be completable in 1-3 weeks of focused work
+- Result in 15-25 tasks when broken down
+- Deliver something usable/testable on its own
+- Have clear boundaries that don't leak into other features
+
+### Scope Assessment Matrix
+
+| Indicator | Right-Sized PRD | Too Large (Split It) |
+|-----------|-----------------|----------------------|
+| Major features | 3-5 related features | 6+ distinct features |
+| User flows | 1-2 main journeys | 3+ separate journeys |
+| Technical domains | Focused area | Frontend + Backend + Infra + DevOps |
+| User personas | 1-2 related personas | Multiple distinct user types |
+| Estimated tasks | 15-25 tasks | 30+ tasks |
+| Dependencies | Few external deps | Multiple other systems |
+
+### When to Split: Red Flags
+
+🚩 **"Build a mobile app"** → Too vague. What features? For whom?
+
+🚩 **"Full e-commerce platform"** → Contains auth, catalog, cart, checkout, payments, orders, admin...
+
+🚩 **"Complete user management"** → Could mean signup, profiles, roles, permissions, teams, invites, admin...
+
+🚩 **Multiple distinct user types** → Admin dashboard + Customer portal = 2 PRDs minimum
+
+### Multi-PRD Project Structure
+
+For large projects, organize PRDs into phases:
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    PROJECT: Task Manager App                 │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  FOUNDATION LAYER (implement first)                         │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ Project Setup   │───▶│ Authentication  │                │
+│  │ [foundation]    │    │ [foundation]    │                │
+│  └─────────────────┘    └────────┬────────┘                │
+│                                  │                          │
+│  MVP LAYER                       ▼                          │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ Task CRUD       │    │ Task Lists      │                │
+│  │ [mvp]           │◀───│ [mvp]           │                │
+│  └─────────────────┘    └─────────────────┘                │
+│                                                             │
+│  POST-MVP LAYER                                             │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ Sharing &       │    │ Notifications   │                │
+│  │ Collaboration   │    │ [post-mvp]      │                │
+│  │ [post-mvp]      │    └─────────────────┘                │
+│  └─────────────────┘                                        │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### PRD Tags
+
+Use tags to organize related PRDs:
+
+| Tag | Meaning | When to Use |
+|-----|---------|-------------|
+| `foundation` | Core infrastructure | Setup, auth, database schema, core APIs |
+| `mvp` | Minimum viable product | Essential features for first release |
+| `mvp-phase-2` | Second wave of MVP | Important but not launch-blocking |
+| `post-mvp` | Future enhancements | Nice-to-have, can wait |
+| `experimental` | Exploratory | R&D, prototypes, uncertain scope |
+| `bugfix` | Defect correction | Addressing issues in existing features |
+| `refactor` | Technical improvement | No new features, internal quality |
+
+### PRD Dependencies
+
+When PRDs depend on each other, document it clearly:
+
+**In the Constraints section:**
+```markdown
+## Constraints
+
+### PRD Dependencies
+- **Requires**: [Authentication PRD](./auth/prd.md) (FLUX-P1) - Need user model and JWT middleware
+- **Blocks**: [Notifications PRD](./notifications/prd.md) (FLUX-P4) - Will need task events
+
+### Shared Components
+- Uses User model from Authentication PRD
+- Extends base API patterns from Project Setup PRD
+```
+
+### Example: Splitting a Large Scope
+
+**User says**: "I want to build a fitness tracking app"
+
+**❌ Bad (too large)**:
+```
+PRD: Fitness Tracking App
+Features:
+- User accounts
+- Workout logging
+- Exercise library
+- Progress charts
+- Social features
+- Meal tracking
+- Sleep tracking
+- Wearable integration
+- Premium subscriptions
+```
+
+**✅ Good (split into focused PRDs)**:
+
+```
+PRD 1: Project Foundation [foundation]
+- Project setup, CI/CD, deployment
+- Core data models
+- API structure
+Dependencies: None
+
+PRD 2: User Authentication [foundation]
+- Sign up, login, profile
+- Password reset
+Dependencies: PRD 1
+
+PRD 3: Workout Logging [mvp]
+- Log workouts manually
+- View workout history
+- Basic exercise library
+Dependencies: PRD 2
+
+PRD 4: Progress Tracking [mvp]
+- Dashboard with charts
+- Weekly/monthly summaries
+Dependencies: PRD 3
+
+PRD 5: Social Features [post-mvp]
+- Follow friends
+- Share workouts
+- Leaderboards
+Dependencies: PRD 2, PRD 3
+```
+
+### Scope Negotiation
+
+When scope is too large, guide the user:
+
+```
+This is a substantial project. Let me help you break it down:
+
+**Option A: Start with foundation**
+Begin with authentication and core infrastructure. Other features build on this.
+
+**Option B: Pick one user journey**
+What's the ONE thing users must be able to do? Let's nail that first.
+
+**Option C: Define MVP strictly**
+What could you launch with in 2 weeks that would be useful?
+
+Which approach works for you?
+```
+
+---
+
+## PRD Structure (Required Sections)
+
+### For Local Adapter (files in `.flux/prds/`)
+
+```markdown
+# {Project Name}
+
+> **Tag**: {foundation | mvp | mvp-phase-2 | post-mvp | experimental}
+> **Depends on**: {None | List of PRD refs like FLUX-P1, FLUX-P2}
+> **Blocks**: {None | List of PRD refs that depend on this}
+
+## Table of Contents
+- [Problem](#problem)
+- [Users](#users)
+- [Solution](#solution)
+- [Features (MVP)](#features-mvp)
+  - [P0: Must Have](#p0-must-have)
+  - [P1: Should Have](#p1-should-have)
+  - [Out of Scope](#out-of-scope)
+- [Technical Context](#technical-context)
+- [Constraints](#constraints)
+- [Open Questions](#open-questions)
+
+## Problem
+{2-3 sentences: What pain point are we solving? Why does it matter now?}
+
+## Users
+{Who experiences this problem? Be specific about user segments.}
+
+## Solution
+{1 paragraph: What are we building? How does it solve the problem?}
+
+## Features
+
+### P0: Must Have
+
+For each feature, use the What/Not pattern:
+
+- **{Feature Name}**: {One-line description}
+  - **What**: {Specific scope - what IS included}
+  - **Not**: {Explicit exclusions - prevents scope creep}
+  - **Acceptance Criteria**:
+    - [ ] {Input → expected output, testable by AI}
+    - [ ] {Another criterion with specific values}
+  - **Edge Cases**:
+    - {Scenario}: {Expected behavior}
+
+### P1: Should Have
+
+- **{Feature}**: {Description}
+  - {Brief acceptance criteria - less detail than P0}
+
+### Out of Scope
+- {What we're explicitly NOT building}
+- {Future considerations deferred}
+
+## Technical Context
+
+### Existing Patterns
+{Describe relevant existing code patterns the implementation should follow.}
+{Reference key files/modules that will be extended or modified.}
+
+### Tech Stack
+- **{Layer}**: {Technology} - {Why this choice}
+
+### API Design (if applicable)
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | /api/... | ... |
+
+## Constraints
+- **Timeline**: {Any deadlines}
+- **PRD Dependencies**: {What must be completed before this PRD can start}
+- **External Dependencies**: {APIs, services, third-party systems}
+- **Performance**: {SLAs, limits}
+
+## Open Questions
+- [ ] {Unresolved decision needing stakeholder input}
+```
+
+**Note**: The metadata block at the top (Tag, Depends on, Blocks) is optional for standalone PRDs but required for multi-PRD projects.
+
+### For External Adapters (Linear, Notion)
+
+**Skip the Table of Contents** - external systems have their own navigation.
+
+---
+
+## Writing for Two Audiences
+
+A PRD must satisfy both humans and AI agents:
+
+| Audience | Needs | What They Read |
+|----------|-------|----------------|
+| **Humans** | Quick understanding, approve/reject decisions | Problem, Solution, feature summaries |
+| **AI Agents** | Unambiguous specs for autonomous implementation | Acceptance criteria, edge cases, code references |
+
+### Size Guidelines
+
+| Section | Target | Guidance |
+|---------|--------|----------|
+| Problem | 2-3 sentences | What pain? Why now? Who suffers? |
+| Solution | 1 paragraph | What we're building, how it solves the problem |
+| P0 Features | 3-5 features | The true MVP, nothing more |
+| Each Feature | 5-10 criteria | Enough for AI to implement without guessing |
+| Total PRD | 1-2 pages | Fits on one screen when scrolling |
+
+---
+
+## Feature Writing: The What/Not Pattern
+
+Every P0 feature must have explicit boundaries. Use the **What/Not** pattern to prevent scope creep and give AI clear implementation guidance.
+
+### Feature Template
+
+```markdown
+- **{Feature Name}**: {One-line description}
+  - **What**: {Specific scope - what IS included}
+  - **Not**: {Explicit exclusions - what is NOT included}
+  - **Acceptance Criteria**:
+    - [ ] {Testable criterion with specific input → expected output}
+    - [ ] {Another criterion - AI can verify pass/fail}
+  - **Edge Cases**:
+    - {Scenario}: {Expected behavior}
+```
+
+### Feature Quality Ladder
+
+**Level 1: Vague** (human might understand, AI cannot implement)
+```markdown
+- User authentication
+```
+*Problem: What kind? Email? OAuth? What flows?*
+
+**Level 2: Named** (clearer, still ambiguous)
+```markdown
+- **User Authentication**: Users can sign up and log in
+```
+*Problem: What about logout? Password reset? Validation rules?*
+
+**Level 3: Scoped** (boundaries defined)
+```markdown
+- **User Authentication**: Email/password auth for user accounts
+  - **What**: Sign up, login, logout, password reset
+  - **Not**: OAuth, 2FA, social login, magic links
+```
+*Better: AI knows the boundaries. Still lacks implementation detail.*
+
+**Level 4: Implementable** (AI can build autonomously)
+```markdown
+- **User Authentication**: Email/password auth for user accounts
+  - **What**: Sign up, login, logout, password reset via email
+  - **Not**: OAuth, 2FA, social login, magic links, session management (use JWT)
+  - **Acceptance Criteria**:
+    - [ ] POST /auth/signup with {email, password, name} → 201 + user object (no password)
+    - [ ] POST /auth/login with valid credentials → 200 + {token, user}
+    - [ ] POST /auth/login with wrong password → 401 + {error: "Invalid credentials"}
+    - [ ] POST /auth/logout with valid token → 200 (token invalidated)
+    - [ ] Password minimum 8 chars; shorter rejected with 400 + validation error
+    - [ ] Email must be valid format; malformed rejected with 400
+  - **Edge Cases**:
+    - Duplicate email on signup: 409 Conflict + {error: "Email already registered"}
+    - Login with non-existent email: 401 (same as wrong password, for security)
+    - Expired token on protected routes: 401 + {error: "Token expired"}
+    - Rate limiting: 429 after 5 failed login attempts per email in 1 minute
+```
+*This is AI-ready: specific endpoints, status codes, error messages, edge cases.*
+
+### Acceptance Criteria Rules
+
+1. **Use input → output format**: `POST /path with {data} → status + {response}`
+2. **Include failure cases**: Don't just test happy paths
+3. **Specify exact values**: "400" not "error", "8 chars" not "short password"
+4. **Be deterministic**: AI should know exactly what to assert in tests
+
+### Edge Cases Worth Documenting
+
+Not every edge case matters. Focus on:
+
+| Include | Skip |
+|---------|------|
+| Security boundaries (auth failures, rate limits) | Obvious validations (null checks) |
+| Business rule exceptions | Framework-handled errors |
+| Data conflicts (duplicates, race conditions) | Infrastructure issues (DB down) |
+| User journey dead ends | Extremely rare scenarios |
+
+---
+
+## Research Phase: What to Investigate
+
+Before writing the PRD, research the following:
+
+### 1. Codebase Context
+- **Project structure**: What patterns are already established?
+- **Existing modules**: What can be reused or extended?
+- **Tech stack**: What frameworks/libraries are in use?
+- **Testing patterns**: How are tests structured?
+
+### 2. Similar Features
+- Look for similar functionality in the codebase
+- Note patterns, naming conventions, file organization
+- Identify shared utilities or base classes
+
+### 3. Technical Feasibility
+- Are there any technical blockers?
+- What dependencies are needed?
+- Are there security considerations?
+
+### 4. Prior Art (External)
+- How do similar products solve this?
+- Any best practices or anti-patterns to know?
+
+---
+
+## Project-Type Specific Guidance
+
+### Web Application
+**Key questions**:
+- What's the authentication model?
+- What data needs persistence?
+- What are the main user flows?
+
+**Common epics**:
+- Project Setup & Configuration
+- Database Schema & Models
+- Authentication/Authorization
+- Core Feature(s)
+- UI/Frontend
+
+### CLI Tool
+**Key questions**:
+- What commands are needed?
+- What's the input/output format?
+- How does configuration work?
+
+**Common epics**:
+- Command Parser & Help
+- Core Command Implementation
+- Configuration Management
+- Output Formatting
+
+### API/Backend Service
+**Key questions**:
+- What's the API contract?
+- What are the data models?
+- What external services integrate?
+
+**Common epics**:
+- API Design & Documentation
+- Data Models & Storage
+- Core Endpoints
+- Authentication & Security
+- Error Handling & Logging
+
+### Library/Package
+**Key questions**:
+- What's the public API surface?
+- What are the main use cases?
+- How should errors be handled?
+
+**Common epics**:
+- API Design
+- Core Implementation
+- Error Handling
+- Documentation & Examples
+
+---
+
+## Supporting Documents (Optional)
+
+Generate based on project complexity and user needs.
+
+| Document | When Useful | Content |
+|----------|-------------|---------|
+| `architecture.md` | Multi-component systems | System diagram, API endpoints, data flow |
+| `data-model.md` | Custom data storage | ERD, table schemas, relationships |
+| `wireframes.md` | UI-heavy features | ASCII wireframes, element descriptions |
+| `user-flows.md` | Complex journeys | Step-by-step user paths |
+
+### When to Offer Supporting Docs
+
+After PRD approval, ask based on project type:
+- **Web App**: Offer architecture, wireframes
+- **API/Backend**: Offer architecture, data-model
+- **CLI Tool**: Usually just PRD is sufficient
+- **Mobile App**: Offer architecture, wireframes
+
+---
+
+## Workflow: Three-Phase PRD Creation
+
+### Phase 1: Discovery (Gather Intent)
+
+**Goal**: Understand what the user wants to build.
+
+1. **Initial prompt**: "What are you trying to build?"
+2. **Follow-up based on response**:
+   - If vague: "Can you describe the problem you're solving?"
+   - If clear: "Who is this for? Who experiences this problem?"
+3. **Scope clarification**: "What's the minimum that would be useful?"
+
+**Gather**:
+- Problem statement
+- Target users
+- Core functionality (what, not how)
+- Any known constraints
+
+### Phase 2: Research (Understand Context)
+
+**Goal**: Gather technical context to inform the PRD.
+
+Spawn a research agent to:
+1. **Explore the codebase** (if exists):
+   - Project structure and patterns
+   - Existing similar features
+   - Tech stack and testing approach
+2. **Research externally** (if needed):
+   - Similar solutions in the ecosystem
+   - Best practices for this type of feature
+   - Potential libraries or tools
+
+**Output**: Technical context section of the PRD.
+
+### Phase 3: Generate (Create AI-Ready PRD)
+
+**Goal**: Produce a PRD ready for breakdown and implementation.
+
+1. **Draft PRD** using the template structure above
+2. **Review with user**: Present outline, ask for feedback
+3. **Refine**: Incorporate feedback
+4. **Store**:
+   - Local adapter: Write to `.flux/prds/{slug}/prd.md`
+   - External adapter: Store in description field
+5. **Offer supporting docs** based on project type
+
+---
+
+## Quality Checklist
+
+Before finalizing a PRD, verify:
+
+### Scope
+- [ ] PRD is right-sized (15-25 tasks when broken down)
+- [ ] Scope is achievable in 1-3 weeks
+- [ ] Features are cohesive (belong together)
+- [ ] If multi-PRD project, dependencies are documented
+- [ ] Tag is assigned (foundation/mvp/post-mvp/etc.)
+
+### Content
+- [ ] Problem statement is specific (not generic)
+- [ ] Solution clearly addresses the problem
+- [ ] Each P0 feature has acceptance criteria
+- [ ] Acceptance criteria are testable (pass/fail determinable)
+- [ ] Edge cases are identified for complex features
+- [ ] Technical context reflects actual codebase (if applicable)
+- [ ] Out of Scope is explicit about what's NOT included
+- [ ] Open Questions are actionable (can be resolved)
+
+---
+
+## Anti-Patterns to Avoid
+
+### 1. Solution Masquerading as Problem
+❌ "We need a React dashboard"
+✅ "Users can't see their data at a glance"
+
+### 2. Implementation Details in Features
+❌ "Use Redux for state management"
+✅ "App state persists across page refreshes"
+
+### 3. Vague Acceptance Criteria
+❌ "System should be fast"
+✅ "API responses complete in < 200ms for 95th percentile"
+
+### 4. Missing Scope Boundaries
+❌ "User management" (how much?)
+✅ "User management: CRUD for users. No roles, no permissions, no team features."
+
+### 5. Ignoring Existing Patterns
+❌ Proposing new patterns when established ones exist
+✅ "Following existing auth middleware pattern in `src/middleware/auth.ts`"
+
+### 6. Boiling the Ocean
+❌ "Build a complete e-commerce platform with user accounts, product catalog, shopping cart, checkout, payments, order management, inventory, shipping integration, admin dashboard, analytics, and mobile apps"
+✅ Split into 8-10 focused PRDs with clear dependencies
+
+### 7. Orphan PRDs
+❌ Creating a PRD that can't be implemented without undefined prerequisites
+✅ Explicitly list dependencies; create foundation PRDs first

package/src/server/index.ts

@@ -11,7 +11,6 @@ import {
   createTaskTool,
   deleteEntityTool,
   getEntityTool,
-  getProjectContextTool,
   getStatsTool,
   getVersionTool,
   initProjectTool,
@@ -47,7 +46,6 @@ const tools: ToolDefinition[] = [
   // Query tools
   getEntityTool,
   queryEntitiesTool,
-  getProjectContextTool,
   initProjectTool,
   getStatsTool,
   getVersionTool,