united-workforce/.workflows/solve-issue.yaml

name: "solve-issue"
description: "TDD-driven issue resolution for small, focused changes. Loop protection relies on engine maxRounds."
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. Read CLAUDE.md (or equivalent project conventions file) to understand coding standards
      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 and terminate
      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)
    output: "Output a brief summary of the test spec. Frontmatter must include: $status (ready or insufficient_info) and plan (CAS hash of the test spec, required when status=ready)."
    frontmatter:
      type: object
      properties:
        $status:
          type: string
          enum: [ready, insufficient_info]
        plan:
          type: string
      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.

      Before starting any work, set up an isolated worktree:
      1. `cd ~/repos/workflow && git fetch origin` to get latest refs
      2. First time (no existing branch):
         - `git worktree add ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> -b fix/<issue-number>-<short-slug> origin/main`
         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug> && bun install`
      3. If bounced back from reviewer or tester (branch already exists):
         - The worktree should already exist at `~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
         - `cd ~/repos/workflow-worktrees/fix/<issue-number>-<short-slug>`
         - `git fetch origin && git rebase origin/main`
      4. ALL subsequent work must happen inside the worktree directory.

      Then implement TDD:
      5. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
      6. If bounced back from reviewer or tester: read the previous role's output to understand what needs fixing
      7. Write tests first based on the spec
      8. Implement the code to make tests pass
      9. Ensure `bun run build` passes with no errors
      10. Run `bun test` to verify all tests pass
    output: "List all files changed and provide a summary. Frontmatter must include: $status (done or failed)."
    frontmatter:
      type: object
      properties:
        $status:
          type: string
          enum: [done, failed]
      required: [$status]
  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: |
      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)

      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 CLAUDE.md conventions):
      - Functional-first: `function` + `type`, not `class` + `interface`
      - No optional properties (`?:`) — use `T | null`
      - Naming conventions (kebab-case files, PascalCase types, camelCase functions)
      - Module boundary discipline (folder exports via index.ts)
      - No `console.log` (use structured logger)
      - 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. Frontmatter must include: $status (approved or rejected)."
    frontmatter:
      type: object
      properties:
        $status:
          type: string
          enum: [approved, rejected]
      required: [$status]
  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: |
      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)

      1. Run `bun test` for automated test verification
      2. Read the test spec from CAS: `uwf cas get <plan hash>` (find the hash from the latest planner step's frontmatter.plan)
      3. Verify each scenario in the spec is covered and passing
      4. Determine outcome:
         - passed: all scenarios verified, tests pass
         - fix_code: tests fail or implementation doesn't match spec → send back to developer
         - fix_spec: the spec itself is wrong or incomplete → send back to planner
    output: "Report test results per scenario. Frontmatter must include: $status (passed, fix_code, or fix_spec)."
    frontmatter:
      type: object
      properties:
        $status:
          type: string
          enum: [passed, fix_code, fix_spec]
      required: [$status]
  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: |
      First, cd into the worktree: `cd ~/repos/workflow-worktrees/fix/<issue-number>-*` (find the exact directory)

      Note: You inherit the developer's worktree and branch. Do NOT create a new branch.
      1. Stage all changes: `git add -A`
      2. Commit with a descriptive message referencing the issue: `git commit -m "type: description\n\nFixes #N"`
      3. Push the branch: `git push -u origin <branch-name>`
         - If push hook fails: capture the error log in your output, mark hook_failed
      4. On push success: create a PR via `tea pr create --repo uncaged/workflow --title "..." --description "..."`
         - The `--repo` flag is required to work in worktree directories (fixes #474 "path segment [0] is empty" error)
         - If working on a different repo, extract owner/repo from: `git remote get-url origin | sed 's/.*[:/]\([^/]*\/[^.]*\).*/\1/'`
         - PR description must follow the project template: What / Why / Changes / Ref sections, with `Fixes #N` in Ref
         - On tea failure: capture stderr/stdout, log the error clearly, include PR details (title, description, branch) for manual creation, and mark success=false
      5. After PR creation, clean up the worktree:
         - `cd ~/repos/workflow`
         - `git worktree remove ~/repos/workflow-worktrees/fix/<issue-number>-<slug>`
    output: "Include PR URL on success or error log on failure. Frontmatter must include: $status (committed or hook_failed)."
    frontmatter:
      type: object
      properties:
        $status:
          type: string
          enum: [committed, hook_failed]
      required: [$status]
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 plan from the planner." }
  developer:
    failed: { role: "$END", prompt: "Development failed; end the workflow." }
    done: { role: "reviewer", prompt: "Send the implementation to the reviewer." }
  reviewer:
    rejected: { role: "developer", prompt: "Reviewer rejected the implementation; fix the issues." }
    approved: { role: "tester", prompt: "Review passed; run tests on the implementation." }
  tester:
    fix_code: { role: "developer", prompt: "Tests found code issues; return to developer." }
    fix_spec: { role: "planner", prompt: "Tests found spec issues; return to planner." }
    passed: { role: "committer", prompt: "Tests passed; commit and push the changes." }
  committer:
    hook_failed: { role: "developer", prompt: "Push hook failed; return to developer to fix." }
    committed: { role: "$END", prompt: "Commit succeeded; complete the workflow." }