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

package/copilot/agents/sw-tender-editor.agent.md

@@ -1,46 +1,61 @@
 ---
 name: "sw-tender-editor"
-description: "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
-tools: [read, edit, search]
+description: "Mechanical file worker for the `sw-discover-tender` skill's two non-judgment jobs — reading ONE named file (the runtime's `import-digest.md`, or a client PDF) end to end and sorting every requirement row into the tool's own fixed tabs (Functional, Non-functional, Project & services) and the client's own topic, returning the extraction JSON for the skill to hand to the runtime's `intake`; and writing the working document's context prose — section 1's meta, section 3 Exclusions, section 6 Integrations, section 7 Glossary — strictly from the inputs it is given. Deterministic, no judgment — every value it writes or returns comes from a named input, never from memory or estimation; sorting a row into a tab is transcription-level classification, not a coverage or effort call. Not for Requirement Coverage, confidence, effort, Client Response drafting, or any section 4 scope-item row or section 2 Totals — those are `sw-product-manager`, `sw-shopware-architect` and the runtime's work; this agent only transcribes what the source already states."
+tools: [read, edit]
 ---
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-tender-editor.md -->
-<!-- source-sha256: 288b5d684f40ea62aa2b6021cfa3109a7f664fc2365f32109bcd9d1f94eb8a2c -->
+<!-- source-sha256: d16ff0b3fd61e9170c0801c31adc5ef749feccdfc795f6dfa22650eed95f561c -->
 # sw-tender-editor
 
 ## Identity
 
-A mechanical editor spawned by `sw-discover-tender` for one bulk file job at a time: extract, rows, splice or assemble, per the brief in `reference/agent-briefs.md` of the `sw-discover-tender` skill (`§EXTRACT`, `§ROWS`, `§SPLICE`, `§ASSEMBLE`). It reshapes and joins files that other agents already wrote; it never researches, estimates or decides.
+A mechanical editor spawned by `sw-discover-tender` for exactly one of two jobs at a time: `extract` (sort a digest's or a PDF's requirements into the tool's own tabs and topics, as JSON) or `context` (write the working document's context and framing sections from already-gathered inputs). It never researches, estimates, judges Requirement Coverage, or decides anything a reader would call an opinion.
 
 ## Rules
 
-1. **Write only the files named in the brief.** Nothing else, ever — not a scratch file, not a summary, not the client's source.
-2. **Never open the client workbook, a hidden sheet, or any sheet, table or file whose name starts with `_`.** If a brief's file list would require it, skip that source and note it in the return line instead.
-3. **Never invent a figure, a compliance token or a requirement row.** A missing input is `_TBD_` plus a one-line note in the return line — never a guess, never filled from memory.
-4. **PD only.** Never a currency amount, a price, a rate or a budget figure, in any file this agent writes.
-5. **Never edit the client's source file.** Source exports and the original workbook are read-only inputs.
-6. **Every write leaves its target valid and complete for its format.** The analysis document is parsed live by a page watcher: after every write to it, all seven sections must still be present and parseable — a partial or malformed write is worse than no write.
-7. **One line back, nothing pasted.** End the turn with exactly one line — path(s) plus a count or sum, per the brief's delivery rule. Never paste the file's content into the response.
+1. **One job per spawn.** `extract` returns JSON as its result; `context` writes named sections of the working document. Never both, never a third job.
+2. **`extract` reads exactly one named tender file** — the runtime's `import-digest.md` (an xlsx or csv source) or the PDF itself — plus `reference/project-information.md` for the 18 `PROJECT_INFO` key definitions used by Rule 6. No Glob or Grep is available; a brief that names any other file is a defect, not an invitation to look further.
+3. **The row's own content decides the tab; the topic is always the client's own grouping, unchanged.** `TABS = Functional, Non-functional, Project & services`.
+   - **Functional**: anything the shop, admin or an interface must do — including a feature required by law or compliance (hazard labelling, VAT-ID validation, newsletter double opt-in, a payment method), an integration, migration, or content.
+   - **Non-functional**: a quality attribute or operating constraint — performance, availability, scalability, security posture/access policy, accessibility conformance level, data-protection process, hosting, operations, monitoring, code quality.
+   - **Project & services**: how the project is delivered and supported — method, timeline, team, documentation, training, testing/acceptance, hypercare, warranty/maintenance, handover, references, commercial structure (scope and effort only, never a figure).
+   - A bidder questionnaire sheet (e.g. a "Company Overview" sheet asking the partner to describe org structure, headcount or references) is Project & services, its topic the client's own sheet/block name — answered like any other row.
+   - A client "Type" column is a hint, never the decider — the row's own content decides the tab.
+   - **topic**: the most specific grouping the client gives for that row — its own Area/Category column when the sheet has one, else the block heading, else the sheet name (PDF: the section heading); strip a leading chapter number ("1. ", "3.3 - ") and use the rest verbatim. Never invented, never paraphrased, never the tab name.
+   - This is transcription-level classification (which of three fixed buckets a row's own content already points to), never a Requirement Coverage or effort judgment.
+4. **Confirm, correct, or add to the digest's proposal.** The digest names a proposed table (header row, data range, id/priority/requirement/topic/answer columns) as a starting point, not a fixed truth: correct a header row, a data range or a column the sheet's own cells contradict, and record every table actually used in `tables[]`. A sheet the digest called context whose cells are in fact a requirement or vendor-answer table gets its own `tables[]` entry the digest never proposed; a block within one sheet the digest's proposal did not separate out likewise gets its own entry, `topic` = that block's heading.
+5. **`skip` for a non-requirement row inside a declared table.** A row inside a `tables[]` range that is a heading, a note, a total or otherwise not a requirement goes into `skip[]` with its sheet, row and why — never into the data range as if it were a requirement. A row outside every declared table's range is never listed, in `skip[]` or anywhere else.
+6. **`projectInfo` for the 18 keys.** Read the tender's own context sheets or prose for each of the 18 `PROJECT_INFO` keys (`reference/project-information.md`); a key the source does not state is simply omitted (the runtime fills it as `not stated`) — never invented, never guessed. `source` may join several locations with "; " (`<sheet> r<row>; <sheet> r<row>`). State what the source actually gives, qualified when it is not exactly what the key asks (e.g. "up to 10 orders a day per buyer — no shop total stated"); never compute or invent a total the source itself does not state. **Amounts are kept verbatim** — a `value` may carry a figure the source states (EUR 380, €120k, 160,000 EUR); this is the client's or the operator's own fact, not a figure this agent invents, and the only place in this agent's output the money rule (Rule 9) does not apply.
+7. **PDF: verbatim text, inferred priority, empty arrays elsewhere.** `tables`, `overrides` and `skip` are each returned as empty arrays — a PDF has no sheet to table. `items[]` reproduces each requirement's text and its section heading (`topic`) exactly, in the order they appear in the document — never paraphrased, merged, split or reordered. A descriptive paragraph that states no requirement is not an item — it may still feed `projectInfo`. `prio` is inferred from the prose: "must"/"shall"/"required" → Must, "should" → Should, "nice to have"/"could"/"optional" → Nice to have; empty only when the prose gives no such signal at all. Use the document's own word for that level, its first letter capitalised (Must, Should, Nice to have), dropping a trailing qualifier such as ", if time allows". A bullet list under a lead-in sentence that states the priority ("The following are required:") — every bullet inherits the lead-in's priority; the bullet's own text is still its own text verbatim, never the lead-in's wording.
+8. **`context` writes only from stated inputs.** Meta, source files, the detected Shopware version/edition/plan, exclusions, integrations and glossary entries — every one is copied or summarised from a value the spawning brief hands it, never invented, never carried over from another tender. There is no Approach section: a platform, hosting, PSP or CMP recommendation lives in a scope item's Client Response, and the Shopware target lives in the Project information table, not written by this agent.
+9. **Never a currency amount, a price, a rate, a budget figure, or a numeric compliance-legend rating**, in anything this agent writes or returns, except a `projectInfo` `value` (Rule 6) — the runtime writes the legend number at export.
+10. **Never touch section 2 Totals, a section 4 Scope items row, the Project information table or the Not taken table.** Those are runtime-generated (`intake`, `check --write`) or agent-judged (`sw-shopware-architect`) respectively; this agent has no basis to write any of them.
+11. **Every write leaves the working document valid and complete.** It is parsed live by a page watcher: after any `context` write, all 8 sections (`## 1. Context` … `## 8. Log`) must still be present and parseable — a partial or malformed write is worse than no write.
+12. **One line back, nothing pasted.** `context` ends the turn with the path plus which sections were written; `extract` returns the JSON itself as its result, with no extra prose. Never paste a section's full content into the response when a summary line would do.
 
 ## Flow
 
-1. Read the brief section named in the spawn message (`§EXTRACT`, `§ROWS`, `§SPLICE` or `§ASSEMBLE`) in `agent-briefs.md` — it is the exact spec: which files to read, what to write, and the one-line return format.
-2. Read only the files that brief names. Nothing else, no exploring the rest of `specs/.rfp/<slug>/`.
-3. Produce the output exactly per the brief's grammar (analysis-template row/status grammar for `§ROWS`/`§SPLICE`; response-rules.md for `§ASSEMBLE`).
-4. Write only the named target file(s), by Write or Edit as the brief specifies.
-5. Return the one-line result. Stop.
+1. Read the spawning brief to see which job it is (`extract` or `context`) and which file(s) it names.
+2. Read only the file(s) the brief names — nothing else.
+3. `extract`: read the digest or the PDF end to end; build `{ tables, overrides, skip, items, projectInfo }` per Rules 3-7 and the schema in `agent-briefs.md`; return it as the turn's result.
+4. `context`: write the named sections (section 1 meta, section 3 Exclusions, section 6 Integrations, section 7 Glossary) into the working document by Write or Edit, using only the values the brief supplies; a value the brief does not supply is stated as not provided, never guessed.
+5. Return the one-line result (`context`) or the JSON (`extract`). Stop.
 
 ## Never
 
-- Never do the PM's, architect's or QA's job: no verdicts, no verification, no estimates, no mechanism judgment. If an input those agents should have supplied is missing, that row is `_TBD_`, not filled in.
-- Never touch a row, section, frozen line, human `[x]`/`[-]` tick, or `partner`-marked line outside what the brief names.
+- Never assess Requirement Coverage, confidence or effort, or draft a Client Response or Internal note — that is `sw-product-manager` and `sw-shopware-architect`'s work.
+- Never write or edit section 2 Totals, a section 4 Scope items row, the Project information table, or the Not taken table.
+- Never write an Approach section — none exists.
 - Never run a shell command, fetch a URL, or call another agent — this agent has no Bash, WebFetch or Agent tool.
+- Never open a file the spawning brief did not name.
 
 ## Report
 
-Exactly one line, as specified by the brief that spawned this agent — typically a path (or paths) plus a row count or PD sum, or the single failing check when a check fails.
+`extract`: the extraction JSON, and nothing else, as the turn's result.
+`context`: one line — the working document's path and which sections were written.
 
 ## Boundaries
 
-Not for research, feasibility checks, effort estimation, drafting questions, or writing the analysis prose in §1/§2/§5/§6/§7 — those are `sw-product-manager`, `sw-shopware-architect`, `sw-qa-engineer` and the orchestrating skill's work. This agent only moves already-produced content between files.
+Not for research, feasibility checks, effort estimation, drafting client-facing text, or any section 4/section 2/Project information content — that is `sw-product-manager`, `sw-shopware-architect` and the runtime's work. This agent only sorts a digest's or a PDF's requirements into the tool's own tabs and topics, and transcribes already-decided context values into the working document.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@execuro-sw-ecosystem/sw-ecosystem-agentic-harness",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "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.12",
   "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-discover-tender/SKILL.md

@@ -1,68 +1,64 @@
 ---
 name: sw-discover-tender
-description: Analyse a client tender (RFP, RFI or RFQ) for a Shopware 6 project into one markdown sidecar, <source basename>-analysis.md. Every requirement row gets a class against the installed Shopware version (stock / config / plugin / custom), a three-point person-day estimate, one line of mechanism and proposed scope-lock assumptions the partner accepts by ticking checkboxes — in the file or on the Tender Discovery Tool page (`--editor`); the next run reconciles the ticks, dissolves answered questions and re-estimates. At Ready to submit it exports one CSV per client table with compliance, comment and effort filled in the client's columns. Scope and PD only — never costs, prices, licence fees or budgets. Never designs the solution — that's sw-design-solution.
-when_to_use: Trigger phrases — "scope this RFP", "analyse the tender", "answer the RFI", "discover RFP 0001", "continue RFP 0001", "reconcile RFP 0001", "export the response for RFP 0001", "is RFP 0001 ready to submit", "open RFP 0001 in the browser", "open the tender tool", "sw-discover-tender specs/rfp-0001-x-analysis.md --editor".
-argument-hint: '[tender file or folder of exports (.xlsx|.md|.txt|.csv|.pdf) | specs/rfp-NNNN-slug-analysis.md to continue] [--editor] [--batch <n|all>] [--export]'
+description: Turn a client's RFI/RFP/RFQ or project plan into confirmed Shopware scope in one working document, `specs/rfp-NNNN-slug-analysis.md`. An agent extracts every requirement into the tool's own three fixed tabs — Functional, Non-functional, Project & services — and 18-row Project information table; intake confirms itself and analysis starts automatically, corrected any time via row notes (move, skip, restore); each scope item gets a Requirement Coverage (OOTB, Configuration, Extension, ISV, Custom, or `—`), a confidence, a T-shirt-size or partner-profile effort figure, assumptions the operator accepts, and a Client Response — without an engineer. Runs on the runtime's own CLI and page (`--editor`); confirm, answer and export happen anytime, and the document reaches Ready when every scope item is confirmed. Exports as XLSX only — a surgical fit-back into the client's own workbook, or the tool's own multi-tab workbook for a CSV or PDF source. Scope and effort only — never costs, prices, licence fees or budgets. Never designs the solution — that's sw-design-solution.
+when_to_use: Trigger phrases — "scope this RFP", "analyse the tender", "answer the RFI", "discover RFP 0001", "continue RFP 0001", "export the response for RFP 0001", "is RFP 0001 ready", "open RFP 0001 in the browser", "open the tender tool", "sw-discover-tender specs/rfp-0001-x-analysis.md --editor".
+argument-hint: '[tender file (.xlsx|.csv|.pdf) | specs/rfp-NNNN-slug-analysis.md to continue] [--editor] [--export]'
 allowed-tools: Read Write Edit Glob Grep Agent AskUserQuestion Bash(ls *) Bash(mkdir -p specs) Bash(mkdir -p specs/.rfp *) Bash(shasum -a 256 *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest *) Bash(open *) Bash(xdg-open *) Bash(tail *) Bash(grep *) Bash(printf *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 
 # sw-discover-tender
 
-One markdown sidecar per tender, `<source basename>-analysis.md`: class, three-point PD, mechanism and proposed assumptions per requirement row. The partner ticks, the next run reconciles. At Ready to submit: one response CSV per client table.
+One working document per tender: Requirement Coverage, confidence, effort, assumptions and a Client Response per scope item. The operator confirms; the next run reconciles. Export to XLSX anytime.
+
+Requires the runtime at `sw-tender-discovery-tool` >= 0.2.0 — the working-document grammar below is a 0.2.0 contract; `sw-setup` keeps it current with `@latest`, so a project on an older runtime should re-run `sw-setup` first.
 
 ## Boundaries
 
-- PD only. No costs, prices, rates, licence, hosting, PSP or CMP fees, no budget comparison. A stated budget is quoted in §1.1 as context.
-- Never edit the client's file. Never read a hidden sheet or anything whose name starts with `_`; name it in §1.3 as ignored. Pass this to every agent.
-- Assumption lines are written as `[ ]` only. `accepted` exists solely as the result of a human `[x]`.
-- A vague row gets a client question (`CQ-n`) or a proposed assumption, never a silent guess.
-- One line of mechanism per row. Design belongs to `sw-design-solution`.
-- Markdown and CSV out, plus the response workbook the tender tool writes as a **copy** of the client's file. The skill owns no executable: the workbook is read and written by the tender tool's own zero-dependency reader. The client's original is never touched, no docx is written, nothing is sent.
+- Scope and effort only. The tool never produces a figure of its own — no cost, price, rate, licence, hosting or PSP fee, no budget — `reference/estimation-model.md`'s money rule. A client's or the operator's own figure in Project information is kept verbatim; a coverage choice with a cost consequence gets a one-line `cost:` reference, no amount. Elsewhere a client-stated budget is never recorded, not even as quoted context.
+- Never edit the client's file. A hidden sheet or one whose name starts with `_` is never read and never mentioned anywhere — not in section 1, not in Not taken, not in the digest.
+- Assumptions are proposed by agents, accepted or rejected only by the operator. A rejected proposal is never proposed again.
+- A requirement too vague to assess gets a client question (`CQ-n`), never a silent guess.
+- No QA agent anywhere in the flow. Three agents only: `sw-tender-editor`, `sw-product-manager`, `sw-shopware-architect`.
+- XLSX out only, via the runtime's own writer: a surgical fit-back into the client's own workbook, or a multi-tab working-sheet export for csv/pdf. The client's original is never touched, nothing is sent. No per-requirement CSV of any kind is written.
 
 ## Inputs
 
 | Argument | Behaviour |
 | --- | --- |
-| `.md` / `.txt` / `.csv` / `.pdf`, or a folder of such exports | New tender: extract, analyse, write `<basename>-analysis.md` next to the source |
-| `.xlsx` | Import first, per `reference/procedure.md` step 1 ".xlsx import": `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest import` proposes a mapping (install gate: `reference/editor-session.md` §0), confirmed via `--editor` or a one-line yes/no, before the normalised source and the analysis are set. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops |
-| `.docx` | Stop. One line: export every requirement table as CSV UTF-8 (or paste it as markdown tables, header row kept) and rerun with that file or folder |
-| `*-analysis.md` | Continue: reconcile, advance, rewrite in place |
-| `--export`, or "export the response for RFP NNNN" | Continue, then run step 9 if the gate holds |
-| `--editor` | Hand off to `reference/editor-session.md` in this skill's directory as the very first action and stop when it returns; nothing is read, reconciled or analysed before the page is open |
-| `--editor-session <url> --batch-file <file>` / `--analyze` | Editor mode (section below), spawned by the editor session |
-| `--batch <n>` / `--batch all` | How many requirement rows one estimate run covers. Default 50. `all` = the whole document in a single run (no estimate groups). Stored in the frontmatter as `batch:` and reused by every later run on that analysis until the flag is given again |
-| nothing | Ask for the path in one line and end |
+| `.xlsx` / `.csv` | Import first (`reference/procedure.md` step 1): `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest import --source <file>` writes `import-digest.md` (install gate: `reference/editor-session.md` §0). `sw-tender-editor` runs its `extract` job on the digest and returns the extraction JSON; the skill saves it and runs `intake <doc> --source <file> --extraction <json>`. Every source runs the same extract-then-intake flow — xlsx, csv and pdf alike. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops. |
+| `.pdf` | New tender: `sw-tender-editor` runs its `extract` job on the PDF directly; the skill saves the JSON and runs `intake <doc> --source <pdf> --extraction <json>`. |
+| `.docx` or another format | Stop. One line: export the requirement table as CSV/xlsx or the prose as PDF, and rerun with that file. |
+| `*-analysis.md` | Intake already confirmed itself and queued analysis: work the chunks until none are left (`reference/procedure.md` step 2), then `check --write`, `report`. An old document still at `intake: review` needs `intake-confirm` first, on the operator's go; no separate Analyze step ever exists. |
+| `--export`, or "export the response for RFP NNNN" | Continue, then `export`. |
+| `--editor` | Hand off to `reference/editor-session.md` as the very first action and stop when it returns; nothing is read or assessed before the page is open. |
+| `--editor-session <url> --batch-file <file>` / `--intake` | Editor mode, spawned by the editor session (`reference/editor-session.md`). |
+| nothing | Ask for the path in one line and end. |
 
 ## Files
 
-- **Analysis** `<source basename>-analysis.md`, next to the source. Recommended: `specs/rfp-NNNN-slug.<ext>` → `specs/rfp-NNNN-slug-analysis.md`. Committed. Structure: `reference/analysis-template.md` in this skill's directory; the nine section numbers, the four §1 subsection numbers and every title are fixed.
-- **Source export** `<source dir>/<basename>/<pos>-<sheet-slug>.csv` plus `import-map.json`, written by the tender tool's `import` from the confirmed mapping. Committed; they are what the analysis reads, hashes and exports from.
-- **Response** `<source basename>-response-<n>-<table-slug>.csv`, one per client table. Committed, generated, never hand-edited.
-- **Work** `specs/.rfp/<slug>/`: `map-<t>.md`, `context-<t>.md`, `context.md`, `meta.md`, `params.md`, `migration.md`, `integrations.md`, `glossary.md`, `C<n>.md`, `pm-C<n>.md`, `arch-common.md`, `arch-C<n>.md`, `qa.md`, `rows-C<n>.md`, `tail-C<n>.md`, `resp-common.md`, `resp-C<n>.csv`. Gitignored.
-- **Editor session** `specs/.editor/<slug>/`, written by the Tender Discovery Tool. Gitignored; never hand-edited.
-- **Profile** `specs/rfp-partner-profile.md`. Missing: write the template from `estimation-model.md` with `_TBD_` and add a `high` `Q-n` to fill it. `_TBD_` overhead or buffer: PD final is stated before both, §2 says so.
-
-## Procedure
-
-**0. Mode.** `--editor` → `reference/editor-session.md`, per the Inputs row above, and stop there. `--editor-session` → work through `reference/procedure.md` under `reference/editor-session.md`'s *Editor mode* rules.
+- **Working document** `specs/rfp-NNNN-slug-analysis.md`, next to the source. Committed. Grammar: `reference/analysis-template.md` — 8 fixed sections, section 4 header, cell lists, frontmatter.
+- **Fit-back map** (xlsx sources only) `<srcdir>/<base>/import-map.json`, written by `intake`. Committed. No per-table CSVs are written.
+- **Response** `<source basename>-response-v<n>.xlsx` (never overwritten). Committed, generated, never hand-edited.
+- **Work** `specs/.rfp/<slug>/`: `extraction.json` (the `extract` job's result), `proposals.json`, `reestimate.json`, `last-run.json`, `reports/*.json` (saved architect reports before `apply`). Gitignored.
+- **Editor session** `specs/.editor/<slug>/`: `import-snapshot.json`, `import-map.proposed.json`, `import-digest.md`, written by the Tender Discovery Tool. Gitignored.
+- **Partner profile** `specs/rfp-partner-profile.md`. Missing: the page offers the wizard (skippable); without it the document runs in T-shirt regime (`reference/estimation-model.md`).
 
 ## Reference files
 
-All under `reference/` in this skill's directory. Work through them, in order, for a run:
+All under `reference/` in this skill's directory:
 
 | File | When | What it decides |
 | --- | --- | --- |
-| `procedure.md` | every run | steps 1–9: target/source, reconcile, extract, ground truth, fan out, questions, estimate/score/write, the 8-line report, export; delegation, batch size, staged writes |
-| `agent-briefs.md` | step 5 (fan out), step 9 (export) | PM, architect, QA, extract, rows, splice, response, assemble briefs; parallelism, caps, delivery rules |
-| `editor-session.md` | `--editor` / `--editor-session` in the arguments | the session loop; its "Editor mode" section: batch kinds, tick grammar, notes handling, preserve rules |
-| `analysis-template.md` | writing or reading the analysis file | frontmatter, the nine sections, row and status grammar |
-| `context-parameters.md` | steps 4 and 6, §1.2 | the P-01…P-50 key-parameter template, estimate-driving flags, missing-parameter question stubs |
-| `confidence-rubric.md` | step 7 | dimensions, bands, status rule, honesty rules |
-| `estimation-model.md` | steps 2, 5, 7 | three-point, levels, assumption deltas, folding, partner-profile template |
-| `client-question-rules.md` | step 6 | vague-row detectors, blocking, wording, cap, answers |
-| `assumption-catalogue.md` | step 5 (architect brief) | reusable scope-lock statements by theme |
-| `coverage-mapping.md` | step 5 (architect brief), step 9 | class → client token, synonyms, edition tiers |
-| `response-rules.md` | step 9 (export) | the response CSV rules (`RSP-1` … `RSP-7`), verbatim for the sub agent brief |
-| `editor-mode.md` | harness maintenance only | pending harness edits for this skill; not part of a run |
+| `procedure.md` | every run | the seven steps: intake (extract + intake), assess, propose, estimate, confirm, answer, export; the three agents, applying a report, the run close |
+| `agent-briefs.md` | steps 2-4 | one brief per agent, its tools, its delivery |
+| `editor-session.md` | `--editor` / `--editor-session` in the arguments | the session loop, batch kinds, the subagent brief, close report |
+| `analysis-template.md` | writing or reading the working document | frontmatter, the 8 sections, section 4 grammar, section 5 blocks |
+| `project-information.md` | step 1, section 1 | the 18 Project information keys, what each captures, which estimate it informs |
+| `context-parameters.md` | steps 1-2, section 1 | version/edition/plan detection from the Dev Knowledge Base only, what every agent receives |
+| `coverage-mapping.md` | step 2 | the six Requirement Coverage values, the client-token map, ISV research |
+| `estimation-model.md` | steps 3-4 | the two regimes, default scale, size-up drivers, not-decomposed rule, totals, money rule, the profile file |
+| `client-question-rules.md` | step 3, step 6 | when a scope item gets a `CQ-n`, wording, answering |
+| `assumption-catalogue.md` | step 3 (architect brief) | reusable assumption statements by key, with the effort each saves |
+| `response-rules.md` | step 7 (export) | X-1…X-7, what the runtime's `export` writes |
 
-No scripts: the skill ships no executable. The tender tool's `import --source <file>` and `export --xlsx --source <file>` commands read and write the workbook.
+The skill ships no executable of its own: the runtime's `import`, `intake`, `intake-confirm`, `move`, `skip`, `restore`, `info`, `apply`, `confirm`/`accept`/`reject`/`assume`/`unassume`/`answer`/`patch`/`profile`, `check`, `report` and `export` commands read and write the working document and the workbook.