@zigrivers/scaffold 2.28.1 → 2.38.0

package/pipeline/build/multi-agent-start.md

@@ -0,0 +1,236 @@
+---
+name: multi-agent-start
+description: Start multi-agent execution loop in a worktree
+summary: "Sets up a named agent in an isolated git worktree so multiple agents can implement tasks simultaneously without file conflicts, each following the same TDD loop."
+phase: "build"
+order: 1530
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [tdd-execution-loop, task-claiming-strategy, worktree-management]
+reads: [coding-standards, tdd, git-workflow]
+argument-hint: "<agent-name>"
+---
+
+## Purpose
+Start a named agent in a git worktree for parallel multi-agent execution.
+Each agent operates in its own worktree, claims tasks independently, and
+creates PRs that are merged back to main. This enables multiple agents to
+work on different tasks simultaneously without stepping on each other.
+
+## Inputs
+- $ARGUMENTS (required) — the agent name (e.g., "alpha", "beta", "agent-1")
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- docs/implementation-playbook.md (required if exists) — primary task execution reference
+- docs/implementation-plan.md (fallback) — task list when no playbook exists
+- docs/onboarding-guide.md (optional) — project context for orientation
+- docs/coding-standards.md (required) — code conventions, naming, patterns
+- docs/tdd-standards.md (required) — test categories, mocking strategy
+- docs/project-structure.md (required) — where files live
+- tests/acceptance/ (optional) — TDD test skeletons
+- tests/evals/ (optional) — project eval checks for quality gates
+- tasks/lessons.md (optional) — previous lessons learned
+- .beads/ (conditional) — Beads task tracking if configured
+
+## Expected Outputs
+- Implemented features with passing tests from this agent's worktree
+- Pull requests for each completed task
+- Updated task status in playbook/plan or Beads
+
+## Quality Criteria
+- (mvp) Agent identity is established and verified (worktree environment confirmed)
+- (mvp) Each task follows red-green-refactor TDD cycle
+- (mvp) All quality gates pass before PR creation
+- (mvp) Task claiming avoids conflicts with other agents
+- (deep) Pre-flight verification confirms worktree isolation
+- (deep) Between-task cleanup ensures no state leakage across tasks
+- (deep) Beads actor identity is set correctly for task ownership tracking
+
+## Methodology Scaling
+- **deep**: Full pre-flight verification including worktree check, Beads actor
+  identity, onboarding guide review, lessons.md per task, eval gates, detailed
+  PR descriptions, between-task cleanup with dependency reinstall.
+- **mvp**: Verify worktree, pick next task, TDD loop, make check, create PR.
+  Skip onboarding review and between-task reinstalls if not needed.
+- **custom:depth(1-5)**: Depth 1-2: verify worktree, TDD loop, make check.
+  Depth 3: add lessons.md review and test skeleton usage. Depth 4: add
+  onboarding guide, eval gates, between-task cleanup. Depth 5: full
+  pre-flight suite, all quality gates, actor verification.
+
+## Mode Detection
+This is a stateless execution command. No document is created or updated.
+- Always operates in EXECUTE MODE.
+- If this agent already has in-progress work (feature branch with changes),
+  redirect to `/scaffold:multi-agent-resume $ARGUMENTS` instead.
+
+## Update Mode Specifics
+Not applicable — this is a stateless execution command that does not produce
+a persistent document.
+
+## Instructions
+
+You are **$ARGUMENTS**.
+
+### Pre-Flight Verification
+
+Before writing any code, verify the worktree environment:
+
+1. **Worktree confirmation**
+   - `git rev-parse --git-dir` — output should contain `/worktrees/` (confirms you are in a worktree, not the main repo)
+   - If NOT in a worktree, stop and instruct the user to set one up:
+     > Run `scripts/setup-agent-worktree.sh $ARGUMENTS` from the main repo to create a worktree for this agent.
+
+2. **Git state check**
+   - `git status` — working tree should be clean
+   - `git branch --show-current` — note the current branch
+   - If on a feature branch with changes, redirect to `/scaffold:multi-agent-resume $ARGUMENTS`
+
+3. **Beads identity** (if `.beads/` exists)
+   - `echo $BD_ACTOR` — should show `$ARGUMENTS`
+   - If not set, the worktree setup may be incomplete
+
+4. **Dependency check**
+   - Run the install command from CLAUDE.md Key Commands
+   - Confirm dependencies are current in this worktree
+
+5. **Test suite health**
+   - Run the project's check command from CLAUDE.md Key Commands
+   - If tests fail before you start, fix them or flag to the user
+
+6. **Project orientation**
+   - Read `CLAUDE.md` for project conventions and key commands
+   - Read `docs/onboarding-guide.md` if it exists
+   - Read `tasks/lessons.md` for relevant anti-patterns
+
+### Worktree-Specific Rules
+
+These rules are critical for multi-agent operation:
+
+- **Never run `git checkout main`** — it will fail because main is checked out in the main repo
+- **Always branch from remote**: `git fetch origin && git checkout -b <branch-name> origin/main`
+- **Between tasks, clean up**: `git fetch origin --prune && git clean -fd` then run the install command from CLAUDE.md Key Commands
+- **Use unique branch names** — include the agent name or task ID to avoid conflicts with other agents
+
+### Beads Detection
+
+**If Beads is configured** (`.beads/` exists):
+- Branch naming: `bd-<id>/<desc>`
+- Run `bd ready` to see available tasks
+- Pick the lowest-ID unblocked task
+- Implement following the TDD workflow below
+- After PR is merged: `bd close <id> && bd sync`
+- Repeat with `bd ready` until no tasks remain
+
+**Without Beads:**
+- Branch naming: `<type>/<desc>` (e.g., `feat/add-auth`)
+1. Read `docs/implementation-playbook.md` as the primary task execution reference.
+   Fall back to `docs/implementation-plan.md` when no playbook is present.
+2. Pick the first uncompleted task that has no unfinished dependencies and is not being
+   worked on by another agent (check for open PRs or in-progress markers).
+3. Implement following the TDD workflow below.
+4. Mark the task complete in the plan/playbook.
+5. Repeat in dependency order until all tasks are done.
+
+### TDD Execution Loop
+
+For each task:
+
+1. **Claim the task**
+   - Create a feature branch from remote main:
+     `git fetch origin && git checkout -b <branch-name> origin/main`
+   - If Beads: use `bd-<id>/<desc>` naming
+
+2. **Red phase — write failing tests**
+   - Check `tests/acceptance/` for existing test skeletons that correspond to the task
+   - If skeletons exist, use them as your starting point
+   - Otherwise, write test cases from the task's acceptance criteria
+   - Run the test suite — confirm the new tests FAIL (red)
+
+3. **Green phase — implement**
+   - Write the minimum code to make the failing tests pass
+   - Follow conventions from `docs/coding-standards.md`
+   - Follow file placement from `docs/project-structure.md`
+   - Run tests after each meaningful change — stop when green
+
+4. **Refactor phase — clean up**
+   - Refactor for clarity, DRY, and convention compliance
+   - Run the full test suite — confirm everything still passes
+
+5. **Quality gates**
+   - Run `make check` (or equivalent from CLAUDE.md Key Commands)
+   - If `tests/evals/` exists, run `make eval` (or equivalent eval command)
+   - Fix any failures before proceeding
+
+6. **Create PR**
+   - Push the branch: `git push -u origin HEAD`
+   - Create a pull request: `gh pr create`
+   - Include in the PR description: what was implemented, key decisions, files changed, agent name
+   - Follow the PR workflow from `docs/git-workflow.md` or CLAUDE.md
+
+7. **Between-task cleanup**
+   - `git fetch origin --prune && git clean -fd`
+   - Run the install command from CLAUDE.md Key Commands
+   - This ensures a clean state before the next task
+
+### Recovery Procedures
+
+**Worktree not set up:**
+- Instruct the user to run: `scripts/setup-agent-worktree.sh $ARGUMENTS`
+- Or reference `docs/git-workflow.md` section 7 for manual worktree setup
+
+**`git checkout main` fails:**
+- This is expected in a worktree. Use `git fetch origin && git checkout -b <branch> origin/main` instead.
+
+**Merge conflicts on PR:**
+- `git fetch origin && git rebase origin/main`
+- Resolve conflicts, re-run tests, force-push the branch
+
+**Another agent claimed the same task:**
+- If Beads: `bd sync` will reveal the conflict — pick a different task
+- Without Beads: check open PRs (`gh pr list`) for overlapping work
+- Move to the next available unblocked task
+
+**Dependency install fails after cleanup:**
+- `git clean -fd` may have removed generated files — re-run the full install sequence
+- If persistent, check if another agent's merge changed the dependency file
+
+**Tests fail after fetching latest origin:**
+- Determine if failure is from your changes or recently merged work
+- If from merged work: fix or flag before continuing
+- If from your changes: debug and fix
+
+### Process Rules
+
+1. **Verify worktree first** — Never start implementation without confirming you are in a worktree.
+2. **Branch from remote, not local** — Always use `origin/main` as the branch point.
+3. **Clean between tasks** — Run cleanup after each task to prevent state leakage.
+4. **TDD is not optional** — Write failing tests before implementation. No exceptions.
+5. **Quality gates before PR** — Never create a PR with failing checks.
+6. **Avoid task conflicts** — Check what other agents are working on before claiming.
+7. **Follow CLAUDE.md** — It is the authority on project conventions and commands.
+
+---
+
+## After This Step
+
+When this step is complete (all tasks done or session ending), tell the user:
+
+---
+**Agent $ARGUMENTS execution session complete.**
+
+**Session summary:**
+- Tasks completed: [list task IDs/titles]
+- PRs created: [list PR numbers]
+- Remaining tasks: [count or "none"]
+
+**If resuming later:** Run `/scaffold:multi-agent-resume $ARGUMENTS` to pick up where this agent left off.
+
+**If all tasks are done:**
+- Review `tasks/lessons.md` and add any patterns learned during implementation.
+- Consider running `/scaffold:version-bump` for a release.
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---

package/pipeline/build/new-enhancement.md

@@ -0,0 +1,456 @@
+---
+name: new-enhancement
+description: Add a new feature to an existing project
+summary: "Walks you through adding a feature the right way — updating the PRD, creating new user stories, running an innovation pass, and generating implementation tasks that integrate with your existing plan."
+phase: "build"
+order: 1560
+dependencies: [implementation-playbook]
+outputs: []
+conditional: null
+stateless: true
+category: pipeline
+knowledge-base: [enhancement-workflow, task-claiming-strategy]
+reads: [create-prd, user-stories, coding-standards, tdd, project-structure]
+argument-hint: "<enhancement description>"
+---
+
+## Purpose
+Guide the addition of a new feature or significant enhancement to an existing
+project. Walks through discovery and impact analysis, updates the PRD and
+user stories, creates implementation tasks, and optionally begins execution.
+This is the full-weight entry point for work that goes beyond a quick fix.
+
+## Inputs
+- $ARGUMENTS (required) — description of the enhancement to add
+- docs/plan.md (required) — current PRD: vision, personas, features, data model
+- docs/user-stories.md (required) — existing stories and epics (note the last story ID used)
+- docs/tech-stack.md (required) — technical constraints and patterns
+- docs/coding-standards.md (required) — code conventions, styling rules, commit format
+- docs/project-structure.md (required) — where new files should go
+- docs/tdd-standards.md (required) — test categories and patterns for task descriptions
+- docs/design-system.md (optional) — design tokens, component patterns (if frontend changes)
+- CLAUDE.md (required) — project conventions, key commands, workflow
+- .beads/ (conditional) — Beads task tracking if configured
+- Relevant source code if needed to understand current implementation
+
+## Expected Outputs
+- Updated `docs/plan.md` with new feature requirements
+- Updated `docs/user-stories.md` with new stories and acceptance criteria
+- Implementation tasks created via Beads or documented in implementation plan
+- Enhancement summary with implementation order
+
+## Quality Criteria
+- (mvp) Impact analysis completed before documentation changes
+- (mvp) PRD feature description is thorough enough for an AI agent to build without follow-up questions
+- (mvp) User stories follow INVEST criteria
+- (mvp) Acceptance criteria are testable Given/When/Then scenarios
+- (mvp) Task dependencies are identified and documented
+- (deep) Innovation pass explores competitive landscape and AI-native possibilities
+- (deep) Cross-reference check verifies consistency between PRD and user stories
+- (deep) Frozen artifact handling preserves version history
+- (deep) Follow-up review recommendations based on enhancement scope
+
+## Methodology Scaling
+- **deep**: Full discovery with innovation pass, competitive analysis,
+  detailed impact analysis, comprehensive PRD and story updates, dependency
+  graph, implementation order, follow-up review recommendations.
+- **mvp**: Streamlined discovery, basic impact analysis, PRD feature addition,
+  minimal user stories with acceptance criteria, task list with dependencies.
+  Skip innovation pass, competitive analysis, and follow-up recommendations.
+- **custom:depth(1-5)**: Depth 1-2: basic impact check, PRD update, stories,
+  task creation. Depth 3: add impact analysis, dependency management, cross-
+  reference check. Depth 4: add innovation pass, frozen artifact handling,
+  migration considerations. Depth 5: full workflow with competitive analysis,
+  AI-native possibilities, and follow-up review recommendations.
+
+## Mode Detection
+This is a stateless execution command. It updates existing documents (plan.md,
+user-stories.md) but does not create a new standalone output document.
+- Always operates in ENHANCEMENT MODE.
+- PRD and user stories are updated in place (append, do not replace).
+
+## Update Mode Specifics
+- **Detect**: `docs/plan.md` and `docs/user-stories.md` exist with content
+- **Preserve**: All existing features, stories, and epics — append only
+- **Triggers**: User requests a new feature or significant change
+- **Conflict resolution**: New features append to existing sections; never remove existing content
+- **Frozen artifacts**: If freeze markers exist, update the amended date rather than removing the marker
+
+## Instructions
+
+I want to add an enhancement to this project. Help me evaluate it, document it properly, and create tasks for implementation.
+
+### The Enhancement
+
+$ARGUMENTS
+
+---
+
+### Phase 1: Discovery & Impact Analysis
+
+#### Review Existing Context
+Before asking questions, thoroughly review:
+- `docs/plan.md` — Current PRD: vision, personas, features, data model
+- `docs/user-stories.md` — Existing stories and epics (note the last story ID used)
+- `docs/tech-stack.md` — Technical constraints and patterns
+- `docs/coding-standards.md` — Code conventions, styling rules, commit format
+- `docs/project-structure.md` — Where new files should go
+- `docs/tdd-standards.md` — Test categories and patterns for task descriptions
+- `docs/design-system.md` — Design tokens, component patterns, styling approach (if frontend changes)
+- `CLAUDE.md` — Project conventions, Key Commands, workflow
+- Relevant source code if needed to understand current implementation
+
+#### Understand the Enhancement
+Use AskUserQuestionTool to batch these questions:
+- What problem does this solve? Who benefits? (Which persona?)
+- What is the user flow? Walk me through it step by step.
+- What triggers this feature? (User action, system event, time-based?)
+- What does success look like? How will we measure it?
+
+#### Challenge and Refine
+Push back where appropriate:
+- Is this the simplest solution? Propose alternatives if you see a better way.
+- Should the scope be smaller for a v1 of this enhancement?
+- Are there edge cases or error states not mentioned?
+- Does this conflict with or duplicate existing functionality?
+- What are the riskiest assumptions?
+
+#### Innovation Pass
+
+Before finalizing the enhancement scope, research and consider:
+
+**Competitive Analysis** (use subagents for research):
+- How do similar apps handle this feature?
+- What do they do well? Where do they fall short?
+- Is there a standard UX pattern users will expect?
+
+**Enhancement Opportunities**:
+- What would make this feature "delightful" vs just "functional"?
+- Are there adjacent features that would multiply the value? (e.g., if adding notifications, should we add notification preferences too?)
+- What would a user complain about if we ship the minimal version?
+
+**AI-Native Possibilities**:
+- Could AI make this smarter? (smart defaults, predictions, natural language)
+- Is there manual work we could automate?
+
+**Present innovation ideas with**:
+- **What**: The enhancement to the enhancement
+- **Why**: User benefit
+- **Cost**: Trivial / Moderate / Significant effort
+- **Recommendation**: Include in this enhancement, or backlog for later
+
+Use AskUserQuestionTool to present innovation ideas for approval BEFORE proceeding.
+
+#### Impact Analysis
+Report what this enhancement affects:
+
+1. **Fit Check**
+   - Does this align with the product vision in the PRD?
+   - Which persona(s) does this serve?
+   - Does it conflict with any existing features or design decisions?
+
+2. **Scope Assessment**
+   - Is this a v1 feature or should it be deferred?
+   - Complexity estimate: Small (1-2 tasks), Medium (3-5 tasks), Large (6+ tasks)
+   - Dependencies on existing features or new infrastructure?
+
+3. **Technical Impact**
+   - **Data Model**: New entities? Changes to existing ones? Migrations needed?
+   - **UI Changes**: New screens? Modifications to existing ones?
+   - **API Changes**: New endpoints? Changes to existing ones?
+   - **External Integrations**: New third-party services?
+
+4. **Recommendation**
+   - Proceed as described
+   - Proceed with modifications (explain)
+   - Defer to a future version (explain why)
+   - Reconsider (if it conflicts with product vision)
+
+**Wait for user approval before proceeding to Phase 2.**
+
+---
+
+### Phase 2: Documentation Updates
+
+After approval, update the relevant documentation.
+
+#### Update `docs/plan.md`
+
+Add the enhancement to the PRD (do NOT remove or significantly alter existing content):
+
+1. **Feature Requirements section** — Add the new feature with:
+   - Clear description of what it does
+   - Why it exists (tied to user need/persona)
+   - Priority: Must-have / Should-have / Future
+   - Business rules or logic that are not obvious
+   - Concrete examples where behavior might be misinterpreted
+   - Mark with: `[Enhancement added YYYY-MM-DD]` for traceability
+
+2. **Data Model Overview** (if applicable):
+   - New entities with their key attributes
+   - Changes to existing entities
+   - New relationships between entities
+
+3. **Core User Flows** (if applicable):
+   - New flow, or modifications to existing flows
+   - Include happy path AND error/edge cases
+   - Be specific: "when X happens, the user sees Y" not "handle errors gracefully"
+
+4. **External Integrations** (if applicable):
+   - New third-party services or APIs
+   - What data flows in/out
+
+5. **Non-Functional Requirements** (if applicable):
+   - Performance implications
+   - Security considerations
+   - Accessibility needs
+
+#### Update `docs/user-stories.md`
+
+Add new user stories following the existing document structure and the User Stories prompt format:
+
+1. **Determine Epic Placement**
+   - Does this fit under an existing epic?
+   - Or does it need a new epic? (Only if it is a significant new area — match existing naming patterns)
+
+2. **Create User Stories** — Each story MUST include ALL of these fields:
+   - **ID**: Continue the existing numbering sequence (check the last ID in the file)
+   - **Title**: Short, scannable summary
+   - **Story**: "As a [persona], I want [action], so that [outcome]"
+   - **Acceptance Criteria**: Written as testable Given/When/Then scenarios
+     - These become TDD test cases — be explicit
+     - Cover happy path AND edge cases
+     - Include error states
+   - **Scope Boundary**: What this story does NOT include (prevents scope creep)
+   - **Data/State Requirements**: What data models, state, or dependencies are implied
+   - **UI/UX Notes**: What the user sees, key interactions, error states, loading states
+   - **Priority**: MoSCoW (Must/Should/Could/Won't)
+   - **Enhancement Reference**: `[Enhancement added YYYY-MM-DD]`
+
+3. **Story Quality Checks** — Before finalizing, verify:
+   - Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+   - No story is so large it could not be implemented in 1-3 focused Claude Code sessions
+   - Acceptance criteria are specific enough that pass/fail is unambiguous
+   - Edge cases and error states are covered explicitly
+
+#### Cross-Reference Check
+
+After updating both documents:
+- Verify every new PRD feature maps to at least one user story
+- Verify terminology is consistent with existing documentation
+- Verify no contradictions were introduced with existing features
+- Check that personas referenced exist in the PRD
+
+#### Frozen Artifact Handling
+
+If documents have a freeze marker (`<!-- FROZEN: ... -->` or `<!-- scaffold:freeze ... -->`), this is an authorized post-freeze change. Note the amendment date and update the freeze marker (e.g., `<!-- FROZEN: original-date, amended YYYY-MM-DD for enhancement -->`).
+
+Freeze marker format: `<!-- scaffold:step-name vN YYYY-MM-DD, amended YYYY-MM-DD -->`
+When updating a frozen document, change the "amended" date to today's date. Do not remove the original version date.
+
+---
+
+### Phase 3: Task Creation
+
+Create tasks for implementation.
+
+#### Task Creation Guidelines
+
+For each user story (or logical grouping of small stories):
+
+**If Beads:**
+```bash
+bd create "US-XXX: <imperative title>" -p <priority>
+# Priority: 0=blocking release, 1=must-have, 2=should-have, 3=nice-to-have
+```
+
+**Without Beads:** Document tasks as a structured list in `docs/implementation-plan.md` with title, priority, dependencies, and description.
+
+#### Task Titles and Descriptions
+
+- **Title format**: `US-XXX: <imperative action>` (e.g., "US-048: Add streak notification settings")
+- **Description should include**:
+  - Reference to user story: `Implements US-XXX`
+  - Key acceptance criteria summary
+  - Technical notes or gotchas from analysis
+  - Migration notes if data model changes
+
+#### Task Sizing
+
+- **One task per story** for small/medium stories
+- **Multiple tasks per story** for large stories — break down by:
+  - Data model/migrations first
+  - Backend API second
+  - Frontend/UI third
+  - Edge cases and polish last
+
+#### Dependency Management
+
+**If Beads:**
+```bash
+# Set up dependencies (child is blocked by parent)
+bd dep add <child-task-id> <parent-task-id>
+
+# Verify the dependency graph
+bd dep tree <task-id>
+```
+
+**Without Beads:** Note dependencies inline (e.g., "depends on: US-045 migration task").
+
+Common dependency patterns:
+- Migrations before features that use new models
+- Backend before frontend
+- Core functionality before edge cases
+- Shared components before features that use them
+
+#### Migration Considerations
+
+If the enhancement requires data model changes:
+- Create a dedicated migration task as the first dependency
+- Note if existing data needs transformation
+- Consider: can this be deployed incrementally or does it require coordination?
+- Document rollback strategy if the migration is risky
+
+---
+
+### Phase 4: Summary & Approval
+
+After completing all updates, provide a clear summary:
+
+#### 1. Enhancement Summary
+One paragraph: what this adds and why it matters.
+
+#### 2. Documentation Changes
+- **docs/plan.md**: What sections were added/modified
+- **docs/user-stories.md**: List new story IDs with titles
+
+#### 3. Tasks Created
+```
+| Task ID | Title | Priority | Depends On |
+|---------|-------|----------|------------|
+| xxx-abc | US-048: Add notification settings | 1 | - |
+| xxx-def | US-049: Send streak reminders | 1 | xxx-abc |
+```
+
+#### 4. Implementation Order
+Recommended sequence based on dependencies:
+1. First: [task(s)]
+2. Then: [task(s)] (can be parallelized)
+3. Finally: [task(s)]
+
+#### 5. Ready to Implement
+```bash
+bd ready  # Show what's available to work on now
+```
+
+#### 6. Open Questions (if any)
+- Decisions deferred to implementation time
+- Areas that may need refinement during development
+- Risks to monitor
+
+#### 7. Consider Follow-Up Reviews
+
+Depending on the enhancement scope, you may want to re-run these prompts:
+- **Implementation Plan Review**: If you created 5+ tasks, run it to verify sizing, dependencies, and coverage
+- **Platform Parity Review**: If the enhancement has platform-specific behavior (web vs. mobile differences), re-run to check platform coverage
+- **Workflow Audit**: Only if the enhancement changed project infrastructure or conventions (rare)
+
+---
+
+### Process Rules
+
+- **Do not skip discovery** — Even if the enhancement seems simple, do the impact analysis
+- **Use subagents for research** — Competitive analysis and UX best practices can run in parallel with other work
+- **Batch questions** — Use AskUserQuestionTool to group related questions — do not ask one at a time
+- **Present innovations before documenting** — Get approval on scope expansions before writing them up
+- **Challenge assumptions** — If something seems overengineered or could be simpler, say so
+- **Maintain consistency** — Match terminology, format, and style of existing docs exactly
+- **Add traceability** — Mark enhancements with dates so we know when features were added
+- **Right-size the scope** — Push back if the enhancement is too large — suggest phasing
+- **Check for conflicts** — If Beads, review `bd list` for in-progress work that might be affected
+
+---
+
+### When to Use This Prompt
+
+- Adding a new feature to an existing product
+- Expanding an existing feature with new capabilities
+- Adding a new user flow or journey
+- Any change that requires updating the PRD or user stories
+
+### When NOT to Use This Prompt
+
+- **Bug fixes**: Use `/scaffold:quick-task` instead — it creates focused, well-defined tasks
+- **Refactoring**: Use `/scaffold:quick-task` instead — no doc updates needed, just a task with clear acceptance criteria
+- **Performance improvements**: Use `/scaffold:quick-task` instead — targeted fixes do not need full discovery
+- **Initial product creation**: Use the PRD prompt instead
+- **Major pivots**: If this changes the core product direction, revisit the full PRD first
+- **Exploratory ideas**: If you are not sure you want this, discuss before documenting
+
+### Optional: Skip Innovation Pass
+
+If you just want to document a well-defined enhancement without competitive research and innovation brainstorming, add this to your request:
+
+> Skip the innovation pass — just document and create tasks for what I described.
+
+This is appropriate when:
+- The enhancement is already well-researched
+- You are porting a feature from a competitor you have already analyzed
+- Time pressure requires moving fast
+- The enhancement is truly trivial (but consider: does it even need this prompt?)
+
+---
+
+### Quality Standards
+
+#### From the PRD prompt — apply these to enhancement documentation:
+- Every feature must be described thoroughly enough that an AI agent can build it without asking follow-up questions
+- Avoid ambiguity: specify what errors can occur and what the user sees for each
+- Include concrete examples where behavior might be misinterpreted
+- Use consistent terminology throughout
+- Non-functional requirements are specific and measurable (not "fast" — how fast?)
+
+#### From the User Stories prompt — apply these to new stories:
+- Stories follow INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)
+- Acceptance criteria are specific enough that pass/fail is unambiguous
+- No story is so large it could not be implemented in 1-3 focused sessions
+- Every story has scope boundaries to prevent creep during implementation
+
+#### From the Gap Analysis prompts — verify before finishing:
+- Every new PRD feature maps to at least one user story
+- Happy paths AND error/edge cases are covered in acceptance criteria
+- No vague language that could be misinterpreted ("intuitive," "user-friendly," "seamless," "handles gracefully")
+- Dependencies between stories are identified (they become Beads dependencies)
+- Priority assignments make sense relative to existing features
+
+### Phase 5: Version Release
+
+After all changes are applied and verified:
+
+1. Determine release type based on change scope:
+   - **patch**: Bug fix or minor documentation update
+   - **minor**: New feature, new user story, or significant enhancement
+   - **major**: Breaking change to existing behavior or architecture
+2. Run `/scaffold:version-bump` to increment the version
+3. Create a release with changelog entry documenting the enhancement
+
+---
+
+## After This Step
+
+When this step is complete, tell the user:
+
+---
+**Enhancement documented** — PRD updated, user stories created, tasks ready.
+
+**Next (if applicable):**
+- If `docs/implementation-playbook.md` exists: Run `/scaffold:implementation-playbook` — Update wave assignments and add per-task context blocks for new tasks.
+- If you created **5+ tasks**: Run `/scaffold:implementation-plan-review` — Review task quality, coverage, and dependencies.
+- If the enhancement has **platform-specific behavior**: Run `/scaffold:platform-parity-review` — Check platform coverage.
+- If user stories were added or changed: Run `/scaffold:story-tests` — Regenerate test skeletons for new user stories.
+- If scope changed materially: Run `/scaffold:create-evals` — Update eval checks for new scope.
+- Otherwise: Run `/scaffold:single-agent-start` or `/scaffold:single-agent-resume` to begin implementation (or `/scaffold:multi-agent-start <agent-name>` / `/scaffold:multi-agent-resume <agent-name>` for worktree agents).
+
+**Pipeline reference:** `/scaffold:prompt-pipeline`
+
+---