@codemcp/workflows 5.3.0 → 6.0.2

package/packages/cli/resources/workflows/slides.yaml

@@ -0,0 +1,237 @@
+name: slides
+description: 'A comprehensive workflow for creating presentations - tool-agnostic approach that works with Slidev, PowerPoint, Google Slides, or any presentation platform'
+initial_state: ideate
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'office'
+  complexity: 'medium'
+  bestFor:
+    - 'Presentation creation'
+    - 'Slide deck development'
+    - 'Conference talks'
+    - 'Training materials'
+  useCases:
+    - 'Creating a technical presentation'
+    - 'Building training slides'
+    - 'Preparing a conference talk'
+  examples:
+    - 'Create a product demo presentation'
+    - 'Build onboarding slides'
+    - 'Develop a technical workshop'
+
+states:
+  ideate:
+    description: 'Brainstorm presentation concept and define strategic foundation'
+    default_instructions: |
+      **Clarify the presentation foundation** with the user by gathering essential information:
+
+      - Brainstorm presentation topic and key messages
+      - Define target audience and their knowledge level
+      - Set presentation goals and success criteria
+      - Research topic and gather reference materials
+      - Define scope, time constraints, and context
+
+      **Update** the plan file with ideation progress and key decisions before proceeding to structure.
+
+    transitions:
+      - trigger: ideation_complete
+        to: structure
+        transition_reason: 'Presentation concept and goals clearly defined, ready for content structuring'
+
+  structure:
+    description: 'Organize content flow and logical progression'
+    default_instructions: |
+      **Create a detailed presentation structure** by organizing your content logically and effectively:
+
+      - Create detailed presentation outline with main sections
+      - Define slide sequence and narrative flow
+      - Plan smooth transitions between topics
+      - Identify key examples, case studies, or demonstrations needed
+      - Estimate timing for each section and overall presentation
+      - Consider audience engagement points and interaction opportunities
+
+      **Update** the plan file with structural decisions and progress before moving to content drafting.
+
+    transitions:
+      - trigger: structure_complete
+        to: draft
+        additional_instructions: |
+          **Structure phase complete!** You have a well-organized outline and clear content flow.
+
+          Update the plan file with drafting tasks and mark completed structural work.
+        transition_reason: 'Content structure and flow established, ready for content creation'
+
+      - trigger: need_more_ideation
+        to: ideate
+        additional_instructions: 'Structural work revealed gaps in the initial concept or goals. Focus on clarifying these fundamental aspects.'
+        transition_reason: 'Structure work revealed need for more ideation or concept refinement'
+
+      - trigger: abandon_presentation
+        to: ideate
+        instructions: |
+          **Abandon structural work** - Clean up structural work and return to ideation.
+
+          The plan file and any completed work will remain for future reference.
+        additional_instructions: 'Presentation abandoned during structure phase. Clean up and prepare for new topics.'
+        transition_reason: 'User decided to abandon presentation during structure phase'
+
+  draft:
+    description: 'Create content, speaker notes, and visual planning'
+    default_instructions: |
+      **Create content and speaker notes** to establish the presentation material and delivery guide:
+
+      - Write clear, engaging content for each slide/section
+      - Create comprehensive speaker notes as a main deliverable
+      - Make strategic decisions about visual vs. spoken content split
+      - Identify concepts that can be effectively visualized
+      - Define what each visualization should communicate
+      - Create placeholders and specifications for visual content
+      - Ensure content aligns with timing and audience needs
+
+      **Update** the plan file with drafting progress and content decisions before moving to styling.
+
+    transitions:
+      - trigger: draft_complete
+        to: style
+        additional_instructions: |
+          **Draft phase complete!** You have solid content, speaker notes, and visual planning.
+
+          Update the plan file with styling tasks and mark completed drafting work.
+        transition_reason: 'Content and speaker notes complete, ready for visual design and styling'
+
+      - trigger: need_more_structure
+        to: structure
+        additional_instructions: 'Drafting revealed issues with content organization or flow. Focus on refining the structural foundation.'
+        transition_reason: 'Content creation revealed need for better structure or organization'
+
+      - trigger: abandon_presentation
+        to: ideate
+        instructions: |
+          **Abandon drafting work** - Clean up content work and return to ideation.
+
+          The plan file and any completed work will remain for future reference.
+        additional_instructions: 'Presentation abandoned during draft phase. Clean up and prepare for new topics.'
+        transition_reason: 'User decided to abandon presentation during draft phase'
+
+  style:
+    description: 'Apply design, create visuals, and enhance presentation aesthetics'
+    default_instructions: |
+      **Apply visual design and create presentation aesthetics** to bring professional appeal and consistency:
+
+      - Evaluate presentation requirements and choose appropriate tool/platform
+      - Select themes, templates, and establish visual design approach
+      - Source existing visuals, images, and graphic elements
+      - Create detailed AI image generation prompts for missing visuals
+      - Generate or create required visual content using AI tools or other methods
+      - Apply consistent visual design, colors, and branding
+      - Ensure visual elements effectively support and enhance the content
+      - Test visual consistency across all slides/sections
+
+      **Update** the plan file with styling progress and design decisions before moving to review.
+
+    transitions:
+      - trigger: style_complete
+        to: review
+        additional_instructions: |
+          **Style phase complete!** You have a visually appealing presentation with consistent design.
+
+          Update the plan file with review tasks and mark completed styling work.
+        transition_reason: 'Visual design and styling complete, ready for content and delivery review'
+
+      - trigger: need_more_content
+        to: draft
+        additional_instructions: 'Styling work revealed gaps in content or speaker notes. Focus on completing the content foundation.'
+        transition_reason: 'Visual design revealed need for additional content or speaker note refinement'
+
+      - trigger: abandon_presentation
+        to: ideate
+        instructions: |
+          **Abandon styling work** - Clean up design work and return to ideation.
+
+          The plan file and any completed work will remain for future reference.
+        additional_instructions: 'Presentation abandoned during style phase. Clean up and prepare for new topics.'
+        transition_reason: 'User decided to abandon presentation during style phase'
+
+  review:
+    description: 'Validate content quality and presentation effectiveness'
+    default_instructions: |
+      **Validate presentation quality** by reviewing content, timing, visuals, and delivery readiness:
+
+      - Review content flow, narrative coherence, and logical progression
+      - Test presentation timing and pacing for your allocated time
+      - Verify visual quality, consistency, and professional appearance
+      - Practice delivery to identify potential issues or improvements
+      - Gather feedback from test audience, colleagues, or stakeholders
+      - Check technical setup, compatibility, and backup plans
+      - Ensure all interactive elements and visuals work correctly
+      - Refine speaker notes and delivery preparation
+
+      **Update** the plan file with review progress and refinements before moving to delivery preparation.
+
+    transitions:
+      - trigger: review_complete
+        to: deliver
+        additional_instructions: |
+          **Review phase complete!** Your presentation has been validated and refined for delivery.
+
+          Update the plan file with delivery preparation tasks and mark completed review work.
+        transition_reason: 'Presentation reviewed and validated, ready for final delivery preparation'
+
+      - trigger: need_style_changes
+        to: style
+        additional_instructions: 'Review revealed visual or design issues that need attention. Focus on addressing these styling concerns.'
+        transition_reason: 'Review process identified visual or design issues requiring style phase work'
+
+      - trigger: need_content_changes
+        to: draft
+        additional_instructions: 'Review revealed content gaps or issues that need addressing. Focus on refining the content and speaker notes.'
+        transition_reason: 'Review process identified content issues requiring draft phase work'
+
+      - trigger: abandon_presentation
+        to: ideate
+        instructions: |
+          **Abandon review work** - Clean up review work and return to ideation.
+
+          The plan file and any completed work will remain for future reference.
+        additional_instructions: 'Presentation abandoned during review phase. Clean up and prepare for new topics.'
+        transition_reason: 'User decided to abandon presentation during review phase'
+
+  deliver:
+    description: 'Prepare final presentation for delivery'
+    default_instructions: |
+      **Prepare final delivery** by exporting formats, testing setup, and ensuring flawless execution:
+
+      - Export presentation to all required formats (native, PDF, backup formats)
+      - Finalize speaker setup, notes, and delivery materials
+      - Configure and test presentation environment and technical setup
+      - Create comprehensive contingency plans for potential technical issues
+      - Conduct final rehearsal in actual delivery environment if possible
+      - Prepare handouts, follow-up materials, or additional resources
+      - Ensure all backup plans and alternatives are ready
+      - Final check of timing, flow, and delivery readiness
+
+      **Update** the plan file with delivery preparation progress to ensure successful delivery.
+
+    transitions:
+      - trigger: delivery_complete
+        to: ideate
+        additional_instructions: |
+          **Delivery phase complete!** Your presentation has been successfully delivered.
+
+          Mark all delivery tasks as complete in the plan file and prepare for new work.
+        transition_reason: 'Presentation delivery completed successfully, ready for new projects'
+
+      - trigger: need_final_review
+        to: review
+        additional_instructions: 'Final preparation revealed issues requiring additional review. Focus on addressing these concerns before delivery.'
+        transition_reason: 'Delivery preparation identified issues requiring additional review'
+
+      - trigger: abandon_presentation
+        to: ideate
+        instructions: |
+          **Abandon delivery preparation** - Clean up delivery preparation and return to ideation.
+
+          The plan file and completed work will remain for future reference.
+        additional_instructions: 'Presentation abandoned before delivery. Clean up and prepare for new topics.'
+        transition_reason: 'User decided to abandon presentation before delivery'

package/packages/cli/resources/workflows/tdd.yaml

@@ -0,0 +1,160 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'tdd'
+description: 'Test-Driven Development workflow: Explore → Red → Green → Refactor cycle for quality-focused development'
+initial_state: 'explore'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'code'
+  complexity: 'medium'
+  bestFor:
+    - 'TDD development'
+    - 'Test-first coding'
+    - 'Quality-focused development'
+    - 'Refactoring existing code'
+  useCases:
+    - 'Adding new features with comprehensive tests'
+    - 'Refactoring legacy code safely'
+    - 'Building robust, well-tested components'
+  examples:
+    - 'Add new API endpoint with full test coverage'
+    - 'Refactor existing function with safety net of tests'
+    - 'Build new feature following TDD principles'
+
+# States with default instructions and transitions
+states:
+  explore:
+    description: 'Research and exploration phase - understanding the problem space and codebase'
+    default_instructions: |
+      **STEP 1:** Gather context about what needs to be developed. Focus on the WHY and WHAT, not the HOW.
+
+      **STEP 2:** Research the codebase and understand existing patterns.
+      - Ask the user about conventions or rules if uncertain
+      - Read relevant files and documentation
+      - If `$REQUIREMENTS_DOC` exists, understand and document requirements there, otherwise document in your task management system
+
+      **STEP 3:** Document your findings and create tasks as needed.
+      - Don't write code or tests yet
+      - Focus on understanding the problem space
+      - Prepare for the RED phase of the TDD cycle
+    transitions:
+      - trigger: 'exploration_complete'
+        to: 'red'
+        additional_instructions: 'Update task progress as you complete exploration work.'
+        transition_reason: 'Sufficient understanding gained, ready to start TDD cycle with failing test'
+
+  red:
+    description: 'RED phase - Write a failing test that defines the expected behavior'
+    default_instructions: |
+      Write a failing test that defines the expected behavior for the feature.
+
+      **STEP 1:** Validate test approach with the user before writing.
+      - Determine what type of test is appropriate (unit, integration, acceptance, etc.)
+      - Confirm your test will validate the actual requirements
+      - Ensure alignment with the feature specification
+
+      **STEP 2:** Write a focused, meaningful test.
+      - Clearly define the expected behavior
+      - Will fail initially since functionality doesn't exist yet
+      - Focus on one specific aspect of the functionality
+      - Use appropriate assertions (not meaningless checks like assert(true))
+
+      **STEP 3:** Validate test failure.
+      - Run the test to confirm it fails for the right reason
+      - Document the test and expected failure mode
+      - Update task progress
+    transitions:
+      - trigger: 'test_written_and_failing'
+        to: 'green'
+        additional_instructions: 'Update task progress as you complete test writing work.'
+        transition_reason: 'Failing test successfully written and validated, ready to implement'
+
+      - trigger: 'need_more_exploration'
+        to: 'explore'
+        transition_reason: 'Test writing revealed need for more exploration'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        additional_instructions: 'Clean up any test artifacts and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during test phase'
+
+  green:
+    description: 'GREEN phase - Write only the necessary code to make the test pass'
+    default_instructions: |
+      Implement the necessary code to make the failing test pass with proper functionality.
+
+      **STEP 1:** Write real, working implementation.
+      - Make the test pass with actual logic, not shortcuts
+      - Write only what's necessary (no over-engineering)
+      - Avoid dirty hacks such as hardcoded return values or meaningless assertions
+      - Focus on solving the actual problem
+
+      **STEP 2:** Validate implementation quality.
+      - Run the test to confirm it passes
+      - Verify no shortcuts or copy-paste code without understanding
+      - Ensure the solution actually solves the problem
+      - Check that logic is proper, not a bypass
+
+      **STEP 3:** Document and track progress.
+      - Document your implementation approach
+      - Update task progress
+    transitions:
+      - trigger: 'test_passing'
+        to: 'refactor'
+        additional_instructions: 'Update task progress as you complete implementation work.'
+        transition_reason: 'Test passes with proper implementation, ready for refactoring'
+
+      - trigger: 'need_different_test'
+        to: 'red'
+        transition_reason: 'Implementation work revealed need to revise the test'
+
+      - trigger: 'need_more_exploration'
+        to: 'explore'
+        transition_reason: 'Implementation work revealed need for more exploration'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        additional_instructions: 'Clean up any incomplete code and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during implementation'
+
+  refactor:
+    description: 'REFACTOR phase - Improve code quality while keeping tests green (cleanup phase)'
+    default_instructions: |
+      Improve code quality while keeping all tests green. This is the cleanup phase where you enhance readability and maintainability.
+
+      **STEP 1:** Identify improvement opportunities.
+      - Remove code duplication
+      - Improve variable and function names
+      - Extract methods for better organization
+      - Simplify complex logic
+      - Apply appropriate design patterns
+
+      **STEP 2:** Make incremental improvements safely.
+      - Run tests after each refactoring change
+      - Immediately revert any change that breaks tests
+      - Make small, focused improvements
+      - Stop when code is clean with no obvious improvements remaining
+
+      **STEP 3:** Document and complete.
+      - Document significant refactoring decisions
+      - Update task progress
+    transitions:
+      - trigger: 'refactoring_complete'
+        to: 'red'
+        additional_instructions: 'Update task progress as you complete refactoring work.'
+        transition_reason: 'Code cleanup complete, ready for next TDD cycle'
+
+      - trigger: 'need_different_approach'
+        to: 'green'
+        transition_reason: 'Refactoring revealed need to revise implementation'
+
+      - trigger: 'feature_complete'
+        to: 'explore'
+        additional_instructions: 'Update task progress to reflect feature completion.'
+        transition_reason: 'Feature fully implemented and cleaned up, ready for new tasks'
+
+      - trigger: 'abandon_feature'
+        to: 'explore'
+        additional_instructions: 'Clean up any refactoring work and prepare for new tasks.'
+        transition_reason: 'User decided to abandon feature during refactoring'

package/packages/cli/resources/workflows/waterfall.yaml

@@ -0,0 +1,209 @@
+# yaml-language-server: $schema=../state-machine-schema.json
+---
+name: 'waterfall'
+description: 'V-Model: Specification down to test – the historical way. Ideal for larger, design-heavy tasks with well-defined requirements'
+initial_state: 'requirements'
+
+# Enhanced metadata for better discoverability
+metadata:
+  domain: 'code'
+  complexity: 'high'
+  bestFor:
+    - 'Large feature development'
+    - 'Complex system changes'
+    - 'Well-defined requirements'
+    - 'Design-heavy projects'
+  useCases:
+    - 'Building a new module from scratch'
+    - 'Implementing complex business logic'
+    - 'Major architectural changes'
+  examples:
+    - 'Create a new authentication system'
+    - 'Build a reporting dashboard'
+    - 'Implement a payment processing workflow'
+  requiresDocumentation: true
+
+# States with default instructions and transitions
+states:
+  requirements:
+    description: 'Gathering and analyzing requirements'
+    default_instructions: |
+      Familiarize yourself with the code base and understand project goals, scope, constraints, and success criteria.
+
+      - Who are the key stakeholders? (end users, business owners, technical teams)
+      - Which requirements are must-have vs nice-to-have?
+      - How will you measure success? What are the acceptance criteria?
+      - What are your time, budget, technical, or regulatory constraints?
+      - What existing systems must this integrate with?
+
+      Document all requirements in `$REQUIREMENTS_DOC`. Create actionable tasks referencing those requirements.
+    transitions:
+      - trigger: 'requirements_complete'
+        to: 'design'
+        transition_reason: 'All requirements tasks completed, moving to technical design'
+        review_perspectives:
+          - perspective: 'business_analyst'
+            prompt: 'Review requirements completeness, clarity, and business value. Ensure all stakeholder needs are captured and requirements are testable. Check for missing edge cases or unclear acceptance criteria.'
+          - perspective: 'ux_expert'
+            prompt: 'Evaluate user experience implications and usability requirements. Ensure user needs and workflows are properly defined. Identify potential UX challenges or accessibility concerns.'
+
+  design:
+    description: 'Technical design and architecture planning'
+    default_instructions: |
+      Review requirements from `$REQUIREMENTS_DOC` and design the technical solution.
+
+      Focus on HOW to implement what's needed including architecture, technologies, data models, API design, and quality goals. Clarify performance expectations and technology preferences if not already obvious from the current analysis.
+
+      Document architectural decisions in `$ARCHITECTURE_DOC` and detailed design in `$DESIGN_DOC`. Create tasks and ensure the approach is solid before implementation.
+    transitions:
+      - trigger: 'need_more_requirements'
+        to: 'requirements'
+        additional_instructions: 'Design work revealed gaps in requirements understanding. Focus on clarifying the specific requirements that are blocking design decisions.'
+        transition_reason: 'Design work revealed need for additional requirements clarification'
+
+      - trigger: 'design_complete'
+        to: 'implementation'
+        transition_reason: 'Technical design is complete, ready for implementation'
+        review_perspectives:
+          - perspective: 'architect'
+            prompt: 'Review technical architecture, design patterns, and system integration. Ensure scalability, maintainability, and alignment with existing systems. Evaluate technology choices and architectural decisions.'
+          - perspective: 'security_expert'
+            prompt: 'Evaluate security considerations, data protection, and potential vulnerabilities in the proposed design. Review authentication, authorization, data handling, and potential attack vectors.'
+
+  implementation:
+    description: 'Building the solution according to design'
+    default_instructions: |
+      Follow the architecture from `$ARCHITECTURE_DOC` and detailed design from `$DESIGN_DOC` to build the solution.
+
+      Before starting, clarify the approach:
+      - Should this be implemented incrementally or all at once? Any specific order of implementation?
+      - Are there high-risk parts that need extra validation or careful implementation?
+
+      Ensure requirements from `$REQUIREMENTS_DOC` are met. Focus on code structure, error handling, security, and maintainability. Write clean, well-documented code and include basic testing. Update task progress during implementation work.
+    transitions:
+      - trigger: 'need_design_changes'
+        to: 'design'
+        additional_instructions: "Implementation revealed issues with the current design. Consider what you've learned during coding and adjust the design accordingly. Document the changes and reasons."
+        transition_reason: 'Implementation work revealed need to revise the design'
+
+      - trigger: 'need_more_requirements'
+        to: 'requirements'
+        additional_instructions: 'Implementation revealed gaps in requirements understanding. Focus on clarifying the specific requirements that are blocking implementation.'
+        transition_reason: 'Implementation work revealed need for additional requirements'
+
+      - trigger: 'implementation_complete'
+        to: 'qa'
+        transition_reason: 'Core implementation is complete, ready for quality assurance'
+        review_perspectives:
+          - perspective: 'senior_software_developer'
+            prompt: 'Review code quality, best practices, and implementation approach. Ensure clean, maintainable, and efficient code. Check for proper error handling, logging, and code organization.'
+          - perspective: 'performance_engineer'
+            prompt: 'Assess performance implications, resource usage, and potential bottlenecks in the implementation. Review algorithms, data structures, and system resource utilization.'
+
+  qa:
+    description: 'Quality assurance and code review'
+    default_instructions: |
+      Perform systematic quality checks and code review:
+
+      **STEP 1: Automated Quality Checks**
+      - Run syntax checking tools or validate syntax manually
+      - Build the project to verify it compiles without errors
+      - Execute linting tools to ensure code style consistency
+      - Run existing tests to verify functionality
+
+      **STEP 2: Multi-Perspective Code Review**
+      Conduct code review from security, performance, UX, maintainability, and requirement compliance perspectives. Verify implementation matches `$DESIGN_DOC` specifications and fulfills targeted requirements from `$REQUIREMENTS_DOC`.
+
+      Update task progress and mark completed work during QA review.
+    transitions:
+      - trigger: 'need_implementation_fixes'
+        to: 'implementation'
+        additional_instructions: 'Quality assurance revealed issues that require code changes. Focus on the specific problems identified during QA review.'
+        transition_reason: 'QA found issues requiring implementation fixes'
+
+      - trigger: 'need_design_changes'
+        to: 'design'
+        additional_instructions: 'Quality assurance revealed fundamental design issues. Consider the QA findings and adjust the design accordingly.'
+        transition_reason: 'QA found issues requiring design changes'
+
+      - trigger: 'qa_complete'
+        to: 'testing'
+        transition_reason: 'Quality assurance is complete, ready for comprehensive testing'
+
+  testing:
+    description: 'Comprehensive testing and validation'
+    default_instructions: |
+      Create and execute comprehensive test plans to validate feature completeness.
+
+      - Write and execute tests with focus on test coverage and edge cases
+      - Conduct integration testing to ensure all components work together
+      - Validate user acceptance and ensure everything works as expected
+    transitions:
+      - trigger: 'need_implementation_fixes'
+        to: 'implementation'
+        additional_instructions: 'Testing revealed bugs or issues that require code changes. Focus on the specific problems identified during testing.'
+        transition_reason: 'Testing found issues requiring implementation fixes'
+
+      - trigger: 'need_qa_review'
+        to: 'qa'
+        additional_instructions: 'Testing revealed quality issues that need additional QA review. Focus on the specific quality concerns identified.'
+        transition_reason: 'Testing found issues requiring additional QA review'
+
+      - trigger: 'testing_complete'
+        to: 'finalize'
+        transition_reason: 'All testing is complete, feature is ready for delivery'
+        review_perspectives:
+          - perspective: 'business_analyst'
+            prompt: 'Verify that all requirements have been met and business objectives are achieved. Ensure the solution delivers the expected business value and meets acceptance criteria.'
+          - perspective: 'ux_expert'
+            prompt: 'Confirm user experience goals are met and the solution is user-friendly and accessible. Validate that user workflows are intuitive and efficient.'
+
+  finalize:
+    description: 'Code cleanup and documentation finalization'
+    default_instructions: |
+      Complete the feature by cleaning up code and updating documentation.
+
+      **STEP 1: Code Cleanup**
+
+      Remove debug output and temporary code:
+      - Search for and remove all temporary debug output statements used during development
+      - Look for language-specific debug output methods (console logging, print statements, debug output functions)
+
+      Review and address TODO/FIXME comments:
+      - Address each TODO/FIXME comment by either implementing the solution or documenting why it's deferred
+      - Remove completed TODOs
+      - Convert remaining TODOs to proper issue tracking if needed
+
+      Remove debugging code blocks:
+      - Remove temporary debugging code, test code blocks, and commented-out code
+      - Clean up any experimental code that's no longer needed
+      - Ensure proper error handling replaces temporary debug logging
+
+      **STEP 2: Documentation Review**
+
+      Review and update documentation to reflect final implementation:
+      - Update `$REQUIREMENTS_DOC` if requirements changed during development
+      - Update `$ARCHITECTURE_DOC` if architectural decisions evolved
+      - Update `$DESIGN_DOC` if design details were refined or changed
+      - Compare documentation against actual implemented functionality
+      - Only modify documentation sections that have functional changes
+      - Remove references to development iterations, progress notes, and temporary decisions
+      - Ensure documentation describes the final implemented state, not the development process
+      - Ask user to review document updates
+
+      **STEP 3: Final Validation**
+
+      - Run existing tests to ensure cleanup didn't break functionality
+      - Verify documentation accuracy with a final review
+      - Ensure code is ready for production/delivery
+
+      Update task progress and mark completed work as you finalize the feature.
+    transitions:
+      - trigger: 'need_final_changes'
+        to: 'implementation'
+        additional_instructions: 'Finalization revealed issues that require code changes. Focus on the specific problems identified during final review.'
+        transition_reason: 'Final review found issues requiring implementation changes'
+
+      - trigger: 'finalization_complete'
+        to: 'requirements'
+        transition_reason: 'Feature delivery complete, beginning new development cycle'

package/packages/core/dist/beads-integration.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Beads Integration Utilities
+ *
+ * Provides utilities for integrating with beads distributed issue tracker:
+ * - Project epic creation
+ * - Phase task management
+ * - Task hierarchy setup
+ */
+import { YamlState } from './state-machine-types.js';
+export interface BeadsPhaseTask {
+    phaseId: string;
+    phaseName: string;
+    taskId: string;
+}
+/**
+ * Beads integration manager for the workflows server
+ */
+export declare class BeadsIntegration {
+    private projectPath;
+    constructor(projectPath: string);
+    /**
+     * Ensure beads is initialized in the project directory
+     */
+    private ensureBeadsInitialized;
+    /**
+     * Create a project epic in beads for the development session
+     */
+    createProjectEpic(projectName: string, workflowName: string, description?: string, planFilename?: string): Promise<string>;
+    /**
+     * Create phase tasks for all workflow phases under the project epic
+     */
+    createPhaseTasks(epicId: string, phases: Record<string, YamlState>, workflowName: string): Promise<BeadsPhaseTask[]>;
+    /**
+     * Create sequential dependencies between workflow phase tasks
+     * Implements graceful error handling: logs warnings for failed dependencies but continues
+     */
+    createPhaseDependencies(phaseTasks: BeadsPhaseTask[]): Promise<void>;
+    /**
+     * Capitalize phase name for display
+     */
+    private capitalizePhase;
+    /**
+     * Validate parameters for epic creation
+     */
+    private validateCreateEpicParameters;
+    /**
+     * Validate parameters for phase task creation
+     */
+    private validateCreatePhaseParameters;
+}