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