tomevault-io 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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.