Clean Flow is a Codex skill pack for cleanup and refactor planning, migration, and execution. It helps an agent understand the repository, choose the right refactor path, keep work resumable, and avoid uncontrolled rewrites while still treating hard restructures as first-class when the architecture is the real problem.
Use it when you want Codex to:
- clarify an unclear cleanup or refactor goal before touching code
- map the current repository shape before planning changes
- trace a workflow or command path and find sequence, ownership, or failure-mode issues
- explain the real impact of a bug, behavior, or change through concrete code-grounded scenarios
- generate or review docs against the code
- review an area for overengineering, duplicated parallel flows, or complexity that no longer earns its place
- split an overloaded file into nearby owned files
- reduce local cognitive complexity in a source file
- regroup related files into a more cohesive local feature slice
- run a larger cleanup/refactor flow with artifact-backed resume
Refactors often fail because the agent starts moving code before it understands the problem, the current boundaries, or the behavior that must stay fixed. Clean Flow gives Codex a practical operating system for that work:
- Problem first: unclear requests are framed before implementation.
- Repository aware: architecture and path evidence are captured from the actual codebase.
- Domain-led: architecture reviews start from product workflows, ownership, and external boundaries before current folders.
- Clean target first: recommendations optimize for the cleanest evidence-backed structure, not the easiest low-impact workaround.
- Low ceremony: boundaries, abstractions, and layers are justified by real ownership, integration, or risk.
- Migration-safe: execution phases require a credible safety net before structural edits and preserve behavior unless a behavior change is explicit.
- Resumable: longer flows store durable state in
.cflow/artifacts. - Scoped: local cleanup, file splitting, cohesion work, and broad refactors use different entrypoints.
Install or update Clean Flow globally for Codex:
Fetch and follow instructions from https://raw.githubusercontent.com/gualask/clean-flow/refs/heads/main/install/codex/GLOBAL.md and sync Cflow globally.
Or install/update it only in the current repository:
Fetch and follow instructions from https://raw.githubusercontent.com/gualask/clean-flow/refs/heads/main/install/codex/LOCAL.md and sync Cflow in the current repository only.
CLI alternatives:
node ./bin/cflow-skills.mjs install /path/to/repo
node ./bin/cflow-skills.mjs install --global
node ./bin/cflow-skills.mjs install /path/to/repo --dry-runThe installer materializes packaged skills, vendors shared authoring files into the consuming skill directories, and syncs packaged Codex custom agents.
Global install writes to $CODEX_HOME/skills and $CODEX_HOME/agents, or falls back to ~/.codex/skills and ~/.codex/agents.
After installation, ask Codex to use one of the public entrypoints below. For most cleanup or refactor work, start with:
Use cf-start to assess this cleanup/refactor and recommend the next step.
Uninstall
Remove only Clean Flow-owned skill directories and Codex custom agents:
node ./bin/cflow-skills.mjs remove /path/to/repo
node ./bin/cflow-skills.mjs remove --globalCodex prompt shortcuts:
Fetch and follow instructions from https://raw.githubusercontent.com/gualask/clean-flow/refs/heads/main/install/codex/GLOBAL.md and uninstall Cflow globally.
Fetch and follow instructions from https://raw.githubusercontent.com/gualask/clean-flow/refs/heads/main/install/codex/LOCAL.md and uninstall Cflow from the current repository only.
The main workflow controller for cleanup and refactor work, including hard-restructure planning and behavior-preserving migration units. Use it for fresh assessment, planning, bounded execution, review, verification, and resume.
It can create and maintain:
.cflow/architecture.md.cflow/refactor-brief.md
Helps frame and solve difficult problems before implementation or refactor assessment.
Invoke it explicitly when the problem is hard, ambiguous, or needs careful reasoning before code changes.
Reviews an area for overengineering, file sprawl, duplicated or parallel near-identical flows, and accidental complexity. Use it when you are unsure whether the current behavior, interface contracts, boundaries, or abstractions are worth their code cost, or whether similar flows should be consolidated behind one abstraction.
Builds or refreshes .cflow/architecture.md from repository evidence.
Use it when Codex needs a current map of the codebase before making planning decisions.
Reconstructs and audits one concrete workflow, command path, install path, or refactor path. Use it to find ordering problems, missing states, unclear ownership, weak failure handling, resume gaps, or test gaps.
Explains what really happens in a concrete scenario, grounded in the code. Use it to frame a bug, compare similar flows, or validate the practical impact of a recent implementation.
Finds or reduces local cognitive complexity in up to three source files. Use it for overloaded functions, deep nesting, hard-to-scan branching, or local readability pressure.
Evaluates or performs a behavior-preserving split of one source file into nearby owned files. Use it when a file has grown past its natural responsibilities.
Evaluates or performs local regrouping of already-related files. Use it when a workflow or feature is scattered across folders and navigation cost is the problem.
Generates or reviews Markdown docs, READMEs, and design notes against the code. Use it when docs may be stale, too verbose, duplicated, or structurally out of sync.
Installing the pack only syncs materialized skills and Codex custom agents.
It does not create .cflow/ immediately.
Skills that own durable artifacts create .cflow/ only when they need it.
When .cflow/ is created for the first time, Clean Flow also adds it to .gitignore.
Use cf-start when you want the normal cleanup/refactor lifecycle:
- assess the repository pressure
- choose a safe path
- plan one bounded unit
- lock behavior with an appropriate safety net
- execute
- review and verify
- resume from
.cflow/refactor-brief.mdwhen needed
For direct local work, use cf-cognitive, cf-split, or cf-cohesion instead.
For overengineering or "are these files necessary?" reviews, use cf-simplify.
For standalone repository mapping, use cf-architecture.
For path reconstruction or workflow audit, use cf-trace.