[!NOTE] Solweaver is an open-source community project. It is not an official OpenAI project.

Why Solweaver

Multi-agent workflows are useful only when ownership stays clear. Solweaver keeps Sol accountable for the whole outcome, works locally when delegation would cost more than it saves, and adds stronger ceremony only as risk grows.

Sol leads	Terra builds	Luna accelerates
Plans, implements or routes, integrates, verifies, and delivers	Handles coupled, ambiguous, multi-file, and judgment-heavy implementation	Handles narrow, mechanical, repetitive, and high-throughput assignments

• One accountable lead: Sol remains on the critical path from plan to final evidence.
• Purposeful routing: auto mode keeps small, low-risk work with Sol and adds Terra or Luna only when a bounded worker materially helps.
• Safe parallelism: workers run together only when their ownership is explicit and their write scopes are disjoint.
• Verification built in: worker summaries are not treated as proof; Sol reviews the changes and runs appropriate checks.
• Risk-proportional assurance: ordinary work uses parent verification; high-risk or explicitly requested work adds a durable final-strict gate.
• Runtime honesty: configured model routing is kept distinct from model and effort actually exposed by runtime metadata.
• No surprise publishing: deployment, production mutation, commits, pushes, and pull requests still require user authorization.

Benchmark context

These are published individual-model baselines from the DeepSWE v1.1 leaderboard. Every model was evaluated under the same mini-swe-agent harness.

[!IMPORTANT] The chart is not a score for Sol + Terra, Sol + Luna, or Solweaver as a team. A valid team benchmark must run each complete configuration on the same tasks, limits, environment, and verifiers. Individual scores must not be added or averaged into a team result.

View the official DeepSWE leaderboard snapshot

DeepSWE v1.1 cost view: 113 tasks, updated July 25, 2026. Screenshot © Datacurve and reproduced here for reference. Click the image for the live leaderboard.

Quick start

Requirements

• A Codex runtime and account with access to gpt-5.6-sol, gpt-5.6-terra, and gpt-5.6-luna
• Python 3.9 or newer for installation
• Python 3.11 or newer for repository validation

The included configuration selects reasoning effort max as a capability-first example. Solweaver requires gpt-5.6-sol for the parent but accepts any reasoning effort that the runtime supports and reports. Package-owned workers and the final-strict reviewer remain pinned to max.

1. Install

git clone https://github.com/jay7793/solweaver.git
cd solweaver
python3 scripts/install.py

The installer copies both user-global skills to ~/.agents/skills/solweaver and ~/.agents/skills/test-driven-development, plus the agent definitions into $CODEX_HOME/agents, or ~/.codex/agents when CODEX_HOME is unset. It refuses to replace an existing skill or non-identical agent file unless --upgrade is supplied. Upgrade mode creates timestamped backups before replacement, migrates legacy copies of either skill from ~/.codex/skills so Codex does not discover duplicates, and reuses identical shared agent definitions. A customized existing TDD skill is never silently overwritten; --upgrade backs it up before installing the pinned bundled copy. Use --user-skills-dir only when testing or intentionally targeting another user-skill root. Custom --codex-home and --user-skills-dir targets must be disjoint from the Solweaver source tree and from each other; the installer rejects any source/write or write/write overlap before mutation. It resolves every source, destination, legacy, and backup path through intermediate symlinks before making that comparison or writing. Its completion message prints an installed-copy validation command with both selected roots preserved.

Upgrade an existing installation with:

git pull
python3 scripts/install.py --upgrade

2. Configure

Merge the relevant settings instead of replacing your existing configuration:

• examples/config.toml → ~/.codex/config.toml
• examples/AGENTS.md → ~/.codex/AGENTS.md

The example caps spawned-agent concurrency at 2. The primary Sol thread is not included in that number, so the maximum visible total is Sol plus two spawned agents.

Restart Codex or open a new task so the skill, agents, model, and reasoning settings are reloaded.

3. Start a Solweaver task

Invoke the skill explicitly:

$solweaver

Goal: implement the feature and verify it end to end.

With the example global policy installed, software-development prompts starting with Goal: or /goal, plus requests such as use software team, can load Solweaver automatically.

Usage

You usually only need to describe the outcome. Sol keeps ownership of the plan, chooses local execution or the smallest useful team, reviews the actual changes, and reports evidence proportional to risk.

Solweaver is project-neutral: it derives languages, frameworks, commands, contracts, and evidence conventions from the active workspace instead of embedding product-specific policy. It can therefore be used from any software repository where Codex can inspect the project guidance and run the applicable tools.

For a small ordinary task, invoke Solweaver normally. Auto mode keeps the work with Sol when delegation would add coordination cost, uses standard assurance, and does not create final-strict artifacts or call a reviewer.

$solweaver

Goal: fix the validation message typo and run its focused test.

TDD discipline

Solweaver bundles the upstream $test-driven-development skill and loads it before production code for features, bug fixes, refactors, and behavior changes. TDD owns the focused RED-GREEN-REFACTOR loop; Solweaver remains the orchestrator and owns integration, candidate-wide verification, and assurance. Every production-code worker receives the same TDD requirement. Tests written after implementation do not retroactively satisfy TDD, and a final full-suite pass does not replace observed RED evidence.

Documentation, research, operations-only, generated, configuration-only, and explicitly authorized throwaway work use the TDD skill's own applicability and exception contract, so bundling it does not add test ceremony to every task. The vendored files are pinned byte-for-byte to obra/superpowers and retain Jesse Vincent's MIT license and attribution.

Choose an execution mode

Mode	Implementation	Independent review
auto (default)	Sol chooses local execution or the smallest useful team	Added only when final-strict applies
solo	Sol plans, implements, and verifies without subagents	None; standard assurance only
solo-reviewed	Sol implements and verifies; no implementation worker is spawned	One target final-strict call, with bounded re-review while budget remains
team	At least one bounded Terra or Luna worker implements under Sol ownership	Added only when final-strict applies

Invoking Solweaver without a mode uses auto; it does not automatically spawn Terra, Luna, or a reviewer. Explicit modes are honored without silent downgrades. Plain solo cannot claim independent review; use solo-reviewed when local implementation still needs a fresh final gate.

Auto delegates only for a concrete benefit: a disjoint lane shortens the critical path, context isolation materially reduces risk, or a worker is a substantially better fit for a bounded assignment. File count and skill invocation alone are not reasons to spawn. It prefers one worker and adds another only when independent write scopes can progress concurrently.

Use the same contract for ordinary feature work:

$solweaver

Goal: add profile editing with validation and regression tests.

Sol decides whether delegation adds value, then inspects and verifies the complete result.

Candidate-bound verification

Sol reads repository guidance, package scripts, CI, task-runner configuration, and Compose entrypoints once to classify commands as focused implementation checks or candidate-wide gates. During edit and checkpoint cycles it runs only the focused checks needed for the changed behavior. Repository-wide verify, full build/E2E, and full Compose rehearsals are deferred until the complete candidate is ready for independent review, or ready to commit/finally deliver under standard assurance.

The target is one green full pass per frozen behavior candidate. Compose is started or safely reused once, health-checked once, exercised once, and torn down once when repository policy requires it. A failed candidate gate returns to focused fix cycles; the next full pass runs only after fixes are batched. Assurance-metadata-only changes reuse the exact candidate-bound verification and Compose receipts. Repository/user instructions that require an earlier gate, and narrow high-risk integration checks for money, migrations, concurrency, or destructive behavior, still take precedence.

Final-strict when needed

Final-strict applies when explicitly requested or when work affects auth, authorization, secrets, tenant isolation, money, data integrity, migrations, destructive behavior, concurrency, public APIs, production-critical paths, or a wide architectural refactor. It defines one coherent phase or delivery unit and adds a fresh independent Sol review after parent verification:

$solweaver

Complete this coherent phase with focused parent verification after every
checkpoint.
Run one fresh final-strict review over the complete integrated assurance unit
at the declared final boundary.

Sol derives a stable ASSURANCE_UNIT_ID from repository and product authority, records REOPEN_GENERATION, and uses a durable ledger that survives task, worktree, branch, and candidate changes. The ledger contains the exact base, cumulative acceptance criteria, checkpoint evidence, review calls, known gaps, and final boundary. Intermediate results are only checkpoint-ready: no final reviewer is spawned and no ship claim is made.

Sol records FROZEN_CANDIDATE_ID for the full behavior scope and a separate ASSURANCE_PACKET_ID for the ledger and evidence snapshot. Only the declared ledger and attempt-coordination sidecar are outside the behavior-candidate identity; product, test, and contract changes are never omitted. This lets review accounting advance without silently changing the frozen candidate. The repository identity reconciles staged, unstaged, and untracked paths; plain git diff is not sufficient when an in-scope file is untracked. If installed, generated, or runtime-loaded copies are part of the acceptance boundary, a deterministic DELIVERY_ARTIFACT_MANIFEST binds their actual content into the frozen candidate. Use the bundled scripts/compute_delivery_manifest.py with stable logical labels and retain its full solweaver-delivery-v1 records plus the exact command at DELIVERY_ARTIFACT_MANIFEST_LOCATION. A parity check or unexplained aggregate by itself is evidence, not an immutable identity for those active files.

At the final boundary, Sol freezes the candidate, re-inspects the complete cumulative diff from the recorded base, resolves product and architecture decisions, and reruns every applicable parent gate. It then performs a separate parent adversarial pass with a risk-surface map, counterexamples, negative paths, changed-to-unchanged interactions, fix-induced regressions, and test-sensitivity evidence. missing or not_run evidence blocks review. The assurance unit must also pass its one-pass reviewability gate and set PARENT_ADVERSARIAL_READY: yes; only then may REVIEW_READY: yes permit the reviewer spawn. This shifts defect discovery before the independent gate.

Final-strict cannot defer review across destructive migration execution, real money movement, production auth or authorization changes, deployment, merge, release, or another irreversible external mutation. If that boundary arrives early, the accumulated relevant change must pass its final gate first. An assurance unit that is too broad for one complete review must be redefined before call 1 rather than partially omitted from the reviewer packet.

Final-strict is Solweaver's independent-review assurance contract. Ordinary low-risk work uses standard assurance and stops after Sol inspects the complete diff and reruns proportionate checks.

Final-strict may defer the independent review during reversible implementation, but it still requires a fresh reviewer and ship verdict before its final or protected boundary. A fix-first verdict returns findings to the responsible worker, while rethink returns the architecture to Sol.

Each final-strict assurance unit generation targets one reviewer call. New units use a default hard budget of three so two sequential fix rounds can still converge on an independent verdict. The third call is contingency, not the target. Existing durable units keep their recorded maximum, including legacy default units capped at two. extended remains a backwards-compatible label for a maximum of three and grants nothing beyond the new default. The mode and maximum cannot be increased after a call is reserved. Every reviewer spawn that begins execution counts, including a runtime mismatch or unusable verdict. The counter follows the stable unit across tasks, chats, continuations, worktrees, branches, spec revisions, and candidate commits. Renaming or splitting unchanged scope cannot reset it, and extended budget cannot compensate for an assurance unit that is too broad for one complete review pass.

Before each reservation, Sol writes a canonical solweaver-final-strict-readiness-v1 record and runs scripts/validate_final_strict_packet.py. The validator binds the exact ledger, attempt journal, review packet, complete candidate manifest, and optional delivery manifest by SHA-256; stale or incomplete packet evidence fails before it consumes a reviewer call.

Before spawning a reviewer, Sol uses an exclusive durable coordination record to reserve the next call with a unique REVIEW_ATTEMPT_ID. The reservation occupies the budget before spawn, preventing two tasks from buying the same call. A Markdown/text journal alone is not a lock: the packet records the exact atomic lock or compare-and-set primitive, path or key, acquisition, protected transition, and release. Reservation fails closed unless the same identity and generation are loaded, UNIT_STATUS: open, REVIEW_READY: yes, budget remains, and no reservation is active. It becomes started when the child begins and may be released as cancelled-before-start only with exact proof. An interrupted or ambiguous reservation is recovered conservatively as consumed. Without an atomic reservation mechanism, REVIEW_READY stays no. A lock-busy contender creates no reservation and consumes no call. Completion under the same primitive clears the reservation and sets UNIT_STATUS: ship for an accepted ship, keeps it open only while another predeclared call remains, or sets REVIEW_STATUS: review-exhausted with UNIT_STATUS: parent-recovery after the final non-ship call.

If a complete reviewer pass finds only assurance-metadata defects, Sol may use one bounded same-attempt metadata closure with the same reviewer child, reservation, attempt ID, and frozen behavior candidate. It corrects only the packet or coordination evidence, reruns the machine validator, and requests one closure verdict. This is not another spawn or call. Any behavior change, mixed finding, incomplete audit, or second non-ship result uses the normal fresh review path.

Any consumed call without a valid accepted ship enters the same re-review preparation gate when predeclared budget remains. This includes fix-first, rethink, an unusable or malformed verdict, and a missing or mismatched runtime gate. Sol resolves the outcome with focused checks, batches fixes, refreezes the candidate, then runs candidate-wide verification and applicable full Compose once for the new candidate. If behavior and command inputs are unchanged, it reuses the bound receipts. Sol reruns parent adversarial readiness and the full gate, and creates a neutral re-review closure matrix before the next call, even when no source file changed. The next fresh reviewer still audits the full cumulative diff, but every blocker must identify the violated contract, reachable failure or material evidence gap, impact, and file references. Later-call findings also classify whether they were pre-existing, introduced by a fix, newly exposed by evidence, or caused by an acceptance mismatch. Review continues after the first blocker so findings are not intentionally drip-fed. If the prior runtime gate was missing or mismatched, configured TOML is not closure. Exact platform evidence that the intended child's turn_context will be exposed is required before spending another call; otherwise the remaining call stays unspent.

If the active surface missed telemetry that was actually persisted, use scripts/extract_child_runtime.py to bind the exact rollout to the expected parent, package-owned role/path, worktree, model, and effort. The script owns the Terra/Luna/reviewer role-to-runtime mapping; callers cannot supply expected model or effort. A premature runtime-only blocked or blocked-external-boundary result may be corrected under the same exclusive lock only when that proof passes, the candidate and closure evidence are unchanged, a predeclared call remains never reserved, and no protected boundary was crossed. The correction preserves terminal history, generation, mode, maximum, and call counts; restores UNIT_STATUS: open with REVIEW_READY: no; then requires refreeze, adversarial, closure-matrix, and full readiness reruns before the remaining call. It cannot recover ship, parent-recovery, parent-completed, or review-exhausted units and never creates a new budget.

When a non-ship call consumes the last predeclared call, Sol sets REVIEW_STATUS: review-exhausted and UNIT_STATUS: parent-recovery, and never exceeds or raises that maximum. Parent Sol then owns completion: it reconciles findings, makes conservative in-scope decisions, applies addressable fixes, refreezes, and verifies the complete result in the same generation without asking the user merely because the review budget ended or spawning another reviewer. When all work and acceptance criteria are complete with no known blocker, report:

WORK_STATUS: complete
ACCEPTANCE_STATUS: met
KNOWN_BLOCKERS: none
INDEPENDENT_ATTESTATION: not-obtained-within-budget
FINAL_STATUS: parent-completed
ASSURANCE_STATUS: final-strict-not-achieved

This says the work is complete while accurately withholding reviewer ship. Parent recovery terminates as UNIT_STATUS: parent-completed, blocked, or blocked-external-boundary; none can reserve another reviewer.

An owner can explicitly authorize release of an unchanged parent-completed/final-strict-not-achieved candidate after a current green preflight by naming the exact unit, commit or candidate, assurance limitation, and release actions. This records risk acceptance without relabeling the result as reviewer ship. External findings are classified as candidate-introduced, candidate-exposure-increased, or baseline-unchanged so unchanged dependency risk is visible without being confused with a candidate regression.

A valid ship or a terminal parent-recovery result closes the generation. Review exhaustion closes only the independent review lane, leaving authorized parent fixes possible without replenishing calls. Later behavior-changing work after terminal closure needs an explicitly authorized incremented REOPEN_GENERATION, durable reason, and material new scope; evidence-only closure does not reopen it. Any UNIT_STATUS other than open blocks another reservation even when the old generation has unused numeric budget, except the exact missed-runtime terminal correction above, which must restore open without resetting budget before any reservation. After ship, parent-completed, blocked, or blocked-external-boundary, Sol records a post-phase retrospective with candidate attempts, exact-evidence reruns, reserved and started reviewer calls, finding classes, preventable waste, and at most three generalizable improvement proposals. Workflow changes are proposed for user approval, never applied automatically.

Steer worker selection

You do not need to select a worker manually, but you can when the boundary is clear.

Use Terra for coupled or judgment-heavy implementation:

$solweaver

Use terra_worker for the implementation.

Goal: refactor the authentication service without changing its public API.

Use Luna for narrow, repetitive, or low-coupling work:

$solweaver

Delegate the isolated validation fixtures to luna_worker.

Goal: add regression coverage for the request validation helpers.

Run independent work in parallel

State the ownership boundaries when you want parallel workers:

$solweaver

Use the software team. Let Terra own the API implementation and Luna own only
the isolated fixtures. Run them in parallel only if their files do not overlap.

Goal: add CSV export with API tests and fixtures.

Parallelism is optional. Shared files, dependency chains, and unresolved design decisions remain serial.

Expected result

Sol should finish with:

• the usable outcome and changed-file scope;
• verification commands actually run and their concrete results;
• the execution and assurance modes selected;
• when final-s