@cliangdev/flux-plugin 0.1.0

package/skills/prd-template/SKILL.md

@@ -0,0 +1,240 @@
+---
+description: PRD structure and patterns for Flux. Use when creating or refining product requirement documents. PRDs should be concise for humans but detailed enough for AI agents to implement.
+---
+
+# PRD Template Skill
+
+PRDs should be **concise for human review** but contain **enough detail for AI implementation**.
+
+## PRD Structure (Required)
+
+```markdown
+# {Project Name}
+
+## 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)
+- [Constraints](#constraints)
+- [Open Questions](#open-questions)
+
+## Problem
+{2-3 sentences: What problem are we solving? Why does it matter?}
+
+## Users
+{Who has this problem? 1-2 user segments.}
+
+## Solution
+{1 paragraph: What are we building to solve this?}
+
+## Features (MVP)
+
+### P0: Must Have
+- **{Feature 1}**: {One sentence description}
+  - {Acceptance criterion 1}
+  - {Acceptance criterion 2}
+- **{Feature 2}**: {One sentence description}
+  - {Acceptance criterion}
+
+### P1: Should Have
+- **{Feature}**: {Description}
+
+### Out of Scope
+- {What we're NOT building}
+- {Future considerations}
+
+## Constraints
+- **Tech Stack**: {Required technologies, if any}
+- **Timeline**: {Any deadlines}
+- **Other**: {Budget, compliance, etc.}
+
+## Open Questions
+- {Unresolved decisions needing input}
+```
+
+### TOC Guidelines
+
+**For Local Adapter** (files in `.flux/prds/`):
+- Include TOC with anchor links (e.g., `[Problem](#problem)`)
+- Use lowercase with hyphens for anchors
+- Nest sub-sections under parent sections
+
+**For External Adapters** (Linear, Notion):
+- **Skip TOC** - External systems have their own navigation (Linear's outline, collapsible sections)
+- Linear generates unique anchor suffixes making pre-built links impossible
+
+## Guidelines
+
+### Keep It Short
+- Problem: 2-3 sentences max
+- Features: 3-5 P0 features for MVP
+- Each feature: 1 sentence + 2-4 acceptance criteria
+- Total PRD: 1-2 pages
+
+### Write for AI Implementation
+- Acceptance criteria should be testable
+- Use specific, unambiguous language
+- Include edge cases in criteria when important
+
+### Bad vs Good Examples
+
+**Bad feature:**
+> - User authentication
+
+**Good feature:**
+> - **User Authentication**: Users can sign up and log in with email/password
+>   - Sign up requires email, password (min 8 chars), and name
+>   - Login with email + password returns JWT token
+>   - Invalid credentials show error message
+>   - Forgot password sends reset email
+
+## Supporting Documents (Optional)
+
+Generate based on **agent confidence** and **user request**.
+
+| Document | When to Generate |
+|----------|------------------|
+| `architecture.md` | Complex systems, multiple components, API integrations |
+| `wireframes.md` | UI-heavy features, user specifically requests |
+| `data-model.md` | Custom data storage, complex relationships |
+| `user-flows.md` | Multi-step processes, complex user journeys |
+
+### Asking About Supporting Docs
+
+After PRD outline approval, ask:
+
+```
+PRD outline looks good. I can also generate:
+- Architecture diagram (recommended for this project)
+- UI wireframes
+- Data model
+
+Which would you like? Or should I proceed with just the PRD?
+```
+
+Recommend based on project type:
+- **Web App**: architecture, wireframes
+- **API/Backend**: architecture, data-model
+- **CLI Tool**: usually just PRD
+- **Mobile App**: architecture, wireframes
+
+## Supporting Doc Templates
+
+### architecture.md
+
+```markdown
+# Architecture
+
+## Overview
+{One paragraph system description}
+
+## Components
+
+```mermaid
+graph TB
+    Client[Client] --> API[API Server]
+    API --> DB[(Database)]
+    API --> Cache[(Redis)]
+```
+
+## API Endpoints
+
+| Method | Path | Description |
+|--------|------|-------------|
+| POST | /api/users | Create user |
+| GET | /api/users/:id | Get user |
+
+## Data Flow
+{Describe key data flows}
+
+## Tech Stack
+- **Frontend**: {tech}
+- **Backend**: {tech}
+- **Database**: {tech}
+```
+
+### wireframes.md
+
+```markdown
+# Wireframes
+
+## Screen: {Name}
+
+```
++----------------------------------+
+|  Logo              [Login] [Sign Up]
++----------------------------------+
+|                                  |
+|     Welcome to {App Name}        |
+|                                  |
+|     [  Email  ]                  |
+|     [Password ]                  |
+|     [  Login  ]                  |
+|                                  |
+|     Forgot password?             |
++----------------------------------+
+```
+
+**Elements:**
+- Logo: links to home
+- Login button: submits form
+- Forgot password: opens reset flow
+```
+
+### data-model.md
+
+```markdown
+# Data Model
+
+## ERD
+
+```mermaid
+erDiagram
+    User ||--o{ Post : creates
+    Post ||--o{ Comment : has
+```
+
+## Tables
+
+### users
+| Column | Type | Constraints |
+|--------|------|-------------|
+| id | uuid | PK |
+| email | varchar | unique, not null |
+| created_at | timestamp | default now() |
+
+### posts
+| Column | Type | Constraints |
+|--------|------|-------------|
+| id | uuid | PK |
+| user_id | uuid | FK users.id |
+| content | text | not null |
+```
+
+## Workflow
+
+Check adapter type via `get_project_context` to determine storage behavior.
+
+### Local Adapter (`adapter.type === "local"`)
+
+1. **Interview** → Collect answers via AskUserQuestion
+2. **Outline** → Generate brief outline, ask for approval
+3. **Create entity** → Call `create_prd` with title and short description
+4. **Write PRD** → Write full PRD to `.flux/prds/{slug}/prd.md`
+5. **Set folder_path** → Call `update_entity` with `folder_path`: `.flux/prds/{slug}`
+6. **Ask about docs** → Offer relevant supporting docs
+7. **Generate docs** → Write requested docs to same folder
+
+### External Adapters (`adapter.type === "linear"`, `"notion"`, etc.)
+
+1. **Interview** → Collect answers via AskUserQuestion
+2. **Outline** → Generate brief outline, ask for approval
+3. **Create entity** → Call `create_prd` with title and short description
+4. **Sync content** → Call `update_entity` with `description`: Full PRD markdown content
+5. **Ask about docs** → Offer relevant supporting docs (stored as attachments in external system)
+
+**Note**: External adapters store all content in the external system. No local `.flux/prds/` files are created.