Table of Contents

Agent Workflow: End-to-End Task Lifecycle

This document describes the full lifecycle of a task in the ai-workarea Claude Code workspace, from the moment a human creates a YouTrack issue through autonomous implementation, review-feedback resolution, and final merge.

Overview

Human creates YouTrack issue
         |
         v
  [issue-resolver]  ------>  Feature branch + Pull Request (PR)
         |
         v
  [pr-reviewer]  ---------->  Reviews PR; posts feedback or approves + merges
         |
    (if feedback)
         v
  [pr-resolver]  ---------->  Addresses review comments, re-labels PR as Ready
         |
         v
  [pr-reviewer]  ---------->  Re-reviews, approves, merges, deletes branch, marks YouTrack Done

The pipeline can cycle between pr-reviewer and pr-resolver more than once if the reviewer requests additional changes. The pipeline ends when pr-reviewer successfully merges the PR.

Stage 1 — Human Creates a YouTrack Issue

Required Fields

Field Required Value Notes
AI State Ready Signals the issue is ready for autonomous pickup
Stage To Do or In Progress Either value is accepted by get-open-issue
Summary Brief, imperative sentence e.g., "Add login endpoint to API"
Description Concrete scope and deliverable Enough detail for the agent to act without clarification

Conventions

  • Write the description as if briefing a developer: state what to change and where. Vague issues cause the agent to leave a clarification comment and stop.
  • Link related issues using YouTrack's link types (e.g., "subtask of", "relates to") to give the agent context.
  • Do not pre-assign a branch name or PR title — the agent derives these from the issue ID and summary.

Agent reads: AI State, Stage, Summary, Description, comments.

Stage 2 — issue-resolver Agent

Definition: .claude/agents/issue-resolver.md

The issue-resolver agent picks up a ready issue (either the next available one or a specific ID) and drives it to a merged-ready PR.

Workflow Steps

  1. Query YouTrack for issues where AI State = Ready and Stage = To Do / In Progress (via the get-open-issue skill).
  2. Fetch full issue details and comments.
  3. If the issue is ambiguous, post a clarification comment and stop.
  4. Set Stage = In Progress and AI State = Progressing on the YouTrack issue.
  5. Create a feature branch off main:
    • Naming convention: <type>/<issue-id>-<short-slug>
    • Examples: feat/COR-42-add-login, fix/COR-99-null-pointer, docs/COR-1011-agent-workflow
  6. Implement the minimal change required by the issue.
  7. Run the project's build/test suite (prefixed with rtk).
  8. Commit using a conventional-commit prefix, referencing the issue ID in the body: 
    feat: add login endpoint

Resolves COR-42
https://youtrack.davidhsaiou.com/issue/COR-42
  9. Push the branch and open a PR targeting main. The PR body must include the YouTrack issue URL.
  10. Post a comment on the YouTrack issue with the PR URL and commit SHA, then set AI State = Done.

YouTrack Fields Written

Field Value Set
Stage In Progress (step 4)
AI State Progressing (step 4), Done (step 10)

Gitea PR Labels Written

None at creation — the PR starts unlabeled.

Skills Used

get-open-issue, get-issue-detail, add-issue-comment, update-issue-status, create-pull-request

Stage 3 — pr-reviewer Agent (First Pass)

Definition: .claude/agents/pr-reviewer.md

The pr-reviewer agent reviews open PRs that carry the Ready label, approves and merges them, or leaves specific feedback and labels them Need Changes.

Workflow Steps

  1. List open PRs in the target Gitea repository (via get-open-pr skill).
  2. Select the first PR that has the Ready label. If no PR carries Ready, the agent stops.
  3. Load the full PR diff and description via view-pull-request.
  4. Evaluate correctness, convention adherence (per CLAUDE.md), base branch, and completeness.
  5. If the PR looks good:
    • Approve via approve-pull-request.
    • Merge via merge-pull-request.
    • Delete the source branch via delete-branch.
    • If the PR description references a YouTrack issue, set Stage = Done on that issue.
  6. If the PR needs changes:
    • Post specific, actionable review feedback via comment-pull-request.
    • Apply the Need Changes label via label-pull-request.
    • Do not approve or merge.

Note: After issue-resolver opens a PR, the PR has no label. pr-reviewer requires the Ready label to pick up a PR. This means a human (or another agent) must apply the Ready label before pr-reviewer will process it — or the pr-resolver agent applies it after addressing feedback.

YouTrack Fields Written

Field Value Set
Stage Done (after successful merge only)

Gitea PR Labels Written

Label When Applied
Need Changes PR requires changes before merging

Skills Used

get-open-pr, view-pull-request, approve-pull-request, merge-pull-request, delete-branch, comment-pull-request, label-pull-request, update-issue-status

Stage 4 — pr-resolver Agent

Definition: .claude/agents/pr-resolver.md

The pr-resolver agent handles PRs that have review comments requesting changes. It reads the feedback, applies fixes, and re-labels the PR as Ready so pr-reviewer can take another pass.

Workflow Steps

  1. List open PRs in the target Gitea repository (via get-open-pr).
  2. Filter to PRs that have at least one review in REQUEST_CHANGES state.
  3. Load the PR diff, description, and all review comments.
  4. Locate and read the relevant source files.
  5. Apply the minimal code changes to address each review comment.
  6. Run build/test (prefixed with rtk).
  7. Commit and push on the PR's existing source branch: 
    fix: address review feedback

Addresses review feedback on PR #42
  8. Apply the Ready label to the PR via label-pull-request.

YouTrack Fields Written

None — pr-resolver does not touch YouTrack.

Gitea PR Labels Written

Label When Applied
Ready After all review feedback is addressed

Skills Used

get-open-pr, view-pull-request, comment-pull-request, label-pull-request

Handoff Summary

From To Trigger
Human issue-resolver AI State = Ready, Stage = To Do / In Progress
issue-resolver pr-reviewer PR opened + Ready label applied (manually or by pr-resolver)
pr-reviewer pr-resolver PR labeled Need Changes by reviewer
pr-resolver pr-reviewer PR re-labeled Ready by pr-resolver
pr-reviewer YouTrack PR merged → Stage = Done set on linked issue

Agent and Skill File Locations

Agents

Agent File
issue-resolver .claude/agents/issue-resolver.md
pr-resolver .claude/agents/pr-resolver.md
pr-reviewer .claude/agents/pr-reviewer.md

Skills

Skill File
get-open-issue .claude/skills/get-open-issue/
get-issue-detail .claude/skills/get-issue-detail/
add-issue-comment .claude/skills/add-issue-comment/
update-issue-status .claude/skills/update-issue-status/
get-open-pr .claude/skills/get-open-pr/
view-pull-request .claude/skills/view-pull-request/
create-pull-request .claude/skills/create-pull-request/
approve-pull-request .claude/skills/approve-pull-request/
merge-pull-request .claude/skills/merge-pull-request/
delete-branch .claude/skills/delete-branch/
comment-pull-request .claude/skills/comment-pull-request/
label-pull-request .claude/skills/label-pull-request/

All paths above are relative to the root of the ai-workarea repository.