@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -7,6 +7,16 @@ release.
 
 ## [Unreleased]
 
+## [0.1.11] - 2026-09-21
+
+### Changed
+
+- **Environment repair lives in `sw-setup` alone.** The other skills no longer
+  repair the setup themselves; they carry only lean preconditions and defer to
+  `sw-setup` for the fix.
+- **A tech spec is rendered before the editor opens**, so the page shows the
+  document rather than opening onto an unrendered one.
+
 ## [0.1.10] - 2026-09-20
 
 ### Changed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@execuro-sw-ecosystem/sw-ecosystem-agentic-harness",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Shopware 6 agentic harness: sw-* skills and sub-agents, plus an installer that writes them into Claude Code, Codex, GitHub Copilot and Cursor.",
   "license": "MIT",
   "author": "Execuro UG (haftungsbeschränkt)",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "sw-ecosystem-agentic-harness",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Shopware 6 agentic harness: sw-* skills and sub-agents for requirements, specs, implementation, verification and documentation, with an installer CLI that writes them into Claude Code, Codex, GitHub Copilot and Cursor. The knowledge-base MCP and the editor tools are separate npm packages.",
   "author": {
     "name": "Execuro UG (haftungsbeschränkt)",

package/skills/sw-design-requirements/SKILL.md

@@ -28,16 +28,18 @@ Tech decisions belong to `sw-design-solution`. Consult `sw-shopware-architect` (
 | Path to `specs/NNNN-*.md` | **Continue mode** — load, keep its number, advance |
 | Any other file path, or free text | **New PRD** — used as source brief |
 | Nothing | Ask for the feature in one sentence, then proceed |
-| `<path> --editor` | **Editor hand-off** — step 0 checks the optional `sw-specs-editor` skill is installed, then invokes it on `<path>` and stops. Nothing else runs. The session edits the PRD only; the tech spec, if it exists, is reference only and has its own session. A `-spec.md` path is refused here. |
+| `<path> --editor` | **Editor hand-off** — step 0 checks the optional `sw-specs-editor` skill, invokes it on `<path>`, stops; nothing else runs. The session edits the PRD alone — the tech spec is reference only, with its own session. A `-spec.md` path is refused. |
 | `<path> --editor-session <url> --batch <file>` | **Editor mode** — continue mode driven by one note batch; see `reference/editor-mode.md` in this skill's directory. |
 
 Images, notes, tickets, transcripts count as sources; extract requirements, discard narrative.
 
 ## Procedure
 
-### 0. Editor flags
+### 0. Flags and preconditions
 
-`--editor` → run the gate in `reference/editor-gate.md` in this skill's directory first; the Specs Editor is optional and may not be installed, in which case stop there. Available → call Skill `sw-specs-editor` with the PRD path, stop; nothing else runs. `--editor-session` → continue mode under `reference/editor-mode.md` in this skill's directory.
+`--editor` → the gate in `reference/editor-gate.md` in this skill's directory settles it, hand-off or stop; nothing else runs. `--editor-session` → continue mode under `reference/editor-mode.md` in this skill's directory.
+
+Then *Preconditions* in `reference/consistency-probes.md`: probe `vendor/` and the KB before writing anything — either missing stops the run.
 
 ### 1. Establish the target file
 
@@ -91,7 +93,7 @@ Work through `reference/readiness-and-report.md` in this skill's directory: appl
 
 All under `reference/` in this skill's directory:
 
-- `reference/consistency-probes.md` — step 2: what counts as a conflict, where to look, the KB stock-behaviour lookup
+- `reference/consistency-probes.md` — step 0's preconditions; step 2: conflicts, where to look, the KB stock-behaviour lookup
 - `reference/prd-template.md` — step 3: section structure to fill
 - `reference/splitting-guidelines.md` — steps 3 and 6: when one PRD should have been two
 - `reference/clarification-loop.md` — step 4: the question loop, recommended-option rules, anchoring answers

package/skills/sw-design-requirements/reference/clarification-loop.md

@@ -6,11 +6,11 @@ Interactive by default; skip if unattended or the user asked for no questions
 
 Loop: ask the user with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`, which is non-blocking outside Plan mode — so end the turn after asking), up to 4 questions/round, 2–4 options each with a short consequence, ranked by confidence unlocked. Max 3 rounds, rest → §11. Contradictions with a prior answer, PRD, plugin, or stock Shopware: explicit choice quoting both sides (stock cites sw-product-manager's evidence).
 
-**Recommended options must be advised — mandatory.** Never mark `(recommended)` on your own judgement; an agent recommends, this skill only records.
+**Recommended options must be advised — mandatory.** Never mark `(recommended)` on your own judgement; an agent recommends, this skill only records. In editor mode that happens in the run that raises the question — see *Editor mode*, *Advice is part of raising a question*.
 - `sw-product-manager` always advises; `sw-shopware-architect` too when options differ in feasibility/platform depth, per *Architect advisor*.
 - One batched brief per agent per run, covering every question it advises on — never one spawn per question. PRD path, questions, options verbatim, (architect only) detected version; ask for the option and one-line reason.
 - Note form: `[<agent>] <stance>: <reason>`, under its option; the recommended option always has one; a note under the question only when nothing is recommended.
-- Disagree → keep `sw-product-manager`'s mark, both notes. No advice → no mark, `[pm] no recommendation — business preference`.
+- Disagree → keep `sw-product-manager`'s mark, both notes. Exactly two unadvised states are legal, both written out: `[pm] no recommendation — business preference` (the agent advised and declined) and `[user] raised on the page — advice not requested` (the user's own question, editor mode). A question carrying neither a `(recommended)` option nor one of those notes is a defect, not a state.
 - Interactive: identical — a "(Recommended)" option needs the same advice, stated in its consequence line.
 
 **Anchoring answers — mandatory.** Never a quote, Q&A pair, or transcript — rewrite into the PRD's own voice, in the section it belongs:

package/skills/sw-design-requirements/reference/consistency-probes.md

@@ -2,6 +2,20 @@
 
 Run before drafting. Every conflict becomes a clarification question — never a silent assumption, never a resolution you pick yourself.
 
+## 0. Preconditions (step 0, before anything is written)
+
+**Probe what this run is about to use, never the whole environment.** Two things, both load-bearing for every probe below:
+
+- `vendor/shopware/core/composer.json` exists — the version-matched cross-check in probe 4 has nothing to stand on without it.
+- One `mcp__ShopwareDevKnowledgeBase__kb_status` reports `platform` as `implemented` — probe 6 is the stock-behaviour lookup.
+
+Either missing → **stop**, write nothing, one line naming the fix:
+
+> `vendor/` is not installed. Run `sw-setup`, then re-run this skill.
+> The ShopwareDevKnowledgeBase MCP is not available. Run `sw-setup`, then re-run this skill.
+
+Never invoke `sw-setup` from here, never fix it yourself, never ask about it: surveying and repairing the environment is its own run, up front, and it costs an `npx` registry resolution plus twelve rows to answer these two. Nothing else is probed — no other row of that table can affect a PRD run. In an editor session the stop still has to release the document: post that line as the run's reply and change nothing.
+
 ## 1. Against earlier answers in this PRD
 
 Continue mode: re-read §12 Clarification Log and §5 before writing. A new answer that contradicts a logged decision is a conflict, not an update.
@@ -62,4 +76,4 @@ Internal contradictions are fixed by editing, not by asking — unless the fix c
 `platform/func` only; `platform/dev` off limits.
 - Once per run: `read_doc { path: "platform/index.md" }`.
 - Per feature noun: `grep_docs { pattern: "<noun>", path: "platform/func" }`, read the page; try `platform/synonyms.md` when empty.
-- Use results only to name stock features and raise a conflict question quoting the doc path — never an FR, §9 line, or design hint. `platform` not `implemented`, or unavailable → say so once, use the `vendor/` grep.
+- Use results only to name stock features and raise a conflict question quoting the doc path — never an FR, §9 line, or design hint. Step 0 already established that the KB answers; a call that fails after that is a stop naming `sw-setup`, not a silent fallback.

package/skills/sw-design-requirements/reference/editor-mode.md

@@ -6,10 +6,12 @@ Invoked as `<prd path> --editor-session <url> --batch <batch.json>` — one note
 - **No terminal questions.** Never invoke a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`). Every gap becomes a §11 question block (`**Q-n**`, 2–4 `- [ ]` options, one `(recommended)`), notes per *Recommended options must be advised*. Max 6/run, ranked by confidence.
 - **Batch input**: read ticks first — a tick with no note is still an answer. Per note: `answer` or `[x]` tick (own answer `- [x] ✎ text`) → anchor per *Anchoring answers*, append §12, delete block. `comment`/`free` → this run's briefing (block-bound: `path`, `line`–`endLine`, verify `md`/`hash`, fall back to `quote`, honour `selection`). `diagram` → update the graph file (below). Technical note → the spec is **read-only** here, a separate session's document: read it — `batch.reference.path` — to check whether a requirement change invalidates something already specified, and say so in the reply; never edit it, never emit against it. Report that it belongs to the spec session (`sw-design-solution <spec path> --editor`) and change nothing in the PRD beyond a §10 `[decision]`/`[constraint]` bullet the user asserted.
 - **Full pass on request only.** A review request ("check the whole PRD", "reconcile") runs the full flow: step 2, §11 gap review, missing options/marks/notes filled. Otherwise touched questions get options.
-- **Scoped agent runs.** Spawn `sw-product-manager`/`sw-shopware-architect` only when a note touches feasibility, §10, or a §11 block changes (one brief per run); else edit, anchor, log alone. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: anchor, log, re-score, reply. No spawn and no step 2; the user is waiting on the page for what is a bookkeeping run.
+- **Scoped agent runs.** Spawn `sw-product-manager`/`sw-shopware-architect` only when a note touches feasibility, §10, or a §11 block changes (one brief per run); else edit, anchor, log alone. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: no step 2 and no research spawn, the user is waiting on the page for what is a bookkeeping run.
+- **Advice is part of raising a question, not a later phase.** A §11 block this run raises is advised before the run finishes — every batch, a light one included. *Light batch* drops step 2 and the research spawn, never the advisory spawn, and never wins over this rule: an answers-only batch is exactly the batch that raises the next round, so its questions are the ones that must not be born unadvised. Never ask the user to request a recommendation.
+- **Reply first, then advise.** 1. `emit chat` the anchored report — changed blocks, answers, new score — so the page has it while the advisor runs; the run stays active. 2. `emit progress "advising Q-16–Q-19"`. 3. One batched advisory brief per agent, one message: question sentences and options verbatim, PRD path, detected version; ask for the option and a one-line reason — a verdict, not research, and never one spawn per question. `sw-product-manager` advises every raised question, `sw-shopware-architect` in addition where the options differ in feasibility or platform depth or the question is a §10 decision. 4. Write the `(recommended)` mark and the `[<agent>]` notes per *Recommended options must be advised*. 5. `emit done` with the final report.
 - **Preserve on every write:** status tags on item ids (`- **FR-3** [done] …`, also `AC-n`/`BR-n`), the `Diagram:` line, the §11 question blocks and ticks. Rewrite in place; never regenerate.
 - **Diagrams.** Domain diagram: `specs/NNNN-slug.domain.graph.json` (business concepts only). Write/update, run `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest diagram specs/NNNN-slug.domain.graph.json specs/NNNN-slug.domain.excalidraw`, ensure §4 carries `Diagram: specs/NNNN-slug.domain.excalidraw`; never write `.excalidraw` directly, first request only.
 - **Progress.** Before each step, before/after each spawn: `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit progress "<step>" --batch <id> --doc <prd path>` (`--doc` is the document path: it names the session, and a feature's PRD and spec are two of them). Keep them few and short — one line per phase, under ~60 characters, no per-tool narration (`reading notes`, `checking feasibility`, `rewriting §4`). They are the page's only sign of life while a spawn runs, not a log.
-- **Report:** changed blocks, answers (Q ids → anchor), top remaining gap or `none`, confidence %, status, `Agents: <list or none>`.
+- **Report:** changed blocks, answers (Q ids → anchor), top remaining gap or `none`, confidence %, status, `Advised: <Q ids> (<agents>)` or `Advised: none`, `Agents: <list or none>`. The last two are mandatory every run, not only when an agent ran.
 
 Graph shape (`bin/cli.mjs diagram` input): `{ "title", "direction": "LR", "groups": [{id,label}], "nodes": [{id,label,type: entity|actor|service|external|event|store, group?, note?}], "edges": [{from,to,label?}] }`.

package/skills/sw-design-solution/SKILL.md

@@ -20,8 +20,8 @@ Answers **how**, never **what**/**why**. Never re-litigate, question, or change
 | --- | --- |
 | `specs/NNNN-slug-spec.md` | **Continue mode** — load, keep its number, advance |
 | `specs/NNNN-slug.md` (a PRD) | **New spec** — PRD is the source of truth |
-| Nothing | Ask for the PRD path |
-| `<path> --editor` | **Editor hand-off**, first reference file below. The path may be the PRD or the spec; it always resolves to `specs/NNNN-slug-spec.md`, created from the template if missing, and the session edits the spec only — the PRD is reference only, with its own session |
+| Nothing | Ask for the PRD path — a tech spec is always written from one (§0.5) |
+| `<path> --editor` | **Editor hand-off**, first reference file below. The path may be the PRD or the spec; it always resolves to `specs/NNNN-slug-spec.md`, **drafted in the terminal first** when that file is missing or has no ACs yet, then opened automatically. The session edits the spec only — the PRD is reference only, with its own session |
 | `<path> --editor-session <url> --batch <file>` | **Editor mode** — see `reference/editor-mode.md` |
 
 ## Procedure
@@ -30,7 +30,7 @@ Then work through the reference files in this skill's directory, in order:
 
 | File | When | What it decides |
 | --- | --- | --- |
-| `reference/pre-check-and-target.md` | before touching the target file | editor flags, the `sw-setup` pre-check, and how to establish the spec file |
+| `reference/pre-check-and-target.md` | before touching the target file | editor flags, the two preconditions a run cannot work without, and how to establish the spec file |
 | `reference/research-and-evidence.md` | after reading the PRD | version detection, KB lookups, the evidence rules, and the architecture guidelines pass |
 | `reference/draft-and-spawn.md` | drafting the spec | architect/QA spawn briefs, merging their output, spot-checks, and cross-AC dependencies |
 | `reference/toolchain-conformance.md` | while drafting, before finalizing | writing the spec so code conforms to Shopware's linters/static analysis on first write |

package/skills/sw-design-solution/reference/clarification-loop.md

@@ -10,4 +10,6 @@ Ask only if the answer changes architecture, data model, or test strategy; other
 
 Loop: ask the user with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`, which is non-blocking outside Plan mode — so end the turn after asking), ≤ 4 questions/round, 4 options each with a consequence, one recommended. Rank by unblock impact. Max 3 rounds; rest → **Open Questions**.
 
+**Recommended options must be advised — mandatory.** Never mark `(recommended)` on your own judgement; an agent recommends, this skill only records. `sw-shopware-architect` advises; `sw-product-manager` too where an option turns on stock Shopware behaviour. One batched brief per agent per run covering every question it advises on — never one spawn per question: spec path, questions and options verbatim, version + evidence; ask for the option and a one-line reason. Note form `[<agent>] <stance>: <reason>` under its option; the recommended option always has one. Disagree → keep the architect's mark, both notes. Advised and declined → no mark, `[architect] no recommendation — project preference`. **Exception:** `[adr]` and `[gate]` blocks carry pre-canned options and need no spawn. In editor mode the advice happens in the run that raises the question — see *Editor mode*.
+
 **Anchoring — mandatory.** Never a quote/transcript — rewrite into the spec's own voice, plus one **Decision Log** line (topic, decision, date). Answer invalidates existing text → edit it, log the supersession.

package/skills/sw-design-solution/reference/editor-mode.md

@@ -4,13 +4,15 @@ Entered when invoked as `<spec path> --editor-session <url> --batch <batch.json>
 
 Same procedure/boundary/verification/ADR rules, plus:
 
-- **Scoped.** Nothing on open. Continue mode: read the batch first, run step 3 only for touched mechanisms, edit only named blocks plus invalidated ones, re-evaluate §7 — no re-verification/new §6 for untouched ACs. Full pass only on an explicit review or draft request, **or when the spec is still the untouched skeleton §0 wrote** (no ACs in §3) — that first batch runs the complete flow, step 0.5 and version detection included.
-- **No terminal questions.** Never ask via a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`). Every ask → §6 block: `**Q-n**`, 2–4 `- [ ]` options, one `(recommended)`, agent notes `  - [<agent>] <stance>: <reason>` under the judged option. Max 6/run. Tags: `[adr] <title>` → `A: Extract` / `B: Keep`; `[gate] Open ADRs <ids>` → `A: Wait (recommended)` / `B: Override`; step-0.5's two `[gate]` titles verbatim → `A: Bootstrap first (recommended)` / `B: Proceed unverified`. Unanswered `[gate]` → *In progress*, never auto-override.
-- **Batch input.** Ticks first — a ticked question with no note is still an answer. `answer`/`[x]` tick → anchor, append Decision Log, delete block (`[adr]` sub-step 3, `[gate]` sub-step 5). `comment`/`free` → this run's briefing (block-bound `path`/`line`–`endLine`/`md`/`quote`/`hash`; verify `md` matches, fall back to `quote`; `selection` → rework only that text). `diagram` → update the graph file. *What*/*why* notes belong to the PRD: read it freely — `batch.reference.path` — as the source of truth for reconciliation, but it is **read-only** here, a separate session's document. Never write it, never anchor an answer into it, never emit against it; report the note in the reply ("this changes FR-4 — take it to the PRD session, `sw-design-requirements <prd path> --editor`") and change nothing. First write migrates a pre-template spec or §0's skeleton; blocks get missing options only when touched.
-- **Scoped runs.** Re-spawn architect only for an overturned/new decision, QA only for a changed test plan, `sw-product-manager` only for feasibility — together still one message; else edit/verify/anchor/log alone, name agents. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: anchor, log, reply. No spawn and no step 3; the user is waiting on the page for what is a bookkeeping run.
+- **Scoped.** Nothing on open. Continue mode: read the batch first, run step 3 only for touched mechanisms, edit only named blocks plus invalidated ones, re-evaluate §7 — no re-verification/new §6 for untouched ACs. Full pass only on an explicit review or draft request, **or when the spec still has no ACs in §3** (§0 drafts before hand-off, so that is a fallback) — that batch runs the complete flow, step 0.5 and version detection included.
+- **No terminal questions.** Never ask via a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`). Every ask → §6 block: `**Q-n**`, 2–4 `- [ ]` options, one `(recommended)`, agent notes `  - [<agent>] <stance>: <reason>` under the judged option. Max 6/run. Tags: `[adr] <title>` → `A: Extract` / `B: Keep`; `[gate] Open ADRs <ids>` → `A: Wait (recommended)` / `B: Override`. Unanswered `[gate]` → *In progress*, never auto-override.
+- **Batch input.** Ticks first — a ticked question with no note is still an answer. `answer`/`[x]` tick → anchor, append Decision Log, delete block (`[adr]` sub-step 3, `[gate]` sub-step 5). `comment`/`free` → this run's briefing (block-bound `path`/`line`–`endLine`/`md`/`quote`/`hash`; verify `md` matches, fall back to `quote`; `selection` → rework only that text). `diagram` → update the graph file. *What*/*why* notes belong to the PRD: read it freely — `batch.reference.path` — as the source of truth for reconciliation, but it is **read-only** here, a separate session's document. Never write it, never anchor an answer into it, never emit against it; report the note in the reply ("this changes FR-4 — take it to the PRD session, `sw-design-requirements <prd path> --editor`") and change nothing. First write migrates a pre-template spec or an AC-less stub; blocks get missing options only when touched.
+- **Scoped runs.** Re-spawn architect only for an overturned/new decision, QA only for a changed test plan, `sw-product-manager` only for feasibility — together still one message; else edit/verify/anchor/log alone, name agents. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: no step 3 and no verification spawn, the user is waiting on the page for what is a bookkeeping run.
+- **Advice is part of raising a question, not a later phase.** A §6 block this run raises is advised before the run finishes — every batch, a light one included. *Light batch* drops step 3, never the advisory spawn, and never wins over this rule: an answers-only batch is exactly the batch that raises the next round, so its questions are the ones that must not be born unadvised. Never mark `(recommended)` on your own judgement — an agent recommends, this skill records. **Exception:** `[adr]` and `[gate]` blocks keep the pre-canned options above (`A: Extract`, `A: Wait (recommended)`) and need no spawn; they are procedure, not judgement.
+- **Reply first, then advise.** 1. `emit chat` the anchored report — changed blocks, answers, §7 — so the page has it while the advisor runs; the run stays active. 2. `emit progress "advising Q-7–Q-9"`. 3. One batched advisory brief per agent, one message: question sentences and options verbatim, spec path, version + evidence; ask for the option and a one-line reason — a verdict, not research, and never one spawn per question. `sw-shopware-architect` advises every raised question, `sw-product-manager` in addition where an option turns on stock Shopware behaviour; QA keeps its own trigger. 4. Write the `(recommended)` mark and the `  - [<agent>] <stance>: <reason>` notes; disagreement → keep the architect's mark, both notes. Advised and declined → no mark, `[architect] no recommendation — project preference`; the user's own question → `[user] raised on the page — advice not requested`. 5. `emit done` with the final report.
 - **Preserve:** status tags (`- **AC-2** [partly] (FR-3)`, `- **Decision:** [done] …`), `Diagram:` line, §6 blocks/ticks — rewrite in place, never regenerate.
 - **Diagrams.** `specs/NNNN-slug-spec.architecture.graph.json`; run `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest diagram specs/NNNN-slug-spec.architecture.graph.json specs/NNNN-slug-spec.architecture.excalidraw`, keep §2's `Diagram:` line — never write it directly.
 - **Progress.** `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit --since <step-0.5 start> progress "<step>" --batch <id> --doc <spec path>` (`--doc` is the document path: it names the session, and a feature's PRD and spec are two of them) before/after each step/spawn; `--since` prefixes `+m:ss`. Keep them few and short — one line per phase, under ~60 characters, no per-tool narration. They are the page's only sign of life while a spawn runs, not a log.
-- **Report:** changed blocks; answers (Q ids → anchor); first unmet §7 criterion or `none`; status/confidence/`Open ADRs`; `Agents: <list or none>`; `Timing:`.
+- **Report:** changed blocks; answers (Q ids → anchor); first unmet §7 criterion or `none`; status/confidence/`Open ADRs`; `Advised: <Q ids> (<agents>)` or `Advised: none`; `Agents: <list or none>`; `Timing:`. Advised and Agents are mandatory every run, not only when an agent ran.
 
 Graph shape: `{ title, direction: "LR", groups: [{id,label}], nodes: [{id,label,type: entity|actor|service|external|event|store,group?,note?}], edges: [{from,to,label?}] }`.

package/skills/sw-design-solution/reference/pre-check-and-target.md

@@ -1,27 +1,40 @@
 # Pre-check and target file
 
-Entered before touching the target file. Decides how to handle `--editor`/`--editor-session` flags, the setup pre-check, and how to establish the spec file to write.
+Entered before touching the target file. Decides how to handle `--editor`/`--editor-session` flags, what this run must have before it starts, and how to establish the spec file to write.
 
 ### 0. Editor flags
 
-`--editor` → **first action**, in this order. An editor session edits **one** document and is named from its filename, so the target has to be the *spec* path and the file has to exist before the page opens.
+`--editor` → **first action**, in this order. An editor session edits **one** document and is named from its filename, so the target has to be the *spec* path, and the page only opens on a spec that already says something.
 
 1. **Resolve to the spec path.** `…-spec.md` → that is it. `specs/NNNN-slug.md` (a PRD) → `specs/NNNN-slug-spec.md`, same `NNNN`/slug, per §1's one-spec-per-PRD rule. Anything else → stop with one line naming the two shapes.
-2. **Gate, before creating anything.** Is the `sw-specs-editor` skill available? It is an optional add-on, installed by `sw-setup`, not part of this plugin. Not available → **stop here** with one line — "The Specs Editor is not installed. Run `sw-setup` to add it, or re-run without `--editor`." — and do not fall back to non-editor mode, and do not leave a skeleton behind for a page that will never open.
-3. **Spec missing → write the skeleton.** Copy `reference/tech-spec-template.md`, section numbers and titles verbatim, every body `_TBD_`; fill only `PRD: specs/NNNN-slug.md`, `Status: In progress`, `Confidence: 0%`, `Updated: <today>`. Still no PRD/spec read, no version detection, no lookup, no agent spawn, no AC drafting — this is a deterministic file write, a file to open, not a first draft.
-4. **Hand off with the spec path** and stop.
-5. If step 3 created the file, add one line: "Created the spec skeleton at `<path>`. Send a note on the page — e.g. 'draft the spec' — to fill it."
+2. **Gate, before any work.** Is the `sw-specs-editor` skill available? It is an optional add-on, installed by `sw-setup`, not part of this plugin. Not available → **stop here** with one line — "The Specs Editor is not installed. Run `sw-setup` to add it, or re-run without `--editor`." — do not fall back to non-editor mode, and never spend a draft on a page that will never open.
+3. **Preconditions, still before any work.** §0.5's probes. Either missing → **stop** with its one line: nothing is drafted, no skeleton is written and no page is opened, exactly as for a missing Specs Editor.
+4. **Branch.** At least one AC block in §3 → already drafted: report `Opening <path> — <status>, <N>/5`, hand off at once, never re-draft. Otherwise → step 5 first.
+5. **Draft it first, in the terminal, before the page.** Run the normal flow end to end — §1, *Research and evidence*, *Draft* (both spawns), *Toolchain conformance*, *ADR flow*, *Readiness* — so §1–§5 and §7 carry real content and a real confidence the moment the page opens; a scored first draft is the target, not *Ready for implementation*. Two deviations, because the user answers on the page and not here: a structured question tool (`AskUserQuestion`, `request_user_input`) is **forbidden**, so *Clarification loop*'s rounds and *ADR flow* sub-steps 2 and 5 become advised §6 `**Q-n**` blocks in *Editor mode*'s shape; and progress is one short plain terminal line per phase — no session exists yet, so nothing is emitted, polled or started here.
+6. **Report one line, then hand off** — `Drafted <path> — <status>, <N>/5, §6: <M> question(s)` — and hand off to `sw-specs-editor` with the spec path. Automatic: `--editor` is the consent, never ask whether to open it.
 
 The Specs Editor opens the page and waits; this skill runs again (*Editor mode*) only when the user sends notes. The PRD is **not** part of that session: it is reference only, and business changes go back to its own session (`sw-design-requirements <prd path> --editor`). `--editor-session` → run the procedure below under *Editor mode*, scoped to the batch.
 
-### 0.5 Pre-check
+### 0.5 Preconditions
 
-Once, before touching the target file. Note the ISO start time (`date -u +%Y-%m-%dT%H:%M:%SZ`) — step 8's Timing line and editor progress prefixes use it. In editor mode it runs on the **first batch**, not on the hand-off: §0's skeleton write precedes it and reads nothing.
+Once, before touching the target file. Note the ISO start time (`date -u +%Y-%m-%dT%H:%M:%SZ`) — step 8's Timing line and editor progress prefixes use it. Under `--editor` it runs at §0 step 3, before the draft; when §0 handed off without drafting, the first batch runs it instead.
 
-- **Check:** invoke `sw-setup` once; rows vendor/ and KB MCP must be ticked. Never proceed past an unticked row without the user's answer.
-- **Terminal, on failure:** the setup skill's own question settles it — declined → proceed with `(unverified — vendor/ not installed)` / `(unverified — KB unavailable)`, blocks readiness, as before.
-- **Editor mode:** failure → `[gate] vendor/ is not installed` / `[gate] ShopwareDevKnowledgeBase MCP is not available`, `A: Bootstrap first (recommended)` / `B: Proceed with unverified decisions`, fix text names `/sw-setup`. Unanswered → *In progress*.
+**Probe what this run is about to use, never the whole environment.** Three things, all of which this skill genuinely cannot work correctly without:
+
+- **The source PRD** — the file this spec is written from: the path given, or in continue mode the one the spec's header names. It has to exist on disk; a well-formed path is not a file.
+- **`vendor/`** — `vendor/shopware/core/composer.json` exists. It is the same file *Research and evidence*'s version detection reads, so read it once and use it for both.
+- **KB MCP** — one `mcp__ShopwareDevKnowledgeBase__kb_status`; `platform` must be `implemented`.
+
+Any of the three missing → **stop**, write nothing, one line naming the fix:
+
+> `<path>` does not exist. A tech spec is written from a PRD — create one with `sw-design-requirements`, then re-run this skill.
+> `vendor/` is not installed. Run `sw-setup`, then re-run this skill.
+> The ShopwareDevKnowledgeBase MCP is not available. Run `sw-setup`, then re-run this skill.
+
+Never invoke `sw-setup` or `sw-design-requirements` from here, never fix it yourself, never ask about it, and never offer to proceed unverified — surveying the environment and writing requirements are those skills' own runs, and both cost far more than these three probes. Nothing else is checked here: Node, `shopware-cli`, the acceptance-test project, Playwright, plugin tests, the wiki and package updates cannot affect a design run.
+
+In an editor session the stop still has to release the document: post that one line as the run's reply (`emit done`) and change nothing in the spec.
 
 ### 1. Establish the target file
 
-New spec: `specs/NNNN-slug-spec.md`, reusing the PRD's `NNNN`/`slug` — one per PRD. Create from `reference/tech-spec-template.md` in this skill's directory, section numbers/titles unchanged. In editor mode §0 already established (and may have skeletoned) this file; the first batch migrates a skeleton exactly as it migrates a pre-template spec. Header: PRD path, `shopware/core` version + KB directory, plugin (`custom/plugins/<Name>`, `<Vendor>\<Name>`, existing domain plugin or new one named after the feature's domain). Plugin never `_TBD_` at readiness. Continue mode: keep path, never renumber/duplicate; pre-template spec → migrate this run, say so in the report.
+New spec: `specs/NNNN-slug-spec.md`, reusing the PRD's `NNNN`/`slug` — one per PRD. Create from `reference/tech-spec-template.md` in this skill's directory, section numbers/titles unchanged. Under `--editor` §0 step 5 already created and drafted this file; one that reached the page untouched migrates on first write. Header: PRD path, `shopware/core` version + KB directory, plugin (`custom/plugins/<Name>`, `<Vendor>\<Name>`, existing domain plugin or new one named after the feature's domain). Plugin never `_TBD_` at readiness. Continue mode: keep path, never renumber/duplicate; pre-template spec → migrate this run, say so in the report.

package/skills/sw-design-solution/reference/research-and-evidence.md

@@ -10,7 +10,7 @@ Every `FR-n` and AC — the fixed contract, never added, removed or reinterprete
 
 **Shopware version — detect once, never assume:** `vendor/shopware/core/composer.json` `version` → `composer.lock` → `composer.json` constraint ("unconfirmed"); PHP from the project runtime (`compose.yaml`, `.ddev/config.yaml`, `Dockerfile`), not the host. Pass version + source to every spawned agent; unknown → ask the user.
 
-Per central mechanism, one `mcp__ShopwareDevKnowledgeBase__grep_docs { pattern: "<mechanism>", path: "platform/dev/<version>", mode: "files" }` — candidate KB paths only, never `read_doc`/`list_docs` a version directory (~340 KB index). Hand paths to the architect, which reads full pages and verifies; empty grep → `platform/synonyms.md`, then `platform/hubs`. `vendor/` missing → step 0.5 already asked; `(unverified — vendor/ not installed)` applies only after the user chose to proceed.
+Per central mechanism, one `mcp__ShopwareDevKnowledgeBase__grep_docs { pattern: "<mechanism>", path: "platform/dev/<version>", mode: "files" }` — candidate KB paths only, never `read_doc`/`list_docs` a version directory (~340 KB index). Hand paths to the architect, which reads full pages and verifies; empty grep → `platform/synonyms.md`, then `platform/hubs`.
 
 Evidence rules, carried in every step-4 brief:
 1. **Live call site, not a fixture, same shape.** DI/service registration, a call site, or a passing test assertion — never a `*/Test*/**` class only a test instantiates; verified only by a live usage of the same shape of change (an `EntityExtension` adding associations doesn't verify one adding a scalar field). Fixture-only or no same-shape usage = unverified, raise it.

package/skills/sw-design-solution/reference/tech-spec-template.md

@@ -37,7 +37,7 @@ _Source: `sw-shopware-architect`'s report, verified in-agent per its evidence ru
 | <!-- one line, "what will exist" --> | <!-- event/subscriber, tag, route, decoration target --> | <!-- entity/field/migration, or "none" --> | <!-- upgrade risk, performance, coupling, testability --> | <!-- file:line citation, or "per official docs: '<sentence>'" — never a bare link, never a fixture/Test-folder class with no call site --> |
 
 **Verified assumptions:** <!-- mechanisms confirmed by real usage + docs, one line each -->
-**Unverified / at risk:** <!-- anything marked `(unverified — vendor/ not installed)` or `(unverified — static citation only)` — must also appear in §6 as an open question -->
+**Unverified / at risk:** <!-- anything marked `(unverified — static citation only)` — must also appear in §6 as an open question -->
 
 <!-- Optional, added by the Specs Editor on first request — keep the line exactly in this shape: -->
 <!-- Diagram: specs/NNNN-slug-spec.architecture.excalidraw -->
@@ -90,7 +90,7 @@ Blocks: AC-2
   - [qa] against: one-line reason
 -->
 
-A question earns its place only if it changes architecture, data model, or test strategy, or is a decision still `(unverified — vendor/ not installed)` / `(unverified — static citation only)`. Any open question blocks *Ready for implementation*.
+A question earns its place only if it changes architecture, data model, or test strategy, or is a decision still `(unverified — static citation only)`. Any open question blocks *Ready for implementation*.
 
 Rules: one block per question, a `**Q-n**` line, `[adr]`/`[gate]` tag right after the id for the ADR Extract/Keep and readiness-override asks, optional `Blocks:` line. Options are `- [ ] <Letter>: text`, 2–4 of them, exactly one `(recommended)`. Agent notes are indented `  - [<agent>] text` under the option they judge; a note under the question line only when no option is recommended. An answer is `[x]` on one option, or an own-answer line `- [x] ✎ text`. Older specs (a legacy question table) are converted to this format automatically on the first editor-mode write.
 

package/skills/sw-implement-feature/SKILL.md

@@ -22,9 +22,18 @@ Implement one feature from its technical spec, under TDD, then hand off to full
 
 ### 0. Pre-check
 
-Invoke `sw-setup` once. Rows an AC's tests need — vendor/ (PHPUnit); Acceptance-test project, Playwright browsers, ATS env (e2e); Plugin tests (target plugin) — must be ticked; unticked → stop, tell the user to run `/sw-setup`. Never mark an AC `partly` for a missing environment.
+**Probe what this run is about to use, never the whole environment.** Check only what the ACs in this run actually need, as file existence — never invoke `sw-setup`, which surveys twelve rows behind an `npx` registry call to answer two or three of them:
 
-**Shopware version — detect once, before spawning anything, never assume:** `vendor/shopware/core/composer.json` `version` → `composer.lock` → `composer.json` constraint ("unconfirmed"); PHP from the project runtime (`compose.yaml`, `.ddev/config.yaml`, `Dockerfile`), not the host. State it with evidence in every Agent-tool brief below — implementer spawns, architect escalation, QA e2e runs — so no sub-agent has to re-derive it; a version with no evidence must still be passed on as unconfirmed (e.g. constraint-only), never treated as certain. Unknown → ask the user.
+| This run has… | Probe |
+| --- | --- |
+| any AC | `vendor/shopware/core`, plus `vendor/bin/phpunit` for a PHPUnit AC |
+| an e2e AC | `tests/acceptance/package.json`, `tests/acceptance/playwright.config.ts`, and `tests/acceptance/.env` defining `APP_URL`, `SHOPWARE_ADMIN_USERNAME`, `SHOPWARE_ADMIN_PASSWORD` |
+| an e2e AC | Playwright browsers — the cache directory (`~/.cache/ms-playwright`, or the project-local browsers path). Never `npx playwright install --dry-run`: it reaches the network |
+| a PHPUnit or Jest AC | in the target plugin: `phpunit.xml.dist`, `tests/TestBootstrap.php`, and `jest.admin.config.js` / `jest.storefront.config.js` only for the surface that AC touches |
+
+An API-only feature never probes Playwright. Anything missing → stop, tell the user to run `/sw-setup` — it is the one place the environment is fixed, and this skill neither invokes nor repairs it. Never mark an AC `partly` for a missing environment.
+
+**Shopware version — detect once, before spawning anything, never assume** (the first path is also the vendor/ probe above, so read it once): `vendor/shopware/core/composer.json` `version` → `composer.lock` → `composer.json` constraint ("unconfirmed"); PHP from the project runtime (`compose.yaml`, `.ddev/config.yaml`, `Dockerfile`), not the host. State it with evidence in every Agent-tool brief below — implementer spawns, architect escalation, QA e2e runs — so no sub-agent has to re-derive it; a version with no evidence must still be passed on as unconfirmed (e.g. constraint-only), never treated as certain. Unknown → ask the user.
 
 
 Then work through the three reference files in this skill's directory, in order:

package/skills/sw-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sw-setup
-description: Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki, `.gitignore` and whether the SW AH npm packages are current, plus the installer CLI's own configuration/drift status. Stops when every row is ticked. When rows are missing, asks one yes/no question and delegates the fix to the installer CLI. Use when asked to set up the project, check if the environment is ready, or bootstrap the tests. Never designs, implements or verifies a feature itself — that's sw-design-solution, sw-implement-feature and sw-verify-feature, which call this skill first. Never writes a coding agent's configuration file itself — that's the installer CLI.
+description: Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki, `.gitignore` and whether the SW AH npm packages are current, plus the installer CLI's own configuration/drift status. Stops when every row is ticked. When rows are missing, asks one yes/no question and delegates the fix to the installer CLI. Use when asked to set up the project, check if the environment is ready, or bootstrap the tests. Never designs, implements or verifies a feature itself — that's sw-design-solution, sw-implement-feature and sw-verify-feature; run this one up front, before them. Never writes a coding agent's configuration file itself — that's the installer CLI.
 when_to_use: Trigger phrases — "set up the project", "is the environment ready", "bootstrap the tests", "sw-setup".
 allowed-tools: Read Glob Grep AskUserQuestion Skill Bash mcp__ShopwareDevKnowledgeBase__kb_status Bash(npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest *) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@latest *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest *)
 ---
@@ -28,10 +28,15 @@ question; it never restates or re-implements the install protocol.
 
 ## Called from other skills
 
-`sw-design-solution`, `sw-implement-feature` and `sw-verify-feature` invoke
-this skill as their own first step and read its table; they never repeat
-these checks themselves. A caller passes no arguments and reads the printed
-table from this run's output — it does not re-run `sw-setup`'s checks.
+`sw-verify-feature` invokes this skill once, before spawning, and passes the
+table to its verifiers as `args`; one run standalone invokes it itself. A
+caller passes no arguments and reads the printed table, never re-running it.
+
+`sw-design-requirements`, `sw-design-solution` and `sw-implement-feature` do
+**not** invoke it: each probes only what its own run uses and stops naming
+`sw-setup` when one is missing. A full table is the price of surveying an
+environment, not of one run's prerequisites — so this skill stays the one place
+it is surveyed and fixed, run up front.
 
 ## Procedure