@zigrivers/scaffold 2.1.2 → 2.38.0

package/pipeline/validation/implementability-dry-run.md

@@ -1,12 +1,13 @@
 ---
 name: implementability-dry-run
 description: Dry-run specs as implementing agent, catching ambiguity
+summary: "Simulates picking up each task as an implementing agent and flags anything ambiguous — unclear acceptance criteria, missing input files, undefined error handling — that would force an agent to guess."
 phase: "validation"
-order: 31
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/implementability-dry-run.md]
+order: 1350
+dependencies: [implementation-plan-review, review-security]
+outputs: [docs/validation/implementability-dry-run.md, docs/validation/implementability-dry-run/review-summary.md, docs/validation/implementability-dry-run/codex-review.json, docs/validation/implementability-dry-run/gemini-review.json]
 conditional: null
-knowledge-base: [implementability-review]
+knowledge-base: [implementability-review, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -15,22 +16,56 @@ AI agent would experience when picking up each implementation task: are the
 inputs clear, are the acceptance criteria testable, are there ambiguities
 that would force the agent to guess?
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent dry-runs — different models encounter different ambiguities
+when simulating implementation.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/implementability-dry-run.md — findings report
+- docs/validation/implementability-dry-run/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/implementability-dry-run/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/validation/implementability-dry-run/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Every task has sufficient input specification for an agent to start without guessing
+- (mvp) Every task has testable acceptance criteria
+- (deep) No task references undefined concepts, components, or APIs
+- (deep) Every task's dependencies are present in the implementation plan
+- (deep) Shared code patterns identified and documented (no duplication risk across tasks)
+- Findings categorized P0-P3 with specific file, section, and issue for each
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+
+## Finding Disposition
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  dispatched to Codex and Gemini if available, with graceful fallback to
+  Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Scale thoroughness with depth.
+- **custom:depth(1-5)**: Depth 1: verify each task has enough context to start. Depth 2: add tool/dependency availability check. Depth 3: full dry-run simulation of first 3 tasks with quality gate verification. Depth 4: add external model dry-run. Depth 5: multi-model dry-run with implementation plan revision recommendations.
 
 ## Mode Detection
-Not applicable — validation always runs fresh against current artifacts.
+Not applicable — validation always runs fresh against current artifacts. If
+multi-model artifacts exist under docs/validation/implementability-dry-run/,
+they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/implementability-dry-run/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/validation/scope-creep-check.md

@@ -1,12 +1,13 @@
 ---
 name: scope-creep-check
 description: Verify specs stay aligned to PRD boundaries
+summary: "Compares everything that has been specified against the original PRD and flags anything that was not in the requirements — features, components, or tasks that crept in without justification."
 phase: "validation"
-order: 33
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/scope-creep-check.md]
+order: 1370
+dependencies: [implementation-plan-review, review-security]
+outputs: [docs/validation/scope-creep-check.md, docs/validation/scope-creep-check/review-summary.md, docs/validation/scope-creep-check/codex-review.json, docs/validation/scope-creep-check/gemini-review.json]
 conditional: null
-knowledge-base: [scope-management]
+knowledge-base: [scope-management, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -17,22 +18,56 @@ should not introduce features not in the PRD — UX-level enhancements are
 allowed only via the innovation step with explicit user approval. Flag any
 scope expansion for explicit approval.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent scope analysis — different models interpret PRD boundaries
+differently, surfacing subtle creep.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
 
 ## Expected Outputs
 - docs/validation/scope-creep-check.md — findings report
+- docs/validation/scope-creep-check/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/scope-creep-check/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/validation/scope-creep-check/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Every user story traces back to a PRD feature or requirement
+- (mvp) Every architecture component traces to a PRD requirement
+- Items beyond PRD scope are flagged with disposition (remove, defer, or justify)
+- (deep) No "gold-plating" — implementation tasks do not exceed story acceptance criteria
+- (deep) Feature count has not grown beyond PRD scope without documented justification
+- Findings categorized P0-P3 with specific file, section, and issue for each
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+
+## Finding Disposition
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  dispatched to Codex and Gemini if available, with graceful fallback to
+  Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Scale thoroughness with depth.
+- **custom:depth(1-5)**: Depth 1: feature count comparison (PRD vs implementation plan). Depth 2: add component-level tracing. Depth 3: full story-level and task-level audit against original PRD scope. Depth 4: add external model scope assessment. Depth 5: multi-model scope review with risk-weighted creep analysis.
 
 ## Mode Detection
-Not applicable — validation always runs fresh against current artifacts.
+Not applicable — validation always runs fresh against current artifacts. If
+multi-model artifacts exist under docs/validation/scope-creep-check/,
+they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/scope-creep-check/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/validation/traceability-matrix.md

@@ -1,12 +1,14 @@
 ---
 name: traceability-matrix
 description: Build traceability from PRD requirements through architecture to implementation tasks
+summary: "Builds a map showing that every PRD requirement traces through to user stories, architecture components, implementation tasks, and test cases — with no gaps in either direction."
 phase: "validation"
-order: 28
-dependencies: [review-tasks, review-security]
-outputs: [docs/validation/traceability-matrix.md]
+order: 1320
+dependencies: [implementation-plan-review, review-security]
+outputs: [docs/validation/traceability-matrix.md, docs/validation/traceability-matrix/review-summary.md, docs/validation/traceability-matrix/codex-review.json, docs/validation/traceability-matrix/gemini-review.json]
+reads: [story-tests, create-evals]
 conditional: null
-knowledge-base: [traceability]
+knowledge-base: [traceability, multi-model-review-dispatch]
 ---
 
 ## Purpose
@@ -15,22 +17,60 @@ to implementation tasks. Verify the full chain: PRD → User Stories → Domain
 Model → Architecture → Tasks, with no orphans in either direction. Every PRD
 requirement must trace to at least one story, every story to at least one task.
 
+At depth 4+, dispatches to external AI models (Codex, Gemini) for
+independent traceability validation — different models catch different
+coverage gaps.
+
 ## Inputs
-- All phase output artifacts (docs/prd.md, docs/domain-models/, docs/adrs/,
+- All phase output artifacts (docs/plan.md, docs/domain-models/, docs/adrs/,
   docs/system-architecture.md, etc.)
+- docs/story-tests-map.md (required if exists) — AC-to-test-case traceability
+- tests/acceptance/ (required if exists) — test skeleton files for verification
+- docs/eval-standards.md (required if exists) — eval coverage documentation
 
 ## Expected Outputs
 - docs/validation/traceability-matrix.md — findings report
+- docs/validation/traceability-matrix/review-summary.md (depth 4+) — multi-model validation synthesis
+- docs/validation/traceability-matrix/codex-review.json (depth 4+, if available) — raw Codex findings
+- docs/validation/traceability-matrix/gemini-review.json (depth 4+, if available) — raw Gemini findings
 
 ## Quality Criteria
-- Analysis is comprehensive (not superficial)
-- Findings are actionable (specific file, section, and issue)
-- Severity categorization (P0-P3)
+- (mvp) Every PRD requirement maps to >= 1 user story
+- (mvp) Every user story maps to >= 1 implementation task
+- (deep) Every acceptance criterion maps to >= 1 test case (verified against `docs/story-tests-map.md`)
+- (deep) Every test case maps to >= 1 implementation task
+- (deep) No orphan items in either direction at any layer
+- (deep) Bidirectional traceability verified: PRD → Stories → Domain → Architecture → Tasks
+- Findings categorized P0-P3 with specific file, section, and issue for each
+- (depth 4+) Multi-model findings synthesized with consensus/disagreement analysis
+
+## Finding Disposition
+- **P0 (blocking)**: Must be resolved before proceeding to implementation. Create
+  fix tasks and re-run affected upstream steps.
+- **P1 (critical)**: Should be resolved; proceeding requires explicit risk acceptance
+  documented in an ADR. Flag to project lead.
+- **P2 (medium)**: Document in implementation plan as tech debt. May defer to
+  post-launch with tracking issue.
+- **P3 (minor)**: Log for future improvement. No action required before implementation.
+
+Findings are reported in the validation output file with severity, affected artifact,
+and recommended resolution. P0/P1 findings block the implementation-plan step from
+proceeding without acknowledgment.
 
 ## Methodology Scaling
-- **deep**: Exhaustive analysis with all sub-checks.
+- **deep**: Exhaustive analysis with all sub-checks. Multi-model validation
+  dispatched to Codex and Gemini if available, with graceful fallback to
+  Claude-only enhanced validation.
 - **mvp**: High-level scan for blocking issues only.
-- **custom:depth(1-5)**: Scale thoroughness with depth.
+- **custom:depth(1-5)**: Depth 1: PRD requirement to user story mapping only. Depth 2: add story to implementation task mapping. Depth 3: full bidirectional chain (PRD → story → task → test → eval). Depth 4: add external model verification of coverage gaps. Depth 5: multi-model reconciliation with gap resolution recommendations.
 
 ## Mode Detection
-Not applicable — validation always runs fresh against current artifacts.
+Not applicable — validation always runs fresh against current artifacts. If
+multi-model artifacts exist under docs/validation/traceability-matrix/,
+they are regenerated each run.
+
+## Update Mode Specifics
+- **Detect**: `docs/validation/traceability-matrix/` directory exists with prior multi-model artifacts
+- **Preserve**: Prior multi-model artifacts are regenerated each run (not preserved). However, if prior findings were resolved and documented, reference the resolution log to distinguish regressions from known-resolved issues.
+- **Triggers**: Any upstream artifact change triggers fresh validation
+- **Conflict resolution**: If a previously-resolved finding reappears, flag as regression rather than new finding

package/pipeline/vision/create-vision.md

@@ -0,0 +1,267 @@
+---
+name: create-vision
+description: Create a comprehensive product vision document from a project idea
+summary: "Asks about your idea — who it's for, what problem it solves, what makes it different — and produces a vision document with elevator pitch, target audience, competitive positioning, guiding principles, and success criteria."
+phase: "vision"
+order: 010
+dependencies: []
+outputs: [docs/vision.md]
+conditional: null
+knowledge-base: [vision-craft]
+---
+
+## Purpose
+Transform a project idea into a strategic product vision document that defines
+the product's purpose, target audience, competitive positioning, and guiding
+principles. This is the North Star document that all subsequent phases reference.
+The vision drives the PRD, architecture decisions, and implementation priorities
+throughout the entire pipeline.
+
+## Inputs
+- Project idea (provided by user verbally or in a brief)
+- Existing project files (if brownfield — any README, docs, or code)
+- Market context or competitive research (if available)
+
+## Expected Outputs
+- docs/vision.md — Product vision document
+
+## Quality Criteria
+- (mvp) Problem statement is specific and testable (not vague aspirations)
+- (mvp) Vision statement describes positive change in the world, not a product feature
+- (mvp) Vision statement is a single sentence of 25 words or fewer
+- (mvp) Target audience defined by behaviors and motivations, not demographics
+- (deep) For each competitor, at least one strength is documented alongside weaknesses
+- (mvp) Each guiding principle is framed as 'We choose X over Y' where Y is a legitimate alternative
+- (deep) Anti-vision contains >= 3 named traps, each referencing a concrete product direction or feature class
+- (deep) Business model addresses sustainability without being a full business plan
+- (mvp) Every section names at least one concrete decision or constraint
+- (mvp) Vision does not contradict docs/plan.md (if PRD exists in update mode)
+
+## Methodology Scaling
+- **deep**: Comprehensive vision document. Full competitive research, detailed
+  personas, 3-5 guiding principles with tradeoff framing, business model
+  analysis, multi-year success horizon. 3-5 pages.
+- **mvp**: Vision statement, target audience, core problem, value proposition,
+  2-3 guiding principles. 1 page. Enough to anchor the PRD.
+- **custom:depth(1-5)**: Depth 1-2: MVP-style. Depth 3: add competitive
+  landscape and anti-vision. Depth 4: add business model and strategic risks.
+  Depth 5: full document with all 12 sections.
+
+## Mode Detection
+If docs/vision.md exists, this is an update. Read and analyze the existing
+document. Check for tracking comment: `<!-- scaffold:vision v<ver> <date> -->`.
+
+## Update Mode Specifics
+- **Detect prior artifact**: docs/vision.md exists
+- **Preserve**: Vision statement (unless user explicitly wants to change it),
+  guiding principles already validated, competitive analysis findings,
+  user-approved strategic decisions
+- **Triggers for update**: Strategic direction changed, new competitive intel,
+  target audience refined, user wants deeper analysis
+- **Conflict resolution**: if update contradicts existing guiding principles,
+  surface the conflict to the user before proceeding
+
+## Instructions
+
+I have an idea for an application and I want you to help me create a
+comprehensive product vision document that will serve as the strategic North
+Star for all downstream product decisions.
+
+### Mode Detection
+
+Before starting, check if `docs/vision.md` already exists:
+
+**If the file does NOT exist → FRESH MODE**: Skip to Phase 1 and create from scratch.
+
+**If the file exists → UPDATE MODE**:
+1. **Read & analyze**: Read the existing document completely. Check for a tracking comment on line 1: `<!-- scaffold:vision v<ver> <date> -->`. If absent, treat as legacy/manual — be extra conservative.
+2. **Diff against current structure**: Compare the existing document's sections against what this prompt would produce fresh. Categorize every piece of content:
+   - **ADD** — Required by current prompt but missing from existing doc
+   - **RESTRUCTURE** — Exists but doesn't match current prompt's structure or best practices
+   - **PRESERVE** — Project-specific decisions, rationale, and customizations
+3. **Cross-doc consistency**: Read `docs/plan.md` if it exists and verify updates won't contradict it.
+4. **Preview changes**: Present the user a summary:
+   | Action | Section | Detail |
+   |--------|---------|--------|
+   | ADD | ... | ... |
+   | RESTRUCTURE | ... | ... |
+   | PRESERVE | ... | ... |
+   If >60% of content is unrecognized PRESERVE, note: "Document has been significantly customized. Update will add missing sections but won't force restructuring."
+   Wait for user approval before proceeding.
+5. **Execute update**: Restructure to match current prompt's layout. Preserve all project-specific content. Add missing sections with project-appropriate content.
+6. **Update tracking comment**: Add/update on line 1: `<!-- scaffold:vision v<ver> <date> -->`
+7. **Post-update summary**: Report sections added, sections restructured, content preserved, and any cross-doc issues found.
+
+**In both modes**, follow all instructions below — update mode starts from existing content rather than a blank slate.
+
+### Update Mode Specifics
+- **Primary output**: `docs/vision.md`
+- **Preserve**: Vision statement (unless user explicitly requests change), guiding principles, competitive findings, strategic decisions
+- **Related docs**: `docs/plan.md`
+- **Special rules**: Never change guiding principles without user approval. Preserve any strategic decisions that were explicitly made by the user.
+
+## Here's my idea:
+$ARGUMENTS
+
+## Phase 1: Strategic Discovery
+
+Use AskUserQuestionTool throughout this phase. Batch related questions together — don't ask one at a time.
+
+### Understand the Problem Space
+- What problem exists in the world? Who suffers from it? How do they cope today?
+- Push for specificity — "everyone" is not a target audience, "it's slow" is not a problem statement
+- What's the root cause of the pain, not just the symptom?
+- How big is this problem? How many people experience it? How often?
+
+### Articulate the Vision
+- What does the world look like when this product succeeds?
+- Craft the Geoffrey Moore elevator pitch together: For [target customer] who [need], the [product] is a [category] that [key benefit]. Unlike [alternative], our product [differentiation].
+- Is this vision inspiring enough that someone would want to work on it?
+- Could someone evaluate a product decision against this vision and get a clear yes/no?
+
+### Define the Target Audience
+- Deep persona work — behaviors, motivations, contexts of use (not demographics)
+- Primary vs secondary audiences — who is the main user? Who else benefits?
+- What are they doing the moment before they reach for this product?
+- What does "success" look like from their perspective?
+
+### Understand the Market
+- What alternatives exist today? Direct competitors, indirect alternatives, "do nothing"
+- Why do existing solutions fall short? Be specific.
+- What's the market gap or timing advantage?
+- Is this a new category, a better mousetrap, or a different approach entirely?
+
+### Challenge and Innovate
+- Challenge assumptions — if something doesn't make sense or is overengineered, say so
+- Identify areas not considered (edge cases, market dynamics, competitive threats)
+- Propose strategic angles the user hasn't thought of
+- Be honest about weaknesses in the positioning
+
+## Phase 2: Strategic Depth
+
+Use AskUserQuestionTool. Batch related questions together.
+
+### Business Model & Viability
+- How does this make money (or sustain itself)?
+- What's the go-to-market intuition? (Not a full business plan — directional thinking)
+- What are the key unit economics assumptions?
+- What would make this economically unviable?
+
+### Guiding Principles
+- Define 3-5 design tenets that will guide every downstream decision
+- Frame as "When in doubt, we choose X over Y"
+- These must actually constrain decisions — test each: would a reasonable team choose the opposite?
+- If nobody would disagree with a principle, it's a platitude — cut it
+
+### Anti-Vision
+- What is this product explicitly NOT?
+- What traps in this product space catch every competitor?
+- What features or directions would dilute the vision?
+- "If we find ourselves doing X, we've lost the plot"
+
+### Success Horizon
+- What does year 1 vs year 3 look like?
+- What are the leading indicators that the vision is being realized?
+- What would make this a failure even if it ships on time?
+- How will we know if the guiding principles are actually guiding decisions?
+
+## Phase 3: Competitive & Market Research
+
+Research the competitive landscape using web search and any context the user provides:
+- Identify direct competitors, indirect alternatives, and the "do nothing" option
+- For each: what they do well, where they fall short, why users would choose this product instead
+- Surface market trends, emerging patterns, and timing considerations
+- Validate or challenge the user's assumptions about the market gap
+- Be honest about what competitors do better — acknowledge strengths, don't dismiss them
+
+## Phase 4: Documentation
+
+Create `docs/vision.md` (create the `docs/` directory if it doesn't already exist) with tracking comment `<!-- scaffold:vision v1 YYYY-MM-DD -->` on line 1.
+
+### Required Sections
+
+1. **Vision Statement** — One inspiring sentence. The North Star. Should describe the positive change the product creates in the world, not a product feature. Must be concise enough to remember and repeat.
+
+2. **Elevator Pitch** — Geoffrey Moore template filled in:
+   > For [target customer] who [need], [product name] is a [product category] that [key benefit]. Unlike [primary alternative], our product [primary differentiation].
+
+3. **Problem Space** — The pain in vivid detail: who feels it, how they cope today, why existing solutions fail, what the root cause is. Grounded in evidence, not assumptions.
+
+4. **Target Audience** — Primary and secondary personas with:
+   - Behaviors and motivations (not demographics)
+   - Context of use (when, where, why they reach for this product)
+   - Current workarounds and their limitations
+   - What "success" looks like from their perspective
+
+5. **Value Proposition** — The unique value delivered, framed as outcomes not features. Why someone would choose this over alternatives (including doing nothing).
+
+6. **Competitive Landscape** — Market map showing:
+   - Direct competitors and their strengths/weaknesses
+   - Indirect alternatives (different approaches to the same problem)
+   - The "do nothing" option and why it's insufficient
+   - The product's genuine differentiation (not wishful thinking)
+
+7. **Guiding Principles** — 3-5 design tenets framed as prioritization tradeoffs:
+   - "We choose simplicity over power" or "We choose correctness over speed"
+   - Each must actually constrain decisions — if nobody would disagree, it's not a principle
+
+8. **Anti-Vision** — What the product is NOT:
+   - Features and directions explicitly excluded
+   - Common traps in this product space to avoid
+   - "If we find ourselves doing X, we've lost the plot"
+
+9. **Business Model Intuition** — Directional thinking about sustainability:
+   - Revenue model (or how it sustains itself if non-commercial)
+   - Key unit economics assumptions
+   - Go-to-market direction (not a full GTM plan)
+
+10. **Success Criteria** — Measurable indicators across time horizons:
+    - Leading indicators (early signals the vision is working)
+    - Year 1 milestones
+    - Year 3 aspirations
+    - What failure looks like (even if the product ships)
+
+11. **Strategic Risks & Assumptions** — Explicit bets being made:
+    - Key assumptions that must hold true for the vision to succeed
+    - What could invalidate each assumption
+    - Risk severity and mitigation thinking
+
+12. **Open Questions** — Unresolved strategic questions:
+    - Questions that don't need answers now but will need them eventually
+    - Research or validation needed before committing to specific directions
+
+### Documentation Quality Standards
+- Every section must be specific enough to guide PRD writing without strategic ambiguity
+- Avoid corporate boilerplate: "user-friendly interface" and "seamless experience" are banned
+- The vision statement must be testable: could you evaluate a product decision against it and get a clear yes/no?
+- Guiding principles must create real tradeoffs, not platitudes
+- Competitive analysis must be honest about the product's weaknesses, not just strengths
+
+## How to Work With Me
+- Treat me as the product owner. I make the strategic calls, you make them happen.
+- Don't overwhelm me with business jargon. Translate everything.
+- Push back if my vision is unfocused, my positioning is weak, or my assumptions are wrong.
+- Be honest about competitive threats. I'd rather adjust my strategy than be blindsided.
+- Batch your questions using AskUserQuestionTool — don't pepper me one at a time.
+
+## What This Document Should NOT Be
+- A product requirements document — that comes later in create-prd
+- A feature list — the vision is about purpose and positioning, not functionality
+- Vague — "make the world a better place" is not a vision. Be specific.
+- A business plan — business model intuition, not a 50-page plan
+- Corporate boilerplate — if it could apply to any product, it's useless
+
+I don't just want a document. I want a North Star that every team member can point to when making a difficult product decision.
+
+## After This Step
+
+When this step is complete, tell the user:
+
+---
+**Phase 0 complete** — `docs/vision.md` created.
+
+**Next:** Run `/scaffold:review-vision` — Review the vision for clarity, coherence, and downstream readiness.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---