本页保存的是公开项目资料快照，阅读过程不需要连接 GitHub。

Sol Advisor

Sol runs the show. Luna handles routine implementation, Terra takes the harder builds, and a fresh Sol review with a requested read-only profile stands between the diff and done.

Sol Advisor is a Codex-native architect workflow for capability-routed software delivery. The primary session stays focused on requirements, architecture, specs, and verification while native Codex custom-agent threads handle implementation and review.

Go deeper

I write Attention Heads — deep, evidence-backed writing on AI, cognition, and agentic engineering. The Agentic Engineering Field Notes series is where I publish practical advice on the craft of using AI. Subscribe to get new posts to your inbox.

Lane	Native agent type	Pinned profile	Use it for
Orchestrator	Primary session	GPT-5.6 Sol / High	Requirements, architecture, decomposition, routing, and acceptance
Routine implementation	sol_advisor_luna_implementer	GPT-5.6 Luna / Max	Mechanical, repeatable, fully specified work
Harder implementation	sol_advisor_terra_implementer	GPT-5.6 Terra / Max	Context-heavy, higher-risk, or wider-blast-radius work
Final review	sol_advisor_sol_reviewer	GPT-5.6 Sol / High / requests read-only	Fresh review of the actual diff and verification evidence

The final review is context-independent, not model-family-independent: Sol reviews Sol’s orchestration with a fresh context. That catches conversational assumptions, but it is not cross-vendor review.

Install from GitHub

Requirements:

• A current Codex CLI or ChatGPT desktop app with plugins, native subagents, and custom agents enabled.
• Access to GPT-5.6 Sol, Terra, and Luna at the required reasoning levels.
• jq, which the companion-install lookup uses to locate the installed plugin package.

Add the GitHub repository as a Codex marketplace, then install the plugin:

codex plugin marketplace add DannyMac180/sol-advisor --ref main
codex plugin add sol-advisor@sol-advisor

Install the companion custom agents

Plugin installation does not automatically install custom-agent files. That is intentional: the files are user-owned role pins, and the installer must never overwrite a different local role silently. Install the companion templates separately:

plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
test -n "$plugin_dir"
test -d "$plugin_dir"
sh "$plugin_dir/scripts/install-agents.sh"
sh "$plugin_dir/scripts/install-agents.sh" --check

Without an explicit target, the installer uses the existing CODEX_HOME value when one is already set, otherwise the user’s default Codex agents directory. It does not invoke Codex, edit config.toml, or overwrite a differing agent file. It only installs a missing template and then verifies every installed copy byte-for-byte.

Start a new Codex task after the check passes. Native agent types are discovered at task creation, so an existing task may not see the installed roles.

Then select GPT-5.6 Sol with High reasoning for the primary session and ask for implementation work normally, or invoke the orchestration skill explicitly:

Use $sol-advisor:orchestration to build this feature, verify it, and obtain the final Sol review before reporting done.

Check and update

Run this check whenever a route must be trusted:

plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
test -d "$plugin_dir"
sh "$plugin_dir/scripts/install-agents.sh" --check

To update the marketplace plugin and then re-check its companion roles:

codex plugin marketplace upgrade sol-advisor
codex plugin add sol-advisor@sol-advisor
plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
test -d "$plugin_dir"
sh "$plugin_dir/scripts/install-agents.sh" --check

If the new shipped template differs from an installed role, the check and installer fail rather than overwriting it. Inspect and deliberately reconcile the reported destination with the shipped template, then rerun the check. Do not use a substitute agent as a shortcut. Start a fresh task after every successful install or update.

Runtime routing evidence

Native spawn/details metadata is the primary source of routing evidence. It must show the selected custom agent type. When it also exposes model and effort, the orchestrator compares those values with the role pin. If Desktop omits model or effort and the local rollout is accessible, use the companion inspector as the authoritative read-only fallback for those omitted fields:

plugin_dir="$(codex plugin list --json | jq -r '.installed[] | select(.pluginId == "sol-advisor@sol-advisor") | .source.path')"
thread_id=""
sh "$plugin_dir/scripts/inspect-agent-runtime.sh" "$thread_id"

For a disposable fixture or a non-default local session root, pass it explicitly:

sh "$plugin_dir/scripts/inspect-agent-runtime.sh" --sessions-dir /absolute/path/to/sessions "$thread_id"

The helper searches only rollout filenames ending in that exact thread id, then emits a single compact JSON object with allowlisted routing fields. It never prints prompts, messages, environment variables, tokens, configuration contents, or arbitrary rollout payloads. It refuses invalid ids, zero or multiple matches, and missing or inconsistent role/model/effort; there is no inferred fallback. If public and local evidence both exist, they must agree.

How routing works

The Sol orchestrator writes a five-part spec for every implementation: objective, file ownership, interfaces, constraints, and verification. Luna is the default producer. Terra is selected when judgment, context, or blast radius is materially higher, or when one Luna attempt demonstrates that the task was misclassified.

Before delegation and acceptance, the skill requires all of the following:

1. The installed role files pass the byte-for-byte companion check.
2. The native spawn tool exposes all three exact names in the table above.
3. Public native spawn/details metadata identifies the selected role and, when exposed, its expected model and effort. If model or effort is omitted, the exact-rollout local inspector above must provide them instead.
4. The reviewer’s observed sandbox policy type and permission profile type are captured and reported.

A missing, stale, conflicting, unavailable, inconsistent, or unobservable role/model/effort stops the affected lane with an actionable error. There is no silent model, reasoning, or agent-type fallback, and per-spawn calls do not override the role pins.

The Sol reviewer TOML requests read-only sandboxing, but the host permission profile may broaden that request. If the observed sandbox policy type is read-only, review can proceed with enforced isolation. If the host broadens it, review can proceed only as behaviorally read-only when hard isolation is not required, the prompt forbids edits, and the parent captures and verifies exact before-and-after repository/artifact state; the broader sandbox and permission profile must be reported as residual risk. If hard isolation is required, the sandbox cannot be observed, or any mutation occurs, stop the review lane and do not claim enforced read-only isolation.

The orchestrator inspects every diff and reruns verification. A fresh Sol reviewer then returns ship, fix-first, or rethink. The session cannot report completion until the reviewer returns ship. These remain native Codex subagent threads; Sol Advisor does not launch a nested Codex CLI process or globally reroute unrelated subagents.

Local development

Install a checkout as a local marketplace when you want Codex to use its skill:

cd /absolute/path/to/sol-advisor
codex plugin marketplace add /absolute/path/to/sol-advisor
codex plugin add sol-advisor@sol-advisor

Run the repository verifier separately. It uses only a disposable target directory and never changes your Codex configuration:

cd /absolute/path/to/sol-advisor
sh plugins/sol-advisor/scripts/verify.sh
git diff --check

To exercise the installer itself against an explicit disposable target:

cd /absolute/path/to/sol-advisor
scratch_agents="$(mktemp -d)"
sh plugins/sol-advisor/scripts/install-agents.sh --target-dir "$scratch_agents"
sh plugins/sol-advisor/scripts/install-agents.sh --target-dir "$scratch_agents" --check

To install this checkout’s templates for real local development, use the same repository-relative commands without —target-dir, then begin a new task:

cd /absolute/path/to/sol-advisor
sh plugins/sol-advisor/scripts/install-agents.sh
sh plugins/sol-advisor/scripts/install-agents.sh --check

After editing the plugin, validate both layers:

cd /absolute/path/to/sol-advisor
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/sol-advisor/skills/orchestration
uv run --no-project --with pyyaml python "$codex_skills/plugin-creator/scripts/validate_plugin.py" plugins/sol-advisor
jq empty .agents/plugins/marketplace.json plugins/sol-advisor/.codex-plugin/plugin.json

The verifier validates JSON and TOML, role pins, installer clean/idempotent/check and conflict behavior, runtime-inspector safe fixtures, contract references, and shell syntax. The uv commands supply the validators’ PyYAML dependency in a disposable environment. They do not install the marketplace or mutate Codex configuration.

License

MIT