Agent Definitions

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• agents/pr-comment-reviewer.md
• skills/resolve-pr-comments/SKILL.md
• skills/README.md
• README.md

Agent Definitions in the AI Dev Atelier project provide a structured framework for how AI agents should operate, behave, and interact within the repository. These definitions are crucial for ensuring consistent, high-quality, and autonomous software development tasks, particularly in complex workflows like PR comment resolution. The system employs a multi-agent architecture where a primary orchestrator agent utilizes specialized sub-agents to perform focused tasks.

This document outlines the general guidelines applicable to all agents and provides a deep dive into the specific definition of the pr-comment-reviewer sub-agent, which is a core component of the automated PR feedback processing system.

Sources: AGENTS.md, agents/pr-comment-reviewer.md, skills/resolve-pr-comments/SKILL.md

General Agent Guidelines

All AI agents operating within this repository are expected to adhere to a set of foundational principles to ensure predictable and effective collaboration.

Sources: AGENTS.md:5-10

Initial Onboarding

Before performing any tasks, an agent must familiarize itself with the project by reading the following key documents:

• README.md: For project capabilities and entry points.
• SETUP.md: For verification steps.
• INSTALL.md: For dependencies and MCP setup.
• WORKFLOW_EXAMPLE.md: For a usage example.

Sources: AGENTS.md:12-17

Agent & Skill Interaction

Agents discover and execute capabilities through a standardized skill system.

This diagram illustrates the agent skill discovery and execution process.

The available skills are summarized below:

Skill	Purpose
code-quality	Typecheck, lint, format, and validate markdown.
docs-check	Detect documentation impact from git diffs.
docs-write	Write or update documentation using project standards.
git-commit	Write Conventional Commits.
code-review	Perform code reviews using CodeRabbit.
resolve-pr-comments	Orchestrate multi-agent PR comment resolution.
search	Search the web and library documentation.
research	Conduct academic research and create evidence cards.
ui-animation	Guide implementation of UI animations.

Sources: README.md:32-51, skills/README.md:11-21

The pr-comment-reviewer Sub-agent

The pr-comment-reviewer is a specialized sub-agent designed to validate and resolve PR review comments from automated bots like CodeRabbit, Copilot, and Gemini. It operates with a "fix-first" mindset, aiming for maximum autonomy.

Sources: agents/pr-comment-reviewer.md:3-9

Identity and Scope

• Role: Code review validator and fixer.
• Scope: A single cluster of related comments on one file.
• Authority: Can fix low, medium, and high-risk issues. Deferral is a last resort after at least three failed fix attempts.
• Mindset: A fix-first problem solver that debugs, researches, and fixes issues autonomously.

Sources: agents/pr-comment-reviewer.md:6-9

Orchestration and Invocation

The pr-comment-reviewer is not invoked directly by the user. Instead, it is spawned as a sub-agent by an orchestrator using the resolve-pr-comments skill. The orchestrator first runs the pr-resolver.sh script to fetch and cluster comments, then spawns a sub-agent for each actionable cluster.

The following sequence diagram shows the orchestration flow.

Sub-agents are invoked using the background_task tool to enable parallel, non-blocking execution.

// Fire ALL clusters immediately (non-blocking, returns task_id)
background_task({ agent: "pr-comment-reviewer", prompt: "Process cluster. Read: .ada/.../cluster-1.md", description: "Cluster 1" })
background_task({ agent: "pr-comment-reviewer", prompt: "Process cluster. Read: .ada/.../cluster-2.md", description: "Cluster 2" })

Sources: skills/resolve-pr-comments/SKILL.md:92-95

Agent Workflow

The sub-agent follows a strict, multi-phase workflow for each unresolved comment.

This flowchart outlines the pr-comment-reviewer's mandatory workflow.

Behavioral Constraints (Anti-Patterns)

The agent's definition includes strict behavioral constraints to prevent common failure modes. Violating these is considered a critical failure.

Anti-Pattern	Correct Behavior
❌ Suppress type errors with as any or @ts-ignore	Fix the underlying type issue.
❌ Delete failing tests to make them pass	Fix the code so the test passes.
❌ Defer without researching first	Research deeply using all available tools before deferring.
❌ Commit changes without explicit request	Only commit when the user explicitly asks.
❌ Skip verification before resolving a comment	Run diagnostics and tests before executing the resolution script.
❌ Dismiss a comment without providing evidence	Use grep or read to find evidence before dismissing.

Sources: agents/pr-comment-reviewer.md:13-30

The "Fix-First" Verification Loop

A core principle for this agent is to debug and fix verification failures rather than immediately deferring.

This diagram shows the mandatory loop for handling verification failures.

The agent is equipped with language-aware verification steps for different tech stacks.

Language	Test Command	Lint Command	Type Check
Node.js	npm test	npm run lint	npm run typecheck
Python	pytest {file}	ruff check {file}	mypy {file}
Go	go test ./...	golangci-lint run	N/A (compiled)
Rust	cargo test	cargo clippy	N/A (compiled)

Sources: agents/pr-comment-reviewer.md:247-251, 119-125

Output Contract

The sub-agent must return its results in a precise format, including a Markdown summary for humans and a structured JSON object for the orchestrator. The JSON output must be wrapped in <output_json> tags.

Sources: agents/pr-comment-reviewer.md:342-344, 363-365

Example of the JSON output structure:

<output_json>
{
  "cluster_id": "{cluster-id}",
  "file": "{file_path}",
  "concern": "{concern_type}",
  "summary": {
    "fixed": 1,
    "dismissed": 1,
    "deferred": 1
  },
  "actions": [
    {
      "comment_id": "123456",
      "classification": "VALID_FIX",
      "confidence": 95,
      "action": "FIXED",
      "reason": "Updated import path to correct module",
      "script_executed": "pr-resolver-resolve.sh 7 123456",
      "script_result": "SUCCESS",
      "thread_resolved": true,
      "verification": {
        "diagnostics": "pass",
        "tests_run": true,
        "tests_passed": true,
        "lint_passed": true
      }
    }
  ],
  "deferred_items": [
    {
      "comment_id": "345678",
      "reason": "Security concern requires human review",
      "context": "Full context for human..."
    }
  ]
}
</output_json>

Sources: agents/pr-comment-reviewer.md:366-413

Summary

The Agent Definitions in AI Dev Atelier establish a robust and opinionated framework for AI agent operation. By providing detailed instructions, behavioral guardrails, and clear interaction protocols like the one for the pr-comment-reviewer, the project ensures that agents can perform complex, multi-step tasks autonomously and reliably. This structured approach is key to leveraging AI for scalable and high-quality software development.

Sources: AGENTS.md, agents/pr-comment-reviewer.md