// Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks.
Guidelines for safe subprocess calls in opencode-swarm. Load before adding, modifying, or reviewing any file that calls spawn, spawnSync, bunSpawn, or child_process. Covers the six required properties, Windows portability, _internals DI seam pattern, and verification grep.
Guidelines for writing, organizing, and maintaining tests in the opencode-swarm repository. Covers framework rules (bun:test), mock isolation, CI pipeline structure, file placement, and anti-patterns that break cross-platform CI. Load this skill before writing or modifying any test file.
Apply when converting test files from mock.module('node:child_process') to _internals DI seam pattern. Guides the complete migration: adding spawnSync/_internals to source files, converting test files, adding proper beforeEach/afterEach save/restore lifecycle, mockReset() cleanup, and temp directory cleanup. Prevents mock.module leaks across Bun's shared test-runner process.
Full execution protocol for MODE: BRAINSTORM -- structured discovery dialogue, approach selection, spec drafting, QA gate selection, and transition handling.
Full execution protocol for MODE: CLARIFY -- structured clarification funnel with critic review before surfacing user decisions.
Full execution protocol for MODE: CLARIFY-SPEC -- resolving spec clarification markers and maintaining spec/planning alignment.
| name | plan |
| description | Full execution protocol for MODE: PLAN -- plan creation, external plan ingestion, QA gate persistence, task granularity, and traceability checks. |
This protocol is loaded on demand by the architect stub in src/agents/architect.ts. The architect prompt keeps only activation, action, and hard safety constraints; the full execution details live here.
SPEC GATE (soft — check before planning):
.swarm/spec.md does NOT exist:
.swarm/spec.md EXISTS:
This is a SOFT gate. When the user chooses "Skip and plan directly", proceed to the steps below exactly as before — do NOT modify any planning behavior.
Run CODEBASE REALITY CHECK scoped to codebase elements referenced in spec.md or user constraints. Discrepancies must be reflected in the generated 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.
Identify ALL uncertainties that could affect the plan. There is NO hard cap on the internal inventory. Cover at minimum:
Classify each item as exactly one of:
self_resolved: answered from the user request, spec, plan, codebase reality check, .swarm/context.md, repo conventions, or an informed default. If the default is not directly supported by user request, spec, or recorded context, classify as user_decision rather than self_resolved.critic_resolved: sent to Critic Sounding Board and resolved by the critic.research_needed: needs SME/explorer/domain lookup before user escalation.user_decision: only the user can decide because it affects product scope, risk tolerance, policy, budget, UX, rollout, or destructive behavior.deferred_nonblocking: useful follow-up detail that does not block a correct initial plan and can be explicitly recorded as an assumption or follow-up.Before asking the user any planning clarification question, the architect MUST consult critic_sounding_board with the candidate question set and context.
For each item classified as research_needed or user_decision in Stage 2, send it to the critic. The critic responds with a verdict from SoundingBoardVerdict (see src/agents/critic.ts). The mapping between critic verdicts and funnel actions is:
| Critic Verdict (SoundingBoardVerdict) | Funnel Action | Meaning |
|---|---|---|
UNNECESSARY | DROP | Item is unnecessary or answerable from existing context |
RESOLVE | RESOLVE | Critic supplies the answer or recommended default |
REPHRASE | REPHRASE | Question is valid but should be clearer, narrower, or grouped |
APPROVED | ASK_USER | User decision is genuinely required |
Hard constraint: Items in the Always-Surface Categories list (below) MUST NOT receive UNNECESSARY/DROP from the critic — only REPHRASE or APPROVED/ASK_USER are allowed. If the critic attempts to UNNECESSARY/DROP an always-surface item, override to APPROVED/ASK_USER.
Overconfidence guard: If the critic attempts to self-resolve an item by supplying an answer (verdict RESOLVE) but the underlying default is not directly supported by user request, spec, or recorded context, the architect MUST classify the item as user_decision rather than self_resolved. Unsupported defaults must not be silently accepted.
Update classifications based on critic response:
UNNECESSARY/DROP → reclassify as self_resolved and record the reason.RESOLVE → reclassify as critic_resolved and record the answer as an assumption.REPHRASE → update the question wording and keep as candidate.APPROVED/ASK_USER → confirm as user_decision.The architect MUST update the plan's assumptions with all resolved items before proceeding to Stage 4.
Exception: QA gate selection questions are already mandatory user decisions (enforced by the save_plan tool itself) and do NOT need to go through the funnel. QA gate selection is always a direct user dialogue.
If any items remain classified as user_decision after Stage 3, present them as a structured decision packet — NOT as an arbitrary subset or a single question.
The packet MUST include for each decision:
The architect MAY ask questions one at a time in interactive mode, but MUST preserve and report the full unresolved list. The architect MUST NOT drop unresolved decisions because of a session question cap.
The critic may improve wording or confirm prior context, but these categories MUST be surfaced to the user unless already explicitly answered by the user or by recorded context:
All items resolved in Stages 2-3 (self_resolved, critic_resolved, deferred_nonblocking) MUST be recorded as explicit assumptions in .swarm/context.md under ## Decisions before calling save_plan. Silently dropping resolved uncertainties is a protocol violation — every uncertainty that entered the funnel must have a recorded outcome.
The plan generated by save_plan MUST include explicit assumptions and remaining unresolved decisions in the task descriptions or acceptance criteria — not silently omit them.
Use the save_plan tool to create the implementation plan. Required parameters:
title: The real project name from the spec (NOT a placeholder like [Project])swarm_id: The swarm identifier (e.g. "mega", "local", "paid")phases: Array of phases, each with id (number), name (string), and tasks (array)id (e.g. "1.1"), description (real content from spec — bracket placeholders like [task] will be REJECTED)size (small/medium/large), depends (array of task IDs), acceptance (string)Example call: save_plan({ title: "My Real Project", swarm_id: "mega", phases: [{ id: 1, name: "Setup", tasks: [{ id: "1.1", description: "Install dependencies and configure TypeScript", size: "small" }] }] })
EXECUTION PROFILE (Optional — set during planning, lock before first task)
The execution_profile field in save_plan controls plan-scoped concurrency. It is independent of the global plugin config and takes precedence when locked.
Fields:
parallelization_enabled (boolean, default false): When true, tasks may run in parallel.max_concurrent_tasks (integer 1–64, default 1): Maximum simultaneous tasks when parallel is enabled.council_parallel (boolean, default false): When true, council review phases may parallelise.locked (boolean, default false): When true, the profile is immutable — future save_plan calls that include execution_profile will be REJECTED (fail-closed).WHEN TO SET IT:
LOCK DISCIPLINE:
WRONG: Setting execution_profile after tasks have started (profile would not apply retroactively). WRONG: Setting locked: true and then trying to change it — save_plan will reject the update. WRONG: Assuming the global plugin config overrides a locked profile — it does not.
Example (set and lock in one call): save_plan({ title: "My Project", swarm_id: "mega", phases: [...], execution_profile: { parallelization_enabled: true, max_concurrent_tasks: 3, council_parallel: false, locked: true } })
POST-SAVE_PLAN: APPLY QA GATE SELECTION.
After save_plan succeeds, read .swarm/context.md:
## Pending QA Gate Selection section exists: parse the gate values, call set_qa_gates with those flags, confirm with the user ("QA gates applied: "), then remove the section from context.md.## Pending Parallelization Config section also exists: parse the values and call save_plan again with execution_profile set to { parallelization_enabled: <parsed>, max_concurrent_tasks: <parsed>, council_parallel: false, locked: true }. Then remove the section from context.md. If the plan already had execution_profile.locked: true, skip this step — the profile is already locked and immutable.## Task Completion Commit Policy section exists: preserve it in .swarm/context.md (do NOT remove). This section is execution-time guidance for optional per-task checkpoint commits after update_task_status(status="completed").## Pending Parallelization Config section to .swarm/context.md alongside the gate selection:## Pending Parallelization Config
- parallelization_enabled: true
- max_concurrent_tasks: <user's number>
- council_parallel: false
- locked: true
- recorded_at: <ISO timestamp>
.swarm/context.md:
## Task Completion Commit Policy
- commit_after_each_completed_task: true
- recorded_at: <ISO timestamp>
## Task Completion Commit Policy section already exists in context.md, honor it as execution-time guidance (do NOT remove).## Task Completion Commit Policy section exists AND pending gate/parallelization sections were pre-written, ask the commit-frequency question now. Write the section to context.md if the user chooses per-task commits; skip if they keep the default phase-level behavior.INLINE GATE SELECTION — no pending section found in context.md. You MUST ask now. ✗ "I'll call set_qa_gates with defaults and move on" → WRONG: set_qa_gates with assumed values is a gate violation. The user must answer first. ✗ "The user provided a plan — they know what gates they want" → WRONG: providing a plan is not the same as configuring gates. Always ask.
MANDATORY PAUSE: Present the gate question. Wait for the user's answer.
Do NOT call set_qa_gates until the user has responded.
Then call set_qa_gates with the user's chosen flags.
Either path must yield a persisted QA gate profile before the first task dispatches.
⚠️ If save_plan is unavailable, delegate plan writing to the active swarm's coder agent:
⚠️ Even in this fallback, you MUST call declare_scope for ".swarm/plan.md" BEFORE the coder delegation. Scope discipline applies to plan-writing delegations too. See Rule 1a.
TASK: Write the implementation plan to .swarm/plan.md
OUTPUT: .swarm/plan.md
INPUT: [provide the complete plan content below]
CONSTRAINT: Write EXACTLY the content provided. Do not modify, summarize, or interpret.
TASK GRANULARITY RULES:
TEST TASK DEDUPLICATION: The QA gate (Stage B, step 5l) runs test_engineer-verification on EVERY implementation task. This means tests are written, run, and verified as part of the gate — NOT as separate plan tasks.
DO NOT create separate "write tests for X" or "add test coverage for X" tasks. They are redundant with the gate and waste execution budget.
Research confirms this: controlled experiments across 6 LLMs (arXiv:2602.07900) found that large shifts in test-writing volume yielded only 0–2.6% resolution change while consuming 20–49% more tokens. The gate already enforces test quality; duplicating it in plan tasks adds cost without value.
CREATE a dedicated test task ONLY when:
If in doubt, do NOT create a test task. The gate handles it. Note: this is prompt-level guidance for the architect's planning behavior, not a hard gate — the behavioral enforcement is that test_engineer already writes tests at the QA gate level.
PHASE COUNT GUIDANCE:
Also create .swarm/context.md with: decisions made, patterns identified, SME cache entries, and relevant file map.
TRACEABILITY CHECK (run after plan is written, when spec.md exists):
After the QA gate selection has been persisted via set_qa_gates and the TRACEABILITY CHECK is complete:
critic_pre_plan is enabled (default: ON): the plan MUST be reviewed by the critic before any implementation begins.