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

package/commands/prd.md

@@ -1,140 +1,879 @@
 ---
 name: flux:prd
-description: Create or refine PRDs through guided interview
-allowed-tools: mcp__flux__*, AskUserQuestion
+description: Create comprehensive PRDs through discovery, research, and guided writing
+allowed-tools: mcp__flux__*, AskUserQuestion, Read, Glob, Grep, Task, WebSearch
 ---
 
-# PRD Interview
+# PRD Creation Command
 
-You are a product requirements interviewer. Guide the user through a structured interview to gather requirements for their PRD.
+You are a product requirements expert. Your job is to help users create PRDs that are:
+1. **Concise for humans** - Easy to read and approve
+2. **Precise for AI** - Detailed enough for autonomous implementation
+
+The `flux:prd-writer` skill contains the full PRD template and guidelines. Follow its structure.
 
 ## Mode Detection
 
-Check if arguments were provided:
-- `/flux:prd` - Start new PRD interview
-- `/flux:prd refine` - Refine existing PRD
-- `/flux:prd resume` - Resume interrupted interview
+Check arguments:
+- `/flux:prd` or `/flux:prd new` - Start new PRD (full workflow)
+- `/flux:prd refine` or `/flux:prd refine {ref}` - Refine existing PRD
 - `/flux:prd {ref}` - Edit specific PRD (e.g., `FLUX-P1`)
 
-## New PRD Interview Flow
+---
+
+## New PRD Workflow
+
+### Pre-Flight Check
+
+1. **Detect adapter type** by calling `get_project_context`:
+   ```
+   mcp__flux__get_project_context()
+   → Returns: { adapter: { type: "local" | "linear" }, name, vision, ... }
+   ```
+   - If not initialized: Tell user to run `/flux` first, then exit
+   - Store `adapter.type` for use throughout the workflow (affects Step 3.4 storage)
+
+2. Call `query_entities` with `type: "prd"` to check existing PRDs
+   - If drafts exist, ask: "You have draft PRDs. Create a new one or continue with {ref}?"
+
+---
+
+### Phase 1: Discovery (Gather Intent)
+
+**Goal**: Understand what the user wants to build before asking structured questions.
+
+#### Step 1.1: Open-Ended Start
 
-### Pre-check
+Begin with an open question:
+```
+What are you trying to build?
+
+Feel free to describe it however makes sense - the problem you're solving,
+the solution you have in mind, or both.
+```
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+#### Step 1.2: Adaptive Follow-Up
 
-2. Call `get_interview` to check for any in-progress interview
-   - If exists, ask: "You have an unfinished interview. Resume it or start fresh?"
+Based on their response, ask follow-up questions to fill gaps. You need:
+- **Problem**: What pain point does this solve?
+- **Users**: Who experiences this problem?
+- **Core solution**: What's the core functionality?
+- **Scope**: What's the minimum viable version?
 
-### Step 1: Project Type
+Use AskUserQuestion for choices when helpful, but prefer conversational follow-ups.
 
-Ask using AskUserQuestion:
+**Examples of good follow-ups**:
+- "Who specifically has this problem? Developers? End users? Admins?"
+- "What would success look like for an MVP?"
+- "Are there any constraints I should know about? (timeline, tech stack, etc.)"
+
+#### Step 1.3: Project Type Detection
+
+Infer project type from context, or ask if unclear:
 ```
-What type of project are you building?
-- Web Application (Recommended)
+Based on what you've described, this sounds like a {detected type}. Is that right?
+
+Options:
+- Web Application
 - CLI Tool
 - API/Backend Service
-- Mobile App
 - Library/Package
+- Mobile App
+- Other (describe)
+```
+
+Store the project type - it affects research and structure.
+
+#### Step 1.4: Scope Assessment
+
+**Goal**: Determine if the scope fits a single PRD or needs to be split.
+
+##### Step 1.4.1: Scope Scoring
+
+Score the project using these indicators (1 point each if Multi-PRD threshold is met):
+
+| Indicator | Single PRD (0 pts) | Multi-PRD (1 pt) |
+|-----------|-------------------|------------------|
+| User flows | 1-2 main flows | 3+ distinct flows |
+| Major features | 3-5 features | 6+ major features |
+| Technical domains | 1-2 domains | Frontend + Backend + Infra |
+| Estimated tasks | < 25 tasks | 25+ tasks |
+| Timeline | 1-2 weeks | Months of work |
+| User types | 1-2 personas | Multiple distinct personas |
+| External integrations | 0-1 integrations | 2+ integrations |
+
+**Scoring interpretation:**
+- **0-2 points**: Single PRD appropriate → proceed to Phase 2
+- **3-4 points**: Consider splitting → discuss with user
+- **5+ points**: Multi-PRD required → actively guide splitting
+
+##### Step 1.4.2: Multi-PRD Project Proposal
+
+**If score >= 5**, present a structured breakdown with visual hierarchy:
+
+```
+## Project Analysis
+
+This project scores {X}/7 on scope indicators, suggesting we split it into focused PRDs.
+
+### Recommended PRD Structure
+
+┌─────────────────────────────────────────────────────────────┐
+│                    PROJECT: {Project Name}                   │
+├─────────────────────────────────────────────────────────────┤
+│                                                             │
+│  PHASE 1: FOUNDATION [tag: foundation]                      │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ PRD-1: Setup    │───▶│ PRD-2: Auth     │                │
+│  │ • CI/CD, deploy │    │ • Login/signup  │                │
+│  │ • Base structure│    │ • User model    │                │
+│  └─────────────────┘    └────────┬────────┘                │
+│                                  │                          │
+│  PHASE 2: MVP [tag: mvp]         ▼                          │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ PRD-3: {Core A} │    │ PRD-4: {Core B} │                │
+│  │ • {feature}     │    │ • {feature}     │                │
+│  └────────┬────────┘    └────────┬────────┘                │
+│           │                      │                          │
+│  PHASE 3: ENHANCEMENTS [tag: post-mvp]                      │
+│           ▼                      ▼                          │
+│  ┌─────────────────┐    ┌─────────────────┐                │
+│  │ PRD-5: {Enh A}  │    │ PRD-6: {Enh B}  │                │
+│  └─────────────────┘    └─────────────────┘                │
+│                                                             │
+└─────────────────────────────────────────────────────────────┘
+
+### Dependency Chain
+PRD-1 → PRD-2 → [PRD-3 || PRD-4] → PRD-5, PRD-6
+```
+
+Use AskUserQuestion:
+- "Start with PRD-1 ({foundation PRD name})" (Recommended)
+- "Modify this structure first"
+- "Just create PRD-1 and plan the rest later"
+- "Proceed with single PRD anyway" (not recommended for this scope)
+
+##### Step 1.4.3: Multi-PRD Creation Workflow
+
+**When user confirms multi-PRD approach:**
+
+1. **Store project context** for continuation:
+   - Project name
+   - Full PRD breakdown with dependencies
+   - Current position in sequence
+
+2. **Create first PRD** with proper metadata:
+   - Set `tag` field (foundation/mvp/post-mvp)
+   - Document dependencies in Constraints section
+   - Reference future PRDs in Out of Scope ("Authentication is handled in PRD-2")
+
+3. **Track progress** for continuation workflow (Step 3.6)
+
+##### Step 1.4.4: Continuation Workflow
+
+After completing any PRD in a multi-PRD project, show progress and offer to continue:
+
+```
+## PRD Saved: {ref} ({title})
+
+### Project Progress: {Project Name}
+┌─────────────────────────────────────────────────┐
+│ ✓ PRD-1: Project Setup [foundation]             │
+│ ✓ PRD-2: Authentication [foundation] ← Done     │
+│ → PRD-3: {Next Feature} [mvp] ← Ready           │
+│ ○ PRD-4: {Future Feature} [mvp]                 │
+│ ○ PRD-5: {Enhancement} [post-mvp]               │
+└─────────────────────────────────────────────────┘
+
+Next up: PRD-3 "{Next Feature}"
+- Dependencies met: PRD-1, PRD-2 ✓
+- Estimated scope: 15-20 tasks
+```
+
+Use AskUserQuestion:
+- "Continue with PRD-3" (Recommended)
+- "I'll create it later"
+- "Show full project roadmap"
+- "Modify the remaining plan"
+
+**When continuing with next PRD:**
+1. Skip Discovery Phase - context already gathered
+2. Pre-populate metadata from project plan
+3. Reference completed PRDs in Technical Context
+4. Run targeted research for specific scope
+5. Generate PRD with proper dependency references
+
+**Tag Conventions:**
+- `foundation` - Infrastructure, setup, core systems (implement first)
+- `mvp` - Minimum viable product features
+- `mvp-phase-2` - Second wave of core features
+- `post-mvp` - Nice-to-have, future enhancements
+- `experimental` - Exploratory features
+
+---
+
+### Phase 2: Research (Understand Context)
+
+**Goal**: Gather technical context to make the PRD specific and implementable.
+
+#### Step 2.1: Codebase Research
+
+Check if there's an existing codebase to analyze:
+
+```typescript
+// Check for common project indicators
+const hasPackageJson = await glob("package.json");
+const hasGo = await glob("go.mod");
+const hasPython = await glob("pyproject.toml") || await glob("setup.py");
+const hasCargo = await glob("Cargo.toml");
+```
+
+If codebase exists, spawn a codebase exploration agent:
+
+```
+Use the Task tool with subagent_type="Explore" to research:
+
+1. Project structure - What's the overall architecture?
+2. Existing patterns - How are similar features implemented?
+3. Tech stack - What frameworks, libraries, testing tools?
+4. Relevant files - What modules might be extended?
+
+Focus on patterns relevant to: {user's described feature}
+```
+
+#### Step 2.2: Technology Research (Researcher Agent)
+
+**Spawn the `flux-researcher` agent** when ANY of these conditions apply:
+
+| Trigger Condition | Example |
+|-------------------|---------|
+| Unfamiliar technology mentioned | "We'll use tRPC" (if you're < 70% confident about it) |
+| External APIs or SDKs involved | "Integrate with Stripe", "Use OpenAI API" |
+| User explicitly asks for research | "Research the best auth library for Node" |
+| Technology comparison needed | "Should we use Prisma or Drizzle?" |
+| Best practices research needed | "What's the standard way to handle file uploads?" |
+
+**Spawning the researcher:**
+
+```
+Task({
+  subagent_type: "flux:flux-researcher",
+  prompt: `Research the following technologies for PRD context:
+
+## Technologies to Research
+- {technology 1}
+- {technology 2}
+
+## Context
+The user is building: {brief project description}
+Project type: {web app / CLI / API / etc.}
+
+## Questions to Answer
+1. What is this technology and what problem does it solve?
+2. Is it actively maintained? What's the ecosystem like?
+3. What are the key features relevant to this project?
+4. Are there alternatives we should consider?
+5. What are common pitfalls to avoid?
+
+Return findings in the standard research output format with sources.`,
+  description: "Research: {technologies}"
+})
+```
+
+**When NOT to spawn researcher:**
+- Quick fact checks → Use inline WebSearch
+- Looking up syntax → Use Context7 directly
+- Known, mainstream technologies (React, Express, PostgreSQL)
+
+#### Step 2.3: Synthesize Findings
+
+Combine codebase exploration and technology research into actionable context:
+
+```
+Based on my research:
+
+**Existing Patterns**:
+- {Pattern 1}: Found in {files}
+- {Pattern 2}: Used for {purpose}
+
+**Tech Stack**:
+- {Framework}: {version}
+- Testing: {approach}
+
+**Relevant Code**:
+- {module}: Could be extended for this feature
+- {file}: Contains related functionality
+
+**Technology Research** (if researcher agent was used):
+- {Technology}: {key finding}
+- Recommendation: {use/avoid and why}
+
+This context will inform the PRD structure.
+```
+
+Ask if the user wants to add or correct anything.
+
+---
+
+### Phase 3: Generate (Create AI-Ready PRD)
+
+**Goal**: Produce a complete PRD following the prd-writer skill template.
+
+#### Step 3.1: Draft PRD Outline
+
+Before writing the full PRD, present an outline for approval:
+
+```
+## PRD Outline: {Title}
+
+**Problem**: {1 sentence}
+
+**Users**: {Target segment}
+
+**Solution**: {Core approach}
+
+**P0 Features**:
+1. {Feature 1}: {Brief description}
+2. {Feature 2}: {Brief description}
+3. {Feature 3}: {Brief description}
+
+**Out of Scope**: {Key exclusions}
+
+Does this capture your vision? I can adjust before writing the full PRD.
+```
+
+Use AskUserQuestion:
+- "Looks good, write the full PRD" (Recommended)
+- "Adjust the scope"
+- "Add/remove features"
+- "Start over"
+
+#### Step 3.2: Write Full PRD
+
+Follow the prd-writer skill template exactly:
+- Include all required sections
+- Write testable acceptance criteria
+- Add edge cases for complex features
+- Include Technical Context from research
+- Mark Open Questions for unresolved items
+
+#### Step 3.3: Review with User
+
+Present the full PRD and ask for feedback:
 ```
+Here's the complete PRD. Please review:
 
-### Step 2: Problem Statement
+{Full PRD content}
 
-Ask: "What problem does this solve? (1-2 sentences describing the pain point)"
+---
 
-Store the answer and proceed.
+Any changes needed before I save it?
+```
 
-### Step 3: Target Users
+Use AskUserQuestion:
+- "Save as-is" (Recommended)
+- "Make changes" (then ask what)
+- "Discard and start over"
 
-Ask: "Who experiences this problem? (Describe your target users)"
+#### Step 3.3a: PRD Critique (Critic Agent)
 
-Store the answer and proceed.
+**Before final save**, spawn the `flux-critic` agent to provide objective analysis.
 
-### Step 4: MVP Scope
+**Auto-trigger critique when ANY of these apply:**
 
-Ask: "What's the simplest version that would be useful? (Minimum viable solution)"
+| Trigger | Threshold |
+|---------|-----------|
+| Scope score from Step 1.4 | >= 3 points |
+| Estimated task count | > 25 tasks |
+| External dependencies | 2+ third-party services |
+| Unfamiliar technologies | Multiple new-to-user techs |
+| User requests review | "Is this feasible?" / "What are the risks?" |
 
-Store the answer and proceed.
+**Skip critique when:**
+- Very simple PRD (1-2 features, single domain)
+- User explicitly requests to skip
+- PRD is a refinement of an already-critiqued version
 
-### Step 5: Core Features
+**Spawning the critic:**
 
-Ask using AskUserQuestion with multiSelect:
 ```
-What are the core features for MVP? (Select all that apply)
-- User Authentication
-- Data Storage/Persistence
-- API Integration
-- Real-time Updates
+Task({
+  subagent_type: "flux:flux-critic",
+  prompt: `Critique this PRD before final approval:
+
+## PRD Content
+${fullPrdMarkdown}
+
+## Context
+- Project type: ${projectType}
+- Existing codebase: ${hasCodebase ? 'Yes' : 'No (greenfield)'}
+- Scope score: ${scopeScore}/7 from assessment
+- Technologies: ${keyTechnologies}
+
+Analyze across these dimensions:
+1. **Feasibility** - Can this be built with stated constraints?
+2. **Scope** - Is it right-sized? (Target: 15-25 tasks)
+3. **Risks** - What could go wrong? What's missing?
+4. **Alternatives** - Are there simpler approaches?
+
+Output your critique in the standard format.`,
+  description: "Critique PRD: ${prdTitle}"
+})
 ```
-Also allow free text for custom features.
 
-### Step 6: Technical Constraints
+**Present critique to user:**
 
-Ask: "Any technical constraints or preferences? (Framework, language, hosting, etc.)"
-- If blank, that's fine - proceed with defaults
+```
+## PRD Review
+
+| Dimension | Assessment | Notes |
+|-----------|------------|-------|
+| Feasibility | {Good/Caution/Concern} | {1-line reason} |
+| Scope | {Good/Caution/Concern} | {1-line reason} |
+| Risks | {Good/Caution/Concern} | {1-line reason} |
 
-### Step 7: Review & Confirm
+### Issues to Address
+{List any critical or high-severity issues from the critique}
 
-Summarize the interview answers:
+### Recommendation
+{Approve / Revise / Rethink}
 ```
-## PRD Summary
 
-**Project Type:** {type}
-**Problem:** {problem}
-**Target Users:** {users}
-**MVP Scope:** {mvp}
-**Core Features:** {features}
-**Constraints:** {constraints}
+Use AskUserQuestion:
+- "Save PRD as-is"
+- "Address the issues first" (then iterate)
+- "Skip critique and save" (if user wants to proceed anyway)
+
+#### Step 3.4: Store PRD
 
-Ready to generate PRD outline?
+**CRITICAL: Detect adapter type FIRST** by calling `get_project_context`:
+
+```
+mcp__flux__get_project_context()
+→ Returns: { adapter: { type: "local" | "linear" | ... }, ... }
 ```
 
-Use AskUserQuestion to confirm:
-- Generate PRD Outline (Recommended)
-- Edit Answers
-- Start Over
+**Branch workflow based on `adapter.type`:**
 
-## After Interview Complete
+---
 
-The `get_project_context` call from Pre-check returns the adapter type. Use this to determine storage behavior.
+**For Linear Adapter** (`adapter.type === "linear"`):
 
-### For Local Adapter (`adapter.type === "local"`):
+The Linear adapter stores PRD content in Linear issues. **Do NOT create local files.**
 
-1. Generate a slug from the PRD title (e.g., "Flux Plugin Versioning" → "flux-plugin-versioning")
-2. Call `create_prd` with title and a short 1-2 sentence description
-3. Write the full PRD markdown to `.flux/prds/{slug}/prd.md`
-4. Call `update_entity` with `folder_path`: `.flux/prds/{slug}`
-5. Inform user of the created PRD ref and file location
+1. Call `create_prd` with title and brief description (1-2 sentences)
+2. Call `update_entity` with `description: {full PRD markdown}` - this stores the content in Linear
+3. Confirm: "PRD saved as {ref} in Linear"
 
-### For External Adapters (`adapter.type === "linear"`, `"notion"`, etc.):
+**Do NOT:**
+- Create local directories
+- Write local `.md` files
+- Set `folder_path`
+
+---
 
-1. Call `create_prd` with title and a short 1-2 sentence description
-2. Call `update_entity` with `description`: The FULL PRD markdown content
-3. Inform user of the created PRD ref (no local file created)
+**For Local Adapter** (`adapter.type === "local"`):
 
-**Note**: External adapters store PRD content in the external system (Linear issue description, Notion page, etc.). No local files are written.
+The local adapter stores PRD content in local files. Create the folder structure.
 
-## Resume Interview Flow
+1. Generate slug from title (e.g., "User Auth Flow" → "user-auth-flow")
+2. Call `create_prd` with title and brief description (1-2 sentences)
+3. Create directory: `.flux/prds/{slug}/`
+4. Write full PRD to `.flux/prds/{slug}/prd.md`
+5. Call `update_entity` with `folder_path: ".flux/prds/{slug}"`
+6. Confirm: "PRD saved as {ref} at `.flux/prds/{slug}/prd.md`"
 
-1. Call `get_interview` to get current state
-2. Show progress: "Resuming interview at step {step}/6"
-3. Continue from the last unanswered question
+---
+
+**Adapter Detection Summary:**
+
+| Adapter Type | PRD Content Storage | Local Files? |
+|--------------|---------------------|--------------|
+| `local` | `.flux/prds/{slug}/prd.md` | Yes - create folder and files |
+| `linear` | Linear issue description | No - never create local files |
+| `notion` | Notion page | No - never create local files |
+| `specflux` | SpecFlux API | No - never create local files |
+
+#### Step 3.5: Offer Supporting Documents
+
+Based on project type and complexity, systematically offer relevant supporting documents.
+
+##### Document Recommendation Matrix
+
+| Project Type | Recommended | Optional |
+|--------------|-------------|----------|
+| Web Application | Architecture, Wireframes | Data Model, User Flows |
+| API/Backend | Architecture, Data Model | API Contract |
+| CLI Tool | (PRD sufficient) | Architecture (if complex) |
+| Mobile App | Architecture, Wireframes | Data Model, User Flows |
+| Library/Package | Architecture | API Surface |
+
+##### Decision Tree
+
+After PRD is approved, ask based on project characteristics:
+
+```
+1. Is this a UI-heavy feature? (Web/Mobile with 3+ screens)
+   → Offer: Wireframes
+
+2. Does it have custom data storage? (New tables, schemas)
+   → Offer: Data Model
+
+3. Is it a multi-component system? (Frontend + Backend, or microservices)
+   → Offer: Architecture Diagram
+
+4. Are there complex user journeys? (3+ step flows, conditional paths)
+   → Offer: User Flow Diagrams
+```
+
+##### Template: ASCII Wireframes
+
+When user wants wireframes, generate using Unicode box-drawing characters:
+
+```markdown
+# Wireframes: {Feature Name}
+
+## {Screen/View Name}
+
+### Desktop Layout (1200px+)
+┌─────────────────────────────────────────────────────────────────┐
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │ HEADER: Logo          Navigation          [User Menu ▼]  │  │
+│  └──────────────────────────────────────────────────────────┘  │
+│                                                                 │
+│  ┌───────────────────────┐  ┌───────────────────────────────┐  │
+│  │                       │  │                               │  │
+│  │     SIDEBAR           │  │     MAIN CONTENT              │  │
+│  │                       │  │                               │  │
+│  │  ○ Nav Item 1         │  │  ┌─────────────────────────┐  │  │
+│  │  ● Nav Item 2 (active)│  │  │ Card Component          │  │  │
+│  │  ○ Nav Item 3         │  │  │                         │  │  │
+│  │                       │  │  │ [Action] [Secondary]    │  │  │
+│  │                       │  │  └─────────────────────────┘  │  │
+│  └───────────────────────┘  └───────────────────────────────┘  │
+│                                                                 │
+│  ┌──────────────────────────────────────────────────────────┐  │
+│  │ FOOTER: Links | Copyright                                │  │
+│  └──────────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────────┘
+
+### Mobile Layout (<768px)
+┌─────────────────────┐
+│ ☰ Logo      [User]  │
+├─────────────────────┤
+│                     │
+│  Main Content       │
+│                     │
+│  ┌───────────────┐  │
+│  │ Card          │  │
+│  │               │  │
+│  │ [Action]      │  │
+│  └───────────────┘  │
+│                     │
+├─────────────────────┤
+│ Tab | Tab | Tab     │
+└─────────────────────┘
+
+### Element Descriptions
+
+| Element | Type | Behavior |
+|---------|------|----------|
+| Header | Fixed | Sticky top, collapses to hamburger on mobile |
+| Sidebar | Collapsible | Hidden by default on mobile |
+| Card | Interactive | Hover: elevate with shadow; Click: navigate to detail |
+| Nav Item | Button | ● = active, ○ = inactive |
+
+### Interactive States
+- **Hover**: Cards elevate, buttons change color
+- **Active**: Nav items show ● indicator
+- **Loading**: Skeleton placeholders
+- **Empty**: Illustrated empty state with CTA
+```
+
+##### Template: Mermaid Architecture Diagrams
+
+When user wants architecture diagrams, generate using Mermaid syntax:
+
+```markdown
+# Architecture: {System Name}
+
+## System Overview
+
+\`\`\`mermaid
+flowchart TB
+    subgraph Client["Client Layer"]
+        WEB[Web App]
+        MOB[Mobile App]
+    end
+
+    subgraph Gateway["API Gateway"]
+        GW[Load Balancer]
+    end
+
+    subgraph Services["Service Layer"]
+        AUTH[Auth Service]
+        API[Core API]
+        NOTIFY[Notification Service]
+    end
+
+    subgraph Data["Data Layer"]
+        DB[(PostgreSQL)]
+        CACHE[(Redis)]
+        QUEUE[Message Queue]
+    end
+
+    subgraph External["External Services"]
+        EMAIL[Email Provider]
+        STORAGE[Cloud Storage]
+    end
+
+    WEB --> GW
+    MOB --> GW
+    GW --> AUTH
+    GW --> API
+    API --> DB
+    API --> CACHE
+    API --> QUEUE
+    QUEUE --> NOTIFY
+    NOTIFY --> EMAIL
+    API --> STORAGE
+\`\`\`
+
+## Key Flow: {Primary User Journey}
+
+\`\`\`mermaid
+sequenceDiagram
+    participant U as User
+    participant C as Client
+    participant G as Gateway
+    participant A as Auth
+    participant API as Core API
+    participant DB as Database
+
+    U->>C: Action
+    C->>G: Request
+    G->>A: Validate Token
+    A-->>G: Valid
+    G->>API: Forward Request
+    API->>DB: Query/Mutation
+    DB-->>API: Result
+    API-->>G: Response
+    G-->>C: Response
+    C-->>U: Update UI
+\`\`\`
+
+## Component Responsibilities
+
+| Component | Responsibility | Technology |
+|-----------|---------------|------------|
+| Gateway | Routing, rate limiting, auth validation | nginx/Kong |
+| Auth Service | JWT, sessions, user management | Node.js |
+| Core API | Business logic, data access | {tech stack} |
+| Database | Persistence | PostgreSQL |
+| Cache | Sessions, hot data | Redis |
+```
+
+##### Template: Data Model Documentation
+
+When user wants data model documentation, generate ERD and schema:
+
+```markdown
+# Data Model: {System Name}
+
+## Entity Relationship Diagram
+
+\`\`\`mermaid
+erDiagram
+    USER {
+        uuid id PK
+        string email UK
+        string password_hash
+        string name
+        timestamp created_at
+        timestamp updated_at
+    }
+
+    RESOURCE {
+        uuid id PK
+        uuid user_id FK
+        string title
+        text content
+        enum status
+        timestamp created_at
+    }
+
+    USER ||--o{ RESOURCE : owns
+\`\`\`
+
+## Table Definitions
+
+### users
+| Column | Type | Constraints | Description |
+|--------|------|-------------|-------------|
+| id | UUID | PK, DEFAULT uuid_generate_v4() | Unique identifier |
+| email | VARCHAR(255) | UNIQUE, NOT NULL | Login email |
+| password_hash | VARCHAR(255) | NOT NULL | Bcrypt hash |
+| name | VARCHAR(100) | NOT NULL | Display name |
+| created_at | TIMESTAMP | DEFAULT NOW() | Creation time |
+| updated_at | TIMESTAMP | DEFAULT NOW() | Last update |
+
+### Indexes
+
+| Table | Index | Columns | Type | Purpose |
+|-------|-------|---------|------|---------|
+| users | idx_users_email | email | UNIQUE | Login lookup |
+| resources | idx_resources_user | user_id | BTREE | User's resources |
+| resources | idx_resources_status | status, user_id | BTREE | Filtered queries |
+
+### Enums
+
+| Enum | Values | Description |
+|------|--------|-------------|
+| resource_status | pending, active, archived | Lifecycle states |
+```
+
+##### Saving Supporting Documents
+
+**Check `adapter.type` from Pre-Flight Check before creating documents:**
+
+**Local Adapter** (`adapter.type === "local"`):
+```
+.flux/prds/{prd-slug}/
+├── prd.md           # Main PRD
+├── wireframes.md    # UI mockups (if created)
+├── architecture.md  # System diagrams (if created)
+└── data-model.md    # Schema design (if created)
+```
+- Create files using Write tool
+- All documents live in the same folder
+
+**Linear/External Adapter** (`adapter.type === "linear"` or other):
+- **Do NOT create local files**
+- Include diagrams inline in the PRD description (Mermaid renders in Linear)
+- Or offer to show the content for the user to copy elsewhere
+- For wireframes, include ASCII art directly in the PRD
+
+#### Step 3.6: Multi-PRD Continuation
+
+If this PRD was part of a multi-PRD breakdown:
+
+```
+PRD saved: {ref} ({title}) [tag: {tag}]
+
+This is part of your {project name} project:
+✅ {completed PRD} [foundation] - DONE
+→  {next PRD} [foundation] - Ready to create
+○  {future PRD} [mvp] - Waiting on dependencies
+
+Would you like to continue with the next PRD?
+```
+
+Use AskUserQuestion:
+- "Continue with {next PRD}" (Recommended)
+- "I'll create it later"
+- "Show full project roadmap"
+
+When continuing with next PRD:
+1. Skip Phase 1 (Discovery) - context is already gathered
+2. Do targeted research for the specific PRD scope
+3. Generate PRD with proper dependency references
+
+---
 
 ## Refine PRD Flow
 
-1. Query existing PRDs: `query_entities` with type=prd
-2. If multiple, ask which one to refine
-3. Load PRD content:
-   - **Local adapter**: Read from `folder_path` (e.g., `.flux/prds/{slug}/prd.md`)
-   - **External adapters**: Use `description` field from `get_entity`
-4. Ask: "What would you like to change?"
-5. Apply changes and update (follow same adapter-specific flow as creation)
+For `/flux:prd refine` or `/flux:prd refine {ref}`:
+
+1. **Detect adapter**: Call `get_project_context` → store `adapter.type`
+2. Query existing PRDs: `query_entities` with `type: "prd"`
+3. If no ref provided and multiple exist, ask which to refine
+4. Load PRD content based on adapter type:
+   - **Local** (`adapter.type === "local"`): Read from `folder_path + "/prd.md"`
+   - **Linear/External** (`adapter.type !== "local"`): Get from `description` field via `get_entity`
+5. Ask: "What would you like to change?"
+6. Make changes following the same quality standards
+7. Save using the appropriate method for detected adapter type
+
+---
+
+## Edit Specific PRD
+
+For `/flux:prd {ref}` (e.g., `/flux:prd FLUX-P1`):
+
+1. **Detect adapter**: Call `get_project_context` → store `adapter.type`
+2. Call `get_entity` with ref and `include: ["epics", "tasks", "criteria"]`
+3. Load full content based on adapter type:
+   - **Local**: Read from `folder_path + "/prd.md"`
+   - **Linear/External**: Content is in `description` field from `get_entity`
+4. Present current PRD
+5. Ask: "What would you like to edit?"
+6. Apply changes, maintaining structure
+7. Save using appropriate method for detected adapter type
+
+---
 
 ## Guidelines
 
-- One question at a time - don't overwhelm
-- Show progress indicators
-- Allow going back to previous questions
-- Save answers incrementally for resume capability
-- Keep it conversational, not robotic
+### Conversation Quality
+- Be conversational, not robotic
+- Ask one question at a time
 - If user seems stuck, offer examples
+- Adapt questioning based on their expertise level
+
+### Research Quality
+- Always explore the codebase before drafting (if exists)
+- Reference specific files and patterns found
+- Note existing code that can be reused
+
+### PRD Quality
+- Every P0 feature needs the What/Not pattern and testable acceptance criteria
+- Edge cases should be explicit with expected behavior
+- Technical context should reference real code paths
+- Out of Scope prevents scope creep
+
+### Autonomy Levels
+- **High confidence** (clear requirements, familiar domain): Move quickly, fewer questions
+- **Low confidence** (vague requirements, unfamiliar domain): Ask more questions, do more research
+
+---
+
+## Agent Spawning Reference
+
+### When to Spawn `flux-researcher`
+
+| Trigger | Action |
+|---------|--------|
+| User mentions unfamiliar technology | Spawn with tech research prompt |
+| Confidence < 70% about approach | Spawn to validate understanding |
+| External APIs/SDKs involved | Spawn to research integration patterns |
+| "What is X?" or "Research X" | Spawn explicitly |
+| Technology comparison needed | Spawn with comparison prompt |
+
+**Don't spawn for:** Quick fact checks (use WebSearch), known technologies
+
+### When to Spawn `flux-critic`
+
+| Trigger | Action |
+|---------|--------|
+| Scope score >= 3 | Auto-trigger after PRD draft |
+| Estimated tasks > 25 | Auto-trigger after PRD draft |
+| 2+ external dependencies | Auto-trigger after PRD draft |
+| User asks "Is this feasible?" | Spawn explicitly |
+| Multiple unfamiliar technologies | Auto-trigger after PRD draft |
+
+**Don't spawn for:** Simple PRDs (1-2 features), already-critiqued refinements
+
+### Spawning Pattern
+
+```
+Task({
+  subagent_type: "flux:flux-{agent}",
+  prompt: "{detailed prompt with context}",
+  description: "{short description}: {subject}"
+})
+```
+
+Always include in prompt:
+- Project context (type, codebase status)
+- Specific questions to answer
+- Expected output format