codex-ultracode-effort

Korean README

Repository: https://github.com/quantsquirrel/codex-ultracode-effort

codex-ultracode-effort is an experimental Codex plugin and local runtime wrapper for working in an ultracode-style operating mode. It is an operational approximation for Codex: a way to structure planning, parallel work lanes, evidence collection, and adversarial verification around native Codex subagents.

This repository does not claim to clone Claude Code's internal ultracode runtime. It focuses on the observable workflow patterns that make high-effort agent work safer and easier to review.

• Split work into safe parallel lanes.
• Freeze the outcome, context, and acceptance criteria before implementation.
• Prevent multiple workers in the same wave from editing the same files.
• Add a researcher or evidence lane when official documentation or external dependencies matter.
• Keep adversarial verification separate from implementation.
• Require a final synthesis with changed files, command evidence, unresolved risks, merge order, and a done/not-done verdict.

In short, this is not a mode for simply calling more agents. It is a mode for structuring safe parallel effort.

Why This Exists

Launching many agents without structure usually creates three problems.

1. Workers edit the same files at the same time.
2. Workers over-trust their own results.
3. The final integrator cannot tell which claims are supported by evidence.

codex-ultracode-effort reduces those risks through prompt discipline and execution conventions. The important unit is not the agent count; it is the workflow shape.

restate outcome
-> context snapshot
-> acceptance criteria
-> lane ownership
-> dependency waves
-> implementation/research/review lanes
-> evidence-backed synthesis
-> done/not-done verdict

What This Repository Provides

This repository is packaged as a Codex marketplace plugin.

.
├── .agents/plugins/marketplace.json
└── plugins/codex-ultracode-effort/
    ├── .codex-plugin/plugin.json
    ├── skills/ultracode/SKILL.md
    └── scripts/
        ├── ultracode-run
        └── ultracode-doctor

It has two main components.

1. Codex skill: $ultracode

   The skill describes how to choose and run an ultracode-style workflow inside Codex. Small tasks stay direct. Wider tasks can be split into native Codex subagent lanes with explicit ownership and verification.

2. Local runtime scripts

   ultracode-run generates prompts for the plan, execute, review, and native modes. ultracode-doctor checks the plugin files and local codex and git state.

Installation

Codex CLI must support Git marketplace sources.

codex plugin marketplace add quantsquirrel/codex-ultracode-effort --ref main
codex plugin add codex-ultracode-effort@codex-ultracode-effort

Verify the installed plugin.

codex plugin list | rg 'codex-ultracode-effort'

In a new Codex thread, you can invoke the skill directly.

$ultracode plan this work as safe parallel lanes.

You can also trigger it with natural language.

Use ultracode mode to split this refactor into parallel lanes.

Local Usage

From a checkout of this repository:

plugins/codex-ultracode-effort/scripts/ultracode-doctor
plugins/codex-ultracode-effort/scripts/ultracode-run --mode plan --task "Refactor auth module"
plugins/codex-ultracode-effort/scripts/ultracode-run --mode execute --task "Refactor auth module"
plugins/codex-ultracode-effort/scripts/ultracode-run --mode review --task "Review reports/ultracode-reproduction/REPORT.md"

--mode native prints an operating prompt for Codex native subagents.

plugins/codex-ultracode-effort/scripts/ultracode-run --mode native --task "Plan a repo-wide migration"

Script Modes

ultracode-run supports four modes.

• plan: generate an intake and lane-planning prompt.
• execute: generate an implementation-oriented native Codex workflow prompt.
• review: generate a review and verification prompt.
• native: generate a Codex native-subagent operating prompt.

Operating Modes

Direct Mode

Use direct mode when the task is small or naturally sequential. There is no value in spawning extra agents for a narrow change.

Examples:

• Fix a small bug in one file.
• Add one clear CLI option.
• Clean up a single document.

Native ultracode mode

Native ultracode mode uses Codex subagents inside the current Codex session.

Recommended lanes:

• Planner lane: write the outcome, constraints, acceptance criteria, and lane plan.
• Researcher/evidence lane: check official documentation or external dependencies.
• Worker lanes: perform non-conflicting file or module work.
• Adversarial verifier lane: test worker claims, find missing coverage, and check for conflicts.

This mode is fast and lightweight, but it does not provide durable tmux, worktree, or long-running lifecycle management.

Prompt-Only Runtime

The runtime is prompt-only. It does not launch external worker processes.

ultracode-run --mode execute prints an implementation prompt by default.

plugins/codex-ultracode-effort/scripts/ultracode-run --mode execute --task "Migrate API client"

Example output:

ULTRACODE-style Codex workflow.

Use that prompt in the current Codex session and spawn native subagents only when the lane boundaries are clear. --run is intentionally refused so the script cannot start an external worker runtime.

plugins/codex-ultracode-effort/scripts/ultracode-run --mode execute --run --task "Migrate API client"

Core Prompt Principles

The executor prompt enforces the following rules.

1. Maximize Safe Parallelism

The goal is not to maximize the number of agents. The goal is to parallelize only work that is safe to parallelize.

Safe parallel work requires:

• Separate file or module ownership.
• No worker overwrites another worker's result.
• Shared files can be serialized into a later wave.
• Each lane can provide its own verification command.

2. Intake Gate Before Editing

Before editing, the workflow freezes:

• task outcome
• constraints
• unknowns
• likely touchpoints
• external docs or dependencies
• acceptance criteria
• done and fail conditions

Skipping this gate increases the chance that workers execute different versions of the task.

3. File and Module Ownership

Each lane must declare its boundary before work starts.

Good:

Lane A: scripts/ultracode-run option parsing and output generation only
Lane B: skills/ultracode/SKILL.md documentation only
Lane C: validation and security review only

Bad:

Worker 1: fix stuff
Worker 2: improve everything
Worker 3: review and edit whatever is needed

4. Dependency Waves

If multiple workers need to touch the same file, they should not run in the same wave.

Wave 1: independent module edits
Wave 2: shared config update
Wave 3: integration verification

5. Evidence Lanes

When framework versions, official documentation, or external API behavior affect correctness, assign a researcher or evidence lane.

That lane provides evidence. It does not implement the change.

6. Adversarial Verification

The workflow does not trust worker self-reports by default.

The verification lane checks:

• whether changed files stayed within lane boundaries
• whether tests and diagnostics actually prove the requirements
• whether any claim is unsupported
• whether shared-file conflicts happened inside the same wave
• whether the final state is done or not done

Safety Notes

ultracode-run prints prompts by default and does not execute external worker runtimes.

plugins/codex-ultracode-effort/scripts/ultracode-run --mode execute --task "..."

External execution is intentionally unavailable.

plugins/codex-ultracode-effort/scripts/ultracode-run --mode execute --run --task "..."

The script includes the following defenses:

• --agents is limited to numbers from 0 through 20.
• --role allows only letters, digits, underscore, dot, and hyphen.
• --run exits before launching anything.

Verification

Run these checks locally.

python3 /path/to/plugin-creator/scripts/validate_plugin.py plugins/codex-ultracode-effort
python3 /path/to/skill-creator/scripts/quick_validate.py plugins/codex-ultracode-effort/skills/ultracode
sh -n plugins/codex-ultracode-effort/scripts/ultracode-run
sh -n plugins/codex-ultracode-effort/scripts/ultracode-doctor
plugins/codex-ultracode-effort/scripts/ultracode-doctor

Simple injection regression checks:

plugins/codex-ultracode-effort/scripts/ultracode-run --agents '5; printf PWNED' --task smoke
plugins/codex-ultracode-effort/scripts/ultracode-run --role 'executor; printf PWNED' --task smoke

Both commands should fail with exit code 2.

Out of Scope

This repository does not currently implement:

• a clone of Claude Code's internal ultracode runtime
• a full orchestrator that automatically merges real worker results
• a benchmark harness that collects external worker artifacts
• mixed Codex/Claude team map automation

These capabilities can be added later as ultracode-run subcommands or adjacent workflow tooling.

License

MIT