# Sol Advisor

> A Codex-native architect orchestration plugin that routes software delivery through Sol, Terra, and Luna implementation lanes with mandatory fresh Sol review.

Sol Advisor is an open-source Codex plugin built by Daniel McAteer (DannyMac180) that implements a capability-routed software delivery workflow for the Codex CLI and ChatGPT desktop app. It keeps architecture, decomposition, verification, and acceptance in a primary Sol session while delegating bounded implementation work to either native Terra subagents or user-visible Luna app tasks. The project is licensed under MIT and hosted on GitHub.

## What It Is

Sol Advisor is a Codex-native architect workflow plugin — a structured orchestration layer that sits on top of OpenAI's Codex platform to enforce separation of concerns between high-level architecture and hands-on implementation. The primary session (GPT-5.6 Sol / High reasoning) owns requirements, specs, verification, and final acceptance. Implementation is routed to either a native Terra subagent (default) or an explicit Luna app task, depending on what the user authorizes. The result is a disciplined, role-pinned delivery pipeline rather than a single monolithic coding session.

## Two Routing Lanes

Sol Advisor exposes two distinct implementation lanes, each with strict activation rules:

- **Native subagent lane (default):** Uses the installed `sol_advisor_terra_implementer` custom-agent role (GPT-5.6 Terra / High), followed by a fresh `sol_advisor_sol_reviewer` (GPT-5.6 Sol / High) for context-independent review. The primary Sol session cannot report completion until the reviewer returns a "ship" verdict.
- **Luna task lane (explicit opt-in):** Creates a user-visible Codex app task using `create_thread` with `model=gpt-5.6-luna` and `thinking=max`. The primary Sol task monitors the Luna task via `wait_threads` and `read_thread`, inspects the actual diff and verification evidence, sends corrections via `send_message_to_thread`, and authorizes PR creation only after accepting the work. This lane never activates automatically — the user must explicitly request it in the current message.

Neither lane has a silent fallback. A missing role file, unavailable model, or unobservable routing metadata stops the affected lane with an actionable error.

## Installation and Setup

Sol Advisor installs via the Codex plugin marketplace using two shell commands:

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

Native mode additionally requires running the companion installer script (`install-agents.sh`) to place the Terra and Sol reviewer TOML role files in the user's Codex agents directory. The installer is intentionally non-overwriting: it refuses to replace modified, symlinked, or nonregular files, and a `--check` flag performs a byte-for-byte verification without mutation. Luna-only users can skip companion installation entirely.

A repository verifier (`verify.sh`) validates JSON and TOML, role pins, installer behavior, migration logic, runtime-inspector fixtures, and lane contracts without touching Codex configuration.

## Update: Version 0.4.0

The repository reached version 0.4.0 shortly after its August 2026 creation. This release retains byte-exact migration support for the historical v0.2.0 companion files (`sol-advisor-luna-implementer.toml` and `sol-advisor-terra-implementer.toml`), updates the native routing to use Terra / High exclusively, and removes the legacy Luna implementer TOML from native mode. The routing update was motivated by Eric Provencher's post on X. The repository accumulated over 1,000 stars and 73 forks within days of creation, according to GitHub metadata.

## Architecture and Safety Model

The orchestration design enforces several hard constraints:

- **Role pinning:** Native per-spawn calls cannot override the installed role pins. Model and effort must match exactly or the lane stops.
- **Read-only reviewer sandboxing:** The Sol reviewer TOML requests read-only sandboxing. If the host broadens the sandbox and hard isolation is required, the review lane stops rather than proceeding with weakened guarantees.
- **Concurrent task safety:** Independent stacks may run concurrently only with separate tasks and non-overlapping file ownership. Shared-file or dependent stacks are always serial.
- **PR authorization gate:** A Luna task must not create or push a PR before the primary Sol task explicitly authorizes it after reviewing the diff and checks.

The runtime inspector script (`inspect-agent-runtime.sh`) provides a read-only fallback for routing evidence when the Desktop app omits model or effort metadata, emitting only allowlisted routing fields and refusing to print prompts, tokens, or configuration contents.

## Features
- Capability-routed software delivery with Sol as primary orchestrator
- Native Terra subagent lane for default implementation routing
- Luna app task lane for explicit opt-in user-visible tasks
- Mandatory fresh Sol reviewer before completion in native mode
- Byte-for-byte companion role file verification via install-agents.sh
- Runtime routing inspector script for model/effort evidence
- PR authorization gate requiring Sol acceptance before push
- Concurrent independent stack support with non-overlapping ownership
- Read-only reviewer sandboxing with residual-risk reporting
- Repository verifier for JSON, TOML, lane contracts, and installer behavior
- v0.2.0 migration support for legacy companion files
- Local marketplace development mode

## Integrations
OpenAI Codex CLI, ChatGPT desktop app, GPT-5.6 Sol / High, GPT-5.6 Terra / High, GPT-5.6 Luna / Max, Codex app task tools (list_projects, list_threads, create_thread, wait_threads, read_thread, send_message_to_thread), jq, uv (Python environment runner), PyYAML

## Platforms
API, CLI

## Pricing
Open Source

## Version
0.4.0

## Links
- Website: https://github.com/DannyMac180/sol-advisor
- Repository: https://github.com/DannyMac180/sol-advisor
- EveryDev.ai: https://www.everydev.ai/tools/sol-advisor