@openflowjs/cli 0.2.0

package/dist/core-artifacts/openflow/skills/implement/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: openflow-implement
+description: Use for the OpenFlow implement phase: implement task slices, validate, review, and record evidence.
+---
+
+# OpenFlow Implement
+
+Implement the approved spec one task slice at a time. Validate each slice and record evidence.
+
+This skill depends on:
+
+- `openflow-workflow-governance` for level, stage, and gate rules.
+- `openflow-cli-reference` for exact CLI command syntax and options.
+
+## Inputs
+
+- `.openflow/current.json`
+- active iteration `flow.json`
+- active iteration `STATE.md`
+- active iteration `SPEC.md`
+- active iteration `TASKS.md`
+- active iteration `CONTEXT.md`
+- active iteration `PLAN.md` when present
+- active iteration `reviews/spec-review.json`
+- active iteration `extensions/**/result.json` when present
+
+## Gate Rules
+
+See `openflow-workflow-governance` for complete level routing rules and gate requirements.
+
+**Key points for implement phase:**
+- Level 0: Not applicable. No OpenFlow artifacts exist.
+- Level 1: No formal gate. Implement directly from SPEC.md.
+- Level 2/3: Approved review required before implementation.
+
+**Implement-specific rules:**
+- Do not batch unrelated slices.
+- Do not mark a task complete without validation evidence.
+- If `SPEC.md`, `TASKS.md`, or `PLAN.md` must change materially, stop implementation, increment `flow.json.revision`, reset the gate, and return to `/openflow-spec`.
+
+## Pre-flight
+
+1. Run `openflow preflight --command implement` and parse the JSON output. If `valid` is `false`, stop and tell the user what went wrong in plain language — do not show the raw preflight error.
+2. Use `language` and `iterationPath` from the output for all subsequent steps.
+3. Determine the execution level from `flow.json` or `STATE.md`:
+   - **Level 1**: Read `SPEC.md` only. No `TASKS.md` exists. Implement directly from SPEC.
+   - **Level 2/3**: Read `TASKS.md` and `PLAN.md` from `iterationPath`. If either file is missing, stop and return to `/openflow-spec`; do not generate planning artifacts during `/openflow-implement`.
+4. Run `openflow validate --flow <iterationPath>`. Stop if validation fails — do not edit product code until artifacts are valid.
+5. Write generated OpenFlow documents in the resolved `language`; if absent, use `en-US`.
+
+## Task Difficulty Assessment
+
+See `openflow-workflow-governance` for the canonical difficulty assessment table and executor selection rules.
+
+## Executor Context Per Level
+
+### Level 1
+
+Implement directly from SPEC.md:
+
+1. Read SPEC.md for goal, scope, non-goals, and acceptance criteria.
+2. Implement the change described in the spec.
+3. Validate against acceptance criteria.
+4. No TASKS.md or PLAN.md exists -- implement the full scope as a single unit.
+
+### Level 2/3
+
+Per-task execution:
+
+1. Load the current task from TASKS.md.
+2. Load context: Read First files + PLAN.md Key Interfaces section.
+3. Inspect only the source needed for that task.
+4. Implement the smallest complete behavior slice.
+5. Validate against the task's acceptance criteria.
+
+## Level 1 Execution
+
+1. Read `SPEC.md` Scope and Acceptance Criteria.
+2. Implement the change directly based on the spec.
+3. Run focused validation for the changed behavior.
+4. Record evidence in `STATE.md`.
+5. Run `openflow flow set-gate approved` and `openflow flow set-stage finalize`.
+6. See **Completion Handoff** section for the next step.
+
+## Level 2/3 Execution
+
+### Per-Task Context Loading
+
+For each task, load context from its **Read First** files plus the PLAN.md Key Interfaces section. Do not load unrelated content (other tasks, full SPEC.md, etc.).
+
+### Wave Knowledge Injection
+
+At the start of each Wave (before executing any task within the Wave), perform knowledge injection:
+
+1. Call the `knowledge-retrieval` skill with the current Wave's task descriptions as input text and `phase: implement`.
+2. The retrieval returns at most 3 knowledge entries.
+3. **Hard limit: each Wave injects at most 3 knowledge entries.** If retrieval returns more, keep only the top 3 by relevance.
+4. For each injected entry, use this two-line format:
+   ```
+   summary: <one-sentence summary of the knowledge>
+   why_relevant: <one-sentence explanation of why this knowledge is relevant to the current task>
+   ```
+5. Write the injected entries to the `## Injected Knowledge` section of `WORKING_MEMORY.md`, overwriting any previous Wave's entries. Format:
+   ```markdown
+   - **<knowledge-id>: <title>**
+     - summary: <one-sentence summary>
+     - why_relevant: <why this is relevant>
+   ```
+
+### Mode A: Main Agent Direct (Trivial Tasks Only)
+
+> **Use Mode A only when ALL of these are true**: (1) single file, (2) change is ≤3 lines, (3) no behavior change (e.g., typo fix, comment update, version bump). For everything else — including Simple-difficulty tasks — use Mode B.
+
+1. Select the next unchecked task from `.openflow/iterations/<iteration-id>/TASKS.md`.
+2. Run `openflow flow set-task <T-###>`, then update `STATE.md` before editing.
+3. Load per-task context per the six-step cycle (see **② Load Context**).
+4. Implement only that task slice.
+5. Run focused validation for the changed behavior.
+6. Update `TASKS.md` with concrete evidence.
+7. Run `openflow flow set-task -` to clear the active task.
+
+### Mode B: Subagent Dispatch (Simple / Medium / Complex Tasks)
+
+1. Select the next unchecked task from `TASKS.md`.
+2. Assess task difficulty (Simple / Medium / Complex) based on file scope, change type, and risk level.
+3. Run `openflow flow set-task <T-###>`, then update `STATE.md`.
+4. If this task has unresolved dependencies on other tasks, skip it and process the dependency first.
+5. Select the executor tier and dispatch subagent:
+   - **Simple**: dispatch `executor-quick`
+   - **Medium**: dispatch `executor-general`
+   - **Complex**: dispatch `executor-deep`
+   Pass to the executor: full task text from TASKS.md (paste inline), context about dependencies and architecture, working directory.
+6. Handle the executor's status report:
+   - **DONE** — proceed to review
+   - **DONE_WITH_CONCERNS** — read concerns; if about correctness, address before review; if observations, note and proceed
+   - **NEEDS_CONTEXT** — provide missing context and re-dispatch
+   - **BLOCKED** — assess: upgrade to higher tier executor / provide more context / break task smaller / escalate to user
+7. Dispatch `code-reviewer` (mode: compliance) subagent with:
+   - Task requirements from `TASKS.md`
+   - Executor's report
+   - File paths that changed
+8. If compliance review finds issues, have the executor fix them, then re-dispatch the reviewer. Repeat until approved.
+9. For complex tasks only: dispatch `code-reviewer` (mode: quality) subagent with:
+    - Task description
+    - Executor's report
+    - Files changed
+10. If quality review finds critical or important issues, have the executor fix them, then re-dispatch the reviewer. Repeat until approved.
+11. Update `TASKS.md` with concrete evidence from the review cycle.
+12. Run `openflow flow set-task -` to clear the active task.
+
+### Model Selection
+
+See `openflow-workflow-governance` for the canonical model selection table (Simple→executor-quick, Medium→executor-general, Complex→executor-deep).
+
+### Post-Task (Both Modes)
+
+1. Update `STATE.md`.
+2. Update `flow.json` gate status via `openflow flow set-gate <gate>`.
+3. Run `openflow validate --flow .openflow/iterations/<iteration-id>`.
+4. Continue to the next unchecked task.
+
+## Six-Step Slice Loop
+
+Each task must follow this fixed order. No skipping or reordering. Mode A (main agent direct) and Mode B (dispatch subagent) both follow this loop — the difference is only in who executes steps ③④⑤: Mode A executes them directly, Mode B delegates them to a dispatched executor subagent.
+
+**① Declare Task**
+- Run `openflow flow set-task <T-###>` to set the active task.
+- Update `STATE.md` to record task start.
+- **Discipline**: set-task must precede any code edits. Do not edit code first and then set the task.
+
+**② Load Context**
+- Load the task's **Read First** files and PLAN.md Key Interfaces section.
+- Do not load unrelated content (other tasks, full SPEC.md, etc.).
+
+**③ Minimal Slice**
+- Implement the smallest complete behavior change.
+- Do not over-build or under-build. Stay strictly within the task scope.
+
+**④ Focused Validation**
+- Run the task's specified validation command.
+- Record before/after signals (RED/BEFORE → GREEN/AFTER).
+- Fix on failure. Do not skip.
+
+**⑤ Record Evidence**
+- Write validation results to the task's Evidence field in TASKS.md.
+- Evidence format: `VALIDATION: command\nBEFORE: <result>\nAFTER: <result>`
+- **Discipline**: do not clear active task before Evidence is written back to TASKS.md.
+- Run `openflow flow set-task -` to clear the active task.
+
+**⑥ Continue or Return to Spec**
+- Check the next task.
+- If a spec mismatch is found (SPEC.md/TASKS.md/PLAN.md must change), follow the drift branch:
+  - Stop implementation → run `openflow flow restart-spec --reason "<reason>" --task <T-###>` → return to Spec phase.
+- **Discipline**: branch transitions must be explicit. No silent step skipping.
+
+### Drift Detection (Two-Tier Response)
+
+When during implementation you find that SPEC/TASKS/PLAN descriptions do not match actual code behavior, respond by severity:
+
+**Cosmetic drift** (wording differences, naming inconsistencies, no impact on acceptance criteria):
+- Continue current implementation without interruption.
+- Record the discrepancy in `WORKING_MEMORY.md` under `## Execution Observations`.
+
+**Substantive drift** (scope change, approach mismatch, missing prerequisite, or goal unreachable with current spec):
+- Stop the current task immediately.
+- Run `openflow flow restart-spec --reason "<drift reason>" --task <T-###>`.
+- Return to the Spec phase to revise the spec.
+- Never "implement first, fix later" or silently rewrite the spec mid-implementation.
+
+### Supplementary Reviews (triggered after step ④ when applicable)
+
+- Behavior changes, shared abstractions, risky paths: use `code-reviewer` (mode: compliance).
+- Complex tasks: after compliance review, also run `code-reviewer` (mode: quality).
+- User documentation / API / command changes: use `artifact-reviewer` (mode: docs).
+- Manual / broad / extension-based evidence: use `artifact-reviewer` (mode: validation).
+
+## Validation-First Execution
+
+For each task slice, choose the validation command before implementation and record a before/after signal:
+
+1. **Write the validation command FIRST** (before any implementation).
+2. **Run it before implementation** and record one of:
+   - `RED`: the command fails with the expected error because the task is not implemented yet.
+   - `BEFORE`: the command establishes a baseline when the check already passes, or when the task is docs, config, or a simple refactor.
+3. **Implement minimal changes** -- the smallest complete change for the task slice.
+4. **Run validation again** and record `GREEN` or `AFTER`.
+5. **Record evidence** in the task's Evidence field with both before and after states.
+
+This makes evidence structured and reproducible without forcing artificial failures. Example evidence formats:
+```
+RED: pnpm test -- src/foo.test.ts failed with "Expected 'bar' but got 'baz'"
+GREEN: pnpm test -- src/foo.test.ts passed (3 tests, 0 failures)
+
+BEFORE: pnpm build passed before docs-only change
+AFTER: pnpm build passed after docs-only change
+```
+
+For non-testable tasks (docs, config, simple refactor), adapt the pattern:
+- **Verification command first** (e.g., `pnpm build`, `grep pattern file`)
+- **Run before** to establish baseline
+- **Implement** then run again to confirm success
+
+## Evidence Standard
+
+Evidence must be concrete: command names, test results, screenshots, reviewer findings, or exact blocker text. A task is not complete if evidence says only "done".
+
+Use `deferred: <reason>`, `blocked: <reason>`, or `waived: <reason>` only when the task is intentionally not completed before archive. Do not check the task box for deferred work.
+
+## Supplementary Reviewers
+
+After subagent review (if any), also use existing reviewers when triggers apply:
+
+- Use `code-reviewer` (mode: compliance) when the task affects behavior, shared code, or risk-bearing paths.
+- Use `artifact-reviewer` (mode: docs) when README, docs, API, commands, or user-facing behavior changed.
+- Use `artifact-reviewer` (mode: validation) when evidence is broad, manual, extension-based, or likely to be overstated.
+
+## Guardrails
+
+Do not mark a task complete without evidence.
+Do not use OpenFlow MCP for workflow state management. MCP is only for Review UI interaction; write `.openflow` artifacts directly and validate them with `openflow validate`.
+Do not let a subagent make routing or phase-transition decisions.
+Do not dispatch multiple task-executor subagents in parallel for tasks that touch the same files.
+Do not skip spec compliance review before code quality review (strict order).
+
+If the approved spec is wrong, stop implementation. Revise `SPEC.md`, `TASKS.md`, or `PLAN.md`, increment `flow.json.revision`, reset the spec gate, and return to `/openflow-spec`.
+
+## Completion Handoff
+
+When all tasks are complete (all checkboxes checked with evidence) and `openflow validate` passes:
+
+1. Run `openflow flow set-stage finalize`.
+2. Update `STATE.md` with completion summary.
+3. **Ask user using `AskUserQuestion`** with the question and exactly 2 options below. Translate the visible text to `config.json.language` (default `en-US`):
+
+   - Question (en): "All tasks complete and validated. What's next?"
+     Question (zh-CN): "所有任务已完成并通过验证。请选择下一步："
+   - Option A (en): "Start finalize now (run /openflow-finalize)"
+     Option A (zh-CN): "立即进入归档流程（运行 /openflow-finalize）"
+   - Option B (en): "Defer finalize"
+     Option B (zh-CN): "暂不归档，稍后处理"
+
+4. If user chooses Option A: hand off to `/openflow-finalize`.
+5. If user chooses Option B: tell the user they can run `/openflow-finalize` when ready.
+
+For Level 1, after implementation is complete:
+1. Run `openflow flow set-gate approved` and `openflow flow set-stage finalize`.
+2. Use `AskUserQuestion` with the same 2 options above.
+
+## User-Facing Output
+
+When communicating with the user:
+
+- Do not show raw `openflow validate` or `openflow preflight` error codes, field names, or schema rules. Translate errors into plain language (e.g. "There is a formatting issue in TASKS.md").
+- Do not explain internal OpenFlow state machine concepts (gates, stages, revisions, level routing rationale) unless the user asks.
+- Do not output "Insight" blocks about OpenFlow's internal mechanics, validation rules, or artifact schemas.
+- Keep status updates short: which task is being worked on, what changed, and whether validation passed.

package/dist/core-artifacts/openflow/skills/implement/references/working-memory.md

@@ -0,0 +1,49 @@
+# WORKING_MEMORY.md
+
+`WORKING_MEMORY.md` is a per-iteration scratchpad that carries injected knowledge and execution observations across waves.
+
+Location: `.openflow/iterations/<iteration-id>/WORKING_MEMORY.md`
+
+## Structure
+
+```markdown
+# Working Memory
+
+## Injected Knowledge
+> Written at the start of each Wave by the implement command. Maximum 3 entries.
+
+- **<knowledge-id>: <title>**
+  - summary: <one-sentence summary>
+  - why_relevant: <why this is relevant to the current task>
+
+## Execution Observations
+> task-executor append-only — records important facts discovered during execution.
+
+- [Wave N] <observation>
+
+## Knowledge Candidates
+> task-executor append-only — records candidates that may be worth archiving as knowledge entries.
+
+- [Wave N] <candidate description>
+
+## Blockers and Resolutions
+> task-executor append-only — records blockers encountered and how they were resolved.
+
+- [Wave N] ❌ <blocker> → ✅ <resolution>
+```
+
+## Sections
+
+1. **`## Injected Knowledge`**: Written at the start of each Wave by the implement command. Contains at most 3 entries. Each entry has an ID, title, one-line summary, and a relevance explanation. This section is overwritten each Wave, not appended to.
+
+2. **`## Execution Observations`**: task-executor appends observations about important facts discovered during execution. Format: `[Wave N] <observation>`.
+
+3. **`## Knowledge Candidates`**: task-executor appends candidates that may be worth archiving as knowledge entries. Format: `[Wave N] <candidate description>`.
+
+4. **`## Blockers and Resolutions`**: task-executor appends blockers encountered and how they were resolved. Format: `[Wave N] ❌ <blocker> → ✅ <resolution>`.
+
+## Append-Only Rules
+
+- The `## Injected Knowledge` section is **replaced** at the start of each Wave by the implement command.
+- The `## Execution Observations`, `## Knowledge Candidates`, and `## Blockers and Resolutions` sections are **append-only** for task-executor. Once written, entries must not be modified or deleted by task-executor.
+- Only the finalize phase may consolidate or prune WORKING_MEMORY.md content.

package/dist/core-artifacts/openflow/skills/knowledge-retrieval/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: openflow-knowledge-retrieval
+description: Retrieve project knowledge from .openflow/knowledge/ before spec drafting. Use before writing CONTEXT.md when starting a new iteration.
+---
+
+# OpenFlow Knowledge Retrieval
+
+Retrieve relevant project knowledge from `.openflow/knowledge/` into the current iteration context.
+
+## Trigger Conditions
+
+Retrieve knowledge at these points during the workflow:
+
+| Phase | Trigger Point | Purpose |
+|-------|---------------|---------|
+| **Spec** | As part of the opening sequence step ① (read repository state), before code exploration | Load relevant project knowledge before code exploration to avoid repeating known decisions and mistakes |
+| **Execute** | At the start of each Wave (batch of related tasks) | Provide relevant context for task implementation |
+| **Archive** | During knowledge extraction | Reference existing knowledge to avoid duplication and ensure consistency |
+
+When no knowledge files exist in `.openflow/knowledge/`, skip retrieval entirely. Do not create placeholders or abort the workflow.
+
+## Inputs
+
+- **Request text**: the user request (Spec), the active task description (Execute), or the knowledge being extracted (Archive)
+- **Current phase**: `spec` / `execute` / `archive`
+- **Context keywords**: extracted from the current task or iteration scope
+- **catalog.json**: the knowledge index at `.openflow/knowledge/catalog.json`
+
+## Retrieval Strategy
+
+### Step 1 — Filter
+
+Read `.openflow/knowledge/catalog.json`. From its `entries` array, keep only entries that:
+
+1. Match the current phase's relevant types:
+   - **Spec phase**: `decision`, `guideline`, `pitfall`
+   - **Execute phase**: `decision`, `guideline`, `pitfall`, `process`
+   - **Archive phase**: all types
+2. Have `scope` overlapping with the current iteration's affected packages/files (skip this filter if scope is unknown).
+
+### Step 2 — Rank by relevance
+
+From the filtered entries, select the most relevant ones by matching keywords from the request text against each entry's `title`, `tags`, and `summary`. Prioritize entries where multiple fields match.
+
+### Step 3 — Select and annotate
+
+Take at most **3** entries. For each, generate:
+
+```
+summary: <one-sentence summary of the knowledge>
+why_relevant: <one-sentence explanation of why this knowledge is relevant to the current task>
+```
+
+**Injection format for the consuming artifact:**
+
+```markdown
+## Retrieved Knowledge
+
+- **<ID>: <title>** (type: <type>)
+  summary: <one-sentence summary>
+  why_relevant: <why this is relevant>
+```
+
+**Budget rules:**
+- Maximum 3 entries per retrieval invocation.
+- Maximum 1 retrieval invocation per Spec phase.
+- Maximum 1 retrieval invocation per Execute Wave.
+- Maximum 1 retrieval invocation per Archive knowledge extraction.
+
+## Fallback Behavior
+
+If `.openflow/knowledge/` does not exist, or `catalog.json` is missing, or no entries pass the metadata filter, skip retrieval silently. Do not abort the workflow or insert placeholder sections.
+
+## Constraints
+
+- Knowledge files are read-only during retrieval. Do not modify knowledge content during Spec or Implement phases.
+- Do not search outside `.openflow/knowledge/` for retrieval.
+- Do not inject raw knowledge file content. Always use the two-line `summary + why_relevant` format.

package/dist/core-artifacts/openflow/skills/prd/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: openflow-prd
+description: Generate formal PRD documents from drafts or user input.
+depends_on: 
+---
+
+# OpenFlow PRD
+
+Generate a structured, detailed PRD document from a brainstorm draft or direct user input. The PRD is product-focused (what, why, for whom) — distinct from SPEC which is implementation-focused (how, when). It serves as a decision log, communication tool, and scope contract across product, engineering, design, and QA.
+
+## Input Source
+
+1. Check whether a PRD ID parameter was passed:
+   - **With parameter**: use the ID to locate the PRD directory.
+   - **Without parameter**: use `AskUserQuestion` to prompt the user for a PRD ID in the format `YYYY-MM-DD-short-slug` (e.g., `2025-05-12-user-auth`).
+
+2. Determine the input source:
+   - If `.openflow/prds/<id>/draft.md` exists, use it as the content basis. Read draft.md and extract section information (including the Decisions section if present).
+   - If draft.md does not exist, use the user's text input as the requirements source.
+   - In either case, read `.openflow/prds/<id>/prd.json` for metadata.
+
+3. Read `.openflow/config.json` and extract the `language` field. Use this language for all generated PRD content and user-facing text. If absent, default to `en-US`.
+
+## Level Routing
+
+Determine the appropriate PRD Level (L1 / L2 / L3) before generating content. See `references/level-routing.md` for the full routing logic.
+
+1. Analyze the input source against Level 3 triggers (cross-module, ≥3 roles, IA/data model changes, external dependencies, lengthy draft).
+2. If no L3 trigger, check Level 1 conditions (single feature, no role split, < 80 lines draft, no external deps).
+3. Default to Level 2.
+4. Inform the user of the routing decision and the section set:
+
+   > "Based on the requirements, I'll generate a Level <N> PRD (<reason>). Sections to include: <list>. Adjust the Level?"
+
+5. Use `AskUserQuestion` to confirm or let the user override the Level.
+
+## Open Questions Resolution
+
+Before writing the PRD, identify any open questions or ambiguities in the requirements.
+
+1. **Identify questions**: Extract unclear points, missing decisions, or ambiguous requirements from the input source.
+2. **Discuss with user**: Present all open questions to the user using `AskUserQuestion` and wait for answers. Do NOT proceed until the user has resolved them.
+3. **Record resolutions in Decision Log**: Each resolved question becomes an entry in the Decision Log section (Level 2+) — capture the options considered, the chosen option, and the rationale.
+4. **No "Open Questions" section in PRD**: The PRD document must not contain unresolved questions. All questions are resolved before writing.
+
+## Visual Analysis
+
+Determine which visual aids genuinely improve understanding. Do not generate visuals for the sake of visuals — if plain text describes a feature clearly, no diagram is needed.
+
+### Visualization Types
+
+| Type | Purpose | When to Use |
+|------|---------|-------------|
+| Wireframe HTML | Page layout and element placement | Visual complexity warrants showing structure |
+| Mermaid flowchart | Step-by-step process with branches | Multi-step interaction with decision points |
+| Mermaid sequence diagram | Cross-component message timing | Multi-service or multi-component coordination |
+| Mermaid state diagram | Object lifecycle states | Stateful entities (orders, tasks, users) |
+| Mermaid mindmap | Feature hierarchy overview | Complex feature group bird's-eye view |
+| Mermaid ER diagram | Data entity relationships | Data modeling needed |
+| User Journey map | Cross-touchpoint experience | Full user lifecycle design |
+
+### Wireframe Rules (MUST follow)
+
+When generating wireframe HTML files, follow `references/wireframe-template.html` and these rules:
+
+- **Grayscale only**: use `#fff`, `#f5f5f5`, `#e0e0e0`, `#999`, `#666`, `#333`. No brand colors, no gradients, no decorative backgrounds.
+- **Structure over style**: focus on layout, hierarchy, element placement. No rounded corners > 4px, no shadows, no animations, no icon libraries.
+- **Dashed borders** for placeholder/content areas, **solid borders** for structural boundaries.
+- **Label everything**: all interactive elements must have clear text labels.
+- **Show states**: indicate normal / empty / error / loading states where relevant, either inline or as variants.
+- **System fonts only**: no custom fonts, no Google Fonts, no Iconify.
+- **Max width 960px**: keep the canvas simple and readable.
+- **One wireframe per feature/page**: name files `<feature-name>-wireframe.html`.
+- **Skip if simple**: if a feature can be described clearly in 2-3 sentences, do not generate a wireframe for it.
+
+### Selection Principles
+
+- For **L1 PRDs**: usually no wireframes needed; rely on text descriptions.
+- For **L2 PRDs**: generate wireframes for core interaction pages only.
+- For **L3 PRDs**: each major UI feature gets its own wireframe; complex flows get flowcharts; stateful objects get state diagrams.
+
+### Output Planning
+
+List planned visualizations with rationale before generating. Determine file names and store all in `.openflow/prds/<id>/assets/`.
+
+## Content Generation
+
+Based on the resolved Level, input source, and visualization plan, generate the formal PRD document.
+
+1. **Write prd.md**:
+   - Path: `.openflow/prds/<id>/prd.md`
+   - Structure follows `references/prd-template.md`
+   - Generate only the sections required (`*`) or recommended (`+`) for the determined Level. Skip `?` and `–` sections unless the input source has rich content for them.
+   - **Functional Design is the core**: organize by feature or feature group. Each feature gets Purpose, User Story, Detailed Behavior, UI/Interaction (if applicable), Edge Cases, and per-feature Acceptance Criteria.
+   - Information from draft.md must be fully reflected. Do not lose details from the discussion.
+   - Reference visualization assets using relative links (e.g., `./assets/feature-x-wireframe.html`).
+   - **Do NOT include an "Open Questions" section** — all questions should be resolved.
+
+2. **Create visualization assets**:
+   - Create files in `.openflow/prds/<id>/assets/`
+   - HTML wireframes follow `references/wireframe-template.html`
+   - Mermaid diagrams can be embedded in prd.md or stored as standalone `.md` files in `assets/`
+   - Verify all asset files referenced in prd.md actually exist after generation
+
+3. **Update prd.json**:
+   - Set `status` to `"reviewing"`
+   - Update `assets` to include all generated asset file paths
+   - Increment `revision` by 1
+   - Update `updatedAt` to ISO 8601 current time
+   - Add a `level` field with the determined Level (1, 2, or 3)
+
+## AI Self-Review (Optional, Recommended for L2+)
+
+For Level 2 and Level 3 PRDs, dispatch `artifact-reviewer` (mode: prd) for AI self-review:
+
+```
+Agent(subagent_type="openflow:artifact-reviewer", prompt="Review PRD document. mode: prd. Level: <N>. PRD directory: .openflow/prds/<id>/")
+```
+
+**Revision loop**:
+- If artifact-reviewer returns `changes_required` or finds BLOCKERs:
+  - Revise prd.md and assets based on findings
+  - Re-invoke artifact-reviewer
+- Maximum 3 revision rounds
+- After 3 rounds with unresolved issues, present remaining issues to the user via `AskUserQuestion` for resolution, then update the PRD accordingly
+
+After revisions, update `revision` and `updatedAt` in prd.json.
+
+## Studio Review
+
+Submit the PRD to Studio for human review.
+
+1. **Initiate review**:
+   - Use MCP tool `openflow_review_start` with parameters:
+     - `flowPath`: pointing to `.openflow/prds/<id>`
+     - `mode`: `"prd"`
+   - Show the review URL to the user
+
+2. **Wait for review result**:
+   - Use MCP tool `openflow_review_wait` to wait for the human review result
+
+3. **Process review result**:
+   - If `changes_requested`:
+     - Read review annotations
+     - Revise prd.md and assets based on annotations
+     - Update prd.json: increment `revision` by 1, update `updatedAt`
+     - Re-submit for review (return to step 1)
+   - If `approved`:
+     - Update prd.json `status` to `"approved"`
+     - Proceed to "Completion Handoff"
+
+## Completion Handoff
+
+After the PRD passes review:
+
+1. Update prd.json: confirm `status` is `"approved"`.
+
+2. Inform the user with an actionable command:
+   > PRD approved. To start implementation, run:
+   > `/openflow-spec prd <prd-id>`
+
+3. Do not automatically execute subsequent commands. Only provide the actionable command above.
+
+## Subagent Dispatch
+
+- **Recommended for L2+**: dispatch `artifact-reviewer` (mode: prd) for AI self-review. See "AI Self-Review" section.
+- The main flow is executed directly by the main agent.
+
+## References
+
+- `references/prd-template.md` — full PRD template with Level annotations
+- `references/level-routing.md` — Level routing rules and section sets
+- `references/wireframe-template.html` — wireframe HTML base