kandev/apps/backend/config/workflows/feature-dev.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: feature-dev
name: Feature Dev
description: >-
  Full development lifecycle: spec with user review, implementation with TDD,
  automated code review, QA verification, draft PR, and CI fixup. Ideal for
  features that need quality gates between phases.

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

  - id: spec
    name: Spec
    position: 1
    color: bg-purple-500
    is_start_step: true
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [SPEC PHASE]
      Analyze this task and create a detailed implementation plan. Do NOT write any code yet.

      {{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 PROBLEM
      - If anything is unclear or ambiguous, ask the user clarifying questions using the ask_user_question_kandev tool before proceeding.
      - Identify: what problem is being solved, who benefits, what are the constraints.

      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, data flow, and extension points.
      - Check if the repo has a decision log (e.g. docs/decisions/) and read relevant decisions.

      STEP 3: DESIGN THE SOLUTION
      - Propose 2-3 approaches with trade-offs and your recommendation.
      - Map which files will be created or modified and what each is responsible for.
      - When including diagrams (architecture, sequence, flowcharts), 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: work
    name: Work
    position: 2
    color: bg-blue-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [WORK 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 (not a compile 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: review
    name: Review
    position: 3
    color: bg-yellow-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [REVIEW PHASE]
      Review the changes made in the Work phase for quality, security, and correctness.

      {{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: DETERMINE WHAT TO REVIEW
      Gather BOTH committed and uncommitted changes on this branch — uncommitted edits and untracked files are still part of the task's work and must be reviewed. Do not commit or discard them yourself.

      - Run: git status --short (see uncommitted modified + untracked files)
      - Run: git remote show origin | grep 'HEAD branch' (find the default branch name)
      - Run: git diff origin/<default_branch>...HEAD --name-only (committed changes on branch)
      - Run: git diff HEAD --name-only (uncommitted tracked changes)
      - Run: git ls-files --others --exclude-standard (untracked new files)

      The review scope is the UNION of those lists. Read each file from the working tree — the working tree already contains the latest state including uncommitted edits. For per-file diffs against the default branch (including uncommitted changes), use: `git diff origin/<default_branch> -- <file>` (no three-dot).

      If this still yields an empty set, report that there is nothing to review and stop — do not fabricate findings.

      STEP 2: REVIEW THE CHANGES
      Review across these layers (skip layers that don't apply):

      ARCHITECTURAL FIT (highest priority):
      - Changes belong in the correct layer/module and follow the dependency direction used by the codebase
      - Business/domain logic is not placed in controllers, transport handlers, repositories, data sources, or infrastructure code
      - Controllers handle protocol concerns, use cases orchestrate workflows, repositories define persistence needs, and data sources handle external systems
      - Domain/application code does not depend on frameworks, transport models, database models, or vendor-specific types
      - Changes do not bypass existing boundaries, duplicate responsibilities, or introduce unnecessary coupling between modules or domains
      - New interfaces and abstractions have clear ownership and represent a meaningful boundary, rather than wrapping a single implementation
      - Compare with neighbouring features and established patterns, but flag deviations only when they create a real architectural or maintainability problem
      - Treat fundamental architectural misplacement or broken dependency direction as a blocker

      DATA & STATE MODELLING:
      - Domain entities, value objects, DTOs, persistence models, and external API models remain separate where their responsibilities differ
      - State transitions and invariants are explicit and cannot create invalid or partially updated state
      - There is a single clear source of truth; state or business rules are not duplicated across layers
      - Nullability, optional fields, defaults, and invalid combinations are modelled deliberately
      - Persistence schemas or transport types are not leaking implementation details into domain/application contracts
      - Concurrency, retries, partial failures, and duplicate requests cannot corrupt state or apply transitions more than once
      - Backward compatibility, migrations, and mixed-version behaviour are considered when contracts or persisted data change

      Security (blockers if found):
      - No secrets, tokens, or credentials in code
      - Input validation at system boundaries
      - No SQL injection, XSS, command injection, or path traversal
      - Auth and authorization checks on new endpoints

      Logic & correctness:
      - Edge cases handled (empty input, nil/null, zero, max values)
      - Error paths covered and not silently swallowed
      - Race conditions in concurrent code

      Performance:
      - No N+1 queries (loop with individual DB calls)
      - No memory leaks (unclosed connections, streams, listeners)

      Code quality:
      - No dead code, unused imports, or commented-out code
      - No speculative code (unused flags, one-off abstractions with single call site)
      - Deep nesting (>3 levels) — suggest early returns

      STEP 3: FIX OR REPORT
      - Fix directly any issues you can resolve confidently (dead code, unused imports, missing early returns).
      - For issues needing the author's input, report with file:line, why it matters, and how to fix.
      - Only report findings you're >=80% confident about.

      Do NOT report issues on code that was not modified in this branch.

      STEP 4: COMMIT ANY FIXES YOU MADE
      If you made direct fixes in STEP 3:
      - Run `git status` to see what changed.
      - Stage only the files YOU edited, using explicit paths (see GIT SAFETY) — never `git add .`. Commit with a descriptive message (e.g. `review: remove dead code` or `review: early returns in X`).
      - Leave any other uncommitted or untracked files alone; they are the user's work and QA will exercise them from the working tree.
    events:
      on_enter:
        - type: reset_agent_context
        - type: auto_start_agent

  - id: qa
    name: QA
    position: 4
    color: bg-orange-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [QA PHASE]
      Verify the feature works end-to-end. Your goal is to find bugs, not confirm it works.

      {{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: UNDERSTAND WHAT WAS BUILT
      Read the task description and recent commits to understand what the feature should do.
      Retrieve the task plan using get_task_plan_kandev if available.

      STEP 2: TRACE THE WIRING
      Before testing behavior, verify the feature is actually connected:
      - Exports are imported and used (not just defined)
      - API routes have consumers
      - Data flows end-to-end: input -> handler -> storage -> response -> display

      STEP 3: TEST THE HAPPY PATH
      Run the feature as intended. For backend changes, call the API. For frontend changes, trace the UI flow.

      STEP 4: TRY TO BREAK IT
      Systematically test:
      - Boundary values: empty input, nil/null, zero, negative, max values, very long strings
      - Error paths: what happens when dependencies fail?
      - Concurrency: simultaneous requests to the same resource
      - Authorization: can the feature be accessed without proper auth?

      STEP 5: VERIFY TEST COVERAGE
      Check that the implementation has tests covering the behaviors you verified.
      If tests are missing for critical paths, write them.

      STEP 6: REPORT
      Summarize: what was verified working, what issues were found (with file:line and how to reproduce), and what test coverage is missing.
    events:
      on_enter:
        - type: auto_start_agent

  - id: pr
    name: PR
    position: 5
    color: bg-indigo-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [PR PHASE]
      Create a draft pull request for the changes.

      {{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: PREPARE
      - Run formatters and linters. If they touch files unrelated to your task, selectively restore them with `git checkout -- <specific-paths>` (see GIT SAFETY) — never `git checkout -- .`.
      - Stage and commit any remaining task-related changes using explicit paths — never `git add .`. Leave uncommitted or untracked files you did not create untouched; they are the user's work.
      - Push the branch to origin.

      STEP 2: CHECK FOR PR TEMPLATE
      Look for a pull request template in the repo:
      - .github/pull_request_template.md
      - .github/PULL_REQUEST_TEMPLATE.md
      - docs/pull_request_template.md
      If found, read it and follow its structure for the PR body.

      STEP 3: CREATE DRAFT PR
      Create the PR as a draft:
      ```bash
      gh pr create --draft --title "<type>: <description>" --body "<body following template or default>"
      ```
      - Title should follow Conventional Commits format if the repo uses it.
      - If no PR template was found, the body should include: summary of what was built and why, validation steps, and a checklist.

      STEP 4: REPORT
      Return the PR URL.
    events:
      on_enter:
        - type: auto_start_agent

  - id: ci-fixup
    name: CI Fixup
    position: 6
    color: bg-amber-500
    show_in_command_panel: true
    allow_manual_move: true
    prompt: |
      [CI FIXUP PHASE]
      Wait for CI checks to complete and fix any failures.

      {{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: FIND THE PR
      Run gh pr list --head $(git branch --show-current) to find the PR number.

      STEP 2: WAIT FOR CI
      Poll CI checks until they all resolve:
      ```bash
      gh pr checks <number>
      ```
      - Poll every 30 seconds, cap at 10 minutes.
      - Once done, note which checks passed and which failed.

      STEP 3: FIX FAILURES
      If any CI checks failed:
      1. Identify the failed run from gh pr checks output.
      2. Fetch failed logs: gh run view <run-id> --log-failed
      3. Read the relevant source files at the failing lines.
      4. Fix the issues (lint errors, test failures, type errors).
      5. Commit and push the fix.
      6. Go back to STEP 2 and verify the fix passes.

      STEP 4: REPORT
      When all checks pass, report the CI status and the PR URL.
    events:
      on_enter:
        - type: auto_start_agent

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