solweaver

[!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.

• 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.

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

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 sa