kandev/apps/backend/config/workflows/plan-and-build.yml

# Internal workflow TEMPLATE definition — NOT the portable import/export format.
# Steps here reference each other by string `step_id`; the importable YAML uses a
# `version`/`type`/`workflows` envelope and `step_position`. Don't paste this file
# (or its `step_id` transitions) into the workflow import endpoint.
# Format reference: docs/workflow-import-export.md
id: standard
name: Plan & Build
description: >-
  Two-phase workflow: the agent first creates a plan for your review,
  then implements it. Ideal for tasks that benefit from upfront design.

steps:
  - id: todo
    name: Todo
    position: 0
    color: bg-neutral-400
    allow_manual_move: true

  - id: plan
    name: Plan
    position: 1
    color: bg-purple-500
    is_start_step: true
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [PLANNING PHASE]
      Analyze this task and create a detailed implementation plan.
      Do NOT make any code changes yet — only analyze and plan.

      {{task_prompt}}

      STEP 0: CREATE A TASK LIST
      Before anything else, create a task list tracking the substeps below (use your todo/task tracking tool if available). Mark each task in_progress when you begin it and completed when you finish. Do not skip ahead — each step feeds the next.

      STEP 1: UNDERSTAND THE REQUIREMENTS
      If anything is unclear or ambiguous, ask the user clarifying questions using the ask_user_question_kandev tool before proceeding.

      STEP 2: EXPLORE THE CODEBASE
      - Find similar features and understand how they are implemented.
      - Identify the architecture and patterns in the relevant area.
      - Map integration points and data flow.

      STEP 3: CREATE THE PLAN
      Create a plan that includes:
      1. Understanding of the requirements
      2. Files that need to be modified or created, and what each is responsible for
      3. Step-by-step implementation approach
      4. Potential risks or considerations
      5. Alternative approaches considered and why the recommended one was chosen

      When including diagrams (architecture, sequence, flowcharts, etc.), always use mermaid syntax in code blocks.

      IMPORTANT: Save your plan using the create_task_plan_kandev MCP tool with the task_id provided in the session context.
      After saving the plan, STOP and wait for user review. The user will review your plan in the UI and may edit it.
      Do not create any other files during this phase — only use the MCP tool to save the plan.
    events:
      on_enter:
        - type: enable_plan_mode
        - type: auto_start_agent
      on_exit:
        - type: disable_plan_mode

  - id: implementation
    name: Implementation
    position: 2
    color: bg-blue-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [IMPLEMENTATION PHASE]
      Implement the task following the approved plan.

      {{task_prompt}}

      GIT SAFETY (read before running any git command)
      - NEVER run `git checkout -- .`, `git checkout .`, `git reset --hard`, `git clean -fd`, or `git stash --include-untracked`. These wipe uncommitted work.
      - When reverting files touched by formatters/linters, ALWAYS pass explicit paths (e.g. `git checkout -- path/to/file path/to/dir/`). Never use `.` or unscoped globs.
      - Treat any uncommitted changes you did not make as intentional user work — leave them in place. Do not revert, stash, or overwrite them.

      STEP 0: CREATE A TASK LIST
      Before anything else, create a task list tracking the substeps below (use your todo/task tracking tool if available). Mark each task in_progress when you begin it and completed when you finish. Do not skip ahead — each step feeds the next.

      STEP 1: RETRIEVE THE PLAN
      Before starting, retrieve the task plan using get_task_plan_kandev with the task_id from the session context.
      Review the plan carefully, including any edits the user may have made.
      Acknowledge the plan and any user modifications before proceeding.

      STEP 2: IMPLEMENT
      Use a TDD strategy — for each behavior:
      1. Write a failing test that asserts the expected behavior
      2. Run the test — confirm it fails with the expected assertion error
      3. Write the minimum code to make it pass
      4. Run the test — confirm it passes
      5. Refactor while keeping tests green
      6. Commit the change

      Build incrementally — one behavior at a time, tests passing at every step.
      Follow existing codebase conventions (naming, patterns, file organization).
      You can update the plan during implementation using update_task_plan_kandev if needed.

      STEP 3: STOP CONDITIONS
      - If you hit a blocker (missing dependency, unclear requirement, test fails repeatedly): stop and ask the user.
      - If a fix requires an architectural change (new DB table, new service layer, switching libraries): stop and ask.
      - After 3 failed fix attempts on the same issue: stop, question the approach, ask the user.

      STEP 4: ENSURE YOUR OWN CHANGES ARE COMMITTED
      Before finishing this phase:
      - Run `git status` to see what changed.
      - Stage and commit every file YOU created or modified for this task, using explicit paths (see GIT SAFETY). Use descriptive messages.
      - Any uncommitted or untracked changes you did not make are intentional user work — leave them as-is. Do not aim for an absolutely clean tree; aim for none of YOUR task-related edits to be uncommitted.
    events:
      on_enter:
        - type: auto_start_agent

  - id: done
    name: Done
    position: 3
    color: bg-green-500
    allow_manual_move: true