Anti-Slop Workflow in oh-my-codex: A Complete Guide to Cleanup and Refactor Tasks

The anti-slop workflow in oh-my-codex is a disciplined six-step process that locks behavior with regression tests, categorizes code smells, executes four ordered cleanup passes, and validates changes through quality gates before producing an evidence-dense report.

The oh-my-codex repository implements a rigorous anti-slop workflow to handle cleanup, refactor, and deslop tasks safely. This process lives inside the standard $deep-interview → $ralplan → $team/$ralph pipeline and is governed by strict working agreements defined in the root AGENTS.md. When triggered, the workflow invokes the $ai-slop-cleaner skill to perform bounded, verifiable code improvement without introducing regressions.

Core Components and Working Agreements

The foundation of the anti-slop workflow rests on enforceable contracts documented in [AGENTS.md](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 47‑56). These agreements mandate specific behaviors before any cleanup begins.

Key working agreements include:

• Write a cleanup plan before modifying code – No ad-hoc edits are permitted without a documented strategy.
• Lock existing behavior with regression tests – Current functionality must be captured in tests before changes occur.
• Prefer deletion over addition – The workflow prioritizes removing dead code and duplication over adding new abstractions.
• No new dependencies without explicit request – Cleanup cannot introduce external libraries unless specifically authorized.
• Run lint, typecheck, tests, and static analysis – All quality gates must pass before completion.
• Writer/reviewer pass separation – Cleanup work requires distinct author and reviewer phases to maintain objectivity.

According to the execution-protocol block in AGENTS.md (lines 71‑76), anti-slop tasks follow the standard interview-plan-execution flow, but substitute the $ai-slop-cleaner skill as the bounded helper during the execution phase.

The Six-Step Cleanup Process

The complete procedure is specified in [skills/ai-slop-cleaner/SKILL.md](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/ai-slop-cleaner/SKILL.md). This skill provides a deterministic, repeatable method for transforming messy code into maintainable solutions.

Step 1: Lock Behavior with Regression Tests

Before touching production code, the workflow captures current behavior through comprehensive regression tests. This creates a safety net that immediately flags any functional changes introduced during cleanup.

Step 2: Create a Concrete Cleanup Plan

The skill generates a structured markdown plan identifying specific issues and remediation strategies. This plan acts as both a roadmap and an audit trail for the cleanup session.

Step 3: Categorize Code Smells

Issues are classified into five categories:

• Duplication – Repeated logic that should be consolidated.
• Dead code – Unused functions, variables, or imports.
• Needless abstraction – Over-engineered patterns that add complexity without value.
• Boundary violations – Functions accessing concerns outside their defined scope.
• Missing tests – Gaps in coverage for edge cases or error paths.

Step 4: Execute Four Ordered Passes

Cleanup occurs in strict sequence to prevent cross-contamination of changes:

1. Dead-code deletion – Remove all unused artifacts.
2. Duplicate removal – Extract shared logic into common utilities.
3. Naming and error-handling cleanup – Rename cryptic identifiers and standardize error handling.
4. Test reinforcement – Add missing edge-case and regression tests.

Each pass is verified independently before proceeding to the next.

Step 5: Run Quality Gate Checks

The workflow enforces five mandatory validation steps:

• Regression tests pass.
• Linting reports zero errors.
• Type checking succeeds.
• All tests pass.
• Static and security scans find no new issues.

Additionally, the skill monitors diff size to ensure changes remain bounded and reviewable.

Step 6: Emit an Evidence-Dense Report

The final output documents every change, remaining risks, and files modified. This report serves as an audit trail for code review and future maintenance.

Ralph Integration and Scope Control

When operating inside a Ralph session, the $ai-slop-cleaner skill automatically constrains its scope to the changed-files list supplied by Ralph (lines 27‑30 in the skill definition). This prevents the workflow from straying into unrelated areas of the codebase.

# Ralph session – automatically runs ai-slop-cleaner on recently edited files

$ralph run --skill ai-slop-cleaner --files $(git diff --name-only HEAD~1)

For manual invocation outside Ralph, developers can specify scope explicitly:

$ai-slop-cleaner \
  --scope src/utils \
  --files src/utils/array.ts src/utils/object.ts

Omitting the --scope and --files flags allows the skill to operate on the entire feature area identified by the surrounding $deep-interview and $ralplan context.

Validation and Test Coverage

The repository validates the anti-slop workflow through [src/hooks/__tests__/anti-slop-workflow.test.ts](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/src/hooks/__tests__/anti-slop-workflow.test.ts). This test suite asserts that:

• Working agreements appear correctly in AGENTS.md.
• The reviewer-only pass is documented in skills/review/SKILL.md and skills/plan/SKILL.md.
• The ai-slop-cleaner skill contains all required procedural sections.

These tests guarantee that the workflow contracts remain intact across repository updates.

Practical Implementation Examples

Minimal Cleanup Plan Structure

After Step 2, the skill generates a concrete plan similar to:

## Cleanup Plan (src/utils)

1. **Dead code** – remove `unusedHelper` in `array.ts` (no references).  
2. **Duplication** – extract common `isEmpty` logic into `src/utils/common.ts`.  
3. **Naming** – rename `fn` → `flattenArray` for clarity.  
4. **Test reinforcement** – add edge-case test for `flattenArray([])`.

Final Report Output Format

Upon completion, Step 6 produces a structured report:

AI SLOP CLEANUP REPORT
======================

Scope: src/utils
Behavior Lock: Added/ran `test/array.test.ts` and `test/object.test.ts`

Cleanup Plan:
1. Delete dead code `unusedHelper`.
2. Remove duplicate `isEmpty` implementations.
3. Rename `fn` → `flattenArray`.
4. Add missing edge-case test.

Passes Completed:
1. Pass 1: Dead code deletion – removed `unusedHelper`.
2. Pass 2: Duplicate removal – consolidated `isEmpty`.
3. Pass 3: Naming/error handling cleanup – renamed function.
4. Pass 4: Test reinforcement – added edge-case test.

Quality Gates:
- Regression tests: PASS
- Lint: PASS
- Typecheck: PASS
- Tests: PASS
- Static/security scan: PASS

Changed Files:
- src/utils/array.ts – dead code removed, function renamed.
- src/utils/common.ts – new helper extracted.
- test/array.test.ts – new edge-case test added.

Remaining Risks:
- None identified.

Summary

• The anti-slop workflow is embedded in the standard oh-my-codex agent pipeline and activated through the $ai-slop-cleaner skill.
• Working agreements in AGENTS.md (lines 47‑56) enforce safety rules like regression-test locking and deletion-preference.
• The six-step procedure includes behavior locking, smell categorization, four ordered passes, and quality-gate validation.
• Ralph integration automatically limits scope to changed files, preventing unbounded rewrites.
• Test coverage in src/hooks/__tests__/anti-slop-workflow.test.ts ensures workflow contracts remain valid.

Frequently Asked Questions

What triggers the anti-slop workflow in oh-my-codex?

The workflow activates when a developer requests "cleanup", "refactor", or "deslop" during a $deep-interview session. The request flows through $ralplan into the execution lane, where the system invokes $ai-slop-cleaner instead of standard code generation skills.

How does the workflow prevent regressions during cleanup?

The workflow mandates regression test locking as Step 1, requiring that all existing behavior be captured in tests before any modifications occur. Additionally, the four ordered passes isolate specific types of changes, and quality gates verify functionality after each phase.

Can the anti-slop workflow run outside of Ralph sessions?

Yes. Developers can invoke the skill directly via $ai-slop-cleaner with optional --scope and --files flags. When run outside Ralph, the skill respects explicit file boundaries or operates on the feature area defined by the interview context.

Where are the working agreements for anti-slop tasks documented?

The primary working agreements appear in [AGENTS.md](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md) (lines 47‑56), while the specific execution protocol referencing $ai-slop-cleaner is documented at lines 71‑76. The reviewer-only pass requirements are detailed in skills/review/SKILL.md and skills/plan/SKILL.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}