@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.0

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

@@ -0,0 +1,102 @@
+---
+name: sw-design-requirements
+description: Turn a briefing — chat text or a file, covering one or more features — into a lean, business-only PRD stored as specs/NNNN-slug.md. Runs an interactive clarification loop for the requirement gaps and inconsistencies that actually change the requirements, then scores a weighted confidence %. Use when asked to write, draft, refine, continue, or score a PRD / requirements doc / feature brief for this Shopware project. Never writes a tech spec or answers architecture questions — that's sw-design-solution.
+when_to_use: Trigger phrases — "write a PRD", "draft requirements", "turn this brief into a PRD", "continue PRD 0003", "is this PRD ready for specification", "raise the confidence on this PRD", "requirements for <feature>".
+argument-hint: [file-path | briefing text | specs/NNNN-slug.md to continue] [--editor]
+allowed-tools: Read Write Edit Glob Grep AskUserQuestion Agent Skill Bash(ls *) Bash(mkdir -p specs) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@0.1.0 *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+
+---
+
+# sw-design-requirements
+
+Produce or advance one PRD, business requirements only. Sole delegate for `specs/*.md`; `sw-product-manager` only researches, never writes one. A feasibility chat is not by itself a PRD request — ask before writing one if unclear.
+
+## Hard boundary
+
+Answers **what** and **why**, never **how**: no architecture, DAL entities, schema, plugin structure, class/service names, APIs, events, subscribers, Symfony/Vue/Twig, performance strategy, or effort estimates.
+
+A user-asserted tech decision or platform limitation: don't discuss, expand, validate, or challenge it — record it as one bullet in **§10 Early Tech Decisions / Limitations**, tagged `[decision]` or `[constraint]`, with who set it. Never raises confidence or feeds FRs. A mid-run technical question: one line it belongs in the tech spec, log in §10 if a decision, return to requirements.
+
+## Architect advisor (exception, not default)
+
+Tech decisions belong to `sw-design-solution`. Consult `sw-shopware-architect` (delegate to it as a sub-agent if your host supports sub-agents; otherwise read that agent's definition and do the work yourself) only when a high-impact §10 decision (data model, checkout/cart, plugin vs app) needs a viability check or conflicts with stock/a plugin, a requirement can't be stated without knowing if Shopware can do it at all, or a §11 `(recommended)` mark needs a feasibility verdict (*Recommended options must be advised*). Check merchant docs first (step 2); spawn only when insufficient. Brief: PRD path, §10 bullet or FR, the question, detected version if known — verdict not design, max 3 lines, anchored as one §10 bullet tagged `[architect]`. Never adds FRs or confidence, never a wording or loop-settleable decision.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| 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. |
+| `<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
+
+`--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 document path, stop; nothing else runs. `--editor-session` → continue mode under `reference/editor-mode.md` in this skill's directory.
+
+### 1. Establish the target file
+
+New PRD:
+```
+mkdir -p specs
+ls specs
+```
+Take the highest `NNNN`, add 1, zero-pad to 4; slug = kebab-case, 2–5 words. Target: `specs/NNNN-slug.md`.
+
+Continue mode: keep the existing path, number and slug. Never renumber or create a second file for the same feature.
+
+### 2. Targeted consistency lookup
+
+Always read first: `specs/*.md` (overlap, contradiction, supersession), `custom/plugins/*` and `custom/static-plugins/*` (what's already built), `CLAUDE.md` if present.
+
+For every distinct Shopware concept named, delegate to the `sw-product-manager` sub-agent if your host supports sub-agents (otherwise read its definition and do the work yourself) against stock Shopware, version-matched, cross-checked with `vendor/`. Never reason from memory or grep `vendor/` yourself — sw-product-manager's job. `shopware_version: unknown` or `unverified` → note it in §10.
+
+Fill **§9 OOTB / Extend / Custom** from that verdict plus the plugin scan: `confirmed-stock` → `OOTB`; an existing plugin → `Extend`; neither → `Custom`; no evidence → `_TBD_`. Word "Why" in what's missing/different from stock, never how it'd be built.
+
+Work through `reference/consistency-probes.md` in this skill's directory for the rest (prior answers, other PRDs, plugins, the stock-Shopware KB lookup, internal coherence) — skill-local, no agent.
+
+Every conflict becomes a step-4 clarification question, never a silent assumption.
+
+### 3. Draft
+
+Fill `reference/prd-template.md` in this skill's directory. Unknown sections stay `_TBD_`, never invented.
+
+Writing rules — enforce on every line:
+- FRs: one testable sentence each, `FR-n`, present-tense imperative ("The storefront shows…", "A guest cannot…").
+- No paragraph over 4 lines; density not length — rows never dropped to shorten.
+- Business vocabulary only. Shopware domain nouns (Product, Order, Cart, Customer Group, Sales Channel, Rule Builder) count as domain, not implementation.
+- No filler: drop "the system should be able to", "in order to", restated goals.
+- Never invent numbers, thresholds, SLAs, metrics — absent means open question.
+
+§9's "Why" column: business terms only, never an implementation approach (see step 2).
+
+Check `reference/splitting-guidelines.md` in this skill's directory; two loosely coupled features → raise it in step 6, never split unasked or on size alone.
+
+### 4. Clarification loop
+
+Work through `reference/clarification-loop.md` in this skill's directory: when to skip, the ask/don't-ask test, the question loop, the recommended-option rules, and how to anchor answers into the PRD.
+
+Use `reference/prd-confidence-checklist.md` in this skill's directory for gap probes; merge with sw-product-manager's `draft_questions` into one queue.
+
+### 5. Score, write, report
+
+Work through `reference/readiness-and-report.md` in this skill's directory: apply the confidence rubric, fill the meta table and §13, write the file, and build the closing report.
+
+## Reference files
+
+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/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
+- `reference/prd-confidence-checklist.md` — step 4: gap probes and the ask/don't-ask test
+- `reference/confidence-rubric.md` — step 5: scoring bands, status rule
+- `reference/readiness-and-report.md` — step 5: scoring, writing the file, and the closing report
+- `reference/editor-mode.md` — `--editor-session` runs: scoped procedure, diagrams, progress events
+- `reference/editor-gate.md` — step 0: the optional-add-on check before the `--editor` hand-off

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

@@ -0,0 +1,20 @@
+# Clarification loop
+
+Interactive by default; skip if unattended or the user asked for no questions — write every gap to §11, stop after step 5.
+
+**One class of question.** Ask only if the answer changes domain modelling, functional behaviour, or acceptance criteria — test: *would requirements differ either way?* No → `(assumed)` marker or leave out, no §11 block. Never ask about wording, ordering, formatting, or anything inferable/technical. **Short and concrete:** one sentence, one decision, no preamble, no "and/or" — split into two, choice not background.
+
+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.
+- `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`.
+- 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:
+
+> "yes but only with a verified email" → §5 gains `FR-7 A guest may submit after confirming email via a one-time link.`; §12 gains `C-3 | Guest access | Allowed, gated by email confirmation | 2026-08-11`
+
+§12 holds one line per resolved decision — topic, decision, date, never the raw question or reply. An answer invalidating existing text: edit it, note the supersession.

package/skills/sw-design-requirements/reference/confidence-rubric.md

@@ -0,0 +1,82 @@
+# Confidence rubric
+
+Score each dimension 0–100 against its bands, multiply by weight, sum, round to a whole percent.
+
+`points = score × weight / 100`
+
+Score the PRD **as written**, not the conversation. If a decision was made in chat but is not in the file, it does not count.
+
+## Scope & boundaries — weight 20
+
+| Score | Band |
+| --- | --- |
+| 100 | §1 goal is unambiguous; §2 in-scope and out-of-scope both populated; sales channels and actors in §3 fixed |
+| 70 | In-scope clear, out-of-scope thin or absent |
+| 40 | Goal clear, boundaries mostly implied |
+| 0 | Goal itself is `_TBD_` or the feature could mean two different things |
+
+## Domain impact — weight 15
+
+| Score | Band |
+| --- | --- |
+| 100 | Every affected concept in §4 with its change; new concepts defined |
+| 70 | Main concepts listed, one or two secondary effects unresolved |
+| 40 | Concepts named without stating what changes |
+| 0 | §4 is `_TBD_` |
+
+## Functional coverage — weight 25
+
+| Score | Band |
+| --- | --- |
+| 100 | FRs cover the whole in-scope surface; each is a single testable sentence; nothing left as "and similar" |
+| 70 | Happy path complete, secondary flows partial |
+| 40 | Only the headline behaviour is specified |
+| 0 | No FRs, or FRs are goals rather than behaviours |
+
+## Acceptance criteria — weight 20
+
+| Score | Band |
+| --- | --- |
+| 100 | Every non-trivial FR has Given/When/Then, externally observable, unambiguous pass/fail |
+| 70 | Majority covered; a few FRs have none |
+| 40 | A handful of examples rather than criteria |
+| 0 | §7 is `_TBD_` |
+
+## Edge cases & rules — weight 10
+
+| Score | Band |
+| --- | --- |
+| 100 | §6 covers empty state, limits, failure, and the reversal/cancellation path; error behaviour is specified from the actor's view |
+| 70 | Main rules stated, failure behaviour thin |
+| 40 | Rules present, no edge cases |
+| 0 | §6 is `_TBD_` |
+
+## Consistency resolved — weight 10
+
+| Score | Band |
+| --- | --- |
+| 100 | All five probes in `consistency-probes.md` run; every conflict found is resolved and logged in §12 |
+| 70 | Probes run; a conflict is recorded in §11 but not yet resolved |
+| 40 | Probes run only partially |
+| 0 | Not run, or a known conflict is left unrecorded |
+
+## Status
+
+| Confidence | Open questions in §11 | Status |
+| --- | --- | --- |
+| ≥ 90% | none | **Ready for specification** |
+| ≥ 90% | one or more | **In progress** |
+| < 90% | any | **In progress** |
+
+The open-question rule overrides the arithmetic without exception: a PRD scoring 94% with one open question stays *In progress*.
+
+## Honesty rules
+
+- Do not round up to cross 90%.
+- Never raise a score because the user seems satisfied, is in a hurry, or asked for the PRD to be finished.
+- A `(assumed)` marker caps its dimension at 70 unless the user confirms the assumption.
+- `_TBD_` anywhere in §1–§8 caps that dimension at 40.
+- §10 Early Tech Decisions is never scored. Recording a technical decision cannot raise confidence.
+- §9 OOTB / Extend / Custom Assessment is never scored either — it is a preliminary signal, not a decision, and carries no weight in the total.
+- If the total moved down since the last run, say so plainly in the report and name the cause — that goes in the report, not in §13.
+- **Weakest dimension** in §13 is one sentence, max 25 words: the dimension, the one gap, what closes it. What changed this run, which rows were answered, why scores moved — none of that goes into §13; it goes into the run report.

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

@@ -0,0 +1,65 @@
+# Consistency probes
+
+Run before drafting. Every conflict becomes a clarification question — never a silent assumption, never a resolution you pick yourself.
+
+## 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.
+
+Ask as an explicit choice, quoting both sides:
+> "C-2 recorded that guests may not use this. The new brief has guests submitting the form. Which holds?"
+
+On resolution: edit the affected FR/AC, and log the supersession in §12 (`C-7 | Guest access | Reversed C-2 — guests now allowed | 2026-08-14`).
+
+## 2. Against other PRDs in `specs/`
+
+Read every `specs/*.md` header and §2 Scope. Look for:
+- The same capability specified twice — the second PRD should reference or supersede the first.
+- Directly contradictory rules across PRDs touching the same domain concept.
+- A PRD marked `Ready for specification` whose assumptions this one breaks.
+
+If this PRD replaces another, fill the `Supersedes` meta row and confirm with the user.
+
+## 3. Against this project's existing code
+
+Read `custom/plugins/*` and `custom/static-plugins/*` — plugin names, `composer.json` descriptions, and any README. On a fresh boilerplate these are empty; then this probe is a no-op.
+
+A conflict is: the brief asks for something an existing plugin already provides, or contradicts behaviour an existing plugin establishes.
+
+When there is no conflict but an existing plugin covers similar ground, that is a signal for §9 OOTB / Extend / Custom Assessment — it points toward `Extend` rather than `Custom` for the FRs it's close to.
+
+## 4. Against stock Shopware
+
+The most valuable probe. Shopware 6 ships a lot; briefs routinely re-specify it. This probe is delegated to the `sw-product-manager` subagent — never reasoned about from memory here, and never a static hardcoded list (Shopware's stock feature set changes across versions).
+
+For every distinct Shopware concept the brief names, invoke `sw-product-manager`. It checks against the official docs matched to the project's actual installed Shopware version (from `composer.lock`), cross-checked with installed `vendor/` code when present, and returns a verdict + evidence (doc URL+version, or vendor path) — or `unverified` if neither source was reachable.
+
+Frame a `confirmed-stock` finding as a scope question, not a design opinion:
+> "sw-product-manager confirmed Shopware's Promotions + Rule Builder already covers 'free shipping over €50' (docs.shopware.com, v6.6). Does FR-3 need behaviour beyond that, or should it be dropped as a configuration task?"
+
+Three valid outcomes — all fine, all the user's call:
+- **Drop** the FR, note it in §2 Out of scope with the stock feature named.
+- **Keep** it, and narrow the FR to the delta that stock Shopware cannot do.
+- **Keep** it as-is because the user has a reason; log the reason in §12.
+
+An `unverified` finding is not a pass — note it in §10 rather than assuming the brief is safe, and leave the corresponding §9 row `_TBD_` rather than guessing.
+
+A `confirmed-stock` verdict, when the FR is kept, is also the signal for §9 OOTB / Extend / Custom Assessment: it points the estimate for that FR toward `OOTB`, cited to sw-product-manager's evidence.
+
+## 5. Internal coherence of the PRD itself
+
+Before scoring:
+- Every FR reachable by at least one actor in §3.
+- Every non-trivial FR has an AC in §7.
+- No FR contradicts a BR in §6.
+- Nothing in §2 Out of scope is specified anyway in §5.
+- Nothing in §9 has leaked into §5 as a requirement.
+
+Internal contradictions are fixed by editing, not by asking — unless the fix changes intent, which is a question.
+
+## 6. Stock behaviour lookup (ShopwareDevKnowledgeBase MCP)
+
+`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.

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

@@ -0,0 +1,15 @@
+# Editor install gate
+
+Runs before the `--editor` hand-off (step 0). The Specs Editor is an **optional** add-on: it is not part of this plugin, and a host that never installed it is a supported, normal setup. `sw-setup` offers to install it.
+
+What is checked is the **skill**, `sw-specs-editor`, because that is what `sw-setup` installs and what the hand-off calls. The skill brings the CLI with it — it invokes `npx -y @execuro-sw-ecosystem/sw-specs-editor@0.1.0`, which fetches the package on first use.
+
+Check: is the `sw-specs-editor` skill available in this session?
+
+**Available** → hand off to it with the document path, and stop. Nothing else runs.
+
+**Not available** → **stop the run here**. Say, in one line:
+
+> The Specs Editor is not installed. Run `sw-setup` to add it, or re-run without `--editor`.
+
+Then stop. Do not fall back to the terminal flow, do not read or write the PRD, do not continue with the normal procedure. The user asked for the page; silently giving them something else is worse than telling them they did not get it.

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

@@ -0,0 +1,15 @@
+# Editor mode
+
+Invoked as `<path> --editor-session <url> --batch <batch.json>` — one note batch from the page. Continue mode, same procedure, boundary, anchoring/logging rules, plus:
+
+- **Scoped to the batch.** Never a full pass on open. Step 2 only for concepts/PRDs/plugins the notes touch; edit only named blocks plus whatever answers invalidate; re-score every run; §11 blocks only where the batch exposed a gap.
+- **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 → report belongs to the spec, change nothing.
+- **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.
+- **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@0.1.0 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@0.1.0 emit progress "<step>" --batch <id> --doc prd`.
+- **Report:** changed blocks, answers (Q ids → anchor), top remaining gap or `none`, confidence %, status, `Agents: <list or none>`.
+
+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-requirements/reference/prd-confidence-checklist.md

@@ -0,0 +1,95 @@
+# Gap checklist (Shopware 6)
+
+Scan the drafted PRD against this list. A probe is worth asking **only** when the brief leaves it genuinely open *and* the two plausible answers produce different requirements. Most probes will not apply to most PRDs — skip them silently.
+
+Never turn a probe into a technical question. "Which customer groups get the discount?" is a requirement. "Should this use the Rule Builder or a subscriber?" is not.
+
+## A. Actors & context — almost always worth checking
+
+- Guests, logged-in customers, or both? Does it need an account?
+- Which customer groups? Net or gross price display — does that change behaviour?
+- B2B involved — a company/business buyer, not just an individual? If yes, see §B.
+- Which sales channels — Storefront, headless via Store API, Admin only?
+- Multi-language / multi-currency / multi-country in play? Does behaviour differ per country?
+- Does a merchant admin configure this, or is it fixed?
+
+## B. B2B — only when §A flagged a business/company buyer
+
+Shopware's B2B Components is a distinct Commercial capability set, Evolve plan or higher (never Rise or Community — see §I). A brief that says "B2B" rarely means all of it; scope which parts apply.
+
+- Which capabilities does the brief actually need — employee roles, order approval, budgets, quotes, organisation units, catalogue restrictions per unit, negotiated pricing, quick order, shopping lists, sales agent login — or a subset?
+- One employee role covers ordering, or do roles need to differ (who can order, who can approve, who manages other employees)?
+- Does every order need approval, or only ones crossing a threshold (amount, weight, shipping cost, method)? What happens to an order while it's pending?
+- Spending limits — company-wide, per department, or per employee? What reset cadence (weekly/monthly/quarterly/yearly) matches the client's actual procurement cycle?
+- Quotes — customer-initiated only, or can the merchant send one proactively? What happens when a quote expires unanswered?
+- Does the company need more than one organisational level (e.g. region > branch > team), and do units need separate addresses or payment methods?
+- Does every unit see the same product catalogue, or does visibility need to differ per unit?
+- Negotiated/individual pricing — per unit, per customer tag, or both? Does it override or stack with existing customer-group/tiered pricing?
+- Quick order — manual number+quantity entry enough, or is bulk CSV upload required, and in what format?
+- Shopping lists (reorder templates) — customer-managed only, or does the merchant's team need to build/edit them on a customer's behalf?
+- Third-party sales agents placing orders on a customer's behalf — needed, or out of scope?
+
+## C. Catalog & pricing
+
+- Which product kinds: standard, variants, digital/downloadable, custom-configurable, bundles, free-gift?
+- Variant-level or parent-level behaviour?
+- Which price wins when several could apply — list, tiered/advanced, customer-group, promotion, manual — and does it stack with existing promotions/vouchers?
+- Stock relevance: reserve, block, or ignore availability? Behaviour when out of stock, on clearance, or on restock delay?
+- Does the rule apply per line item, per cart, or per customer over time?
+
+## D. Cart, checkout & order
+
+- Cart stage, order stage, or both? What happens to a cart already holding the old behaviour?
+- Effect on totals, taxes, shipping costs, surcharges?
+- Constrained to specific payment or shipping methods?
+- Which order-state transitions matter — cancellation, return, refund?
+- Recorded on the order for later reference — invoice, document, confirmation?
+
+## E. Content, storefront & communication
+
+- New page, new URL, or change to an existing one? SEO-relevant?
+- Editable via Shopping Experiences (CMS) by merchants, or hard-coded by developers?
+- Which notifications fire, to whom, and on what event?
+- Any new or changed content — email, page copy — the merchant must be able to edit or translate?
+
+## F. Admin & permissions
+
+- Does a merchant need a new list, detail view, or setting — or is an existing module extended?
+- Which roles may see and which may change it?
+- Bulk actions, import/export, or CSV needed?
+
+## G. Data & integrations
+
+- Who owns the data — Shopware or an external system (ERP, PIM, CRM, WMS)?
+- Direction and business freshness expectation (real time, hourly, nightly)?
+- What happens when the external system is unavailable — block, queue, degrade?
+- Existing records: migrated, backfilled, or left as-is?
+- Personal data, consent, retention, invoice or tax implications?
+
+## H. Acceptance & failure
+
+- For each FR: what observable outcome makes it done?
+- What does the actor see when it fails, is not permitted, or hits a limit?
+- Empty state and first-run behaviour?
+- Any threshold, limit, or timing the business has actually stated? (Never invent one.)
+
+## I. Licence tier — a business availability question, not a technical one
+
+Several capabilities are Shopware **Commercial** (Rise / Evolve / Beyond), not open-source Community. If the brief assumes one, confirm the plan covers it or that the PRD requires building it.
+
+Commercial-only: B2B Components — Evolve or higher, never Rise or Community (see §B) — Subscriptions (Beyond only), Multi-Inventory (Evolve/Beyond), Advanced Search, Returns Management, Content Generator, Text/Image AI, Spatial Commerce, Custom Products (Rise, and a separate feature from B2B Components despite the naming similarity).
+
+Individual/negotiated pricing within B2B Components has conflicting tier documentation (Evolve vs. Beyond) — confirm directly against the client's Commercial contract before writing acceptance criteria that assume it.
+
+Ask as: *"This relies on Shopware's B2B order-approval feature, which needs the Evolve plan or higher. Does the project have that plan, or must this be built from scratch?"* — the answer changes scope and requirements, so it is high-impact.
+
+## Ask or don't
+
+There is no impact grading. A gap is either worth a question or it is not:
+
+| | Handling |
+| --- | --- |
+| Changes domain modelling, functional behaviour, or acceptance criteria — answering it moves confidence toward 90% | Ask it, or write it as a §11 row. It blocks *Ready for specification* while open. |
+| Everything else — wording, ordering, cosmetics, inferable defaults, details the requirements do not turn on | Never ask, never write a row. Assume and mark `(assumed)`, or leave it out. |
+
+Test before writing any question: *if answered both ways, would the PRD's requirements differ?* No → it is not a question.

package/skills/sw-design-requirements/reference/prd-template.md

@@ -0,0 +1,153 @@
+# PRD template
+
+Copy verbatim, fill, delete every `<!-- -->` hint. Keep section numbers and titles unchanged — later tooling and the rubric key off them.
+
+Unknown content stays `_TBD_`. Never delete an empty section; an empty section is a signal, an invented one is a defect.
+
+---
+
+```markdown
+# PRD-NNNN — <Feature name>
+
+| | |
+| --- | --- |
+| **Status** | In progress |
+| **Confidence** | 0% |
+| **Created** | YYYY-MM-DD |
+| **Updated** | YYYY-MM-DD |
+| **Source** | chat \| path/to/brief.md |
+| **Supersedes** | — |
+
+## 1. Problem & Goal
+
+<!-- 2–4 sentences. Who is blocked or losing value today, and what changes for them. No solution. -->
+
+**Success looks like:** <!-- one sentence, observable from the outside -->
+
+## 2. Scope
+
+**In scope**
+- <!-- bullet per capability -->
+
+**Out of scope**
+- <!-- bullet per explicitly excluded thing, with a 3–6 word reason -->
+
+## 3. Actors & Sales-Channel Scope
+
+| Actor | Where | Notes |
+| --- | --- | --- |
+| <!-- Guest / Registered customer / B2B buyer / Merchant admin / External system --> | <!-- Storefront / Store API / Admin / Background --> | <!-- customer group, role, country restriction --> |
+
+**Sales channels:** <!-- which, or "all" -->
+**Languages / currencies / countries:** <!-- or "inherits project default" -->
+
+## 4. Domain Impact
+
+Business-level only — what concepts change, not how they are stored.
+
+| Concept | Change | Why |
+| --- | --- | --- |
+| <!-- Order --> | <!-- gains a customer-chosen delivery date --> | <!-- FR-3 --> |
+
+**New concepts:** <!-- name + one-line definition, or "none" -->
+
+<!-- Optional, added by the Specs Editor on first request — keep the line exactly in this shape: -->
+<!-- Diagram: specs/NNNN-slug.domain.excalidraw -->
+
+## 5. Functional Requirements
+
+One testable sentence each. Present tense, active voice.
+
+<!-- Status tag convention (FR, BR, AC): an optional `[done]` / `[partly]` / `[open]` directly after the bold id, e.g. `- **FR-1** [done] …`; absent = open. Set by the user in the Specs Editor or by sw-implement-feature / sw-verify-feature. Preserve it on every rewrite. -->
+
+- **FR-1** <!-- The storefront shows … -->
+- **FR-2**
+
+## 6. Business Rules & Edge Cases
+
+- **BR-1** <!-- condition → required outcome -->
+
+**Edge cases**
+- <!-- empty state, limit reached, concurrent change, cancelled/refunded, deleted reference, unsupported currency … -->
+
+**Error behaviour visible to the actor**
+- <!-- what they see when it fails -->
+
+## 7. Acceptance Criteria
+
+Given/When/Then, one block per FR that needs it. Externally observable only.
+
+- **AC-1** (FR-1)
+  - **Given** …
+  - **When** …
+  - **Then** …
+
+## 8. Data & Integrations
+
+| Data | Source of truth | Direction | Business expectation |
+| --- | --- | --- | --- |
+| <!-- Stock levels --> | <!-- ERP --> | <!-- ERP → Shop --> | <!-- accurate within 15 min --> |
+
+**Existing data:** <!-- what happens to records created before this ships, or "none" -->
+**Personal data / compliance:** <!-- GDPR, invoices, legal texts, or "none" -->
+
+## 9. OOTB / Extend / Custom Assessment (preliminary)
+
+_Preliminary signal, not a decision. Estimates the most likely delivery path per requirement, to surface complexity early. The binding classification is made in the tech spec (`sw-design-solution`)._
+
+| FR | Customer ask | Estimate | Why | Source |
+| --- | --- | --- | --- | --- |
+| <!-- FR-3 --> | <!-- one line --> | <!-- OOTB \| Extend \| Custom --> | <!-- what is missing or differs from stock Shopware / an existing project plugin, in business terms only — never an implementation approach --> | <!-- sw-product-manager verdict (Shopware vX, doc/vendor evidence) or existing-plugin scan --> |
+
+Leave a row `_TBD_` rather than guessing without a `sw-product-manager` verdict or a plugin-scan finding behind it.
+
+## 10. Early Tech Decisions / Limitations
+
+Decisions the business or team has already fixed. Recorded, not evaluated. Not requirements. No effect on confidence.
+
+- `[decision]` <!-- statement --> — set by <!-- who -->, <!-- date -->
+- `[constraint]` <!-- statement --> — set by <!-- who -->, <!-- date -->
+- `[architect]` <!-- one-line verdict, only if sw-shopware-architect was consulted --> — <!-- date -->
+
+## 11. Open Questions
+
+<!-- One block per question, blank line between. Example: -->
+<!--
+**Q-1** One short, concrete question — no preamble, no restated context.
+Blocks: FR-4, AC-2
+- [ ] A: First option (recommended)
+  - [pm] one-line reason
+- [ ] B: Second option
+- [ ] C: Third option — options stay blank until an editor-mode run touching this question fills them
+-->
+
+Every question here is a gap that changes domain modelling, functional behaviour, or acceptance criteria — nothing smaller is written down. Any open question blocks *Ready for specification*.
+
+Rules: one block per question, a `**Q-n**` line, optional `[adr]`/`[gate]` tag right after the id (decision cards in the Specs Editor), 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 PRDs (a legacy question table) are converted to this format automatically on the first editor-mode write.
+
+## 12. Clarification Log
+
+One line per resolved decision. No question text, no quotes, no transcript.
+
+| # | Topic | Decision | Date |
+| --- | --- | --- | --- |
+| C-1 | <!-- --> | <!-- --> | YYYY-MM-DD |
+
+## 13. Confidence Breakdown
+
+| Dimension | Weight | Score | Points |
+| --- | --- | --- | --- |
+| Scope & boundaries | 20 | 0 | 0.0 |
+| Domain impact | 15 | 0 | 0.0 |
+| Functional coverage | 25 | 0 | 0.0 |
+| Acceptance criteria | 20 | 0 | 0.0 |
+| Edge cases & rules | 10 | 0 | 0.0 |
+| Consistency resolved | 10 | 0 | 0.0 |
+| **Total** | **100** | | **0%** |
+
+**Weakest dimension:** <!-- <dimension name> — one sentence (max 25 words): the single gap holding it down and what closes it. Never a run summary; that belongs in the report. -->
+```
+
+---
+
+Leanness here means density, not size. A PRD is as long as the feature needs: fill every row the feature actually has and drop none to hit a target. See `splitting-guidelines.md` for when one PRD should have been two.

package/skills/sw-design-requirements/reference/readiness-and-report.md

@@ -0,0 +1,21 @@
+# Readiness and report
+
+Entered at step 5, after the clarification loop settles. Decides how confidence is scored, what gets written, and what the step 6 report contains.
+
+### 5. Score and write
+
+Apply `reference/confidence-rubric.md` in this skill's directory. Fill the meta table and §13 — **Weakest dimension** is one sentence, max 25 words, naming the gap and what closes it; the run narrative belongs only in the report, never §13. Status: `In progress` below 90%; `Ready for specification` at 90%+ **and** no open §11 question — absolute, every question changes requirements.
+
+Write the file. In continue mode, update `Updated`, `Confidence`, `Status` and §13; append to §12.
+
+### 6. Report
+
+Five lines, no more (six with an architect), each one line:
+- path written
+- confidence % and status
+- what changed this run (continue mode)
+- remaining gap costing most confidence, or `none`
+- a split recommendation, phrased as a question, only if guidelines warrant one
+- `Architect consulted: <topic> — <one-line verdict>`, only if spawned this run
+
+Never paste the PRD body back into chat.