# Integrator Agent (amia-)
<!-- The badge above is rewritten by scripts/publish.py (stage 8) on every release.
It replaced a hand-maintained "**Version**: 1.3.0" line that had gone stale by
nine patch releases: nothing updated it and nothing checked it, so the README
advertised 1.3.0 while 1.3.9 shipped. Keep the `version-X.Y.Z-blue` shape — that
is the pattern the release stage matches on. -->
## Overview
The Integrator Agent handles **quality gates, testing, merging, and release candidates**. It ensures code quality before integration into the main branch.
## Core Responsibilities
1. **Code Review**: Review PRs for quality and correctness
2. **Quality Gates**: Enforce TDD, tests, and standards
3. **Branch Protection**: Prevent direct pushes to protected branches
4. **Issue Closure Gates**: Verify requirements before closing issues
5. **GitHub Integration**: Manage PRs, issues, and projects
## Components
### Agents
| Agent | Description |
|-------|-------------|
| `ai-maestro-integrator-agent-main-agent.md` | Main integrator agent |
| `amia-api-coordinator.md` | Coordinates GitHub API operations |
| `amia-bug-investigator.md` | Investigates reported bugs |
| `amia-code-reviewer.md` | Reviews code for quality |
| `amia-committer.md` | Handles git commit operations |
| `amia-debug-specialist.md` | Debugs CI/CD and test failures |
| `amia-github-sync.md` | Syncs GitHub state |
| `amia-integration-verifier.md` | Verifies integration success |
| `amia-pr-evaluator.md` | Evaluates PR readiness |
| `amia-screenshot-analyzer.md` | Analyzes screenshots for visual regressions |
| `amia-test-engineer.md` | Manages test execution and coverage |
### Skills
| Skill | Description |
|-------|-------------|
| `amia-github-integration` | GitHub Projects integration, label setup, PR workflows |
| `amia-github-pr-workflow` | PR review orchestration with delegation and verification |
| `amia-github-pr-checks` | CI status monitoring and PR readiness verification |
| `amia-github-pr-merge` | PR merge strategies and auto-merge configuration |
| `amia-github-pr-context` | PR metadata, diff, and changed files retrieval |
| `amia-github-issue-operations` | Issue creation, labels, milestones, assignees, comments |
| `amia-github-projects-sync` | GitHub Projects V2 synchronization via GraphQL |
| `amia-github-thread-management` | PR review thread management and resolution |
| `amia-code-review-patterns` | Two-stage PR review with 8-dimension analysis |
| `amia-multilanguage-pr-review` | Multi-language PR review routing |
| `amia-tdd-enforcement` | TDD enforcement via RED-GREEN-REFACTOR |
| `amia-ci-failure-patterns` | CI/CD failure diagnosis and pattern matching |
| `amia-git-worktree-operations` | Parallel PR processing with git worktrees |
| `amia-integration-protocols` | Shared utilities and cross-skill protocols |
| `amia-quality-gates` | Pre-review, review, pre-merge, post-merge checkpoints |
| `amia-release-management` | Version bumping, changelogs, release coordination |
| `amia-ai-pr-review-methodology` | Evidence-based PR review (4 phases, 5 dimensions) |
| `amia-label-taxonomy` | GitHub label taxonomy for PR/issue management |
Core 3-pillars operations (PRRD/TRDD/kanban) are **not** shipped locally: they go
through the core `ai-maestro-plugin` `ama-*` skills (`ama-prrd-*`, `ama-trdd-*`,
`ama-kanban-render`, `ama-proposal-approvals`), which route to the installed
`trddgrep` / `prrdgrep` / `specgrep` CLIs.
### Hooks
| Hook | Event | Description |
|------|-------|-------------|
| `amia-branch-protection` | PreToolUse | Block pushes to main/master |
| `amia-issue-closure-gate` | PreToolUse | Verify before issue closure |
| `amia-stop-check` | Stop | Block exit until integration work is complete |
## Quality Gates
1. **Branch Protection**: No direct pushes to main/master
2. **Issue Closure Gate**: Requires:
- Merged PR linked to issue
- All checkboxes checked
- Evidence of testing
- TDD compliance
## Workflow
1. Receives completion signal from Orchestrator
2. Reviews code changes
3. Runs quality gates
4. Verifies tests pass
5. Creates/reviews PR
6. Merges when approved
7. Reports to Assistant Manager
## Prerequisites
- **Python 3.8+** (recommended: 3.12)
- **`gh` CLI** installed and authenticated (`gh auth login`)
- **`uv`** for running Python scripts (`pip install uv`)
- **AI Maestro** installed and running (for inter-agent messaging)
- **`ai-maestro-plugin`** — the home of the core 3-pillars governance skills
(`ama-prrd-*`, `ama-trdd-*`, `ama-kanban-render`, `ama-proposal-approvals`,
`team-governance`) this plugin's persona drives; they route to the installed
`trddgrep` / `prrdgrep` / `specgrep` CLIs. Without `ai-maestro-plugin`
installed those skills and commands are absent and the governance steps fail
(command-not-found) rather than running silently.
Install `ai-maestro-plugin` from the `Emasoft/ai-maestro-plugins`
marketplace.
- **Claude Code 2.1.132+** recommended. Hooks read `$CLAUDE_CODE_SESSION_ID`
(added in 2.1.132) and `$CLAUDE_EFFORT` (2.1.133) for cross-hook log
correlation, run without terminal access since 2.1.139 (so stderr is
captured safely), and honor the `$CLAUDE_CODE_STOP_HOOK_BLOCK_CAP`
consecutive-block cap added in 2.1.143 (default 8). Older Claude Code
versions still work — the env vars are simply absent and `$CLAUDE_PROJECT_ROOT`
is the legacy fallback for `$CLAUDE_PROJECT_DIR`.
- **From Claude Code 2.1.233** (tightened by the 2.1.268 tool-surface gating) the
todo/task tools (`TaskCreate`, `TaskGet`, `TaskUpdate`, `TaskList`, `TodoWrite`)
are unavailable on Opus 4.8+, Sonnet 5+, Fable 5+ — the models this plugin's
agents run on. The skills therefore read GitHub issue checklists as plain
`- [ ]` / `- [x]` Markdown and write task records directly, with no todo-tool
call. Setting `CLAUDE_CODE_ENABLE_TODO_TOOLS=1` restores the tools but is not
required.
- **Aligned through Claude Code 2.1.284.** Notable platform changes this plugin
accounts for: hooks on Claude 2.1.251+ gain `PreModelSwitch`/`PostModelSwitch`;
project `.claude/settings.json` can no longer set
`CLAUDE_CONFIG_DIR`/`CLAUDE_CODE_TMPDIR`/`TMPDIR` (2.1.261) or enable
OpenTelemetry export (2.1.282); `"type": "sdk"` MCP entries in plugin files are
skipped with a warning (2.1.274) — this plugin declares none; agent-type hooks
no longer fire on PermissionRequest (2.1.280) — this plugin's hooks are all
command-type; skills named in the reserved `anthropic-skills` namespace do not
load (2.1.282) — none shipped here. Model pricing in
`scripts/cpv_token_cost.py` carries Fable 5.1 (2.1.257), Opus 5.5 (2.1.280)
and Sonnet 5.5 (2.1.284) with their documented cache-read exceptions.
## Installation
Clone the plugin repo and load it with `--plugin-dir`:
```bash
git clone https://github.com/Emasoft/ai-maestro-integrator-agent.git
claude --plugin-dir ./ai-maestro-integrator-agent
```
Or start a session with the main agent directly:
```bash
claude --agent ai-maestro-integrator-agent-main-agent --plugin-dir ./ai-maestro-integrator-agent
```
> **Note:** Marketplace distribution is TBD. For now, use `--plugin-dir` with a local clone.
## Non-Standard Directories
| Directory | Purpose |
|-----------|---------|
| `shared/` | Shared Python modules (thresholds, constants) used by multiple plugin scripts across skills and hooks |
| `tests/` | Plugin test suites (e.g. `test_governance_compliance.py`); run with `uv run python tests/<file>.py` |
| `git-hooks/` | Optional pre-push validation hook (runs CPV remote validation via `uvx`); installed via `cp git-hooks/pre-push .git/hooks/pre-push`. Note: this repo's own checkout uses `core.hooksPath=.githooks` (the publish.py ancestry gate), which takes precedence over `.git/hooks/` |
## Platform Requirements
All plugin scripts are written in Python for cross-platform compatibility (Linux, macOS, Windows).
## Skill Architecture
Skills use a **progressive discovery** pattern: each `SKILL.md` is a compact index (under 4000 chars) that agents read first, with detailed content in `references/*.md` files discovered on demand. Most skill scripts (54 of 70 at last count) support `--output-file <path>` to write full JSON to a file and print only a summary to stdout, minimizing token consumption.
## Validation
```bash
cd ai-maestro-integrator-agent
uvx --from git+https://github.com/Emasoft/claude-plugins-validation \
cpv-remote-validate plugin . --strict --verbose
```
(The same command CI runs in `.github/workflows/validate.yml` — the legacy
in-repo validator script was retired in favor of CPV remote validation.)
Current status: **0 CRITICAL, 0 MAJOR, 0 MINOR, 0 NIT** issues.