CI Iteration

Overview

Run the specified CI target and automatically fix any failures. Keep iterating until all checks pass or you get stuck on an issue that requires human intervention.

IMPORTANT: All make commands must be run from the repository root directory. The Makefile is located at the root of the repository, not in subdirectories.

Sub-Agent Policy

CRITICAL: When spawning sub-agents to run make , pytest , ty , ruff , prettier , or gt commands, you MUST use devrun :

Task tool with:

• subagent_type: devrun <- MUST be devrun, NEVER general-purpose

Why: devrun has hard tool constraints (no Edit/Write) preventing destructive changes. The parent agent (you) processes reports and applies fixes - sub-agents only report.

FORBIDDEN:

• Spawning general-purpose or other sub-agents for make/pytest/ty/ruff/prettier/gt

• Giving sub-agents prompts like "fix issues" or "iterate until passing"

REQUIRED:

• Sub-agents run ONE command and report results

• Parent agent decides what to fix based on reports

Core Workflow

1. Initial Run

Use the devrun agent to run the specified make target from the repository root:

Task tool with:

• subagent_type: devrun
• description: "Run [make target] from repo root"
• prompt: "Change to repository root and execute: [make target]"

2. Parse Failures

Analyze the output to identify which check(s) failed:

• Ruff lint failures: "ruff check" errors

• Format failures: "ruff format --check" or files needing reformatting

• Prettier failures: Markdown files needing formatting

• MD-check failures: CLAUDE.md files not properly referencing AGENTS.md

• ty failures: Type errors with file paths and line numbers

• Test failures: pytest failures with test names and assertion errors

3. Apply Targeted Fixes

Based on failure type, apply appropriate fixes:

Failure Type Fix Command

Ruff lint make fix via devrun

Ruff format make format via devrun

Prettier make prettier via devrun

Sync-Kit erk sync directly

MD-check Edit CLAUDE.md to contain only @AGENTS.md

ty Edit files to fix type annotations

Tests Read and edit source/test files

4. Verify and Repeat

After applying fixes, run the make target again via devrun. Continue the cycle: run -> identify failures -> fix -> verify.

Iteration Control

Safety Limits:

• Maximum iterations: 10 attempts

• Stuck detection: If the same error appears 3 times in a row, stop

• Progress tracking: Use TodoWrite to show iteration progress

Progress Reporting

Use TodoWrite to track progress:

Iteration 1: Fixing lint errors Iteration 2: Fixing format errors Iteration 3: Fixing type errors in src/erk/cli/commands/switch.py Iteration 4: All checks passed

When to Stop

SUCCESS: Stop when the make target exits with code 0 (all checks passed)

STUCK: Stop and report to user if:

• You've completed 10 iterations without success

• The same error persists after 3 fix attempts

• You encounter an error you cannot automatically fix

Reporting Formats

Success Format

Finalization Status: SUCCESS

All CI checks passed after N iteration(s):

(check) Lint (ruff check): PASSED

(check) Format (ruff format --check): PASSED

(check) Prettier: PASSED

(check) AGENTS.md Standard (md-check): PASSED

(check) ty: PASSED

(check) Tests: PASSED

(check) Sync-Kit (erk check): PASSED

The code is ready for commit/PR.

IMPORTANT: Each check line MUST be separated by a blank line in the markdown output to render properly in the CLI.

Stuck Format

Finalization Status: STUCK

I was unable to resolve the following issue after N attempts:

Check: [lint/format/prettier/md-check/ty/test]

Error: [Exact error message]

File: [file path if applicable]

Attempted Fixes:

1. [What you tried first]
2. [What you tried second]
3. [What you tried third]

Next Steps: [Suggest what needs to be done manually]

Guidelines

• Be systematic: Fix one type of error at a time

• Run full CI: Always run the full make target, not individual checks

• Use devrun agent: Always use the Task tool with devrun agent for ALL make commands

• Run from repo root: Always ensure make commands execute from repository root

• Track progress: Use TodoWrite for every iteration

• Don't guess: Read files before making changes

• Follow standards: Adhere to AGENTS.md coding standards

• Fail gracefully: Report clearly when stuck

• Be efficient: Use targeted fixes (don't reformat everything for one lint error)

Example Flow

Iteration 1:

• Use Task tool with devrun agent to run make target from repo root
• Found: 5 lint errors, 2 files need formatting
• Fix: Use Task tool with devrun agent to run make fix, then make format from repo root
• Result: 3 lint errors remain

Iteration 2:

• Use Task tool with devrun agent to run make target from repo root
• Found: 3 lint errors (imports)
• Fix: Edit files to fix import issues
• Result: All lint/format pass, 2 type errors

Iteration 3:

• Use Task tool with devrun agent to run make target from repo root
• Found: 2 ty errors in switch.py:45 and switch.py:67
• Fix: Add type annotations
• Result: All checks pass

SUCCESS

Important Reminders

• NEVER run pytest/ty/ruff/prettier/make/gt directly via Bash

• Always use the Task tool with subagent_type: devrun

• Covered tools: pytest, ty, ruff, prettier, make, gt

• Always ensure make commands execute from the repository root directory