Solweaver

Coordinate execution without delegating orchestration itself. Keep the main agent on the critical path. Work solo or use the smallest team that materially improves speed, context isolation, or review quality.

Preflight

1. Classify the request before spawning agents.
2. Read applicable AGENTS.md files and repository guidance. Confirm the working directory, branch or worktree, and existing changes before assigning ownership.
3. Keep the active parent as orchestrator. Require gpt-5.6-sol as the parent model, but allow any reasoning effort reported by the current turn_context. This skill cannot select or prove the runtime.
4. Inspect agent availability only when the selected path actually needs an agent. Auto or solo execution with standard assurance does not require a worker or reviewer to be available. Do not silently substitute a missing agent when an explicit mode or assurance gate requires it.
5. Describe model evidence precisely:
   • Observed: current session turn_context reports model and effort.
   • Configured: a validated agent definition pins the value, but runtime metadata does not expose it.
   • Unverified: neither source establishes the value.
6. If the observed parent model is not gpt-5.6-sol, stop before implementation and direct the user to select that model. Do not reject an observed Sol parent based on its reasoning effort. If the parent model or effort metadata is unavailable, do not claim the parent runtime gate passed.
7. Enforce the package-owned child identity matrix: terra_worker requires model == "gpt-5.6-terra" and effort == "max"; luna_worker requires model == "gpt-5.6-luna" and effort == "max"; and solweaver_reviewer requires model == "gpt-5.6-sol" and effort == "max".
8. After every package-owned child turn, inspect the child session turn_context before accepting its report or verdict. If the active surface omits it, search the persisted child rollout before declaring runtime metadata unavailable; use scripts/extract_child_runtime.py to bind the rollout to the expected parent, child role/path, worktree, model, and effort, and record its hash plus ordinals or version-gated physical record indices. If either value differs or no actual turn_context can be proved, mark the lane mismatched or unverified and apply the handling in references/contracts.md. A model-generated self-report, task label, UI name, or agent definition is not runtime proof.
9. Do not impose a fixed model gate on optional platform specialists that this package does not define. Report their runtime as observed, configured, or unverified, and honor any explicit runtime requirement from the user.
10. Preserve user changes, repository boundaries, and explicit external-action approval requirements.
11. Keep Solweaver project-neutral. Discover language, framework, commands, repository layout, product contracts, and evidence conventions from the active workspace. Keep project-specific names, paths, requirements, and governance in task-local artifacts rather than the Solweaver package.
12. After installing or changing Solweaver definitions, run scripts/validate_install.py, restart Codex or open a new task, and follow references/runtime-smoke-test.md before describing the workflow as runtime-certified.
13. Build a repository verification profile once from applicable AGENTS.md, package scripts, CI, task runners, and Compose configuration. Separate narrow FOCUSED_CHECKS used during implementation from repository-wide CANDIDATE_CHECKS and any full COMPOSE_CHECK. Treat full verify, full build, full E2E, and full Compose rehearsals as candidate-boundary gates unless the repository or user explicitly requires an earlier run.
14. For every feature, bug fix, refactor, or behavior change, load the bundled $test-driven-development skill before writing production code. It owns the RED-GREEN-REFACTOR discipline while Solweaver continues to own orchestration, integration, and candidate verification. When writing or changing tests, read its writing-good-tests.md reference. Pass the same requirement to every production-code worker. If the bundled skill is missing or fails installed-copy integrity validation, stop before implementation and repair the installation. Do not force TDD onto documentation, research, operations-only work, generated code, configuration-only changes, or an explicitly authorized throwaway prototype beyond the TDD skill's own applicability and exception contract.

Choose execution mode

• Use auto mode when the user does not name a mode. Sol chooses local solo execution or the smallest useful team; invoking Solweaver alone does not require a subagent.
• For small, low-risk, low-coupling tasks in auto mode, prefer local solo execution with standard assurance. Do not spawn a worker or reviewer, create final-strict artifacts, or add phase machinery merely because Solweaver was invoked.
• Use solo mode when the user wants Sol alone. Sol plans, implements, verifies, and delivers without spawning any worker or reviewer. Solo supports standard assurance only.
• Use solo-reviewed mode when the user wants Sol to implement alone with an independent final gate. Do not spawn implementation workers; after parent verification at the final-strict boundary, spawn one fresh solweaver_reviewer at a time and apply final-strict acceptance, including a fresh review after a fix round only while review budget remains. Solo-reviewed always uses final-strict assurance.
• Use team mode when the user explicitly requests delegation. Spawn at least one bounded implementation worker, while Sol retains integration and verification. Add the fresh reviewer only when a final-strict assurance unit reaches its gate.
• Honor an explicit mode without silently changing it. If solo mode conflicts with a user-requested or risk-triggered independent review, stop before implementation and ask the user to choose solo with standard assurance, solo-reviewed, or auto/team execution with final-strict assurance.

In auto mode, spawn only when at least one concrete benefit outweighs the coordination cost: a disjoint lane can shorten the critical path, context isolation reduces material risk, or the worker is a substantially better fit for a bounded assignment. File count, task size labels, or skill invocation alone are not reasons to delegate. Prefer one worker; add another only for independent write scopes that can make useful progress concurrently.

Choose assurance

• Use standard assurance for ordinary work in auto, solo, or team execution. Sol inspects the complete diff, reruns proportionate verification, and accepts or returns the work without final-strict artifacts or a reviewer.
• Use final-strict assurance when the user wants one independent review over a coherent completed phase or delivery unit, or when the change affects auth, authorization, secrets, tenant isolation, money, data integrity, migrations, destructive behavior, concurrency, public APIs, production-critical paths, or a wide architectural refactor. Before implementation, assign a stable ASSURANCE_UNIT_ID, set REOPEN_GENERATION, choose a durable LEDGER_LOCATION plus an exclusive ATTEMPT_COORDINATION_LOCATION, and record the exact base state, objective, acceptance criteria, final boundary, and cumulative evidence. Derive the identity from repository and product authority such as repository, track, and canonical phase or delivery ID; never derive it from a task, thread, worktree, branch, timestamp, or candidate SHA. Apply focused parent verification after every intermediate checkpoint, do not spawn solweaver_reviewer yet, and report only checkpoint-ready.
• At the declared final boundary, inspect the complete cumulative diff from the recorded base, run the repository-owned candidate checks and applicable full Compose rehearsal once for the frozen candidate, then pass the referenced final-strict readiness gate before applying the fresh reviewer gate and final-strict acceptance rules.
• Final-strict is Solweaver's only independent-review assurance mode. Auto and team use standard assurance unless final-strict is requested or risk-triggered; solo-reviewed always uses final-strict. Readiness must lead to a fresh solweaver_reviewer attempt; parent self-review never satisfies the independent gate.
• Record REVIEW_BUDGET_MODE before reviewer call 1. New assurance units use default with TARGET_REVIEW_CALLS = 1 and MAX_REVIEW_CALLS = 3; the third call is contingency, not a target. Existing durable units keep their already recorded maximum, including historical default units capped at 2. extended remains a backwards-compatible legacy label for a predeclared maximum of 3 and grants no calls beyond the new default. Once any call is reserved, never increase or change the mode or maximum. Count every solweaver_reviewer spawn that begins execution, including attempts with missing or mismatched runtime metadata or an unusable verdict. Carry REVIEW_CALLS_USED across tasks, chats, continuations, worktrees, branches, spec revisions, and candidate commits. Never exceed the recorded maximum or reset it by renaming, splitting, or reopening unchanged scope. A three-call budget is not a substitute for making the assurance unit coherent and reviewable.
• Keep the assurance-unit ledger in the repository's existing phase, build, or evidence log when one is authoritative. Otherwise choose a user-authorized durable artifact before implementation. It must survive task context and be recoverable from another worktree or continuation. Never create a competing generic ledger when repository guidance defines another authority. If a prior final-strict attempt is mentioned or discoverable but its exact call count cannot be reconstructed, treat the remaining budget as unknown and do not spawn a reviewer as though the count were zero.
• Keep reviewer-attempt coordination in a durable sidecar or repository-provided lock/CAS facility outside the frozen behavior candidate. A Markdown journal alone is not a lock: record and use an exact atomic primitive, path or key, acquisition result, protected state transition, and release. It must support an exclusive atomic reservation across tasks and worktrees. Before a spawn, reserve one call with a unique REVIEW_ATTEMPT_ID and CALL_STATE: reserved; a reservation occupies the remaining budget. A lock-busy contender creates no reservation and consumes no call. After the child begins, mark it started and increment REVIEW_CALLS_USED. Release a reservation as cancelled-before-start only when exact tool evidence proves the child never began. After interruption or ambiguous recovery, count the reservation as consumed. If exclusive reservation is unavailable, reviewer spawn is forbidden.
• A missed-runtime terminal correction is the only evidence-only exception to terminal closure. Use it only when a generation was prematurely set to blocked or blocked-external-boundary solely because actual child turn_context was thought unavailable, exact persisted rollout evidence later proves the expected runtime, the candidate and closure evidence are unchanged, a predeclared call remains unreserved and unused, and no protected boundary was crossed. Under the same exclusive primitive, preserve terminal history and all counters, correct the completed attempt, set UNIT_STATUS: open with REVIEW_READY: no, then rerun refreeze, adversarial, closure-matrix, and full readiness gates before reserving the remaining call. This is not a generation reopen and never replenishes budget. Read the exact gate in references/contracts.md.
• Record a FROZEN_CANDIDATE_ID for the complete declared behavior scope and a separate ASSURANCE_PACKET_ID for the ledger, attempt journal, and evidence snapshot. Exclude only the declared ledger and coordination artifacts from the behavior-candidate identity; never omit product, test, contract, or other changed scope. Attempt accounting changes the assurance packet but does not invalidate the frozen candidate. Any change outside those declared artifacts requires candidate refreeze and a full readiness rerun. Include staged, unstaged, and untracked files inside the declared scope; git diff alone is not a complete candidate identity when untracked files exist.
• Before reserving any reviewer call, write a canonical FINAL_STRICT_READINESS_RECORD and run scripts/validate_final_strict_packet.py against the exact ledger, attempt journal, reviewer packet, and candidate manifest, plus the delivery manifest when applicable. Persist its passing JSON proof and SHA-256 identities at FINAL_STRICT_READINESS_RECORD_LOCATION. Prose assertions or a manually assembled packet do not replace this machine gate. Any later mutation makes the proof stale and requires regeneration before reservation.
• When installed, generated, or runtime-loaded copies are part of the declared acceptance boundary, bind their actual content into FROZEN_CANDIDATE_ID with a deterministic DELIVERY_ARTIFACT_MANIFEST. Point-in-time parity alone is evidence, not immutable identity. Use scripts/compute_delivery_manifest.py with stable logical labels and persist its full versioned per-file records, aggregate, and exact command at DELIVERY_ARTIFACT_MANIFEST_LOCATION; an unexplained aggregate is not reproducible. For Solweaver package installation or release, include both the installed solweaver and test-driven-development skill trees plus agent definitions; the bundled TDD license and provenance are part of the delivery boundary. Mark installed copies not applicable only when they are genuinely outside the boundary.
• Permit final-strict execution during high-risk implementation only while it remains reversible and no protected boundary is crossed. Before a destructive migration, real money movement, production auth or authorization change, deploy, merge, release, or other irreversible external mutation, complete the final-strict gate for the relevant cumulative change or stop.
• Before the first reviewer call, pass the referenced reviewability gate: one coherent objective, explicit invariant and risk surfaces, a complete diff that one reviewer can inspect in a single full pass, and captured cross-unit interactions. If it fails, redefine the delivery units before call 1; extended budget cannot repair incoherent scope. After a reviewer begins, splitting or renaming scope never replenishes the budget. Never omit parts of the diff merely to preserve the one-review target.
• Never describe solo execution or a parent self-review as independent review. Never describe an intermediate final-strict checkpoint as ship or final-strict acceptance.

Plan and decompose

1. Form a short outcome-focused plan before implementation or delegation.
2. Record TDD_REQUIRED: yes for production-code behavior changes or TDD_REQUIRED: no with the exact applicability reason. When required, identify the first observable test seam and RED command before implementation.
3. Identify the immediate blocker and keep it with the parent when local progress depends on it.
4. Split only bounded work. Parallelize only assignments that are independent and have disjoint write ownership.
5. Read references/contracts.md before the first delegated write or final-strict review in a task.
6. Send every worker the complete task packet from that reference. Use fork_turns="none" when selecting a custom worker so the packet, not leaked parent context, defines the assignment.
7. Keep delegated communication and reports in English by default. Set another report language explicitly in the task packet only when the user-facing workflow or parent integration needs it. Repository content still follows the task and repository conventions.
8. Keep shared-file edits, unresolved design decisions, and dependency chains serial.

Select agents

Apply the selected execution mode before routing:

• In solo mode, do not spawn any agent.

• In solo-reviewed mode, spawn no implementation worker and reserve reviewer spawns for the final-strict gate and any required re-review.

• In team mode, spawn at least one bounded implementation worker.

• In auto mode, spawn only agents that materially improve the outcome.

• Use terra_worker for the default implementation path and for ambiguous, coupled, multi-file, architecture-sensitive, backend, frontend, database, integration, debugging, and refactoring work.

• Use luna_worker when the assignment is narrow, low-coupling, mechanical, or high-throughput with explicit acceptance criteria. Good fits include isolated tests, fixtures, documentation-adjacent code, repetitive migrations, and independent file clusters.

• Use solweaver_reviewer only as a fresh, read-only reviewer. It never implements its own findings.

• Prefer Terra and final-strict assurance when incorrect routing could affect a high-risk boundary.

• Use code_mapper, tester, reviewer, or security_reviewer only when the current runtime exposes them and their specialization materially helps.

• Use another implementation agent only when the user explicitly requests it.

When workers are allowed, parallelize disjoint assignments within the configured concurrency limit; the limit is a ceiling, not a target. Terra and Luna may run together only when their ownership is disjoint.

Coordinate execution

Apply these rules to active subagents. In solo mode, keep all execution local to the parent.

1. Tell every writing agent it is not alone in the codebase, must preserve unrelated edits, and owns only its assigned scope.
2. Assume native subagents share the active working tree unless the host explicitly reports an isolated worktree. Disjoint file ownership is not the same as filesystem isolation.
3. Create a separate user-visible task or worktree only when the user explicitly authorizes that action and the current surface supports it.
4. Continue parent-owned inspection, integration planning, or blocker work while independent agents run.
5. Track dependencies and progress. Correct missing evidence or scope drift in the responsible worker; do not create a replacement merely to avoid a correction loop.
6. Resolve overlaps and conflicts centrally. Never ask workers to orchestrate the team.
7. If a Terra or Luna runtime gate fails, do not accept the worker report as evidence or count that lane as correctly routed. Inspect the shared worktree and complete diff, preserve all unrelated changes, and never roll back child edits automatically.
8. In auto mode, Sol may take ownership of inspected changes and verify them locally, but must report the failed worker lane. In explicit team mode, pause before further implementation and make at most one corrected re-dispatch when the expected runtime is available; otherwise request user direction. Never downgrade an explicit team request silently.

Integrate and verify