worker-dashboard/.workflows/solve-issue.yaml

name: solve-issue
description: TDD-driven issue resolution adapted for the workflow monorepo with bun + vitest
roles:
  planner:
    description: Analyzes issue and outputs a TDD test spec
    goal: You are a planning agent. You analyze Gitea issues and produce a TDD test specification that downstream roles will implement and verify.
    capabilities:
    - issue-analysis
    - planning
    procedure: 'On first run (no previous steps):

      1. Read the issue and all comments from Gitea using `tea issues <number> -r <owner/repo>`

      2. Look for project conventions files (CLAUDE.md, CONTRIBUTING.md) in the repo

      3. Assess whether the issue has enough information to produce a test spec

      4. If insufficient info: comment on the issue via `echo "..." | tea comment <number> -r <owner/repo>` (skip if you already commented), then output $status=insufficient_info

      5. If sufficient: produce a detailed TDD test spec in markdown covering all scenarios


      On subsequent runs (bounced back by tester with fix_spec):

      1. Read the tester''s output from the previous step to understand what''s wrong with the spec

      2. Revise the test spec accordingly


      After producing the test spec:

      1. Store it via `uwf cas put-text "<markdown content>"` and capture the returned hash

      2. Put the hash in frontmatter.plan (required when $status=ready)

      3. Set repoPath to the absolute path of the repository root



      IMPORTANT: Extract the repo remote (owner/repo) from git:

      ```bash

      git remote get-url origin | sed ''s|.*[:/]\([^/]*/[^.]*\).*|\1|''

      ```

      Store the result as repoRemote in your frontmatter output so downstream roles can use it for tea/API calls.'
    output: Output a brief summary of the test spec. Set $status to ready (with plan hash and repoPath) or insufficient_info.
    frontmatter:
      oneOf:
      - properties:
          $status:
            const: ready
          plan:
            type: string
          repoPath:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - plan
        - repoPath
      - properties:
          $status:
            const: insufficient_info
        required:
        - $status
  developer:
    description: TDD implementation per test spec
    goal: You are a developer agent. You implement code changes following TDD — write tests first, then implementation.
    capabilities:
    - coding
    procedure: "IMPORTANT: Always work in a git worktree, NEVER modify the main working directory directly.\nThe repo path and other details are provided in your task prompt.\n\nBefore starting any work,\
      \ set up an isolated worktree:\n1. cd into the repo path provided in your task prompt\n2. `git fetch origin` to get latest refs\n3. First time (no existing branch):\n   - `git worktree add .worktrees/fix/<issue-number>-<short-slug>\
      \ -b fix/<issue-number>-<short-slug> origin/main`\n   - `cd .worktrees/fix/<issue-number>-<short-slug> && bun install`\n4. If bounced back from reviewer or tester (branch already exists):\n   - cd\
      \ into the existing worktree under `.worktrees/fix/<issue-number>-<short-slug>`\n   - `git fetch origin && git rebase origin/main`\n5. ALL subsequent work must happen inside the worktree directory.\n\
      \nThen implement TDD:\n6. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the planner's output in your task prompt)\n7. If bounced back from reviewer or tester: read the\
      \ previous role's feedback in your task prompt\n8. Write tests first based on the spec (use vitest)\n9. Implement the code to make tests pass\n10. Ensure `bun run build` passes with no errors\n11.\
      \ Run `bun test` to verify all tests pass\n\nIf you cannot complete the implementation (e.g. the issue is too complex, blocked by external factors,\nor repeated attempts fail), set $status=failed\
      \ with a reason.\n"
    output: List all files changed and provide a summary. Set $status to done (with branch/worktree), or failed (with reason).
    frontmatter:
      oneOf:
      - properties:
          $status:
            const: done
          branch:
            type: string
          worktree:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - branch
        - worktree
      - properties:
          $status:
            const: failed
          reason:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - reason
  reviewer:
    description: Code standards compliance check
    goal: You are a code reviewer. You verify code standards compliance — NOT functionality (that's the tester's job).
    capabilities:
    - code-review
    - static-analysis
    procedure: 'The worktree path is provided in your task prompt. cd into it first.


      Before reviewing, verify the git branch:

      1. Run `git branch --show-current` — confirm the branch name references the issue number being worked on

      2. If the branch doesn''t correspond to the issue, flag it in your output and reject


      Then perform code review:

      Hard checks (must all pass):

      3. `bun run build` — no build errors

      4. `bunx biome check` — no lint violations

      5. TypeScript strict mode — no type errors


      Soft checks (review against project conventions from CLAUDE.md):

      - Functional-first: functions + types, no classes (except for errors or third-party requirements)

      - Named exports only, no default exports

      - No optional properties (use `T | null` instead of `?:`)

      - Folder module discipline: index.ts only re-exports, types in types.ts

      - Crockford Base32 log tags (8-char, unique per call site)

      - No `console.log` in production code (use createLogger from @uncaged/workflow-util)

      - No dynamic imports in production code


      Only review standards compliance. Do NOT test functionality.

      If rejecting, you MUST explain the specific reason in your output.

      '
    output: Explain your decision with specific file/line references. Set $status to approved (with branch/worktree) or rejected (with comments).
    frontmatter:
      oneOf:
      - properties:
          $status:
            const: approved
          branch:
            type: string
          worktree:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - branch
        - worktree
      - properties:
          $status:
            const: rejected
          comments:
            type: string
          worktree:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - comments
        - worktree
  tester:
    description: Functional correctness verification
    goal: You are a tester agent. You verify that the implementation correctly satisfies every scenario in the test spec.
    capabilities:
    - testing
    procedure: "The worktree path is provided in your task prompt. cd into it first.\n\n1. Run `bun test` for automated test verification\n2. Read the test spec from CAS: `uwf cas get <plan hash>` (find\
      \ the hash from the planner step in the thread history)\n3. Verify each scenario in the spec is covered and passing\n4. Determine outcome:\n   - passed: all scenarios verified, tests pass\n   - fix_code:\
      \ tests fail or implementation doesn't match spec → send back to developer\n   - fix_spec: the spec itself is wrong or incomplete → send back to planner\n"
    output: Report test results per scenario. Set $status to passed (with branch/worktree), fix_code (with report), or fix_spec (with report).
    frontmatter:
      oneOf:
      - properties:
          $status:
            const: passed
          branch:
            type: string
          worktree:
            type: string
          repoRemote:
            type: string
        required:
        - $status
        - branch
        - worktree
      - properties:
          $status:
            const: fix_code
          report:
            type: string
          repoRemote:
            type: string
          worktree:
            type: string
          branch:
            type: string
        required:
        - $status
        - report
      - properties:
          $status:
            const: fix_spec
          report:
            type: string
          repoRemote:
            type: string
          worktree:
            type: string
          branch:
            type: string
        required:
        - $status
        - report
  committer:
    description: Commits and creates PR
    goal: You are a committer agent. You create a clean commit and push a PR linking the original issue.
    capabilities: []
    procedure: "The worktree path, branch name, and repo remote (owner/repo) are provided in your task prompt.\ncd into the worktree first.\n\nNote: You inherit the developer's worktree and branch. Do NOT\
      \ create a new branch.\n1. Stage all changes: `git add -A`\n2. Commit with a descriptive message referencing the issue: `git commit -m \"type: description\\n\\nFixes #N\"`\n3. Push the branch: `git\
      \ push -u origin <branch-name>`\n4. **Verify push succeeded** — run `git ls-remote origin <branch-name>` and confirm it prints a commit hash.\n   - If no output or push failed: capture the error, mark hook_failed\n\
      5. Create a PR using the Gitea API (do NOT use `tea pr create` — it fails in worktrees):\n   ```bash\n   GITEA_TOKEN=$(cfg get GITEA_TOKEN)\n   curl -s -X POST -H \"Authorization: token $GITEA_TOKEN\" -H \"Content-Type: application/json\" \\\n\
      \     \"https://git.shazhou.work/api/v1/repos/<owner>/<repo>/pulls\" \\\n     -d '{\"title\":\"...\",\"body\":\"...\",\"head\":\"<branch>\",\"base\":\"main\"}'\n   ```\n   - The repo remote (owner/repo format, e.g. \"uncaged/workflow\") is given in your task prompt — use it directly.\n\
      \   - PR body must include: What / Why / Changes / Ref sections, with `Fixes #N` in Ref\n6. **Verify PR was created** — parse the curl response JSON: it must contain a `\"number\"` field. Print the PR URL.\n\
      \   - If curl returns an error or no number field: capture the response, mark hook_failed\n7. After PR creation, clean up the worktree:\n   - cd to the repo root (parent of .worktrees)\n   - `git worktree remove <worktree-path>`"
    output: Include PR URL on success or error log on failure. Set $status to committed (with prUrl) or hook_failed (with error).
    frontmatter:
      oneOf:
      - properties:
          $status:
            const: committed
          prUrl:
            type: string
          repoRemote:
            type: string
          worktree:
            type: string
          branch:
            type: string
        required:
        - $status
        - prUrl
      - properties:
          $status:
            const: hook_failed
          error:
            type: string
          repoRemote:
            type: string
          worktree:
            type: string
          branch:
            type: string
        required:
        - $status
        - error
graph:
  $START:
    _:
      role: planner
      prompt: Analyze the issue and produce an implementation plan.
  planner:
    insufficient_info:
      role: $END
      prompt: Insufficient information to proceed; end the workflow.
    ready:
      role: developer
      prompt: 'Implement the TDD test spec (CAS hash: {{{plan}}}) in repo {{{repoPath}}}. Repo remote: {{{repoRemote}}}.'
  developer:
    done:
      role: reviewer
      prompt: 'Review branch {{{branch}}} at {{{worktree}}} for code standards compliance. Repo remote: {{{repoRemote}}}.'
    failed:
      role: $END
      prompt: 'Developer failed: {{{reason}}}. Ending workflow.'
  reviewer:
    rejected:
      role: developer
      prompt: 'Reviewer rejected: {{{comments}}}. Fix the issues in repo {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
    approved:
      role: tester
      prompt: 'Review passed. Run tests on branch {{{branch}}} at {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
  tester:
    fix_code:
      role: developer
      prompt: 'Tests found code issues: {{{report}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
    fix_spec:
      role: planner
      prompt: 'Tests found spec issues: {{{report}}}. Revise the test spec. Repo remote: {{{repoRemote}}}.'
    passed:
      role: committer
      prompt: 'All tests passed. Commit and push branch {{{branch}}} from {{{worktree}}}. Repo remote (owner/repo): {{{repoRemote}}}.'
  committer:
    hook_failed:
      role: developer
      prompt: 'Push hook failed: {{{error}}}. Fix and re-submit. Worktree: {{{worktree}}}. Repo remote: {{{repoRemote}}}.'
    committed:
      role: $END
      prompt: 'PR created: {{{prUrl}}}. Workflow complete.'