/sol-luna-router

name: sol-luna-router
description: Route coding or repository-review work so GPT-5.6 Sol remains the commander and verifier while a separate GPT-5.6 Luna Max Codex CLI session performs bounded implementation or read-only investigation. Use when the user asks for Sol to direct, plan, supervise, or review Luna work; when native Sol-to-Luna spawning is unavailable or incompatible; or when a task needs auditable agent ownership, budgeted verification, live progress, timeout recovery, usage telemetry, and a Sol review loop.

Sol-Luna Router

Keep Sol responsible for decisions and final verification. Use Luna Max for one bounded implementation or read-only investigation. Use the bundled runner instead of native `spawn_agent`; current Sol and Luna releases can select different multi-agent backends.

Boundaries

• Treat the current Sol thread as commander and reviewer. Do not edit target product files from

this thread.

• Delegate concrete implementation, fixes, worker-owned tests, or bounded read-only investigation

to Luna Max.

• Fix every new and resumed worker invocation to `gpt-5.6-luna` with reasoning effort `max`.
• Allow only one write-capable Luna worker in a worktree at a time. Parallelize read-only work, or

use isolated worktrees with explicit, disjoint file ownership.

• Keep the parent approval and sandbox boundary intact. Never add bypass, full-access, force-push,

credential, or secret-handling flags.

• Stop after three failed correction cycles on the same root cause and reassess the hypothesis.
• Never claim completion from the worker summary alone. Verify from the current session.
• Do not use worker timeout as a test budget. Select a profile and give every potentially expensive

command an explicit bound before launch.

• Keep the commander thin: do not duplicate Luna's repository scan or implementation analysis;

launch one bounded worker, collect one result, and combine independent verification commands into the smallest safe check. Resume only from concrete failed evidence.

Operating Contract

• Direct actions: inspect local state, create external task prompts, run Luna within scope, and perform read-only verification.
• Escalate before: expanding ownership or permissions, using new network or credentials, destructive recovery, publishing, pushing, merging, or changing products.
• Evidence-backed pushback: cite a diff, command, repository rule, run record, or capacity failure when the requested route is unsafe or cannot satisfy done-when conditions.
• Feedback loop: use aggregate ledger evidence and correction patterns for the smallest runner, test, profile, or gotcha update; never optimize from token totals alone.

Workflow

1. Preflight

1. Confirm the target working directory and resolve its Git root. 2. Inspect dirty and untracked state without modifying it. Preserve user changes. 3. Read applicable `AGENTS.md` files and repository verification commands. 4. State the goal, constraints, allowed file ownership, done-when conditions, command budget, and verification commands. 5. If the task is ambiguous enough to change architecture or scope, clarify before delegation.

Select `implementation` for edits and focused tests (`workspace-write`, 1800s default). Select `bounded-review` for investigation (`read-only`, 900s, at most 8 commands, no full suites).

Use `bounded-review` whenever repository mutation is not the deliverable. It instructs Luna to return broader checks as `requires_commander_verification`; Sol decides whether to run them later. The runner also disables Python bytecode writes and redirects common Python, Rust, Go, Node, Ruff, and mypy caches to temporary storage for the duration of the worker.

2. Prepare the worker task

Write a temporary UTF-8 task file outside the target repository. Include only task-local context:

Role: implementation worker.
Objective: <one bounded outcome>
Target repository: <absolute path>
Allowed files: <explicit paths or one narrow subtree>
Do not touch: <user changes and out-of-scope paths>
Constraints: <applicable requirements>
Reproduction or evidence: <fresh evidence>
Command budget: <count, per-command limit, and forbidden broad suites>
Done when: <observable conditions>
Verification: <repository commands to run>
Return: root cause, changed files, commands with outcomes, and remaining risks.

Do not leak an intended patch or diagnosis when Luna must independently determine the root cause.

3. Run Luna Max

For implementation, run the bundled script with an absolute target directory and task-file path:

python3 <skill-dir>/scripts/run_luna_worker.py run \
  --cwd /absolute/path/to/repo \
  --prompt-file /absolute/path/to/task.md \
  --sandbox workspace-write

For review or diagnosis, add `--profile bounded-review` to use the budgeted read-only profile.

The script fixes new and resumed workers to `gpt-5.6-luna` with `model_reasoning_effort="max"`, disables native multi-agent tools for the worker, invokes Codex without a shell, and returns one JSON object containing `thread_id`, `final_response`, usage, profile, sandbox, duration, and repository metadata.

Every invocation also appends one privacy-safe record to `$CODEX_HOME/state/sol-luna-router/runs.jsonl` (normally under `~/.codex`). It captures the commander session ID, Luna thread ID, token usage, duration, profile, warnings or failure class, and a prompt fingerprint, but not prompt text, final response text, or raw errors. The current Codex session is detected from `CODEX_THREAD_ID`; use `--parent-session-id` only when an explicit override is required. Use `--run-log` to select another absolute ledger or `--no-run-log` for an intentional one-off opt-out. A ledger write failure is reported without discarding a successful worker result. Read [references/run-log.md](references/run-log.md) before analyzing or exporting the ledger.

Use `--allow-non-git` only when the user explicitly wants work outside a Git repo