agentvibes 2.9.7 → 2.12.0

package/.bmad/bmm/workflows/2-plan-workflows/tech-spec/instructions.md

@@ -1,980 +0,0 @@
-# Tech-Spec Workflow - Context-Aware Technical Planning (quick-flow)
-
-<workflow>
-
-<critical>The workflow execution engine is governed by: {project-root}/.bmad/core/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
-<critical>Communicate all responses in {communication_language} and language MUST be tailored to {user_skill_level}</critical>
-<critical>Generate all documents in {document_output_language}</critical>
-<critical>This is quick-flow efforts - tech-spec with context-rich story generation</critical>
-<critical>Quick Flow: tech-spec + epic with 1-5 stories (always generates epic structure)</critical>
-<critical>LIVING DOCUMENT: Write to tech-spec.md continuously as you discover - never wait until the end</critical>
-<critical>CONTEXT IS KING: Gather ALL available context before generating specs</critical>
-<critical>DOCUMENT OUTPUT: Technical, precise, definitive. Specific versions only. User skill level ({user_skill_level}) affects conversation style ONLY, not document content.</critical>
-<critical>Input documents specified in workflow.yaml input_file_patterns - workflow engine handles fuzzy matching, whole vs sharded document discovery automatically</critical>
-<critical>⚠️ ABSOLUTELY NO TIME ESTIMATES - NEVER mention hours, days, weeks, months, or ANY time-based predictions. AI has fundamentally changed development speed - what once took teams weeks/months can now be done by one person in hours. DO NOT give ANY time estimates whatsoever.</critical>
-<critical>⚠️ CHECKPOINT PROTOCOL: After EVERY <template-output> tag, you MUST follow workflow.xml substep 2c: SAVE content to file immediately → SHOW checkpoint separator (━━━━━━━━━━━━━━━━━━━━━━━) → DISPLAY generated content → PRESENT options [a]Advanced Elicitation/[c]Continue/[p]Party-Mode/[y]YOLO → WAIT for user response. Never batch saves or skip checkpoints.</critical>
-
-<step n="0" goal="Validate workflow readiness and detect project level" tag="workflow-status">
-<action>Check if {output_folder}/bmm-workflow-status.yaml exists</action>
-
-<check if="status file not found">
-  <output>No workflow status file found. Tech-spec workflow can run standalone or as part of BMM workflow path.</output>
-  <output>**Recommended:** Run `workflow-init` first for project context tracking and workflow sequencing.</output>
-  <output>**Quick Start:** Continue in standalone mode - perfect for rapid prototyping and quick changes!</output>
-  <ask>Continue in standalone mode or exit to run workflow-init? (continue/exit)</ask>
-  <check if="continue">
-    <action>Set standalone_mode = true</action>
-
-    <output>Great! Let's quickly configure your project...</output>
-
-    <ask>How many user stories do you think this work requires?
-
-**Single Story** - Simple change (bug fix, small isolated feature, single file change)
-→ Generates: tech-spec + epic (minimal) + 1 story
-→ Example: "Fix login validation bug" or "Add email field to user form"
-
-**Multiple Stories (2-5)** - Coherent feature (multiple related changes, small feature set)
-→ Generates: tech-spec + epic (detailed) + 2-5 stories
-→ Example: "Add OAuth integration" or "Build user profile page"
-
-Enter **1** for single story, or **2-5** for number of stories you estimate</ask>
-
-    <action>Capture user response as story_count (1-5)</action>
-    <action>Validate: If not 1-5, ask for clarification. If > 5, suggest using full BMad Method instead</action>
-
-    <ask if="not already known greenfield vs brownfield">Is this a **greenfield** (new/empty codebase) or **brownfield** (existing codebase) project?
-
-    **Greenfield** - Starting fresh, no existing code aside from starter templates
-    **Brownfield** - Adding to or modifying existing functional code or project
-
-    Enter **greenfield** or **brownfield**:</ask>
-
-    <action>Capture user response as field_type (greenfield or brownfield)</action>
-    <action>Validate: If not greenfield or brownfield, ask again</action>
-
-    <output>Perfect! Running as:
-
-- **Story Count:** {{story_count}} {{#if story_count == 1}}story (minimal epic){{else}}stories (detailed epic){{/if}}
-- **Field Type:** {{field_type}}
-- **Mode:** Standalone (no status file tracking)
-
-Let's build your tech-spec!</output>
-</check>
-<check if="exit">
-<action>Exit workflow</action>
-</check>
-</check>
-
-<check if="status file found">
-  <action>Load the FULL file: {workflow-status}</action>
-  <action>Parse workflow_status section</action>
-  <action>Check status of "tech-spec" workflow</action>
-  <action>Get selected_track from YAML metadata indicating this is quick-flow-greenfield or quick-flow-brownfield</action>
-  <action>Get field_type from YAML metadata (greenfield or brownfield)</action>
-  <action>Find first non-completed workflow (next expected workflow)</action>
-
-  <check if="selected_track is NOT quick-flow-greenfield AND NOT quick-flow-brownfield">
-    <output>**Incorrect Workflow for Level {{selected_track}}**
-    Tech-spec is for Simple projects. **Correct workflow:** `create-prd` (PM agent). You should Exit at this point, unless you want to force run this workflow.
-</output>
-</check>
-
-  <check if="tech-spec status is file path (already completed)">
-    <output>⚠️ Tech-spec already completed: {{tech-spec status}}</output>
-    <ask>Re-running will overwrite the existing tech-spec. Continue? (y/n)</ask>
-    <check if="n">
-      <output>Exiting. Use workflow-status to see your next step.</output>
-      <action>Exit workflow</action>
-    </check>
-  </check>
-
-  <check if="tech-spec is not the next expected workflow">
-    <output>⚠️ Next expected workflow: {{next_workflow}}. Tech-spec is out of sequence.</output>
-    <ask>Continue with tech-spec anyway? (y/n)</ask>
-    <check if="n">
-      <output>Exiting. Run {{next_workflow}} instead.</output>
-      <action>Exit workflow</action>
-    </check>
-  </check>
-
-<action>Set standalone_mode = false</action>
-</check>
-</step>
-
-<step n="0.5" goal="Discover and load input documents">
-<invoke-protocol name="discover_inputs" />
-<note>After discovery, these content variables are available: {product_brief_content}, {research_content}, {document_project_content}</note>
-</step>
-
-<step n="1" goal="Comprehensive context discovery - gather everything available">
-
-<action>Welcome {user_name} warmly and explain what we're about to do:
-
-"I'm going to gather all available context about your project before we dive into the technical spec. The following content has been auto-loaded:
-
-- Product briefs and research: {product_brief_content}, {research_content}
-- Brownfield codebase documentation: {document_project_content} (loaded via INDEX_GUIDED strategy)
-- Your project's tech stack and dependencies
-- Existing code patterns and structure
-
-This ensures the tech-spec is grounded in reality and gives developers everything they need."
-</action>
-
-<action>**PHASE 1: Load Existing Documents**
-
-Search for and load (using dual-strategy: whole first, then sharded):
-
-1. **Product Brief:**
-   - Search pattern: {output*folder}/\_brief*.md
-   - Sharded: {output*folder}/\_brief*/index.md
-   - If found: Load completely and extract key context
-
-2. **Research Documents:**
-   - Search pattern: {output*folder}/\_research*.md
-   - Sharded: {output*folder}/\_research*/index.md
-   - If found: Load completely and extract insights
-
-3. **Document-Project Output (CRITICAL for brownfield):**
-   - Always check: {output_folder}/index.md
-   - If found: This is the brownfield codebase map - load ALL shards!
-   - Extract: File structure, key modules, existing patterns, naming conventions
-
-Create a summary of what was found and ask user if there are other documents or information to consider before proceeding:
-
-- List of loaded documents
-- Key insights from each
-- Brownfield vs greenfield determination
-  </action>
-
-<action>**PHASE 2: Intelligently Detect Project Stack**
-
-Use your comprehensive knowledge as a coding-capable LLM to analyze the project:
-
-**Discover Setup Files:**
-
-- Search {project-root} for dependency manifests (package.json, requirements.txt, Gemfile, go.mod, Cargo.toml, composer.json, pom.xml, build.gradle, pyproject.toml, etc.)
-- Adapt to ANY project type - you know the ecosystem conventions
-
-**Extract Critical Information:**
-
-1. Framework name and EXACT version (e.g., "React 18.2.0", "Django 4.2.1")
-2. All production dependencies with specific versions
-3. Dev tools and testing frameworks (Jest, pytest, ESLint, etc.)
-4. Available build/test scripts
-5. Project type (web app, API, CLI, library, etc.)
-
-**Assess Currency:**
-
-- Identify if major dependencies are outdated (>2 years old)
-- Use WebSearch to find current recommended versions if needed
-- Note migration complexity in your summary
-
-**For Greenfield Projects:**
-<check if="field_type == greenfield">
-<action>Use WebSearch to discover current best practices and official starter templates</action>
-<action>Recommend appropriate starters based on detected framework (or user's intended stack)</action>
-<action>Present benefits conversationally: setup time saved, modern patterns, testing included</action>
-<ask>Would you like to use a starter template? (yes/no/show-me-options)</ask>
-<action>Capture preference and include in implementation stack if accepted</action>
-</check>
-
-**Trust Your Intelligence:**
-You understand project ecosystems deeply. Adapt your analysis to any stack - don't be constrained by examples. Extract what matters for developers.
-
-Store comprehensive findings as {{project_stack_summary}}
-</action>
-
-<action>**PHASE 3: Brownfield Codebase Reconnaissance** (if applicable)
-
-<check if="field_type == brownfield OR document-project output found">
-
-Analyze the existing project structure:
-
-1. **Directory Structure:**
-   - Identify main code directories (src/, lib/, app/, components/, services/)
-   - Note organization patterns (feature-based, layer-based, domain-driven)
-   - Identify test directories and patterns
-
-2. **Code Patterns:**
-   - Look for dominant patterns (class-based, functional, MVC, microservices)
-   - Identify naming conventions (camelCase, snake_case, PascalCase)
-   - Note file organization patterns
-
-3. **Key Modules/Services:**
-   - Identify major modules or services already in place
-   - Note entry points (main.js, app.py, index.ts)
-   - Document important utilities or shared code
-
-4. **Testing Patterns & Standards (CRITICAL):**
-   - Identify test framework in use (from package.json/requirements.txt)
-   - Note test file naming patterns (.test.js, test.py, .spec.ts, Test.java)
-   - Document test organization (tests/, **tests**, spec/, test/)
-   - Look for test configuration files (jest.config.js, pytest.ini, .rspec)
-   - Check for coverage requirements (in CI config, test scripts)
-   - Identify mocking/stubbing libraries (jest.mock, unittest.mock, sinon)
-   - Note assertion styles (expect, assert, should)
-
-5. **Code Style & Conventions (MUST CONFORM):**
-   - Check for linter config (.eslintrc, .pylintrc, rubocop.yml)
-   - Check for formatter config (.prettierrc, .black, .editorconfig)
-   - Identify code style:
-     - Semicolons: yes/no (JavaScript/TypeScript)
-     - Quotes: single/double
-     - Indentation: spaces/tabs, size
-     - Line length limits
-   - Import/export patterns (named vs default, organization)
-   - Error handling patterns (try/catch, Result types, error classes)
-   - Logging patterns (console, winston, logging module, specific formats)
-   - Documentation style (JSDoc, docstrings, YARD, JavaDoc)
-
-Store this as {{existing_structure_summary}}
-
-**CRITICAL: Confirm Conventions with User**
-<ask>I've detected these conventions in your codebase:
-
-**Code Style:**
-{{detected_code_style}}
-
-**Test Patterns:**
-{{detected_test_patterns}}
-
-**File Organization:**
-{{detected_file_organization}}
-
-Should I follow these existing conventions for the new code?
-
-Enter **yes** to conform to existing patterns, or **no** if you want to establish new standards:</ask>
-
-<action>Capture user response as conform_to_conventions (yes/no)</action>
-
-<check if="conform_to_conventions == no">
-  <ask>What conventions would you like to use instead? (Or should I suggest modern best practices?)</ask>
-  <action>Capture new conventions or use WebSearch for current best practices</action>
-</check>
-
-<action>Store confirmed conventions as {{existing_conventions}}</action>
-
-</check>
-
-<check if="field_type == greenfield">
-  <action>Note: Greenfield project - no existing code to analyze</action>
-  <action>Set {{existing_structure_summary}} = "Greenfield project - new codebase"</action>
-</check>
-
-</action>
-
-<action>**PHASE 4: Synthesize Context Summary**
-
-Create {{loaded_documents_summary}} that includes:
-
-- Documents found and loaded
-- Brownfield vs greenfield status
-- Tech stack detected (or "To be determined" if greenfield)
-- Existing patterns identified (or "None - greenfield" if applicable)
-
-Present this summary to {user_name} conversationally:
-
-"Here's what I found about your project:
-
-**Documents Available:**
-[List what was found]
-
-**Project Type:**
-[Brownfield with X framework Y version OR Greenfield - new project]
-
-**Existing Stack:**
-[Framework and dependencies OR "To be determined"]
-
-**Code Structure:**
-[Existing patterns OR "New codebase"]
-
-This gives me a solid foundation for creating a context-rich tech spec!"
-</action>
-
-<template-output>loaded_documents_summary</template-output>
-<template-output>project_stack_summary</template-output>
-<template-output>existing_structure_summary</template-output>
-
-</step>
-
-<step n="2" goal="Conversational discovery of the change/feature">
-
-<action>Engage {user_name} in natural, adaptive conversation to deeply understand what needs to be built.
-
-**Discovery Approach:**
-Adapt your questioning style to the complexity:
-
-- For single-story changes: Focus on the specific problem, location, and approach
-- For multi-story features: Explore user value, integration strategy, and scope boundaries
-
-**Core Discovery Goals (accomplish through natural dialogue):**
-
-1. **The Problem/Need**
-   - What user or technical problem are we solving?
-   - Why does this matter now?
-   - What's the impact if we don't do this?
-
-2. **The Solution Approach**
-   - What's the proposed solution?
-   - How should this work from a user/system perspective?
-   - What alternatives were considered?
-
-3. **Integration & Location**
-   - <check if="brownfield">Where does this fit in the existing codebase?</check>
-   - What existing code/patterns should we reference or follow?
-   - What are the integration points?
-
-4. **Scope Clarity**
-   - What's IN scope for this work?
-   - What's explicitly OUT of scope (future work, not needed)?
-   - If multiple stories: What's MVP vs enhancement?
-
-5. **Constraints & Dependencies**
-   - Technical limitations or requirements?
-   - Dependencies on other systems, APIs, or services?
-   - Performance, security, or compliance considerations?
-
-6. **Success Criteria**
-   - How will we know this is done correctly?
-   - What does "working" look like?
-   - What edge cases matter?
-
-**Conversation Style:**
-
-- Be warm and collaborative, not interrogative
-- Ask follow-up questions based on their responses
-- Help them think through implications
-- Reference context from Phase 1 (existing code, stack, patterns)
-- Adapt depth to {{story_count}} complexity
-
-Synthesize discoveries into clear, comprehensive specifications.
-</action>
-
-<template-output>problem_statement</template-output>
-<template-output>solution_overview</template-output>
-<template-output>change_type</template-output>
-<template-output>scope_in</template-output>
-<template-output>scope_out</template-output>
-
-</step>
-
-<step n="3" goal="Generate context-aware, definitive technical specification">
-
-<critical>ALL TECHNICAL DECISIONS MUST BE DEFINITIVE - NO AMBIGUITY ALLOWED</critical>
-<critical>Use existing stack info to make SPECIFIC decisions</critical>
-<critical>Reference brownfield code to guide implementation</critical>
-
-<action>Initialize tech-spec.md with the rich template</action>
-
-<action>**Generate Context Section (already captured):**
-
-These template variables are already populated from Step 1:
-
-- {{loaded_documents_summary}}
-- {{project_stack_summary}}
-- {{existing_structure_summary}}
-
-Just save them to the file.
-</action>
-
-<template-output file="tech-spec.md">loaded_documents_summary</template-output>
-<template-output file="tech-spec.md">project_stack_summary</template-output>
-<template-output file="tech-spec.md">existing_structure_summary</template-output>
-
-<action>**Generate The Change Section:**
-
-Already captured from Step 2:
-
-- {{problem_statement}}
-- {{solution_overview}}
-- {{scope_in}}
-- {{scope_out}}
-
-Save to file.
-</action>
-
-<template-output file="tech-spec.md">problem_statement</template-output>
-<template-output file="tech-spec.md">solution_overview</template-output>
-<template-output file="tech-spec.md">scope_in</template-output>
-<template-output file="tech-spec.md">scope_out</template-output>
-
-<action>**Generate Implementation Details:**
-
-Now make DEFINITIVE technical decisions using all the context gathered.
-
-**Source Tree Changes - BE SPECIFIC:**
-
-Bad (NEVER do this):
-
-- "Update some files in the services folder"
-- "Add tests somewhere"
-
-Good (ALWAYS do this):
-
-- "src/services/UserService.ts - MODIFY - Add validateEmail() method at line 45"
-- "src/routes/api/users.ts - MODIFY - Add POST /users/validate endpoint"
-- "tests/services/UserService.test.ts - CREATE - Test suite for email validation"
-
-Include:
-
-- Exact file paths
-- Action: CREATE, MODIFY, DELETE
-- Specific what changes (methods, classes, endpoints, components)
-
-**Use brownfield context:**
-
-- If modifying existing files, reference current structure
-- Follow existing naming patterns
-- Place new code logically based on current organization
-  </action>
-
-<template-output file="tech-spec.md">source_tree_changes</template-output>
-
-<action>**Technical Approach - BE DEFINITIVE:**
-
-Bad (ambiguous):
-
-- "Use a logging library like winston or pino"
-- "Use Python 2 or 3"
-- "Set up some kind of validation"
-
-Good (definitive):
-
-- "Use winston v3.8.2 (already in package.json) for logging"
-- "Implement using Python 3.11 as specified in pyproject.toml"
-- "Use Joi v17.9.0 for request validation following pattern in UserController.ts"
-
-**Use detected stack:**
-
-- Reference exact versions from package.json/requirements.txt
-- Specify frameworks already in use
-- Make decisions based on what's already there
-
-**For greenfield:**
-
-- Make definitive choices and justify them
-- Specify exact versions
-- No "or" statements allowed
-  </action>
-
-<template-output file="tech-spec.md">technical_approach</template-output>
-
-<action>**Existing Patterns to Follow:**
-
-<check if="brownfield">
-Document patterns from the existing codebase:
-- Class structure patterns
-- Function naming conventions
-- Error handling approach
-- Testing patterns
-- Documentation style
-
-Example:
-"Follow the service pattern established in UserService.ts:
-
-- Export class with constructor injection
-- Use async/await for all asynchronous operations
-- Throw ServiceError with error codes
-- Include JSDoc comments for all public methods"
-  </check>
-
-<check if="greenfield">
-"Greenfield project - establishing new patterns:
-- [Define the patterns to establish]"
-</check>
-
-</action>
-
-<template-output file="tech-spec.md">existing_patterns</template-output>
-
-<action>**Integration Points:**
-
-Identify how this change connects:
-
-- Internal modules it depends on
-- External APIs or services
-- Database interactions
-- Event emitters/listeners
-- State management
-
-Be specific about interfaces and contracts.
-</action>
-
-<template-output file="tech-spec.md">integration_points</template-output>
-
-<action>**Development Context:**
-
-**Relevant Existing Code:**
-<check if="brownfield">
-Reference specific files or code sections developers should review:
-
-- "See UserService.ts lines 120-150 for similar validation pattern"
-- "Reference AuthMiddleware.ts for authentication approach"
-- "Follow error handling in PaymentService.ts"
-  </check>
-
-**Framework/Libraries:**
-List with EXACT versions from detected stack:
-
-- Express 4.18.2 (web framework)
-- winston 3.8.2 (logging)
-- Joi 17.9.0 (validation)
-- TypeScript 5.1.6 (language)
-
-**Internal Modules:**
-List internal dependencies:
-
-- @/services/UserService
-- @/middleware/auth
-- @/utils/validation
-
-**Configuration Changes:**
-Any config files to update:
-
-- Update .env with new SMTP settings
-- Add validation schema to config/schemas.ts
-- Update package.json scripts if needed
-  </action>
-
-<template-output file="tech-spec.md">existing_code_references</template-output>
-<template-output file="tech-spec.md">framework_dependencies</template-output>
-<template-output file="tech-spec.md">internal_dependencies</template-output>
-<template-output file="tech-spec.md">configuration_changes</template-output>
-
-<check if="field_type == brownfield">
-  <template-output file="tech-spec.md">existing_conventions</template-output>
-</check>
-
-<check if="field_type == greenfield">
-  <action>Set {{existing_conventions}} = "Greenfield project - establishing new conventions per modern best practices"</action>
-  <template-output file="tech-spec.md">existing_conventions</template-output>
-</check>
-
-<action>**Implementation Stack:**
-
-Comprehensive stack with versions:
-
-- Runtime: Node.js 20.x
-- Framework: Express 4.18.2
-- Language: TypeScript 5.1.6
-- Testing: Jest 29.5.0
-- Linting: ESLint 8.42.0
-- Validation: Joi 17.9.0
-
-All from detected project setup!
-</action>
-
-<template-output file="tech-spec.md">implementation_stack</template-output>
-
-<action>**Technical Details:**
-
-Deep technical specifics:
-
-- Algorithms to implement
-- Data structures to use
-- Performance considerations
-- Security considerations
-- Error scenarios and handling
-- Edge cases
-
-Be thorough - developers need details!
-</action>
-
-<template-output file="tech-spec.md">technical_details</template-output>
-
-<action>**Development Setup:**
-
-What does a developer need to run this locally?
-
-Based on detected stack and scripts:
-
-```
-1. Clone repo (if not already)
-2. npm install (installs all deps from package.json)
-3. cp .env.example .env (configure environment)
-4. npm run dev (starts development server)
-5. npm test (runs test suite)
-```
-
-Or for Python:
-
-```
-1. python -m venv venv
-2. source venv/bin/activate
-3. pip install -r requirements.txt
-4. python manage.py runserver
-```
-
-Use the actual scripts from package.json/setup files!
-</action>
-
-<template-output file="tech-spec.md">development_setup</template-output>
-
-<action>**Implementation Guide:**
-
-**Setup Steps:**
-Pre-implementation checklist:
-
-- Create feature branch
-- Verify dev environment running
-- Review existing code references
-- Set up test data if needed
-
-**Implementation Steps:**
-Step-by-step breakdown:
-
-For single-story changes:
-
-1. [Step 1 with specific file and action]
-2. [Step 2 with specific file and action]
-3. [Write tests]
-4. [Verify acceptance criteria]
-
-For multi-story features:
-Organize by story/phase:
-
-1. Phase 1: [Foundation work]
-2. Phase 2: [Core implementation]
-3. Phase 3: [Testing and validation]
-
-**Testing Strategy:**
-
-- Unit tests for [specific functions]
-- Integration tests for [specific flows]
-- Manual testing checklist
-- Performance testing if applicable
-
-**Acceptance Criteria:**
-Specific, measurable, testable criteria:
-
-1. Given [scenario], when [action], then [outcome]
-2. [Metric] meets [threshold]
-3. [Feature] works in [environment]
-   </action>
-
-<template-output file="tech-spec.md">setup_steps</template-output>
-<template-output file="tech-spec.md">implementation_steps</template-output>
-<template-output file="tech-spec.md">testing_strategy</template-output>
-<template-output file="tech-spec.md">acceptance_criteria</template-output>
-
-<action>**Developer Resources:**
-
-**File Paths Reference:**
-Complete list of all files involved:
-
-- /src/services/UserService.ts
-- /src/routes/api/users.ts
-- /tests/services/UserService.test.ts
-- /src/types/user.ts
-
-**Key Code Locations:**
-Important functions, classes, modules:
-
-- UserService class (src/services/UserService.ts:15)
-- validateUser function (src/utils/validation.ts:42)
-- User type definition (src/types/user.ts:8)
-
-**Testing Locations:**
-Where tests go:
-
-- Unit: tests/services/
-- Integration: tests/integration/
-- E2E: tests/e2e/
-
-**Documentation to Update:**
-Docs that need updating:
-
-- README.md - Add new endpoint documentation
-- API.md - Document /users/validate endpoint
-- CHANGELOG.md - Note the new feature
-  </action>
-
-<template-output file="tech-spec.md">file_paths_complete</template-output>
-<template-output file="tech-spec.md">key_code_locations</template-output>
-<template-output file="tech-spec.md">testing_locations</template-output>
-<template-output file="tech-spec.md">documentation_updates</template-output>
-
-<action>**UX/UI Considerations:**
-
-<check if="change affects user interface OR user experience">
-  **Determine if this change has UI/UX impact:**
-  - Does it change what users see?
-  - Does it change how users interact?
-  - Does it affect user workflows?
-
-If YES, document:
-
-**UI Components Affected:**
-
-- List specific components (buttons, forms, modals, pages)
-- Note which need creation vs modification
-
-**UX Flow Changes:**
-
-- Current flow vs new flow
-- User journey impact
-- Navigation changes
-
-**Visual/Interaction Patterns:**
-
-- Follow existing design system? (check for design tokens, component library)
-- New patterns needed?
-- Responsive design considerations (mobile, tablet, desktop)
-
-**Accessibility:**
-
-- Keyboard navigation requirements
-- Screen reader compatibility
-- ARIA labels needed
-- Color contrast standards
-
-**User Feedback:**
-
-- Loading states
-- Error messages
-- Success confirmations
-- Progress indicators
-  </check>
-
-<check if="no UI/UX impact">
-  "No UI/UX impact - backend/API/infrastructure change only"
-</check>
-</action>
-
-<template-output file="tech-spec.md">ux_ui_considerations</template-output>
-
-<action>**Testing Approach:**
-
-Comprehensive testing strategy using {{test_framework_info}}:
-
-**CONFORM TO EXISTING TEST STANDARDS:**
-<check if="conform_to_conventions == yes">
-
-- Follow existing test file naming: {{detected_test_patterns.file_naming}}
-- Use existing test organization: {{detected_test_patterns.organization}}
-- Match existing assertion style: {{detected_test_patterns.assertion_style}}
-- Meet existing coverage requirements: {{detected_test_patterns.coverage}}
-  </check>
-
-**Test Strategy:**
-
-- Test framework: {{detected_test_framework}} (from project dependencies)
-- Unit tests for [specific functions/methods]
-- Integration tests for [specific flows/APIs]
-- E2E tests if UI changes
-- Mock/stub strategies (use existing patterns: {{detected_test_patterns.mocking}})
-- Performance benchmarks if applicable
-- Accessibility tests if UI changes
-
-**Coverage:**
-
-- Unit test coverage: [target %]
-- Integration coverage: [critical paths]
-- Ensure all acceptance criteria have corresponding tests
-  </action>
-
-<template-output file="tech-spec.md">test_framework_info</template-output>
-<template-output file="tech-spec.md">testing_approach</template-output>
-
-<action>**Deployment Strategy:**
-
-**Deployment Steps:**
-How to deploy this change:
-
-1. Merge to main branch
-2. Run CI/CD pipeline
-3. Deploy to staging
-4. Verify in staging
-5. Deploy to production
-6. Monitor for issues
-
-**Rollback Plan:**
-How to undo if problems:
-
-1. Revert commit [hash]
-2. Redeploy previous version
-3. Verify rollback successful
-
-**Monitoring:**
-What to watch after deployment:
-
-- Error rates in [logging service]
-- Response times for [endpoint]
-- User feedback on [feature]
-  </action>
-
-<template-output file="tech-spec.md">deployment_steps</template-output>
-<template-output file="tech-spec.md">rollback_plan</template-output>
-<template-output file="tech-spec.md">monitoring_approach</template-output>
-
-</step>
-
-<step n="4" goal="Auto-validate cohesion, completeness, and quality">
-
-<critical>Always run validation - this is NOT optional!</critical>
-
-<action>Tech-spec generation complete! Now running automatic validation...</action>
-
-<action>Load {installed_path}/checklist.md</action>
-<action>Review tech-spec.md against ALL checklist criteria:
-
-**Section 1: Output Files Exist**
-
-- Verify tech-spec.md created
-- Check for unfilled template variables
-
-**Section 2: Context Gathering**
-
-- Validate all available documents were loaded
-- Confirm stack detection worked
-- Verify brownfield analysis (if applicable)
-
-**Section 3: Tech-Spec Definitiveness**
-
-- Scan for "or" statements (FAIL if found)
-- Verify all versions are specific
-- Check stack alignment
-
-**Section 4: Context-Rich Content**
-
-- Verify all new template sections populated
-- Check existing code references (brownfield)
-- Validate framework dependencies listed
-
-**Section 5-6: Story Quality (deferred to Step 5)**
-
-**Section 7: Workflow Status (if applicable)**
-
-**Section 8: Implementation Readiness**
-
-- Can developer start immediately?
-- Is tech-spec comprehensive enough?
-  </action>
-
-<action>Generate validation report with specific scores:
-
-- Context Gathering: [Comprehensive/Partial/Insufficient]
-- Definitiveness: [All definitive/Some ambiguity/Major issues]
-- Brownfield Integration: [N/A/Excellent/Partial/Missing]
-- Stack Alignment: [Perfect/Good/Partial/None]
-- Implementation Readiness: [Yes/No]
-  </action>
-
-<check if="validation issues found">
-  <output>⚠️ **Validation Issues Detected:**
-
-{{list_of_issues}}
-
-I can fix these automatically. Shall I proceed? (yes/no)</output>
-
-<ask>Fix validation issues? (yes/no)</ask>
-
-  <check if="yes">
-    <action>Fix each issue and re-validate</action>
-    <output>✅ Issues fixed! Re-validation passed.</output>
-  </check>
-
-  <check if="no">
-    <output>⚠️ Proceeding with warnings. Issues should be addressed manually.</output>
-  </check>
-</check>
-
-<check if="validation passes">
-  <output>✅ **Validation Passed!**
-
-**Scores:**
-
-- Context Gathering: {{context_score}}
-- Definitiveness: {{definitiveness_score}}
-- Brownfield Integration: {{brownfield_score}}
-- Stack Alignment: {{stack_score}}
-- Implementation Readiness: ✅ Ready
-
-Tech-spec is high quality and ready for story generation!</output>
-</check>
-
-</step>
-
-<step n="5" goal="Generate epic and context-rich stories">
-
-<action>Invoke unified story generation workflow: {instructions_generate_stories}</action>
-
-<action>This will generate:
-
-- **epics.md** - Epic structure (minimal for 1 story, detailed for multiple)
-- **story-{epic-slug}-N.md** - Story files (where N = 1 to {{story_count}})
-
-All stories reference tech-spec.md as primary context - comprehensive enough that developers can often skip story-context workflow.
-</action>
-
-</step>
-
-<step n="6" goal="Finalize and guide next steps">
-
-<output>**✅ Tech-Spec Complete, {user_name}!**
-
-**Deliverables Created:**
-
-- ✅ **tech-spec.md** - Context-rich technical specification
-  - Includes: brownfield analysis, framework details, existing patterns
-- ✅ **epics.md** - Epic structure{{#if story_count == 1}} (minimal for single story){{else}} with {{story_count}} stories{{/if}}
-- ✅ **story-{epic-slug}-1.md** - First story{{#if story_count > 1}}
-- ✅ **story-{epic-slug}-2.md** - Second story{{/if}}{{#if story_count > 2}}
-- ✅ **story-{epic-slug}-3.md** - Third story{{/if}}{{#if story_count > 3}}
-- ✅ **Additional stories** through story-{epic-slug}-{{story_count}}.md{{/if}}
-
-**What Makes This Tech-Spec Special:**
-
-The tech-spec is comprehensive enough to serve as the primary context document:
-
-- ✨ Brownfield codebase analysis (if applicable)
-- ✨ Exact framework and library versions from your project
-- ✨ Existing patterns and code references
-- ✨ Specific file paths and integration points
-- ✨ Complete developer resources
-
-**Next Steps:**
-
-**🎯 Recommended Path - Direct to Development:**
-
-Since the tech-spec is CONTEXT-RICH, you can often skip story-context generation!
-
-{{#if story_count == 1}}
-**For Your Single Story:**
-
-1. Ask DEV agent to run `dev-story`
-   - Select story-{epic-slug}-1.md
-   - Tech-spec provides all the context needed!
-
-💡 **Optional:** Only run `story-context` (SM agent) if this is unusually complex
-{{else}}
-**For Your {{story_count}} Stories - Iterative Approach:**
-
-1. **Start with Story 1:**
-   - Ask DEV agent to run `dev-story`
-   - Select story-{epic-slug}-1.md
-   - Tech-spec provides context
-
-2. **After Story 1 Complete:**
-   - Repeat for story-{epic-slug}-2.md
-   - Continue through story {{story_count}}
-
-💡 **Alternative:** Use `sprint-planning` (SM agent) to organize all stories as a coordinated sprint
-
-💡 **Optional:** Run `story-context` (SM agent) for complex stories needing additional context
-{{/if}}
-
-**Your Tech-Spec:**
-
-- 📄 Saved to: `{output_folder}/tech-spec.md`
-- Epic & Stories: `{output_folder}/epics.md` + `{sprint_artifacts}/`
-- Contains: All context, decisions, patterns, and implementation guidance
-- Ready for: Direct development!
-
-The tech-spec is your single source of truth! 🚀
-</output>
-
-</step>
-
-</workflow>