{"slug": "refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using", "title": "refactor-like-hermes — Refactor any software project with Codex subagents, using lessons from the Hermes refactor.", "summary": "A developer released refactor-like-hermes, a Codex subagent workflow for refactoring large software projects, distilled from lessons learned during Nous Research's Hermes Agent refactor. The approach treats refactoring as a controlled program of baseline measurement, non-overlapping ownership groups, isolated worktrees, and contract preservation, with bounded subagents assigned to cohesive subsystems rather than arbitrary line ranges. It emphasizes freezing a baseline commit and metrics before edits and keeping feature work out of the refactor.", "body_md": "| name | refactor-like-hermes | \n|---|---|\n| description | Refactor any software project with Codex subagents using lessons from the Hermes refactor. Use for major simplification, god-file decomposition, helper consolidation, or resuming a multi-agent refactor; scale the workflow to the target repository. | \n\nApply the operating lessons from Nous Research’s Hermes Agent refactor to any repository. Hermes is the source case study, not the target product: inspect the actual target project, its contracts, instructions, tools, and test suite.\n\nRun a large refactor as a controlled program of measurement, bounded edits, contract preservation, and integration. The target is a codebase that is easier to change without changing its supported behavior.\n\nUse the host's collaboration tools to spawn bounded subagents for independent work and collect their results in this task. Preserve the configured model, reasoning, permissions, and user constraints. A skill invocation does not authorize new user-owned tasks, a Hermes installation, or changing global Codex settings. If delegation is unavailable, carry out independent preparation and report the missing capability; label any serial fallback rather than claiming a subagent run.\n\n1. Resolve the repository, branch, working-tree state, governing `AGENTS.md` files, test commands, language/runtime, and the actual Codex/subagent capabilities available in this session. Read the relevant Codex CLI or app-server guidance when you need to launch external Codex workers; use live`--help` output for flags. Use the target project’s own language and build documentation for implementation details.\n2. Define the refactor in observable terms: target modules/files, a structural acceptance criterion or useful quantitative goal, behavior that must remain unchanged, allowed API migrations, and a done condition. Preserve a user-specified target; otherwise derive the target from actual problems. A percentage reduction is not mandatory. Count production, tests, generated code, and documentation separately so deleting tests or rationale cannot satisfy a source-reduction target. Keep feature work out of the refactor unless explicitly required.\n3. Freeze a baseline before edits. Record the commit, clean/dirty state, source metrics, public names and import paths, CLI/API schemas, representative help output, focused tests, and known pre-existing failures. If relevant user changes are uncommitted, preserve a scoped patch or snapshot without committing unrelated work, and identify the exact candidate tree every worker must use. Measure full-suite, import/runtime, resource, and navigation metrics when they affect the target or a stated risk; otherwise record why they are out of scope. Re-run a failing check on unchanged baseline code before attributing it to a worker.\n\nCompletion: a future integrator can identify and reconstruct the exact baseline, scope, contracts, selected metrics, and pre-existing failures without asking the user.\n\n1. Measure first, then divide work into non-overlapping ownership groups. Partition by cohesive subsystem or file family, not arbitrary line ranges. Give each group a small enough surface that a worker can understand its callers and contracts.\n2. Prepare a written assignment for every group. Include the candidate baseline, owned paths, nearby instructions, interfaces to preserve, allowed new module boundaries, required focused checks, checkpoint requirement, and explicit out-of-scope paths. Tell workers to inspect callers and public exports before deleting or moving anything. Schedule dependencies in waves; assign shared helpers, lockfiles, generated registries, and cross-cutting edits to one owner. A worktree prevents overwrites, not semantic integration conflicts.\n3. Use isolated worktrees or equivalent disposable checkouts for concurrent writers. Native Codex subagents may initially share the parent filesystem, so put the assigned absolute checkout path in every brief and require the worker to verify repository root, branch, baseline, and working directory before editing. Never allow two workers to edit the same owned path. Keep worker branches, briefs, reports, logs, and commits durable so a coordinator can resume after a provider, process, or host failure.\n4. Bound concurrency and shared resources when the selected Codex surface exposes those controls. Set a worker/depth limit, monitor CPU/RAM/process/file-descriptor use for resource-sensitive runs, reuse multi-root language servers where supported, and stop or reap only workers owned by this orchestration. Prefer fewer coherent workers over a larger fan-out that overloads the machine or provider.\n5. Let workers delegate only bounded subproblems. Preserve the ownership tree and require nested workers to return evidence to their parent; do not let nested delegation become an untracked second orchestrator.\n\nCompletion: every assignment has one owner, disjoint paths, a done condition, an evidence location, and a recovery path; the coordinator has a branch/commit ledger.\n\nRequire each worker to:\n\n- map the current call graph and exports before extraction;\n- preserve facade modules or compatibility shims when external imports may exist;\n- extract along semantic seams such as dispatch, streaming, lifecycle, persistence, or transport;\n- replace repeated routing with explicit tables only when ordering, fallbacks, and error behavior are preserved;\n- unify helpers only after comparing signatures, side effects, exception behavior, and call-site assumptions;\n- avoid deleting names solely because repository-local callers are absent;\n- keep rationale comments and useful docstrings; remove only duplicated or stale prose;\n- commit after each verified slice with a message that identifies the behavior boundary.\n\nHonor explicit no-commit constraints with a recoverable patch and file hashes instead. For allowed checkpoints, stage only the worker's owned changes. Run checks against the assigned checkout; verify import/module resolution or build inputs so an editable installation or cache cannot silently test another tree.\n\nPrefer thin public entry points over mass import rewrites. When a public name moves, inventory old imports, plugin/extension entry points, dynamic imports, reflection, documented examples, monkeypatch seams, and packaging/module lists. Add compatibility tests or an explicit migration plan before removing the old path.\n\nCompletion: each worker report names changed paths, preserved contracts, focused checks run, commit SHA, remaining risk, and any public surface it intentionally changed.\n\n1. Integrate the smallest coherent wave first. Read worker reports and inspect representative diffs before merging; do not trust a green summary without the underlying commands and commit IDs.\n2. After each wave, run the selected structural metrics, import/compile checks, focused tests, public-surface checks, and contract comparisons. Integrate worker commits sequentially through the coordinator. Resolve conflicts against the intended contract, re-run affected checks, and start dependent workers from the new integration revision. Keep the original comparison baseline immutable even as wave starting points advance.\n3. Use a frozen baseline to classify failures. A failure is pre-existing only when the same test identity, command, failure signature, and relevant environment reproduce it on the unchanged baseline. Matching file-level counts are supporting evidence only. A changed or unmatched failure is a regression or unresolved until explained; preserve uncertain causes instead of weakening the check.\n4. Keep a compatibility ledger for affected surfaces. Choose contracts from the target project: public symbols/signatures, plugin imports, CLI output, HTTP/wire schemas, serialization, database migrations, UI interaction/accessibility, compiled ABI, packaging, or exception/cleanup semantics. Use byte comparisons for stable textual contracts; behavioral tests for semantics. Record any normalization for nondeterministic values. An export-name scan is a triage aid, not proof of compatible behavior.\n5. Run a full suite only after focused checks make the wave intelligible. Record runtime, resource, import, and integration changes; a refactor can improve lookup cost while increasing module count, import latency, or dependency cycles.\n\nCompletion: every integrated wave has a verified commit, updated metrics, a failure classification, and a readable compatibility record.\n\nIf a provider expires, a worker dies, or the coordinator stops, preserve the worktrees and commits. Start a fresh coordinator session with a handoff containing the baseline SHA, active assignments, completed commits, incomplete extractions, failing checks, resource state, and the next safe commands. Have workers inspect saved state before changing it. Never infer completion from a worker process disappearing.\n\nInspect failed-child signals while siblings run. Keep interim notices separate from terminal results, and obtain missing/truncated reports from saved artifacts before integrating. Use supported bounded waits; when workers finish, resume integration. A Codex goal or scheduler is optional and depends on user authorization and host support; do not assume Hermes `/goal` or judge controls exist. Before replacing an unresponsive worker, establish that its writer has stopped so two attempts cannot edit the same checkout.\n\nCompletion: a restart can resume from durable artifacts without replaying completed edits or losing the reason a worker stopped.\n\nRun a final review that is independent of the editing workers. Check:\n\n- public names, old import paths, plugin APIs, dynamic loading, and packaging;\n- semantic rewrites of exception suppression, context managers, ordering, retries, and cleanup;\n- dispatch-table fallthrough, default handlers, and error messages;\n- import cycles, startup/import latency, memory, process counts, and file-descriptor use;\n- new files and module ownership against the repository’s local guidance;\n- tests removed, weakened, or rewritten around still-live behavior;\n- docs and examples that still describe the old structure;\n- generated artifacts, build manifests, and release packaging.\n\nCompletion: independent review has either found and resolved issues or recorded them with evidence and ownership.\n\nCompare final metrics to the frozen baseline and label every result by scope. Use the same predefined corpus, lookup procedure, tokenizer, and distribution statistics before and after when measuring agent ergonomics; report mean, median, tail, multi-window rate, and any symbols that became costlier. Report trade-offs such as module/import growth and runtime changes beside improvements. Do not convert model spend, estimated manual labor, or a benchmark into a measured ROI claim.\n\nBefore delivery, verify the final tree, tests, compatibility checks, worker cleanup, and exact commits. Retain task-owned worktrees and logs until all writers and recovery needs end; before cleanup, prove integrated commits and preserve any required patch or evidence in the approved provenance location. Do not delete unrelated or pre-existing processes, checkouts, or files. Preserve the baseline and final evidence in the repository’s normal provenance location. Follow the repository’s delivery and review policy before a final commit, push, PR, or deployment.\n\nThe refactor is complete only when the chosen acceptance criteria are met, affected contracts and required checks pass or have explicit accepted limitations, all worker results are reconciled, and another agent can reproduce the outcome from the ledger and checkpoints. Turn verified mistakes into small project tests or local guidance updates when they prevent recurrence within the requested scope.", "url": "https://wpnews.pro/news/refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using", "canonical_source": "https://gist.github.com/coygeek/f8bf72a19a4548b79032327c2a1e8b57", "published_at": "2026-09-15 23:13:54+00:00", "updated_at": "2026-09-16 00:06:42.204418+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "large-language-models"], "entities": ["Codex", "Hermes Agent", "Nous Research", "refactor-like-hermes"], "alternates": {"html": "https://wpnews.pro/news/refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using", "markdown": "https://wpnews.pro/news/refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using.md", "text": "https://wpnews.pro/news/refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using.txt", "jsonld": "https://wpnews.pro/news/refactor-like-hermes-refactor-any-software-project-with-codex-subagents-using.jsonld"}}