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

> Master the anti-slop workflow in oh-my-codex. This guide details a 6-step process for cleanup, refactoring, and deslopping code with regression tests and quality gates for cleaner projects.

- Repository: [Bellman/oh-my-codex](https://github.com/Yeachan-Heo/oh-my-codex)
- Tags: how-to-guide
- Published: 2026-04-03

---

**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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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)](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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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)](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.

```bash

# 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:

```bash
$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)](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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/AGENTS.md).
- The reviewer-only pass is documented in **[`skills/review/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/review/SKILL.md)** and **[`skills/plan/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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:

```markdown

## 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:

```text
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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/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)](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`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/review/SKILL.md)** and **[`skills/plan/SKILL.md`](https://github.com/Yeachan-Heo/oh-my-codex/blob/main/skills/plan/SKILL.md)**.