opencode-swarm 7.79.1 → 7.79.5

package/.opencode/skills/council/SKILL.md

@@ -27,7 +27,8 @@ This mode is ADVISORY. It does not block any other workflow and does not modify
 code, plans, or specs. The output is for the user (general mode) or for the spec
 being drafted (spec_review mode is available via `/swarm council --spec-review`
 for manual spec review). General Council advisory input is offered as an early
-workflow option in MODE: BRAINSTORM (Phase 1b).
+workflow option in MODE: BRAINSTORM (Phase 1b) and MODE: PLAN before
+`save_plan`.
 
 #### Pre-flight (always run first)
 

package/.opencode/skills/loop/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: loop
+description: >
+  Full execution protocol for MODE: LOOP — the compound-engineering loop:
+  brainstorm → plan → build → review → improve, iterating under
+  defense-in-depth stop conditions with generator/critic separation,
+  durable resumable state, and mandatory compounding learning capture.
+  Loaded on demand by the architect when the loop command emits a
+  [MODE: LOOP ...] signal.
+---
+
+# Compound-Engineering Loop Protocol
+
+MODE: LOOP runs an objective end to end as a series of gated phases, then
+loops to compound improvements until the objective is met or a stop condition
+fires. Each cycle reuses the existing mode skills (`brainstorm`, `plan`,
+`critic-gate`, `execute`, `phase-wrap`) and ends with a learning-capture step
+so the next cycle is cheaper — that is what makes the loop *compounding* rather
+than merely repeating.
+
+This is a real implementation workflow: it delegates to the coder, declares
+scope, and mutates source code through the normal EXECUTE path. It is distinct
+from full-auto (autonomous cross-phase oversight via the `critic_oversight`
+agent) and turbo (parallel lanes within a single phase). LOOP is a
+user-initiated, gated, sequential, compounding workflow.
+
+The two design rules that everything below serves:
+
+1. **Separate the generator from the verifier.** The context that writes a
+   change must never be the only context that approves it. Implementation,
+   independent review, and critic challenge live in separate delegated
+   contexts. Review is report-only; a distinct fix step applies changes.
+2. **Stop on positive evidence or a budget — never on vibes.** Every phase has
+   an entry gate and an exit gate backed by concrete evidence, and the loop has
+   layered stop conditions so it can never run away.
+
+---
+
+## Step 0 — Parse Header
+
+Parse the `[MODE: LOOP ...]` header to extract:
+
+- `objective`: the goal text after the header (the WHAT to achieve). Empty only
+  when `resume=true`.
+- `max_cycles`: integer 1..5 (default 3) — hard cap on outer improvement cycles.
+- `autonomy`: `checkpoint` (default) or `auto`.
+  - `checkpoint`: pause at each phase gate and wait for explicit user approval
+    before continuing.
+  - `auto`: proceed across gates without prompting, but still enforce every
+    hard stop condition and the mandatory review/critic gates.
+- `depth`: `standard` (default) or `exhaustive` (wider exploration in
+  BRAINSTORM and PLAN: more candidate approaches, deeper localization).
+- `resume`: `true` | `false`. When true, resume the existing run from durable
+  state instead of starting a new objective.
+
+If the header is malformed or required fields are missing, report the error and
+stop.
+
+---
+
+## Step 1 — Preconditions & Durable State
+
+1. **Working tree.** Check `git status`. If the tree is dirty, surface the
+   uncommitted changes and ask whether to proceed (checkpoint) or proceed only
+   if the changes are clearly part of this objective (auto). Do not silently
+   build on an unknown working state.
+2. **Run state directory.** Loop state lives under `.swarm/loop/<run-id>/`
+   (containment invariant — never write loop state outside `.swarm/`).
+   - New run (`resume=false`): allocate a `run-id` (short slug + timestamp),
+     create `.swarm/loop/<run-id>/state.json`, and record the baseline:
+     objective, parsed parameters, start HEAD commit, `cycle: 0`,
+     `phase: brainstorm`, empty `improvements` and `learnings` lists.
+   - Resume (`resume=true`): locate the most recent `.swarm/loop/<run-id>/`
+     with an unfinished state, read it, **validate required fields** (`run_id`,
+     `cycle`, `phase`, `done` must all be present and have the correct types;
+     if any are missing or malformed, report the corruption clearly and stop
+     rather than continuing with undefined values), print a short progress
+     summary (cycle N of max_cycles, current phase, last gate result), and
+     continue from the recorded phase. If no resumable run exists, say so and
+     stop.
+   - **Retention:** On both new-run and resume entry, prune completed runs
+     (`.done === true`) that exceed 10 in count — keep the 10 most recent by
+     timestamp, remove the rest. This prevents unbounded state accumulation
+     under `.swarm/loop/`.
+3. **State is derived, not authoritative for code.** The durable state file
+   tracks *loop control* (cycle counter, phase, gate outcomes, captured
+   learnings, stop reason). Actual implementation progress is derived from git
+   and the plan ledger (`.swarm/plan-ledger.jsonl`), never from conversation
+   memory — so a killed/resumed session never loses or re-does work.
+
+Write the state file after every gate transition. The on-disk state is the
+single source of truth for resumability.
+
+---
+
+## Step 2 — The Cycle
+
+One cycle is five phases run in order: **BRAINSTORM → PLAN → BUILD → REVIEW →
+IMPROVE**. Do not skip or collapse phases. Each phase has an entry gate
+(precondition) and an exit gate (positive evidence required before the next
+phase begins). In `checkpoint` autonomy, pause at each gate for user approval.
+
+On cycle 2+, BRAINSTORM is replaced by a lightweight **refinement** step: feed
+the prior cycle's captured improvements and residual findings into PLAN
+directly (skip full discovery dialogue) — the objective is already framed.
+
+### Phase 1 — BRAINSTORM (cycle 1 only)
+
+- **Entry gate:** objective is non-empty; no approved plan already covers it.
+- **Action:** Load `file:.opencode/skills/brainstorm/SKILL.md` and run it to
+  produce `.swarm/spec.md` and a QA gate profile. With `depth=exhaustive`,
+  require at least one non-obvious candidate approach.
+- **Exit gate:** `spec.md` exists with explicit, testable success criteria and
+  scope boundaries. Record the success criteria into loop state — they are the
+  objective-met test used by the stop conditions. Checkpoint: confirm the spec
+  with the user.
+
+### Phase 2 — PLAN
+
+- **Entry gate:** a spec (or, on cycle 2+, the improvement directives) exists.
+- **Action:**
+  1. Load `file:.opencode/skills/pre-phase-briefing/SKILL.md` (required before
+     planning, especially on cycle 2+: it reads the prior retrospective and
+     verifies codebase reality so the new plan reflects what actually changed).
+  2. Load `file:.opencode/skills/plan/SKILL.md` to decompose the work into
+     tasks and call `save_plan`. With `depth=exhaustive`, prefer finer task
+     granularity and deeper localization.
+  3. Load `file:.opencode/skills/critic-gate/SKILL.md` to put the plan through
+     an independent critic.
+- **Exit gate:** critic verdict is APPROVED (NEEDS_REVISION → revise and
+  re-submit, max 2 cycles per the critic-gate skill; REJECTED → stop and report
+  to the user). Record the verdict in loop state.
+
+### Phase 3 — BUILD
+
+- **Entry gate:** a critic-approved plan exists.
+- **Action:** Load `file:.opencode/skills/execute/SKILL.md` and run the plan
+  phase by phase. The coder implements each task; per-task QA gates (tests,
+  lint, security, etc.) run as defined by the selected QA profile. The coder
+  context is the **generator** — it does not get to declare its own work
+  correct.
+- **Exit gate:** all planned tasks for the cycle are implemented and their
+  per-task QA gates pass with recorded evidence. NEVER weaken, mock, skip, or
+  delete a failing test/assertion to make a gate pass — fix the root cause or
+  stop and report.
+
+### Phase 4 — REVIEW (report-only) + FIX
+
+This phase is the heart of the generator/verifier separation. It runs on the
+**actual current diff**, in contexts independent of the coder.
+
+- **Entry gate:** BUILD exit gate passed; capture the current diff
+  (`git diff` against the cycle's start commit).
+- **Action:**
+  1. **Independent reviewer.** Delegate the real diff and the QA evidence to a
+     fresh reviewer context. It defaults to disbelief, looks for correctness
+     bugs, regressions, security issues, missing edge cases, and
+     claimed-vs-actual mismatches, and classifies each finding. The reviewer
+     does not edit code — it reports.
+  2. **Critic challenge.** Delegate the reviewer-approved diff and any
+     HIGH/CRITICAL findings to a separate critic context that challenges weak
+     evidence, overclaimed severity, and missing sibling-file checks. The
+     critic may overturn the reviewer.
+  3. **Fix step.** For every `NEEDS_REVISION` / `REJECTED` / `BLOCKED` item,
+     return to the coder (generator) to fix it with code, tests, or evidence,
+     then re-run the affected reviewer/critic gate. Any edit after approval
+     invalidates that approval — re-review.
+- **Exit gate:** reviewer approval AND critic approval on the latest diff, with
+  the latest edit older than both approvals. Record the reviewer/critic verdicts
+  durably alongside the phase evidence (the phase-wrap evidence manager writes
+  retrospective and gate artifacts under `.swarm/evidence/` — keep the
+  review/critic outcomes with that phase's evidence so `phase_complete` and any
+  later audit can read them). This satisfies the mandatory implementation
+  closeout gate.
+
+### Phase 5 — IMPROVE (phase-wrap + compounding capture)
+
+This is what makes the loop compound. Do not declare completion without it.
+
+- **Entry gate:** REVIEW exit gate passed.
+- **Action:**
+  1. Load `file:.opencode/skills/phase-wrap/SKILL.md` and write the mandatory
+     retrospective (the `phase_complete` gate blocks without a valid `retro-N`
+     bundle). Rescan the codebase and update documentation exactly as the
+     phase-wrap skill directs — that is, scoped to its authorized set
+     (README.md / CONTRIBUTING.md / docs/ via the `docs` agent). Do NOT edit the
+     governance contract files (AGENTS.md / CLAUDE.md); they constrain the loop
+     and are out of scope for autonomous edits.
+  2. **Capture learnings durably.** Distill what this cycle taught — recurring
+     bug classes, surprising couplings, tooling gotchas, convention decisions —
+     into the knowledge base (the `knowledge_add` tool / the memory tools when
+     enabled) and/or a categorized note under `.swarm/loop/<run-id>/learnings/`.
+  3. **Make learnings discoverable.** Ensure the next loop will actually read
+     them: persist via `knowledge_add` (which `knowledge_recall` surfaces in
+     later phases) rather than a write-only note nobody reads — capturing
+     learnings nothing retrieves does not compound.
+  4. **Feed findings forward.** Record any review/critic finding that recurred
+     so it becomes an explicit check in the next cycle's reviewer prompt.
+- **Exit gate:** retrospective written and accepted by `phase_complete`;
+  learnings persisted; the cycle's improvements and residual findings recorded
+  in loop state.
+
+---
+
+## Step 3 — Loop Decision (Stop Conditions)
+
+After IMPROVE, evaluate the stop conditions **in order**. Use defense in depth:
+several overlapping conditions, not one. Record the chosen `stop_reason` in
+loop state.
+
+1. **Objective met (primary).** The success criteria captured in Phase 1 are
+   all satisfied AND the full validation suite / required QA gates are green.
+   → STOP (success).
+2. **Cycle budget exhausted.** `cycle >= max_cycles`. → STOP. Never exceed
+   `max_cycles`.
+3. **No-progress / plateau.** The just-finished cycle produced no qualifying
+   improvement toward the objective (no new passing criteria, no accepted
+   review fix that advanced the goal). → STOP and report the plateau; looping
+   again would burn budget without progress.
+4. **Oscillation.** The cycle reintroduced or reverted a change made in a prior
+   cycle (the diff fingerprint repeats). → STOP and report; the loop is
+   thrashing.
+5. **Unrecoverable error.** A gate cannot pass for a reason outside this
+   objective's scope (e.g., REJECTED plan, environment failure, a required
+   external dependency is unavailable). → STOP and report.
+6. **Explicit user stop.** The user asked to stop. → STOP immediately.
+
+If none fire and budget remains: increment `cycle`, set the next cycle's input
+to the recorded improvement directives + residual findings, and return to
+**Phase 2 (PLAN)** (cycle 2+ skips full BRAINSTORM). In `checkpoint` autonomy,
+confirm "continue for another cycle?" with the user before looping.
+
+---
+
+## Step 4 — Completion
+
+When a stop condition fires:
+
+1. Mark loop state `done` with the `stop_reason` and final HEAD commit.
+2. Present a human-readable summary:
+   - Objective and whether it was met.
+   - Baseline → final state (what changed, key files/tasks).
+   - Cycles run (and why it stopped).
+   - Tasks completed vs deferred; residual review findings and where they are
+     recorded.
+   - Learnings captured this run and where they live.
+   - Suggested next steps (e.g., open a PR via `/swarm pr-review` or the
+     commit-pr flow — do NOT open a PR unless the user asks).
+3. Emit a machine-detectable completion marker on its own line so callers /
+   automation can detect terminal state:
+
+   `<loop-complete reason="objective-met|budget-exhausted|plateau|oscillation|unrecoverable-error|user-stop" cycles="N"/>`
+
+---
+
+## Durable State Schema (`.swarm/loop/<run-id>/state.json`)
+
+A minimal, append-friendly shape — extend as needed but keep these fields:
+
+```json
+{
+  "run_id": "rate-limit-20260618T0712Z",
+  "objective": "add rate limiting to the public API",
+  "params": { "max_cycles": 3, "autonomy": "checkpoint", "depth": "standard" },
+  "start_commit": "<sha>",
+  "cycle": 1,
+  "phase": "review",
+  "success_criteria": ["...", "..."],
+  "gates": [
+    { "cycle": 1, "phase": "plan", "result": "approved", "at": "<iso>" }
+  ],
+  "improvements": [],
+  "learnings": [],
+  "done": false,
+  "stop_reason": null,
+  "final_commit": null
+}
+```
+
+---
+
+## Autonomy Quick Reference
+
+| Behavior | `checkpoint` (default) | `auto` |
+| --- | --- | --- |
+| Pause at phase gates | Yes — wait for user approval | No |
+| Confirm before next cycle | Yes | No |
+| Mandatory review + critic gates | Enforced | Enforced |
+| Hard stop conditions (budget, plateau, oscillation, errors) | Enforced | Enforced |
+| Weaken/mock/skip a failing test | Never | Never |
+
+`auto` reduces prompts; it never reduces verification.
+
+---
+
+## Anti-Patterns (do not do these)
+
+- Letting the coder context approve its own diff. Review and critic must be
+  independent contexts.
+- Treating passing tests, explorer output, or self-review as the implementation
+  closeout gate. They are not.
+- Editing code after reviewer/critic approval and then declaring done without
+  re-review. Any post-approval edit invalidates the approval.
+- Looping "one more time" past `max_cycles` or after a plateau because it feels
+  close. Stop and report.
+- Skipping the IMPROVE/compound capture step to finish faster. The compounding
+  step is the point of the loop.
+- Storing loop progress only in conversation context. Persist to
+  `.swarm/loop/<run-id>/` so the loop survives interruption.
+- Weakening, mocking, skipping, or deleting a failing assertion to turn a gate
+  green. Fix the root cause or stop.

package/.opencode/skills/plan/SKILL.md

@@ -39,6 +39,22 @@ This is a SOFT gate. When the user chooses "Skip and plan directly", proceed to
 
 Run CODEBASE REALITY CHECK scoped to codebase elements referenced in spec.md or user constraints. Discrepancies must be reflected in the generated plan.
 
+### GENERAL COUNCIL ADVISORY OPTION (pre-save_plan)
+
+Before drafting or saving the plan, the architect MUST offer General Council advisory input when `council.general.enabled` is true in the resolved opencode-swarm config and a search API key is configured.
+
+- Ask the user: "Use General Council advisory input before I write the plan? The 3-agent council (generalist, skeptic, domain expert) will gather current external context and provide perspectives that I will fold into the plan before critic review. (default: no)"
+- If the user declines, proceed to the clarification funnel and planning normally.
+- If the user accepts:
+  1. Run the General Council Research Phase: formulate 1-3 targeted `web_search` queries grounded in the work being planned.
+  2. Dispatch `the active swarm's council_generalist agent`, `the active swarm's council_skeptic agent`, and `the active swarm's council_domain_expert agent` in PARALLEL with the RESEARCH CONTEXT.
+  3. Collect responses and call `convene_general_council` with mode `general`.
+  4. Record the council consensus, disagreements, cited sources, and any plan-impacting assumptions in `.swarm/context.md` under `## Decisions`.
+  5. Use that recorded council input as planning context before calling `save_plan`.
+- If General Council is unavailable and the user explicitly requested council input, surface the config/key requirement and stop before `save_plan` rather than writing an ungrounded plan.
+
+General Council is advisory and distinct from `council_mode`, `phase_council`, and `final_council`. It is not a QA gate. Its purpose here is to make current external context available before the architect writes any plan and before any critic pre-plan review.
+
 ### CLARIFICATION FUNNEL (pre-save_plan)
 
 Before calling `save_plan` — whether creating a new plan or finalizing an external plan ingestion — the architect MUST run this four-stage clarification funnel. The goal is to limit unnecessary user interruption, not planning completeness.
@@ -292,4 +308,4 @@ After the QA gate selection has been persisted via `set_qa_gates` and the TRACEA
 3. Wait for the critic's verdict before proceeding to MODE: EXECUTE.
 4. If the critic approves: proceed to MODE: EXECUTE for implementation.
 5. If the critic requests revision (NEEDS_REVISION): revise the plan and re-submit to the critic (max 2 cycles).
-6. If the critic rejects after 2 cycles: escalate to the user with a full explanation.
+6. If the critic rejects after 2 cycles: escalate to the user with a full explanation.

package/.opencode/skills/specify/SKILL.md

@@ -30,10 +30,10 @@ Activates when: user asks to "specify", "define requirements", "write a spec", o
    - Edge cases and known failure modes
     - `[NEEDS CLARIFICATION]` markers for items where uncertainty could change scope, security, or core behavior, BUT ONLY after running the clarification funnel: (1) inventory all material uncertainties without numeric cap, (2) classify each as self_resolved/critic_resolved/research_needed/user_decision/deferred_nonblocking — **overconfidence guard:** if the default is not directly supported by user request, spec, or recorded context, classify as `user_decision` rather than `self_resolved`, (3) consult critic_sounding_board with candidate items — critic responds per SoundingBoardVerdict: UNNECESSARY→DROP, RESOLVE→RESOLVE, REPHRASE→REPHRASE, APPROVED→ASK_USER — **always-surface protection:** always-surface categories must not receive UNNECESSARY/DROP; override to APPROVED/ASK_USER, (4) record all resolved items as explicit assumptions in the spec, (5) use markers only for items that survive the funnel (ASK_USER or unresolved after critic consultation). Decision packet format: grouped by category, recommended defaults, blocking vs optional markers, impact of accepting default. Prefer informed defaults over asking
 5. Write the spec to `.swarm/spec.md`.
-5b. **QA GATE SELECTION, PARALLEL CODERS, AND COMMIT FREQUENCY (dialogue only).**
-Ask the user which QA gates to enable for this plan, how many parallel coders to use, and the commit frequency -- do not select on their behalf. Present all three items together as one unified exchange.
+5b. **QA GATE SELECTION, PARALLEL CODERS, COMMIT FREQUENCY, AND AUTO_PROCEED (dialogue only).**
+Ask the user which QA gates to enable for this plan, how many parallel coders to use, the commit frequency, and auto_proceed -- do not select on their behalf. Present all four items together as one unified exchange.
 
-Present the eleven gates with their defaults (DEFAULT_QA_GATES), parallel coder count, and commit frequency as a single user-facing section. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
+Present the eleven gates with their defaults (DEFAULT_QA_GATES), parallel coder count, commit frequency, and auto_proceed as a single user-facing section. Offer the user a one-shot choice: accept defaults, or customize. The eleven gates are:
 - reviewer (default: ON) -- code review of coder output
 - test_engineer (default: ON) -- test verification of coder output
 - sme_enabled (default: ON) -- SME consultation during planning/clarification
@@ -46,12 +46,12 @@ Present the eleven gates with their defaults (DEFAULT_QA_GATES), parallel coder
 - drift_check (default: ON) -- when enabled, mandatory per-phase drift verification via critic_drift_verifier at PHASE-WRAP; compares implemented changes against spec.md intent; hard-blocks phase_complete when spec.md exists and drift evidence is missing or REJECTED; advisory-only when no spec.md exists (recommended for all projects with a specification)
 - final_council (default: OFF) -- when enabled, after all phases complete the architect dispatches the full 5-member council (critic, reviewer, sme, test_engineer, explorer) -- NOT the General Council -- at project scope, collects `CouncilMemberVerdict` objects, and calls `write_final_council_evidence`. This does not require `council.general.enabled`.
 
-Additionally, present these two sub-items as part of the same exchange:
+Additionally, present these three sub-items as part of the same exchange:
 - Parallel coders (default: 1, range: 1-4) -- how many coders should run in parallel.
 - Commit frequency (default: phase-level only) -- optional per-task checkpoint commit after each task completion.
 - auto_proceed (boolean, default: false) -- when true, auto-advance to the next phase without asking "Ready for Phase N+1?"; runtime toggle via /swarm auto-proceed on|off.
 
-The user answers all three (gates, parallel coders, commit frequency) in one exchange. Wait for the user's response.
+The user answers all four (gates, parallel coders, commit frequency, auto_proceed) in one exchange. Wait for the user's response.
 
 If the user says parallel coders > 1, write a `## Pending Parallelization Config` section to `.swarm/context.md` alongside the gate selection:
 ```
@@ -88,9 +88,9 @@ GATE SELECTION IS MANDATORY — these thoughts are WRONG and must be ignored:
 
 MANDATORY PAUSE: Do NOT write the spec summary (step 7). Do NOT suggest next steps.
 You are BLOCKED until ALL THREE of these conditions are met:
-  (1) The unified gate/coders/commit selection section has been presented to the user in a single message
-  (2) The user has responded (accept defaults OR customized list for all three items)
-  (3) The elected gates, parallel coder config, and commit policy have been written to .swarm/context.md under "## Pending QA Gate Selection" (and related sections as applicable)
+  (1) The unified gate/coders/commit/auto_proceed selection section has been presented to the user in a single message
+  (2) The user has responded (accept defaults OR customized list for all four items)
+  (3) The elected gates, parallel coder config, commit policy, and auto_proceed selection have been written to .swarm/context.md under "## Pending QA Gate Selection" (and related sections as applicable)
 <!-- BEHAVIORAL_GUIDANCE_END -->
 
 Do NOT call `set_qa_gates` yet — `plan.json` does not exist at this point. Once the user answers, write the elected gates to `.swarm/context.md` under a new section:
@@ -111,7 +111,7 @@ Do NOT call `set_qa_gates` yet — `plan.json` does not exist at this point. Onc
 ```
 MODE: PLAN will read this section after `save_plan` succeeds and persist via `set_qa_gates`.
 
-General Council advisory input is offered as an early workflow option in MODE: BRAINSTORM (Phase 1b), not as a SPECIFY step. If the user wants council input during SPECIFY, they can use `/swarm council <question>` manually.
+General Council advisory input is offered as an early workflow option in MODE: BRAINSTORM (Phase 1b) and MODE: PLAN before `save_plan`, not as a SPECIFY step. If the user wants council input during SPECIFY, they can use `/swarm council <question>` manually.
 
 7. Report a summary to the user (MUST count, SHALL count, scenario count, clarification markers, elected QA gates) and suggest the next step: `CLARIFY-SPEC` (if markers exist) or `PLAN`.
 

package/dist/agents/architect.d.ts

@@ -21,7 +21,8 @@ export interface CouncilWorkflowConfig {
     /**
      * General Council Mode (advisory). When `general?.enabled === true`, the
      * architect's tool list includes `convene_general_council` and the prompt
-     * emits `MODE: COUNCIL` and `SPECIFY-COUNCIL-REVIEW` instructions.
+     * emits `MODE: COUNCIL` plus pre-plan advisory instructions in the loaded
+     * PLAN protocol.
      */
     general?: {
         enabled?: boolean;