kandev/apps/backend/config/workflows/improve-kandev.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: improve-kandev
name: Improve Kandev
description: >-
  Hidden three-step workflow for filing improvements to kandev.
  The agent implements the change, the user tests it in a secondary
  kandev instance, then the agent opens a pull request to kdlbs/kandev.
hidden: true

steps:
  - id: improve
    name: Improve
    position: 0
    color: bg-purple-500
    is_start_step: true
    show_in_command_panel: false
    allow_manual_move: true
    prompt: |
      [IMPROVE PHASE]
      Implement the requested change to kandev using TDD.

      {{task_prompt}}

      If the task description references a context bundle (paths to
      metadata.json, backend.log, frontend.log in a temp directory),
      read those files for additional debugging context before starting.

      STEP 0: CREATE A TASK LIST
      Track the substeps below using your todo tool. Mark each in_progress
      when you start and completed when you finish.

      STEP 1: UNDERSTAND THE REPORT
      Re-read the title and description carefully. If anything is unclear
      or ambiguous, use the ask_user_question_kandev tool before coding.

      PLANNING GATE
      If this request adds a feature or changes product behavior and does not
      reference an approved spec, plan, and current task file, follow the
      `spec-driven-development` skill through spec, plan, and task creation.
      Record any partial implementation as continuation context, then stop at
      the model-switch checkpoint before changing more production or permanent
      test files. The [IMPROVE PHASE] label and implementation checklist below
      are Phase 5 guidance; they do not opt the task out of planning. Continue
      directly only when approved task artifacts already exist or the user
      explicitly says to skip planning.

      STEP 2: EXPLORE THE CODEBASE
      - Find similar features and understand how they are implemented.
      - Identify the architecture and patterns in the relevant area.
      - Read AGENTS.md for repo-specific conventions.

      STEP 3: IMPLEMENT WITH TDD
      For each behavior:
      1. Write a failing test that asserts the expected behavior.
      2. Run the test — confirm it fails with the expected assertion.
      3. Write the minimum code to make it pass.
      4. Run the test — confirm it passes.
      5. Refactor while keeping tests green.
      Add an E2E test (Playwright) when the change touches a user-facing flow.

      STEP 4: VERIFY
      Run `make fmt` first, then `make typecheck test lint` per AGENTS.md.

      STEP 5: COMMIT
      Stage and commit your changes with a Conventional Commits message
      (e.g. `fix:`, `feat:`). Use explicit paths in `git add`.

      When the implementation is complete and verified, stop and tell the
      user. The user will move the task to the next step (Test) when ready.
    events:
      on_enter:
        - type: auto_start_agent

  - id: test
    name: Test
    position: 1
    color: bg-blue-500
    show_in_command_panel: false
    allow_manual_move: true
    prompt: |
      [TEST PHASE]
      Help the user verify the implemented change in a secondary kandev
      instance running side-by-side with the primary one.

      STEP 1: PREPARE
      Run `make install` to install dependencies if needed.

      STEP 2: START THE SECONDARY INSTANCE
      Run `make dev` with auto-port assignment so the new instance does not
      collide with the primary one. Capture the assigned URLs (web app,
      backend API) from stdout.

      STEP 3: REPORT
      Tell the user exactly:
      - Which URL to open to test the change.
      - What to look for / how to reproduce the bug or exercise the feature.
      - Any login or setup steps needed.

      Wait for the user to confirm the change works. If the user reports
      issues, take notes and ask the user to move the task back to Improve.
      When the user is satisfied, they will move the task to PR.
    events:
      on_enter:
        - type: auto_start_agent

  - id: pr
    name: PR
    position: 2
    color: bg-green-500
    show_in_command_panel: false
    allow_manual_move: true
    prompt: |
      [PR PHASE]
      Open a pull request against `main` in `kdlbs/kandev` for the change
      implemented and verified in the previous steps.

      STEP 1: PRE-FLIGHT
      - Confirm your changes are committed (`git status`).
      - For executor-owned credentials without a server-authored managed
        destination, run `gh auth status` to confirm GitHub CLI access.

      STEP 2: PUBLISH THROUGH THE TASK'S PREPARED ROUTE
      Task creation prepares the publication route before a managed task
      launches. Do not run a fork command, rename `origin`, or rewrite the
      canonical remote in this workflow.

      For Managed workspace credentials:
      - `origin` remains the canonical `kdlbs/kandev` repository. Use it for
        pulls, base comparisons, issue lookup, and the pull request target.
      - The task branch has a prepared push remote. Run ordinary `git push`
        and let Git use the branch's configured push remote.
      - Confirm that the configured push remote points at the task's exact
        GitHub fork. If it is missing or points at another repository, stop
        and report that the managed publication route is unavailable. Do not
        repair it with ambient credentials.
      - Create the pull request with an explicit canonical target and fork
        head: `gh pr create --repo kdlbs/kandev --base main --head
        <fork-owner>:<branch>` plus the title, body, and draft options.

      Executor-owned credentials are a separate compatibility path. It may
      use the executor's own publication setup only when the task has no
      server-authored managed destination. In that case, verify `gh auth
      status`, then run `gh repo fork kdlbs/kandev --remote
      --remote-name=origin` when the executor does not already have a
      writable fork. Verify that `origin` points at the executor-owned fork
      and that the canonical repository remains available as `upstream`.
      Never select this path to recover from a managed preparation failure or
      a missing managed push remote.

      STEP 3: INVOKE THE PR SKILL
      Use the `pr` skill (see `.claude/skills/pr/SKILL.md`):
      - Push the current branch through the prepared route from step 2.
      - Open a pull request against `main` in `kdlbs/kandev` with a clear
        title and description summarising the change and how it was tested.
        Use the explicit repository and fork head from step 2.
      - Reference the original task title in the PR description.

      STEP 4: REPORT
      Tell the user the PR URL. Stop and wait — the user takes it from here
      (review, merge, follow-ups).
    events:
      on_enter:
        - type: auto_start_agent