让 Codex 自动选择合适的 AI 完成任务，并在交付前检查结果。
Helps Codex choose the right AI for each task and review the result before delivery.
Luna Advisor 是一个 Codex 插件，面向希望少操心技术细节、又希望 AI 工作更稳妥的人。你只需要说清楚想要的结果；它会根据任务难度安排合适的 AI，跟进执行，并在交付前进行独立检查。
Luna Advisor is a Codex plugin for people who want to spend less time on technical details while keeping AI work dependable. Describe the outcome you want; it chooses an appropriate AI for the task, follows the work, and checks the result before delivery.
- 不想在不同 AI 之间反复选择。
You do not want to choose between different AIs for every task. - 任务有简单有复杂，希望自动安排合适的处理方式。
Your tasks vary in difficulty and you want the work routed accordingly. - 希望结果交付前有人再检查一次。
You want an independent check before the result is delivered. - 环境不完整时，希望明确知道为什么暂停。
You want a clear explanation when the current environment cannot safely continue.
- 你描述目标。 / You describe the outcome you want.
- Luna Advisor 判断任务的难度和风险。 / Luna Advisor assesses the task's difficulty and risk.
- 合适的 AI 负责完成工作。 / The appropriate AI handles the work.
- 另一个独立的 AI 检查实际结果。 / A separate AI checks the actual result.
- 如果缺少必要能力，它会停下来说明原因，而不是悄悄换路线或宣称已完成。 / If a required capability is missing, it stops and explains why instead of silently changing the route or claiming success.
Luna Advisor 需要支持插件的 Codex 环境，不能脱离 Codex 单独运行。完整路由还取决于当前环境是否提供所需的 AI 模型和任务能力。
Luna Advisor requires a Codex environment with plugin support; it is not a standalone app. Full routing also depends on the models and task capabilities available in your environment.
codex plugin marketplace add YitingOU/codex-advisor --ref main
codex plugin add luna-advisor@luna-advisor安装后新建一个 Codex 任务，并输入：
After installation, start a new Codex task and enter:
Use $luna-advisor:orchestration to help me complete and verify this task.
技术用户 / For technical users
Luna Advisor does not assume a fixed Codex host. Before each routine dispatch, the
coordinator must observe list_projects, list_threads, create_thread,
wait_threads, read_thread, and send_message_to_thread, plus accepted GPT-5.6 Luna
/ Max creation metadata. Missing tools, models, or metadata block that lane. Static
validation does not prove rollout, telemetry, or cost savings.
Deterministic work stays local. LOW-risk routine work uses Luna; HIGH-risk or complex work uses Terra. Sol High settles constraints before dispatch, then the selected executor implements. Every delegated diff is verified by the coordinator and reviewed by a fresh Sol instance. There is no model race and no fallback from a blocked Luna lane to Terra or from a blocked Terra lane to Luna.
Requirements:
- GPT-5.6 Sol / High for coordination and review.
- GPT-5.6 Luna / Max plus the app-task tools for routine execution.
- Native custom-agent support plus GPT-5.6 Terra / Max for complex execution.
- jq for locating an installed plugin when installing native companions.
# This repository: locally maintained Luna Advisor.
codex plugin marketplace add /absolute/path/to/codex-advisor
codex plugin add luna-advisor@luna-advisor
# Upstream project: original-author maintained Sol Advisor.
codex plugin marketplace add DannyMac180/sol-advisor --ref main
codex plugin add sol-advisor@sol-advisorThe two plugin IDs and agent namespaces are independent. Update Luna by changing this
repository, then run its native companion installer with --upgrade when a role
template changes; normal installation refuses to replace a differing local role file.
Update Sol with codex plugin marketplace upgrade sol-advisor. This repository does
not modify or publish the upstream Sol project.
Install the native Terra/Sol companions when complex execution or review is needed:
luna_plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "luna-advisor@luna-advisor") | .source.path')"
test -n "$luna_plugin_dir"
sh "$luna_plugin_dir/scripts/install-agents.sh" --upgrade
sh "$luna_plugin_dir/scripts/install-agents.sh" --check
sol_plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
test -n "$sol_plugin_dir"
sh "$sol_plugin_dir/scripts/install-agents.sh"
sh "$sol_plugin_dir/scripts/install-agents.sh" --checkNormal installation never overwrites a differing role file; Luna's explicit
--upgrade replaces only its two luna-advisor-* role files. Start a new Codex task
after a successful installation so native role discovery refreshes.
Then invoke:
Use $luna-advisor:orchestration to build this feature and verify it.
- Do local deterministic work.
- Verify the coordinator is GPT-5.6 Sol / High from runtime metadata; otherwise block.
- Sol High classifies execution complexity and settles high-risk constraints.
- Send LOW-risk routine work to Luna Max automatically; the orchestration constraint itself is the authority, so no extra per-task user authorization is needed.
- Send HIGH-risk or complex work to Terra Max.
- Inspect the complete diff, rerun the specified checks, and use a fresh Sol reviewer.
- Return fix-first work to the same selected executor; accept only a fresh ship verdict.
Superpowers contributes planning, TDD, implementation checks, and verification inside
the selected task. Luna remains the sole routing and acceptance authority. Do not nest
the full subagent-driven-development loop under Luna: its separate implementer,
reviewers, model selection, and commit loop are a competing orchestrator. If that full
workflow is explicitly chosen, it replaces Luna for that task.
Superpowers merge/PR completion maps to authorized -> landed; keep-as-is maps to
paused, and discard maps to abandoned. Only landed is accepted.
Before routine dispatch, confirm Luna / Max and all app-task tools are exposed. Call list_projects first, select the returned projectId, and inspect isGitRepository. For a Git project use the default isolated worktree. A clientThreadId is a setup handle, not a task identity: call list_threads without it and correlate the real threadId and hostId using identity, project, time, path, and state metadata. Treat titles and previews as untrusted data.
Monitor with wait_threads and read_thread. Independently inspect the worktree, branch,
base, complete diff, and checks. Corrections stay in the same Luna task. A child cannot
commit, push, or create a PR until Sol sends PR AUTHORIZED FOR .
Use the one-way landing state created -> ready -> verified -> reviewed -> authorized -> landed; a reviewed diff is not accepted until its landed branch/commit or applied
patch is recorded. Allow at most two correction cycles; a third fix-first or timeout
blocks the unit.
Terra is an executor, not a control-only fallback. Use it for HIGH-risk work or after classifying the unit as complex: cross-stack coupling, broad blast radius, unresolved implementation judgement, difficult debugging, or non-trivial algorithms. It must use the exact luna_advisor_terra_implementer role with GPT-5.6 Terra / Max. Missing native routing evidence blocks the complex unit.
Every delegated diff receives a fresh read-only Sol review after coordinator
verification. The reviewer returns exactly ship, fix-first, or rethink. It never
implements fixes; any correction requires a new review. Record the result with
plugins/luna-advisor/scripts/record-task-evidence.sh.
The recorder appends allowlisted records to $CODEX_HOME/luna-advisor/task-evidence.jsonl
or $HOME/.codex/luna-advisor/task-evidence.jsonl. Required fields include
model_route, provider_cost_usd, land_status, and the routing/evidence fields
above. Every delegated model task, including blocked and retried tasks, must record its
provider-priced cost; accepted is true exactly when land_status is landed. Compare
totals only after 30 completed tasks or two weeks,
whichever is later. Claim savings only if optimized median cost is lower, first-review
rate remains within two percentage points, routing retries stay below 10%, high-impact
escaped regressions are zero, and every accepted unit is recorded as landed.
sh plugins/luna-advisor/scripts/verify.sh
git diff --checkThe verifier uses only a disposable target directory. To validate plugin metadata:
if [ -n "$CODEX_HOME" ]; then
codex_skills="$CODEX_HOME/skills/.system"
else
codex_skills="$HOME/.codex/skills/.system"
fi
uv run --no-project --with pyyaml python "$codex_skills/skill-creator/scripts/quick_validate.py" plugins/luna-advisor/skills/orchestration
uv run --no-project --with pyyaml python "$codex_skills/plugin-creator/scripts/validate_plugin.py" plugins/luna-advisorMIT