Codex-worker-patch-loop

Codex Worker Patch Loop

Use this when you want Codex to act as a specialist worker that directly edits files, while the main session stays as orchestrator/reviewer.

Best for:

• refining skills, workflows, policies, and route definitions
• applying a batch of structured documentation/process edits
• tightening a canonical file over several review/patch cycles
• using Codex for execution while Hermes keeps orchestration, verification, and synthesis

When to use

Choose this pattern when:

• the work is non-trivial but file-local or small-batch
• you want Codex to make edits directly, not just give advice
• you already know the target file(s)
• you want an external worker to improve wording/structure while preserving orchestration discipline

Do not use this pattern when:

• the task needs user interaction mid-stream
• the file ownership is unclear
• many files have overlapping edits that require central conflict resolution first

Core pattern

1. Orchestrate in the main session

• identify the exact target skill/file
• inspect current content first
• define the specific improvement scope
• keep the worker task self-contained

2. Delegate to Codex as worker Use delegate_task with acp_command: Codex and tell Codex to:

• patch the target file directly
• avoid asking questions
• preserve current route/style
• return a concise change summary

Pass context that includes:

• exact skill/file path
• current conventions already present
• the exact sections to strengthen
• constraints such as “targeted edits only” and “do not bloat”

3. Prefer focused worker goals Good worker goals:

• patch Step 4 with reviewer schema, synthesis, and re-review rules
• patch Step 5 with approval normalization and label discipline
• strengthen entry gate and verification-first closure path

Avoid vague goals like:

• improve this skill
• make it better

4. Verify from the main session after Codex returns Always inspect the file after the worker completes. Check for:

• intended sections actually present
• no accidental regressions in neighboring sections
• version/frontmatter updated if appropriate
• canonical names preserved
• wording consistent with the existing route style

Use skill_view and search_files to verify exact inserted section titles/phrases.

5. Iterate in small loops If more improvements are needed:

• send Codex back for the next bounded patch
• do not bundle too many conceptual changes into one worker pass
• keep a verify step between worker passes

Recommended delegate_task template

Use a worker task shaped like this:

• Goal: Patch the canonical skill <name> to strengthen <specific sections>. Edit the file directly. Keep current style. Do not ask questions. Return a concise summary of exact changes made.

• Context: Include:

  • exact file/skill name
  • current sections already present
  • desired additions
  • constraints like:
    • preserve canonical route style
    • targeted edits only
    • avoid bloating too much

Good verification pattern

After Codex returns:

1. skill_view(name) to inspect the current full skill
2. search_files(pattern=...) for the newly required section names
3. confirm version bump and description change if expected
4. synthesize the worker result into next-step recommendations

What worked well in practice

This pattern worked well for canonical route refinement by having Codex directly patch:

• planning-route Step 4 and Step 5 gates
• execution-route early entry and verification-first checks
• delegation structure for agent-team packaging
• middle/late execution gates (TDD loop, targeted validation, adversarial review, commit/push, unified closeout)
• cross-route consistency cleanup between paired canonical skills
• creation of compact checklist companion skills derived from long canonical routes

Useful section-level additions Codex handled well:

• decision gates
• GitHub authority split
• zero-contention rules
• workstream split contracts
• reviewer output schemas
• verification-first closure checks
• prompt-pack vocabulary alignment
• closeout/result vocabulary alignment
• compact checklist extraction from canonical skills

Paired-route pattern

For two closely related canonical files, use Codex in one of these ways:

• one worker for planning route, one worker for execution route in parallel
• then a follow-up Codex worker for cross-route consistency audit

This worked especially well for:

• gh-work-planning
• gh-work-execution
• their companion checklist skills

Companion-checklist extraction pattern

After a canonical route becomes comprehensive, ask Codex to create a short checklist companion skill rather than over-compressing the main skill. Use this when:

• the canonical skill is now the source of truth
• users need a live-execution checklist
• you want fast operational use without weakening the canonical route

Checklist companion rules:

• explicitly state the canonical skill remains authoritative
• keep the checklist action-oriented and short
• include trigger notes and one-screen live sequence
• do not duplicate the full decision framework

Interrupted-worker recovery pattern

If a Codex delegate task is interrupted mid-audit or mid-review:

• launch a continuation delegate task with explicit "continue the interrupted audit" context
• keep the target files and audit scope the same
• ask for direct patches only where real inconsistencies exist

This worked well for a cross-route consistency pass after an interrupted audit.

Pitfalls

• Do not assume the worker edited the right file without verification.
• Do not skip reading the current file first; give Codex concrete context.
• Do not ask Codex for broad “improvements” without explicit target sections.
• Do not let the worker own final synthesis; keep that in the main session.
• If a bulk patch fails, break the next worker request into smaller targeted edits.

Decision rule

Use Codex as worker when:

• execution quality matters more than keeping all edits in the main context
• the task is patchable with clear scope
• you want the main session to remain the orchestrator and verifier

Keep Hermes as orchestrator for:

• deciding what to change next
• verifying edits
• reconciling multiple worker passes
• reporting the final state to the user