codex-spark

Codex Spark

You are the calling parent, whether Claude Code or Codex. Prepare the task and invoke the shared runner; do not perform the delegated work yourself or call another delegation plugin. The worker must not invoke this skill recursively.

Choose the mode

• usage: run python3 <skill-directory>/scripts/run.py usage directly and report the live result in Korean. Do not partition work, launch a Spark worker, or inspect the repository. Show available Spark model IDs and the returned limitId/limitName buckets, window duration, used/remaining percentage, reset time in the user's timezone, and lookup time. Preserve null/missing as unknown. Never substitute ordinary Codex limits, infer independent per-model quotas or shared membership, or promise a model is runnable from catalog visibility alone. If a Spark bucket is absent, report that its quota was not provided. Do not consume reset credits, modify accounts, read auth files, or repeat the lookup automatically. After reporting, stop; the remaining workflow is for test/review only.
• review: read-only review, without writing files or running tests. With no extra prompt, review every tracked unstaged change plus non-ignored untracked files in the current Git repository. Exclude staged-only changes. An extra prompt narrows this scope; it does not authorize edits or silently expand to the entire branch.
• test: select, write or update, and execute the minimum useful tests for the current task. Do not make the worker fix production code. Do not test unsettled presentation details.
• When no mode is given, use review.

Partition before dispatch (required)

The parent MUST inspect the change inventory and partition the work before launching Spark. Never send a broad repository-wide assignment to one worker. Partition by behavior, ownership, and dependency boundaries, not equal file counts. A small, cohesive change can remain one task; a large file may need separate symbol or scenario tasks. Aim for one independently understandable question per worker.

For review, first run scripts/run.py review --inventory --cwd /absolute/repository. With no narrowing prompt, every listed change must be covered by some task, but size tasks by cohesion (see below), never by splitting the inventory evenly. Keep a coverage ledger of files/change regions, task IDs, and outcomes. Read related callers when defining boundaries. If a worker cannot finish its scope, split the remaining work again; do not count it as reviewed.

The concurrency cap is three workers at once — a maximum, not a target. It does NOT mean split the inventory into three buckets, and you must never divide the total change set by the worker count. Size each partition by the narrowest independently-reviewable unit — one behavior, one symbol cluster, one scenario — so each worker holds a tight scope and one codex sees far less than a third of the inventory. This usually yields more partitions than three; dispatch them in waves of at most three, running dependent work sequentially, using the host's process/task tools. For test tasks, allocate explicit write_targets; workers must not edit the same test/helper file concurrently. The parent must not edit files being tested while that worker is running. Do not create dummy partitions for an already small task.

Handoff

For each worker, prepare a JSON handoff in a temporary file using the available file-editing tool, with the following fields. Populate it from the current conversation and files; do not require the user to repeat information already available. Ask only when the intended behavior or task scope is genuinely ambiguous.

{
  "task_id": "auth-callback-review",
  "intent": "Why this change is being made",
  "progress": "What is implemented, pending, or known to fail",
  "targets": ["exact/file/path/relative/to/cwd"],
  "write_targets": [],
  "expected_behavior": ["Observable behavior and important regression cases"],
  "exclusions": ["Unrelated changes and intentional limitations"],
  "commands": ["Existing narrow test commands, if known"]
}

Every worker needs a task ID, intent, progress, and exact target files, not a repository root or directory. In review mode, use repository-relative targets from the inventory, and --cwd the repository root. The runner rejects targets outside the current unstaged/untracked inventory. expected_behavior is required for tests and optional for review. write_targets is required for tests and lists exact test/helper paths that the worker may create or modify. Review must have no write targets. The runner validates the boundary; the role instructions constrain writes inside the sandbox, but this is not a per-file OS access-control list.

The default review remains the entire unstaged set across all workers, not just the last conversation topic. Pass any user-supplied narrowing focus as --prompt and assign only the matching change regions. Explain omissions explicitly in the final coverage report.

Execute

Resolve scripts/run.py relative to this skill's directory. The local installation is ~/.agents/skills/codex-spark. Python 3.11+ and a signed-in Codex CLI are required.

python3 ~/.agents/skills/codex-spark/scripts/run.py review --cwd /absolute/repository --inventory
python3 ~/.agents/skills/codex-spark/scripts/run.py review --cwd /absolute/repository --handoff /absolute/review-chunk.json
python3 ~/.agents/skills/codex-spark/scripts/run.py review --cwd /absolute/repository --handoff /absolute/review-chunk.json --prompt 'Review only the authentication changes'
python3 ~/.agents/skills/codex-spark/scripts/run.py test --cwd /absolute/module --handoff /absolute/handoff.json

Quote arguments safely; never interpolate handoff content into shell code. Prefer stdin via --handoff - when the tool supports passing stdin separately.

The runner reads config/test_manager.toml or config/reviewer.toml, queries Codex App Server's model catalog, and chooses a visible Spark model. With multiple versioned candidates it selects the highest numeric GPT/Spark version; ambiguous model names stop the run. This is catalog-based selection, not a promise about unlisted models or remaining quota. No pinned model, API-key fallback, or non-Spark fallback is allowed.

--dry-run validates inputs, discovers the model, and prints the execution plan without starting a model turn. It does not validate model inference or run tests.

Use the host's existing process handle and poll when a worker outlives a tool call. Do not start a duplicate job while one is running. For a subsequent verification pass, pass an updated handoff to a new run.

Return the result

The parent collects every worker report, verifies its claims against the actual source/diff and command output, deduplicates findings, and reconciles the coverage ledger before reporting. For tests, check that assertions exercise the intended branch rather than failing earlier for unrelated reasons. Do not claim a complete review if any partition failed or remains unread. Keep finding locations, actual commands and outcomes, and unverified scope. A successful CLI exit means the agent finished, not that tests passed. Missing output, authentication errors, unavailable Spark, timeout, or an incomplete run are BLOCKED, not a clean review. Review findings do not authorize the parent to apply fixes unless the user has requested them.

For test failures in production code, the parent owns the fix and requests another test pass. Do not silently replace Spark with the parent model. Remove only temporary handoff files owned by this invocation when no longer needed.