| name | cleanup-session-protocol |
| description | Use for the cleanup session leader. Defines the issue surfacing, fix cycle, review round, clean-check voting, and cleanup report phases unique to cleanup sessions. |
Cleanup Session Protocol
Protocol for the active phases of a code cleanup session. The leader is the only editor — team members are advisors who read, critique, and surface issues.
Issue Surfacing
Open the floor: post a short summary of the cleanup scope (3-5 sentences), then ask specific members to review specific areas using @agent-name.
Team members respond with issues — style violations, dead code, unclear naming, missing error handling, unnecessary complexity. Each issue should be a short, actionable message with file path and line number.
Your role during surfacing:
- Direct traffic. Ask specific members to look at specific files or subsystems.
- Acknowledge each issue briefly: "Got it" or "Will fix" or "Disagree — [reason]."
- If you disagree with an issue, say why in 1-2 sentences. The team can push back.
- Batch issues mentally. Do not start fixing mid-surfacing.
- When the flow of new issues slows, announce: "Closing this surfacing round. Fixing now."
Fix Cycle
Work through the surfaced issues. For each fix:
- Edit the file(s).
- Run the build script. The build intercept hook will commit, push, and build automatically.
- If the build fails, fix the error and rebuild. Do not move on until the build is green.
- After a successful build, post to the channel: "Fixed [brief description]. Build green. Fetch my branch to review."
Batch small related fixes together — don't trigger a build for every single-line change. Group fixes by file or by theme, then build once.
Review Round
After completing all fixes from the current surfacing round:
- Post: "All fixes from this round are pushed. Fetch and review with:"
- Post the exact commands (substitute your actual agent name):
git fetch origin docker/{project-id}/{your-agent-name}
git diff HEAD FETCH_HEAD
- Wait for participants to review and respond.
Clean-Check Vote
If new issues are surfaced: return to Fix Cycle.
If no new issues: initiate a clean-check vote.
Post: "No new issues raised. Vote: is the code clean? Reply Clean or Not clean (with specifics)."
- Wait for ALL members to vote. Do not tally early.
- If unanimous Clean or strict majority Clean: proceed to conclusion.
- If Not clean wins: address the specifics raised, return to Fix Cycle.
Maximum 5 full loops (surfacing -> fix -> review). If the code is not clean after 5 loops, record remaining issues and conclude.
Cleanup Report
Write a cleanup report to plans/cleanup-report-{brief-name}.md on disk. Include:
- Files modified
- Issues fixed (one-liner each)
- Issues deferred (if any, with reasons)
- Final build status
Scope Constraints
- You are the sole editor. Team members advise and review only.
- Stay within the scope defined by the brief. Do not refactor adjacent systems unless the brief authorizes it.
- Do not add new features. Cleanup means: fix style, remove dead code, improve naming, simplify logic, fix obvious bugs.
- If you discover a real bug that needs a design decision, defer it.