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.

Solweaver component model baselines on DeepSWE v1.1

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

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

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

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.

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.

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.

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.

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.

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

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.

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.

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-strict applies, its base and boundary, stable assurance-unit identity, readiness result, review call count, reviewer verdict, and post-phase retrospective status;
• remaining gaps, risks, or behavior that was not proved; and
• external actions such as commit, push, pull request, merge, or deployment still waiting for explicit authorization.

flowchart LR
 G["Software goal"] --> P["Sol<br/>Any effort<br/>Classify mode and risk"]
 P --> S{"Does delegation help?"}
 S -->|"No"| I["Sol<br/>Any effort<br/>Implement or integrate and verify"]
 S -->|"Coupled or judgment-heavy"| T["Terra max<br/>Default worker"]
 S -->|"Narrow or high-throughput"| L["Luna max<br/>Bounded worker"]
 T --> I
 L --> I
 I --> A{"Final-strict required?"}
 A -->|"No"| R["Evidence-backed result"]
 A -->|"Yes"| Q{"Final-strict readiness green?"}
 Q -->|"No"| I
 Q -->|"Yes"| V["Fresh Sol max<br/>Read-only review"]
 V -->|"ship"| H["Post-phase retrospective"]
 V -->|"not accepted"| C{"Review call"}
 C -->|"Budget remains"| X["Close outcome and verify again"]
 C -->|"Final budget call"| E["Review exhausted<br/>Parent recovery"]
 E --> H
 H --> R
 X --> I

Sol owns orchestration throughout. Workers receive a concrete goal, explicit file or module ownership, acceptance criteria, validation commands, and an expected evidence format. Delegated communication and reports use English by default; Sol can explicitly request another report language when the workflow needs it. Code and repository content continue to follow the task and local conventions. Terra and Luna may run in parallel only when their write scopes are disjoint.

For the parent, Solweaver inspects the current turn_context, requires model == "gpt-5.6-sol", records the observed effort, and accepts any reported reasoning effort. After every package-owned child turn, Solweaver inspects turn_context.model and turn_context.effort:

Missing or mismatched worker metadata means the lane is not counted as correctly routed and its report is not evidence. Because native workers share the worktree, Sol preserves their edits, inspects the complete diff, and verifies any changes it takes over; it never rolls them back automatically. Missing or mismatched reviewer metadata rejects the verdict and cannot satisfy final-strict acceptance.

The gate intentionally checks only those two runtime fields. Agent self-reports, task labels, and UI names are not proof, and sandbox enforcement is not inferred from this gate. Optional platform specialists are reported honestly but are not hard-coded to a model because Solweaver does not own their definitions.

Final-strict review is intentionally fresh-context and read-only. The reviewer never implements its findings. Any call without a valid accepted ship returns to Sol for the same re-review preparation gate while predeclared budget remains: resolve the finding or failed runtime/packet prerequisite, refreeze the candidate, rerun parent adversarial readiness and the full gate, and attach a neutral closure matrix. A non-ship final budget call triggers review-exhausted. Sol separates implementation defects, evidence gaps, fix-induced regressions, unresolved product or architecture decisions, and acceptance-versus-review expectation mismatches, then owns the fixes and final verification instead of looping, requesting user direction, switching workflows, or lowering the review bar.

• The skill cannot change the active parent model by itself.
• Orchestration stays with Sol; a worker cannot silently take over the team.
• Writing agents must preserve unrelated changes and stay inside their assigned ownership.
• Native subagents are assumed to share the active worktree unless the host explicitly reports isolation.
• A configured model is not described as observed runtime unless runtime or session metadata exposes it. Package-owned child results are accepted only after their model and effort pass the runtime identity gate.
• Standard assurance avoids reviewer, ledger, manifest, and coordination overhead for ordinary work while still requiring complete-diff inspection and proportionate parent verification. Focused checks run during edits; full repository verify and applicable Compose run once at the commit/final-delivery candidate boundary.
• When final-strict applies, it defers only the independent reviewer. Parent focused verification still runs at every checkpoint, intermediate work cannot claim ship, and candidate-wide verify/Compose plus protected irreversible or production boundaries require the final gate first.
• The final-strict review target is one call. New units have a default hard budget of three, while existing units retain their immutable recorded maximum of two or three. The durable counter crosses tasks, worktrees, branches, and candidates. Exclusive durable reservation prevents concurrent tasks from consuming the same call, and candidate identity stays separate from mutable attempt accounting. A non-ship final budget call hard-stops review and cannot be bypassed by raising the cap, renaming, splitting, or reopening unchanged scope. It enters non-reviewable parent-recovery, where Sol may fix and refreeze without replenishing calls, then terminates with transparent work and independent-attestation status. Protected external actions remain unexecuted without their required authority.
• High-risk auth, money, tenant-isolation, data-integrity, concurrency, and production work stays under parent control and requires the final-strict gate; ordinary low-risk work does not.
• The skill does not authorize deployment, production mutation, pushing, merging, or pull-request creation.

Run the same check used by CI:

python3 scripts/validate.py

It validates skill frontmatter, folder and name consistency, UI metadata, worker TOML definitions, model assignments, reasoning effort, runtime-gate contracts, the smoke test, and the example configuration. It also executes a throwaway installer matrix covering fresh installation, overwrite refusal, backup-on-upgrade, legacy-root migration, installed validation, and exact source-installed parity.

Validate an installed copy with:

python3 ~/.agents/skills/solweaver/scripts/validate_install.py

Restart Codex or open a new task and follow the bundled runtime smoke test before describing the workflow as runtime-certified.

Ideas, issues, and focused pull requests are welcome. Please keep routing rules concise, update examples when behavior changes, and run the validator before submitting a change.

• Open an issue
• View the skill source

Solweaver is available under the MIT License.