AI Agent Development Workflow

Relevant source files

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

• skills/mutineer/SKILL.md
• CLAUDE.md
• AGENTS.md
• lib/mutineer/reporter.rb
• action.yml
• rake/docs_contract.rb

The AI Agent Development Workflow defines the iterative process for using Mutineer to improve Ruby test suites. It provides a machine-readable contract for AI coding agents to detect surviving mutants, strengthen tests, and gate continuous integration (CI) based on mutation scores.

Sources: skills/mutineer/SKILL.md:1-12, lib/mutineer/reporter.rb:15-20

The Agent Iteration Loop

The core workflow for an AI agent consists of four main steps focused on diff-scoped mutation testing. This approach ensures that agents only focus on code changed within their current context or branch.

1. Modify Code: You edit source code and tests on a feature branch.
2. Run Scoped Report: You run Mutineer with the --since flag and --format json to generate a machine-readable report of the changes.
3. Analyze Survivors: You parse the survivors[] array in the JSON report to identify code changes that the current test suite did not catch.
4. Verify Fix: You write or strengthen tests for each survivor and re-run Mutineer until the exit code is 0 and the mutation score meets the required threshold.

Sources: skills/mutineer/SKILL.md:21-33

Workflow Logic

The following diagram illustrates the iterative cycle an AI agent follows to eliminate surviving mutants.

This diagram shows the feedback loop between code modification and mutation testing verification.
Sources: skills/mutineer/SKILL.md:21-36

Machine-Readable Contract

Agents interact with Mutineer through standardized exit codes and a versioned JSON report schema. This contract ensures predictable behavior across different environments and toolings.

Exit Code Definitions

Mutineer uses specific exit codes to signal the state of the mutation run to the calling agent or CI environment.

Code	Meaning
0	Score ≥ threshold (or no gate) and no baseline regression.
1	Score below threshold, baseline regression, or incomplete run (e.g., too many errors).
2	Usage error, invalid flags, or unreadable baseline.

Sources: skills/mutineer/SKILL.md:46-52, rake/docs_contract.rb:58-62

JSON Report Structure

The JSON report (--format json) provides detailed metadata about the mutation run. The reporter.rb module maintains this schema, currently at version 1.8.

• Summary: Contains global counts including killed, survived, and score.
• Survivors: An array of mutants that were covered by tests but not killed.
• No Verdict: Mutants that failed to produce a result due to timeouts, errors, or uncapturable states.
• No Coverage: Mutants on lines that were never executed by the test suite.

Sources: lib/mutineer/reporter.rb:25-30, lib/mutineer/reporter.rb:140-195

CI Gating and Scoping

In CI environments, Mutineer typically scopes mutations to the pull request (PR) diff to provide fast feedback.

Scoping Strategy

The GitHub Action automatically determines the diff scope using the following hierarchy:

1. Explicit Ref: Uses the since input if provided.
2. PR Base: On pull_request events, it attempts to fetch the exact base commit SHA from the event payload.
3. Branch Tip: Falls back to origin/<base_ref> if the exact SHA is unavailable.
4. Full Scan: Runs a full scan if since: none is passed or if git resolution fails.

Sources: action.yml:18-36, action.yml:105-135

Scoping and Gating Flow

The following sequence diagram shows how the GitHub Action resolves the scoping and executes the gate.

The diagram represents the interaction between the CI environment and the Mutineer CLI during a PR check.
Sources: action.yml:95-150, action.yml:250-320

Contributor Non-negotiables

Agents or contributors modifying the Mutineer codebase itself must adhere to strict architectural constraints to maintain its suitability for agentic workflows.

• Zero Runtime Dependencies: The gem must only use the Ruby standard library and Prism. No runtime gems are allowed.
• No eval: The code must avoid eval to prevent security flags in supply-chain scanners; use load for snippet redefinition instead.
• 100% Documentation: Every new method or constant must have YARD documentation. The yard:strict task enforces this.
• Stability: The CLI contract (flags, exit codes, and JSON shape) must remain stable to prevent breaking agents that depend on them.

Sources: AGENTS.md:6-18, AGENTS.md:28-32, lib/mutineer/reporter.rb:140-150

Summary

The AI Agent Development Workflow leverages Mutineer's precision in detecting test weaknesses through a structured iteration loop. By combining scoped mutation runs with a stable machine-readable contract, the workflow enables automated systems to maintain high test quality without manual intervention. Success is achieved when the agent eliminates all relevant survivors and the CI gate confirms no regressions against the established baseline.

Sources: skills/mutineer/SKILL.md:40-45, AGENTS.md:120-130