implement.yaml

# Implementation Workflow
#
# This example demonstrates an implementation workflow that mirrors
# the /implement command pattern. It shows:
# - Epic selector agent (Sonnet) for identifying the next epic to implement
# - Coder agent (Opus) for deep research, analysis, and implementation
# - Epic reviewer agent (Sonnet) for per-epic quality assessment
# - Committer agent (Sonnet) for git commits and plan updates
# - Plan reviewer agent (Opus) for holistic review of all changes
# - Fixer agent (Sonnet) for addressing plan-level issues
#
# Architecture Decision:
# - Epic selector enforces one-epic-at-a-time execution
# - Opus excels at deep reasoning, codebase analysis, and implementation
# - Sonnet excels at focused review, selection, and documentation tasks
# - Two-tier review: epic-level (fast) and plan-level (thorough)
#
# Usage:
#   conductor run examples/implement.yaml --input plan="Path to implementation plan document"
#
# With specific epic:
#   conductor run examples/implement.yaml --input plan="..." --input epic="EPIC-001"
#
# With verbose output:
#   conductor -V run examples/implement.yaml --input plan="..."

workflow:
  name: implement
  description: Implement a feature based on an implementation plan document
  version: "2.0.0"
  entry_point: epic_selector

  runtime:
    provider: copilot
    mcp_servers:
      web-search:
        command: npx
        args: ["-y", "open-websearch@latest"]
        env:
          MODE: stdio
          DEFAULT_SEARCH_ENGINE: duckduckgo
          ALLOWED_SEARCH_ENGINES: duckduckgo,brave,exa
        tools: ["search"]
      context7:
        command: npx
        args: ["-y", "@upstash/context7-mcp@latest"]
        tools: ["*"]
      ms-learn:
        type: http
        url: https://learn.microsoft.com/api/mcp
        tools: ["*"]
        
  input:
    plan:
      type: string
      required: true
      description: A link to an implementation plan (e.g., `.plan.md`) or the plan content itself
    epic:
      type: string
      required: false
      description: A specific epic ID to implement. If not provided, all incomplete epics are in scope

  context:
    mode: accumulate

  limits:
    max_iterations: 100
    # timeout_seconds is unlimited by default

agents:
  - name: epic_selector
    description: Reads the plan and selects exactly one epic to implement next
    model: claude-sonnet-4.6
    input:
      - workflow.input.plan
      - workflow.input.epic?
      - committer.output?
    system_prompt: |
      You are an Implementation Planner agent. Your ONLY job is to read an implementation
      plan document and identify the SINGLE next epic that needs to be implemented.

      You do NOT implement anything. You do NOT write code. You ONLY:
      1. Read and parse the plan document
      2. Identify epic statuses (DONE, IN PROGRESS, NOT STARTED, TO DO)
      3. Select the first incomplete epic
      4. Extract that epic's details for the implementation agent

      You must be precise about epic identification and status tracking.
    prompt: |
      Read the implementation plan and identify the next epic to implement.

      **Plan:**
      {{ workflow.input.plan }}

      {% if workflow.input.epic %}
      **Requested Epic:** {{ workflow.input.epic }}
      Only select this specific epic. If it is already DONE, report all_complete as true.
      {% endif %}

      {% if committer is defined and committer.output %}
      **Previous Epic Completed:** {{ committer.output.epic_completed }}
      **Committer's Remaining Epics:** {{ committer.output.remaining_epics | json }}
      **Committer's Next Epic Suggestion:** {{ committer.output.next_epic }}
      {% endif %}

      ## YOUR TASKS

      1. **Read the Plan Document**
         - If the plan is a file path, read the file to get the full plan content
         - Parse the entire document to identify ALL epics
         - For each epic, determine its current status:
           - Look at task status fields (DONE, IN PROGRESS, NOT STARTED, TO DO)
           - An epic is DONE only if ALL its tasks are marked DONE
           - An epic is IN PROGRESS if any task is IN PROGRESS
           - Otherwise it is NOT STARTED

      2. **Select the Next Epic**
         - If a specific epic was requested via input, select that epic
         - If the committer suggested a next epic, verify it is indeed incomplete and select it
         - Otherwise, scan epics in order (Epic 1, Epic 2, etc.) and select the FIRST one that is NOT DONE
         - Check prerequisites: verify all prerequisite epics are DONE before selecting
         - If ALL epics are DONE, set `all_complete` to true

      3. **Extract Epic Details**
         - Copy the FULL epic details including:
           - Epic title and description/goal
           - All tasks with their descriptions and file paths
           - Acceptance criteria
           - Prerequisites
           - Any technical notes relevant to the epic
         - This will be the ONLY information the implementation agent receives about the epic

      4. **Create a Plan Summary**
         - Summarize the overall plan (what is being built)
         - List all epics with their current status

      **CRITICAL:** Do NOT implement anything. Do NOT write or modify any code.
      Your output will be passed to the implementation agent.
    output:
      plan_summary:
        type: string
        description: Summary of the overall implementation plan
      all_epics:
        type: array
        description: List of all epic IDs/names with their current status
      current_epic:
        type: string
        description: The epic ID/name selected for implementation
      epic_details:
        type: string
        description: Full details of the selected epic (tasks, acceptance criteria, files, prerequisites)
      prerequisites_met:
        type: boolean
        description: Whether all prerequisites for the selected epic are satisfied
      all_complete:
        type: boolean
        description: True only if ALL epics in the plan are marked DONE
      remaining_count:
        type: number
        description: Number of epics still remaining (not DONE)
    routes:
      - to: coder
        when: "{{ not output.all_complete and output.prerequisites_met }}"
      - to: plan_reviewer
        when: "{{ output.all_complete }}"
      - to: $end

  - name: coder
    description: Implements code changes for a single epic
    model: claude-opus-4.6-1m
    input:
      - workflow.input.plan
      - epic_selector.output
      - epic_reviewer.output?
    system_prompt: |
      You are a Senior Software Engineer agent. Your task is to implement code changes
      for ONE specific epic that has been assigned to you.

      Your core capabilities include:
      - Deep codebase research to understand existing patterns, dependencies, and conventions
      - Identifying all relevant code, modules, and integration points
      - Writing clean, well-documented, production-ready code
      - Anticipating edge cases and handling them properly
      - Creating comprehensive tests
      - Following existing code patterns and conventions precisely

      CRITICAL CONSTRAINT: You must implement ONLY the epic specified below.
      Do NOT implement any other epics, even if you can see them in the plan.
      After completing this ONE epic, stop and report your results.
    prompt: |
      Implement the following epic. Do NOT implement any other epics.

      **Epic to Implement:** {{ epic_selector.output.current_epic }}

      **Epic Details:**
      {{ epic_selector.output.epic_details }}

      **Plan Context (for reference only - do NOT implement other epics):**
      {{ epic_selector.output.plan_summary }}

      **Plan Document:**
      {{ workflow.input.plan }}

      {% if epic_reviewer is defined and epic_reviewer.output and epic_reviewer.output.decision == "REQUEST_CHANGES" %}
      **Previous Implementation Failed Review - Fix These Issues:**
      {{ epic_reviewer.output.feedback }}

      **Specific Issues to Address:**
      {% for issue in epic_reviewer.output.issues %}
      - {{ issue }}
      {% endfor %}
      {% endif %}

      ## IMPLEMENTATION TASKS

      You are implementing ONLY: **{{ epic_selector.output.current_epic }}**

      1. **Deep Codebase Research**
         - Analyze the codebase to understand existing patterns and conventions
         - Identify all files that will be created, modified, or deleted for THIS epic
         - Review related modules and their interfaces
         - Identify integration points and potential conflicts
         - Document the coding style, naming conventions, and patterns used

      2. **Update Plan Status to IN PROGRESS**
         - Open the plan document and update this epic's status to "IN PROGRESS"
         - Update task statuses within this epic from "TO DO" or "NOT STARTED" to "IN PROGRESS"
         - Save the plan document

      3. **Implement the Changes**
         For THIS epic only:
         - Create or modify files as specified in the epic details
         - Follow existing code patterns and conventions exactly
         - Handle all edge cases appropriately
         - Add proper error handling and logging
         - Write clean, well-documented code

      4. **Create Tests**
         - Write comprehensive tests for all new functionality in THIS epic
         - Ensure tests cover edge cases and error conditions
         - Run tests to verify they pass

      5. **Document Your Changes**
         - Add inline comments where helpful
         - Update any relevant documentation

      **STOP after completing this epic. Do NOT continue to the next epic.**
    output:
      current_epic:
        type: string
        description: The epic that was implemented
      epic_details:
        type: string
        description: Detailed description of the implemented epic
      files_modified:
        type: array
        description: List of files that were created or modified
      changes_made:
        type: array
        description: List of specific changes made during implementation
      tests_added:
        type: array
        description: List of tests that were added or updated
      edge_cases_handled:
        type: array
        description: List of edge cases that were handled
      implementation_notes:
        type: string
        description: Notes about the implementation, decisions made, and any concerns
    routes:
      - to: epic_reviewer

  - name: epic_reviewer
    description: Reviews the implementation for a single epic
    model: claude-sonnet-4.6
    input:
      - coder.output
    system_prompt: |
      You are a Code Review agent. You conduct thorough reviews of code changes
      to ensure quality, correctness, and adherence to best practices.

      You are critical but constructive, providing specific, actionable feedback
      that helps improve the code.
    prompt: |
      Review the implementation changes for the following epic.

      **Epic:** {{ coder.output.current_epic }}

      **Epic Details:**
      {{ coder.output.epic_details }}

      **Changes Made:**
      {% for change in coder.output.changes_made %}
      - {{ change }}
      {% endfor %}

      **Files Modified:**
      {% for file in coder.output.files_modified %}
      - {{ file }}
      {% endfor %}

      **Tests Added:**
      {% for test in coder.output.tests_added %}
      - {{ test }}
      {% endfor %}

      **Edge Cases Handled:**
      {% for edge_case in coder.output.edge_cases_handled %}
      - {{ edge_case }}
      {% endfor %}

      **Implementation Notes:**
      {{ coder.output.implementation_notes }}

      ## REVIEW TASKS

      1. **Requirements Verification**
         - Verify that all requirements from the epic are met
         - Check that acceptance criteria are satisfied
         - Ensure no requirements were missed

      2. **Code Quality**
         - Check for bugs, errors, or logical issues
         - Verify proper error handling
         - Ensure code is clean and well-documented
         - Confirm code follows existing patterns and conventions

      3. **Edge Case Verification**
         - Confirm edge cases were handled appropriately
         - Check error handling is comprehensive

      4. **Test Coverage**
         - Verify tests cover the new functionality
         - Check that tests cover edge cases and error conditions

      Provide your decision: APPROVE or REQUEST_CHANGES.

      If REQUEST_CHANGES, provide specific, actionable feedback.
    output:
      decision:
        type: string
        description: Review decision - APPROVE or REQUEST_CHANGES
      feedback:
        type: string
        description: Detailed feedback on the implementation
      issues:
        type: array
        description: List of specific issues that need to be addressed
      strengths:
        type: array
        description: List of things done well in the implementation
      approved:
        type: boolean
        description: Whether the implementation is approved
    routes:
      - to: committer
        when: "{{ output.approved }}"
      - to: coder

  - name: committer
    description: Commits the changes and updates the plan document
    model: claude-sonnet-4.6
    input:
      - workflow.input.plan
      - coder.output
      - epic_reviewer.output
    system_prompt: |
      You are a Commit and Documentation agent. Your job is to:
      - Create clear, descriptive git commits for completed work
      - Update plan documents to reflect progress
      - Determine if there are more epics to implement
    prompt: |
      The following epic has been implemented and approved.

      **Epic:** {{ coder.output.current_epic }}

      **Epic Details:**
      {{ coder.output.epic_details }}

      **Changes Made:**
      {% for change in coder.output.changes_made %}
      - {{ change }}
      {% endfor %}

      **Files Modified:**
      {% for file in coder.output.files_modified %}
      - {{ file }}
      {% endfor %}

      **Reviewer Feedback:**
      {{ epic_reviewer.output.feedback }}

      **All Epics:**
      {{ epic_selector.output.all_epics | json }}

      ## COMMIT AND UPDATE TASKS

      1. **Update Plan Document**
         Open the plan document and make the following updates:

         a. **Update Epic Status**
            - Change the epic's status from "IN PROGRESS" to "DONE"

         b. **Update Task Statuses**
            - For each task in the epic, update the status field from "IN PROGRESS" or "TO DO" to "DONE"
            - Example: Change `Status: IN PROGRESS` to `Status: DONE`
            - Example: Change `Status: TO DO` to `Status: DONE`

         c. **Check Acceptance Criteria Checkboxes**
            - For each acceptance criterion that has been satisfied, check the checkbox
            - Change `- [ ]` to `- [x]` for completed criteria
            - Only check boxes for criteria that were actually implemented and verified

         d. **Add Completion Notes**
            - Add completion date if there's a field for it
            - Add any relevant implementation notes

         Save the updated plan document.

      2. **Create Git Commit**
         - Stage all modified files INCLUDING the updated plan document
         - Create a clear commit message starting with the epic ID
         - Example: "EPIC-001: Implement user authentication flow"

      3. **Determine Next Steps**
         - Re-read the plan document after updating it
         - Scan ALL epics in order (EPIC-001, EPIC-002, etc.)
         - Build a list of remaining epics that are NOT marked as "DONE"
         - If there are remaining epics:
           - Set `all_complete` to FALSE
           - Set `next_epic` to the FIRST remaining epic (by ID order)
           - Set `remaining_epics` to the full list of non-DONE epics
         - ONLY set `all_complete` to TRUE if EVERY epic in the plan is marked as "DONE"

      **IMPORTANT:** Do NOT set `all_complete` to true unless you have verified that
      ALL epics in the entire plan document are marked as DONE. When in doubt, 
      set `all_complete` to false and specify the next epic to implement.

      Commit the changes and update the plan.
    output:
      epic_completed:
        type: string
        description: The epic that was completed
      commit_message:
        type: string
        description: The git commit message used
      plan_updated:
        type: boolean
        description: Whether the plan document was updated
      remaining_epics:
        type: array
        description: List of ALL remaining epics (not marked DONE) in the plan, in order
      all_complete:
        type: boolean
        description: TRUE only if EVERY epic in the plan is marked DONE. FALSE if any epic remains.
      next_epic:
        type: string
        description: The FIRST remaining epic to implement (by ID order). Empty only if all_complete is true.
    routes:
      - to: epic_selector
        when: "{{ not output.all_complete }}"
      - to: plan_reviewer
        when: "{{ output.all_complete }}"

  - name: plan_reviewer
    description: Reviews the entire implementation plan and all commits holistically
    model: claude-opus-4.6-1m
    input:
      - workflow.input.plan
      - epic_selector.output
      - coder.output
      - committer.output
    system_prompt: |
      You are a Senior Architecture Reviewer. Your job is to perform a holistic review
      of the entire implementation after all epics have been completed.

      You review:
      - Overall architecture and design coherence
      - Cross-cutting concerns (error handling, logging, security)
      - Code consistency across all changes
      - Integration between components
      - Documentation completeness
      - Test coverage across the entire feature

      You are thorough and ensure the implementation is production-ready.
    prompt: |
      All epics have been implemented. Perform a holistic review of the entire implementation.

      **Original Plan:**
      {{ workflow.input.plan }}

      **Plan Summary:**
      {{ epic_selector.output.plan_summary }}

      {% if committer is defined and committer.output %}
      **Epics Completed:**
      {{ committer.output.epic_completed }}

      **Final Commit:**
      {{ committer.output.commit_message }}
      {% else %}
      **Note:** All epics were already marked DONE in the plan. No implementation was performed.
      {% endif %}

      ## HOLISTIC REVIEW TASKS

      1. **Architecture Review**
         - Review the overall architecture of the changes
         - Ensure components integrate well together
         - Check for proper separation of concerns
         - Verify the design is maintainable and extensible

      2. **Cross-Cutting Concerns**
         - Review error handling across all components
         - Check logging and observability
         - Verify security considerations
         - Ensure proper resource management

      3. **Code Consistency**
         - Check for consistent patterns across all changes
         - Verify naming conventions are consistent
         - Ensure code style is uniform

      4. **Documentation Review**
         - Verify documentation is complete and accurate
         - Check that README or other docs are updated
         - Ensure code comments are helpful

      5. **Test Coverage**
         - Review overall test coverage
         - Identify any gaps in testing
         - Verify integration tests exist where needed

      6. **Git History Review**
         - Review all commits made during implementation
         - Ensure commit messages are clear and descriptive
         - Check for any commits that should be squashed or amended

      Provide your decision: APPROVE or REQUEST_CHANGES.

      If REQUEST_CHANGES, provide specific issues that need to be fixed.
    output:
      decision:
        type: string
        description: Review decision - APPROVE or REQUEST_CHANGES
      feedback:
        type: string
        description: Detailed holistic feedback on the implementation
      architecture_issues:
        type: array
        description: List of architecture or design issues
      code_issues:
        type: array
        description: List of code quality or consistency issues
      documentation_issues:
        type: array
        description: List of documentation issues
      test_gaps:
        type: array
        description: List of test coverage gaps
      strengths:
        type: array
        description: List of things done well across the implementation
      approved:
        type: boolean
        description: Whether the overall implementation is approved
    routes:
      - to: $end
        when: "{{ output.approved }}"
      - to: fixer
        when: "{{ output.decision == 'REQUEST_CHANGES' }}"

  - name: fixer
    description: Fixes issues identified by the plan reviewer
    model: claude-sonnet-4.6
    input:
      - workflow.input.plan
      - coder.output
      - plan_reviewer.output
    system_prompt: |
      You are a Senior Software Engineer agent specializing in fixing issues
      identified during holistic code review.

      Your job is to address all issues raised by the plan reviewer:
      - Architecture and design issues
      - Code quality and consistency issues
      - Documentation gaps
      - Test coverage gaps

      You make targeted, precise fixes while maintaining the overall integrity
      of the implementation.
    prompt: |
      The plan reviewer has identified issues that need to be fixed.

      **Original Plan:**
      {{ workflow.input.plan }}

      **Reviewer Decision:** {{ plan_reviewer.output.decision }}

      **Reviewer Feedback:**
      {{ plan_reviewer.output.feedback }}

      **Architecture Issues:**
      {% for issue in plan_reviewer.output.architecture_issues %}
      - {{ issue }}
      {% endfor %}

      **Code Issues:**
      {% for issue in plan_reviewer.output.code_issues %}
      - {{ issue }}
      {% endfor %}

      **Documentation Issues:**
      {% for issue in plan_reviewer.output.documentation_issues %}
      - {{ issue }}
      {% endfor %}

      **Test Gaps:**
      {% for gap in plan_reviewer.output.test_gaps %}
      - {{ gap }}
      {% endfor %}

      ## FIX TASKS

      1. **Address Architecture Issues**
         - Review and fix any architecture or design problems
         - Ensure proper component integration
         - Maintain separation of concerns

      2. **Fix Code Issues**
         - Address all code quality issues
         - Ensure consistency across all changes
         - Fix any bugs or logical errors

      3. **Complete Documentation**
         - Fill in documentation gaps
         - Update README or other docs as needed
         - Add missing code comments

      4. **Add Missing Tests**
         - Write tests to cover identified gaps
         - Add integration tests where needed
         - Ensure comprehensive coverage

      5. **Commit Fixes**
         - Stage all fixes
         - Create a clear commit message describing the fixes
         - Example: "fix: Address plan review feedback - improve error handling and add tests"

      Fix all identified issues.
    output:
      issues_fixed:
        type: array
        description: List of issues that were fixed
      files_modified:
        type: array
        description: List of files that were modified during fixes
      tests_added:
        type: array
        description: List of tests that were added
      documentation_updated:
        type: array
        description: List of documentation that was updated
      commit_message:
        type: string
        description: The git commit message for the fixes
      fix_notes:
        type: string
        description: Notes about the fixes made
      all_issues_resolved:
        type: boolean
        description: Whether all issues have been resolved
    routes:
      - to: plan_reviewer
        when: "{{ output.all_issues_resolved }}"
      - to: plan_reviewer

output:
  plan: "{{ workflow.input.plan }}"
  epic_requested: "{{ workflow.input.epic | default('all') }}"
  epics_completed: "{{ committer.output.epic_completed if committer is defined else '' }}"
  remaining_epics: "{{ committer.output.remaining_epics | json if committer is defined else '[]' }}"
  all_complete: "{{ committer.output.all_complete if committer is defined else false }}"
  last_commit: "{{ committer.output.commit_message if committer is defined else '' }}"
  epic_review_decision: "{{ epic_reviewer.output.decision if epic_reviewer is defined else '' }}"
  plan_review_decision: "{{ plan_reviewer.output.decision if plan_reviewer is defined else '' }}"
  iterations: "{{ context.iteration }}"