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

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

@@ -0,0 +1,52 @@
+---
+name: sw-implement-feature
+description: Implement a feature from its technical spec (specs/NNNN-slug-spec.md, written by sw-design-solution) following TDD — tests first per acceptance criterion, then the implementation, fixing until every relevant test passes (including that AC's own acceptance/e2e test, run immediately, not deferred), running Shopware's own shopware-cli fixers/static-analysis per AC to conform to Shopware's coding standards as code is written rather than after the fact. Builds ACs group by group per the spec's Parallel groups/Depends on data, fanning out independent ACs to concurrent agent spawns instead of one at a time. Runs sw-verify-feature as its final step to produce a full verification report. Use when asked to implement, build, or code a feature/epic from an existing tech spec.
+when_to_use: Trigger phrases — "implement spec 0007", "build this feature", "code the epic-1 spec", "implement the tech spec".
+argument-hint: [specs/NNNN-slug-spec.md]
+allowed-tools: Read Write Edit Glob Grep Bash Agent mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+---
+
+# sw-implement-feature
+
+Implement one feature from its technical spec, under TDD, then hand off to full verification.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| Path to `specs/NNNN-slug-spec.md` | Implement this spec |
+| Path to `specs/NNNN-slug.md` (a PRD, no spec) | Tell the user to run `sw-design-solution` first — do not improvise a spec |
+| Nothing | Ask the user for the spec path |
+
+## Procedure
+
+### 0. Pre-check
+
+Invoke `sw-setup` once. Rows an AC's tests need — vendor/ (PHPUnit); Acceptance-test project, Playwright browsers, ATS env (e2e); Plugin tests (target plugin) — must be ticked; unticked → stop, tell the user to run `/sw-setup`. Never mark an AC `partly` for a missing environment.
+
+**Shopware version — detect once, before spawning anything, never assume:** `vendor/shopware/core/composer.json` `version` → `composer.lock` → `composer.json` constraint ("unconfirmed"); PHP from the project runtime (`compose.yaml`, `.ddev/config.yaml`, `Dockerfile`), not the host. State it with evidence in every Agent-tool brief below — implementer spawns, architect escalation, QA e2e runs — so no sub-agent has to re-derive it; a version with no evidence must still be passed on as unconfirmed (e.g. constraint-only), never treated as certain. Unknown → ask the user.
+
+
+Then work through the three reference files in this skill's directory, in order:
+
+| File | When | What it decides |
+| --- | --- | --- |
+| `reference/build-order.md` | before spawning anything | the spec's §3 Parallel groups, the fallback for specs without dependency data, the proven-approach guard, and when to stop a group |
+| `reference/delegation.md` | once the build order is known | which agent owns each AC, what every brief must contain, the KB docs rule, and the architect escalation path |
+| `reference/ac-loop.md` | once per acceptance criterion | steps 1-5 — test first, implement, conform, confirm (including running that AC's e2e now), scope check — plus the rules on multi-interface ACs, deviating from the spec, and migrations |
+
+You orchestrate; you do not write feature code yourself.
+
+## Completion check
+
+Once every AC in the spec has been implemented:
+
+1. Verify that every AC has relevant code and a passing test — unit/integration and, where applicable, its e2e scenario already run per-AC in step 4 above — walk the spec's AC list explicitly, do not assume.
+2. If any test is not passing, fix the implementation and re-check. Do not report completion with known failing tests.
+3. Once all relevant tests pass, run the **`sw-verify-feature`** skill against the same spec path, as the final step of this flow — since every AC's tests (including e2e) already ran during implementation, this is a full-feature audit and cross-check, not the first execution of any test, and it still produces the authoritative pass/not pass/partly report per AC.
+
+**Status tags.** After an AC's own tests pass, you may mark it in the spec by inserting `[done]` (or `[partly]` when only part of the plan landed) directly after its bold id — `- **AC-2** [done] (FR-3)` — and the same on the matching `- **FR-n**` / `- **AC-n**` line of the PRD. Edit that line only; touch nothing else in either document. The Specs Editor and `sw-verify-feature` read and preserve these tags.
+
+## Report
+
+After `sw-verify-feature` completes, relay its report to the user. Do not produce a second, separate summary — `sw-verify-feature`'s report is the source of truth for completion status.

package/skills/sw-implement-feature/reference/ac-loop.md

@@ -0,0 +1,24 @@
+# The per-AC loop
+
+Entered once per acceptance criterion, by the agent the delegation table routed it to. Steps 1-5 run in order; none is optional.
+
+For each AC:
+
+1. **Test first.** Write the test(s) the spec defines for this AC — unit/integration, and, when the AC is user-facing, the e2e scenario the spec planned for it too. Do not defer writing the e2e test to `sw-verify-feature` — it is written now, alongside the unit/integration tests, so it exists to run in step 4. Confirm they fail for the right reason.
+2. **Implement.** Write the minimum code to satisfy the spec's architectural decision for this AC.
+3. **Conform.** Before running tests, bring this AC's new/changed code in line with Shopware's own toolchain, so conformance issues are caught and fixed while the AC is still open, not accumulated until `sw-verify-feature`'s final pass. If step 0's table shows the shopware-cli row unticked, skip this whole step for this AC and say so once, not per-AC — installing it is not this skill's job. Otherwise, scoped to `custom/plugins/<PluginName>` (or the narrower directory this AC actually touched):
+   - **Fix** (mutates code) — `shopware-cli extension fix --only <tools> custom/plugins/<PluginName>`, using only the tools that have a real `Fix()` in shopware-cli's own source (confirmed from `internal/verifier/*.go`): `eslint`,`stylelint` for Admin/Storefront JS/SCSS this AC touched, `rector` for PHP changes, `admin-twig` for Administration Twig templates, `symfony-xml` if the AC left a `services.xml`/`routes.xml` behind. Do **not** put `php-cs-fixer` or `phpstan` in this `--only` list — their `Fix()` is a no-op in shopware-cli; nothing will happen and it wastes a run.
+   - **Format** (style-only, still mutates) — `shopware-cli extension format --only <tools> custom/plugins/<PluginName>`, using `php-cs-fixer` for PHP changes and/or `prettier` for JS/JSON changes this AC touched — these two only do real work through `format`, not `fix`.
+   - **Validate** (read-only check, must fix anything it reports by hand) — `shopware-cli extension validate --full --only=phpstan,eslint,stylelint custom/plugins/<PluginName>` scoped to the areas this AC touched (PHP → phpstan; Admin/Storefront JS → eslint; SCSS → stylelint). **`--only` has no effect without `--full`** — passing `--only` alone silently resets to the default `sw-cli` structural check and none of these three run; always pass both flags together. Fix anything it reports before moving on — do not defer a known conformance error to the end-of-feature verification pass.
+   - This three-step sequence is a lighter, per-AC version of the full gates `sw-verify-feature` runs at the end (`sw-verify-feature-code-quality` for phpstan/eslint/stylelint at whole-plugin scope, `sw-verify-feature-architecture` for the `admin-twig`/`storefront-twig` read-only Twig lint gate); it exists to prevent surprises there, not to replace it. `sw-cli` itself (the default structural/manifest validation) and `storefront-twig` (no real `Fix()`) are check-only tools this skill never runs — that's `sw-verify-feature`'s job.
+4. **Confirm.** Run only the test(s) relevant to this AC (and any test it could plausibly have broken) — never the full suite mid-implementation. If they fail, fix the implementation, not the test, unless the test itself is wrong relative to the spec.
+   - **Run this AC's acceptance test now, not later.** Do not wait for the end-of-feature `sw-verify-feature` run to be the first time an AC's acceptance-level test executes. If the AC is user-facing and has an e2e scenario, execute it immediately after the unit/integration tests pass: spawn `sw-qa-engineer` with the spec path, this AC's id, the detected Shopware/PHP version and evidence, and the e2e scenario written in step 1, and have it run that scenario now via the Playwright MCP tools. Treat a failure here exactly like a failing unit test — the AC is not done until it passes.
+   - This means every AC leaves this loop already proven at both levels (unit/integration and acceptance/e2e). `sw-verify-feature`'s job at the end is to audit and re-confirm across the whole feature, not to be the first execution of any AC's test.
+5. **Scope check.** Run `git diff --stat` for this AC's changes. Every file listed must be explained by this AC's §3 plan or an existing §6 Decision Log entry — anything else gets reverted or added to §6 with a one-line reason before moving to the next AC.
+
+If the AC's data is exposed through more than one interface (Admin UI, Storefront, Store API, Admin API), the test(s) for it must check the real shape of **every** interface touched — rendered HTML, raw JSON response — not only a PHP entity accessor. Accessor methods can return a value through a fallback (e.g. an extension bag) that the actual serialized/rendered output does not expose the same way; a test that only calls `->get()` can pass while the feature is broken for every real consumer.
+
+Do not deviate from the spec's technical decisions. If the spec is ambiguous or wrong for a given AC, escalate to `sw-shopware-architect` (see above) rather than inventing a different technical approach. **Stop after the first workaround, not after several:** if satisfying an AC requires decorating, subclassing, or overriding a framework-internal class or service that the spec did not name, treat that as "the spec is wrong for this AC" immediately. Do not add a second override to patch a side effect of the first — report back instead of stacking fixes.
+
+If the spec's plan touches the database schema (migration, new table/column), run that migration against every environment the feature will be checked in before any manual or live check — not just the environment the automated test suite bootstraps for itself. A migration applied only where tests auto-provision it, and not in the environment used for manual verification, produces confusing "column/table not found" failures that look like implementation bugs.
+

package/skills/sw-implement-feature/reference/build-order.md

@@ -0,0 +1,17 @@
+# Build order and parallelisation
+
+Entered from step 0 of `sw-implement-feature`, before any agent is spawned. It decides *what* is built in which order and what may run concurrently.
+
+Work through the spec's §3 **Parallel groups** (written by `sw-design-solution`), one group at a time, in the build order given — not raw AC order. Within a group, every AC is implemented concurrently; a group only starts once every AC it depends on (per each AC's `Depends on` line) has gone fully green (test passing, conformance clean per step 3 below).
+
+**When the spec has no Parallel groups / Depends on data (older spec).** Fall back to determining parallel safety yourself, conservatively: default to sequential, and only parallelize a set of ACs when **all** of the following hold:
+- None of them touch the same migration, entity/DAL definition, or plugin service registration (`services.xml`) — check the spec's data model section, not just the AC text.
+- At least one AC from the same architectural area (entity, association, core extension point) has already gone green sequentially first, so the underlying approach is proven against the real framework, not still an assumption.
+- They don't depend on each other's output (one AC's test fixture, service, or UI element being present for another's).
+
+Note in the final report that the spec predates dependency data, so re-run `sw-design-solution` on it to unlock full parallelization next time.
+
+**Even with an explicit group, keep the proven-approach guard.** The spec's dependency data tells you *what* is safe to parallelize architecturally, not that the approach has been exercised against the framework yet. For the first group, land one AC from each distinct architectural area (entity, association, core extension point) before fanning the rest out — once proven green, the rest of that area's ACs across any group go fully parallel.
+
+If a parallelized AC's test fails for an architectural reason (not a simple bug), stop all parallel work in that group — the shared assumption behind them may be wrong, and continuing would just multiply the rework. Escalate per the Architect escalation rule below before resuming the group.
+

package/skills/sw-implement-feature/reference/delegation.md

@@ -0,0 +1,18 @@
+# Delegation, briefs and escalation
+
+Entered from step 0 of `sw-implement-feature`, once the build order is known. It decides *who* builds each AC and what they are told.
+
+**Delegation.** You orchestrate; you do not write feature code yourself. Route each AC to the agent that owns its layer via the Agent tool. Within a parallelized group, spawn one agent per AC concurrently (same message, multiple Agent calls) — dependencies are already resolved. Outside a parallel group (sequential fallback, or a group of size one), spawn one AC per call as before:
+
+| Step | AC touches | Agent |
+| --- | --- | --- |
+| 1 — tests | every AC (all test levels the spec lists, including the Playwright spec for e2e-tagged ACs) | `sw-qa-engineer` |
+| 2–4 — code | PHP: DAL entities, migrations, Store/Admin API routes, services/decorators, subscribers, flow/rule, message handlers | `sw-php-backend-developer` |
+| 2–4 — code | Administration: Vue modules/components, ACL privileges, snippets | `sw-admin-frontend-developer` |
+| 2–4 — code | Storefront: Twig, theme/SCSS, storefront controllers/pages/pagelets, storefront JS plugins | `sw-storefront-developer` |
+
+An AC spanning layers is split: backend first (route contract fixed), then Admin/Storefront against it. Each brief contains: the spec path, the AC id, the spec's architectural decision for that AC, the detected Shopware/PHP version and its evidence, the KB doc paths the spec's Decision Log cites for that AC (`platform/dev/<version>/…`), the gating conditions above, and the instruction to run steps 1–5 below and reply in the agent's own report format. Review the report; if anything is red, re-spawn the same agent with the failure. Do not fix the agent's output yourself.
+
+**Docs (ShopwareDevKnowledgeBase MCP).** Tell each implementing agent: `read_doc` the cited pages before writing code; when the spec names a mechanism without a citation, `grep_docs { pattern: "<mechanism>", path: "platform/dev/<version>" }` and read the page first. The version directory matches the installed `shopware/core` (`composer.lock`). The spec's decisions still win; the docs explain how, not whether.
+
+**Architect escalation.** When an implementer reports the spec is ambiguous or wrong for an AC, or the named extension point misbehaves (see the "stop after the first workaround" rule below), first `grep_docs` the KB for that mechanism yourself and `read_doc` the hit. Then spawn `sw-shopware-architect` with the spec path, AC id, the implementer's report, the KB page path (or "no KB page"), and the same detected Shopware/PHP version and evidence, before doing anything else. If the architect's decision stays within the spec, pass it to the implementer and continue; if it changes the spec, stop and report to the user — that change belongs in `sw-design-solution`.

package/skills/sw-setup/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: sw-setup
+description: Print one environment-readiness table for the project's development/test setup — containers, vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki and `.gitignore`, plus the installer CLI's own configuration/drift status. Stops when every row is ticked. When rows are missing, asks one yes/no question and delegates the fix to the installer CLI. Use when asked to set up the project, check if the environment is ready, or bootstrap the tests. Never designs, implements or verifies a feature itself — that's sw-design-solution, sw-implement-feature and sw-verify-feature, which call this skill first. Never writes a host configuration file itself — that's the installer CLI.
+when_to_use: Trigger phrases — "set up the project", "is the environment ready", "bootstrap the tests", "sw-setup".
+allowed-tools: Read Glob Grep AskUserQuestion Skill Bash mcp__ShopwareDevKnowledgeBase__kb_status Bash(npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 *)
+---
+
+# sw-setup
+
+One readiness table for this project's development/test environment. No
+arguments. Read-only by default; writes only after the user answers yes.
+
+## This file is a stub
+
+The harness ships as an npm package with an installer CLI
+(`@execuro-sw-ecosystem/sw-ecosystem-agentic-harness`) that owns every write
+to a host's configuration. Do not follow this file's workflow or rule-list
+instructions as the protocol for what gets installed or how — an installed
+copy of this skill can go stale while the CLI does not. For the current
+source of truth, run:
+
+```
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 guide
+```
+
+This skill only renders the CLI's output as a table and relays its one
+question; it never restates or re-implements the install protocol.
+
+## Called from other skills
+
+`sw-design-solution`, `sw-implement-feature` and `sw-verify-feature` invoke
+this skill as their own first step and read its table; they never repeat
+these checks themselves. A caller passes no arguments and reads the printed
+table from this run's output — it does not re-run `sw-setup`'s checks.
+
+## Procedure
+
+### 1. Status
+
+Run:
+
+```
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 status
+```
+
+It prints one JSON object (`ok`, `next_step`, `help`, and its own
+`hosts[]`/`drift[]` configuration state). Alongside it, run every
+environment row's check from `reference/rows.md` in this skill's directory —
+read-only, seconds each: file/directory existence, one `docker compose ps`,
+one version command, one `kb_status` call. Never write, never install, never
+ask a question in this step.
+
+Print one checkbox list, one line per row — the environment rows first, then
+one line per configuration item the CLI's `hosts[]`/`drift[]` reports:
+
+```
+- [x] Containers — web running
+- [x] vendor/ — shopware/core 6.7.13.0
+- [ ] Node — 18.x (need >= 20)
+- [-] Visual editors (optional) — Specs Editor not installed, Tender tool not installed
+- [x] shopware-cli — 0.16.10
+- [x] KB MCP — platform: implemented
+- [ ] Acceptance-test project — tests/acceptance/ missing
+- [ ] Playwright browsers — not installed
+- [ ] ATS env — tests/acceptance/.env missing
+- [x] Plugin tests — AhCheckout: phpunit + jest ok
+- [ ] Project wiki — docs/project-wiki/ missing
+- [ ] Installer config — .mcp.json entry: drift (from CLI status)
+```
+
+Per-plugin rows print one line per directory under `custom/plugins/`, e.g.
+`- [ ] Plugin tests — AcmeFeature: jest.admin.config.js missing`.
+
+### 2. All ticked
+
+Print one closing line: `Environment ready.` Stop. No question.
+
+### 3. Missing rows
+
+For a missing environment row, research only what it needs: the guideline
+sections `reference/rows.md` cites for that row
+(`shopware-project-qa-guidelines.md` §3.3–§3.7, §6.1), `compose.yaml` for the
+service name, `custom/plugins/*` names for per-plugin rows.
+
+For a missing/drifted configuration row, do not research or plan the fix
+yourself — the CLI's `plan` command already has it:
+
+```
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 plan
+```
+
+List the concrete steps in plain words: environment-row fixes in order
+(Containers → vendor/ → Visual editors → KB MCP → Acceptance-test project →
+Playwright browsers → ATS env → Plugin tests → Project wiki), then the CLI's
+planned configuration changes last. Skip any row already ticked.
+
+Ask exactly one question: "Do this and that?" with the steps spelled out in
+plain words (no command dump). 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).
+Options:
+- **Yes, run it** — run the environment-row fixes in order, then
+  `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 apply --yes`
+  for the configuration changes, then re-run step 1 and print the final table.
+- **No, stop** — stop; the table from step 1 is already on screen.
+
+### 4. Rules
+
+- Everything stays under the project directory; never a global install,
+  never a path under `~`.
+- Host tools that cannot live under the project (Node, shopware-cli, Docker
+  itself) are reported with install advice only, never installed.
+- Credentials (ATS env values) are prompted for as part of the single
+  question in step 3, never invented, never printed back once entered.
+- A fix that needs a running container states so in the step list and stops
+  before running if the Containers row is still unticked at execution time.
+- The Project wiki fix invokes `sw-document-feature --setup` with the Skill
+  tool; the KB MCP row only reports whether the platform layer is built —
+  the corpus ships already built inside the
+  `@execuro-sw-ecosystem/sw-dev-knowledge-base-mcp` package. If `platform` is
+  not `implemented`, the fix is to check the registration (re-run the
+  installer CLI's `apply --yes`) or update that package — never build a
+  corpus here. Neither is replicated in this skill.
+- This skill never writes a host configuration file itself (`.mcp.json`,
+  permission grants, `.gitignore` lines). Every such write goes through the
+  installer CLI's `apply --yes`, run only after the user's yes.
+
+### 5. Report
+
+Print the final table (from step 1, or re-run after step 3's fix), then one
+line:
+- `Ready for: design · implement · verify` when every row is ticked, or
+- the first row still unticked and which skills it blocks, per
+  `reference/rows.md`'s "Blocks" line for that row (environment rows), or the
+  CLI's own `next_step` (configuration rows) — e.g. `Blocked: vendor/ —
+  blocks sw-design-solution, sw-implement-feature, sw-verify-feature`.
+
+## Reference files
+
+`reference/rows.md` in this skill's directory — the twelve environment rows:
+check command(s), what "ticked" means, the fix steps verbatim from the
+guideline, and which skills the row blocks. Host configuration state (what
+gets installed into `.mcp.json`, permissions, `.gitignore`) is not in this
+file — it comes from the installer CLI's `status`/`plan`/`apply` output.

package/skills/sw-setup/reference/rows.md

@@ -0,0 +1,223 @@
+# Readiness rows
+
+Eleven environment rows. Each: check (read-only), what "ticked" means, the fix
+(only run on approval, in this order), and which skills the row blocks when
+unticked. Host configuration files (`.mcp.json` entries, `.gitignore` lines,
+permission grants) are not rows here — the installer CLI owns them and
+reports their state in its own `status`/`plan` output; see `SKILL.md`.
+
+## 1. Containers
+
+- **Check:** `docker compose ps` — service `web` (or the service named in
+  `compose.yaml`) shows `running`/`healthy`.
+- **Ticked:** the `web` service is up.
+- **Fix:** `docker compose up -d` (guideline §6.1). If the shop was never
+  installed: `docker compose exec web php bin/console system:install --basic-setup --force --no-interaction` (guideline §6.1).
+- **Blocks:** every other row's fix that runs `docker compose exec web …`
+  (vendor/, plugin tests). Design/implement/verify skills that need a running
+  shop for live checks.
+
+## 2. vendor/
+
+- **Check:** `vendor/shopware/core` exists, `composer.lock` exists,
+  `vendor/bin/phpunit` exists — file presence only, never a host
+  executable-bit check: composer runs inside the container, so the file can
+  land `-rw-------` on the host and still run fine inside the container
+  (guideline §6.2).
+- **Ticked:** all three present; report the `shopware/core` version from
+  `composer.lock`.
+- **Fix:** `docker compose exec web composer install --no-interaction`
+  (guideline §6.1 — "a vendor tree built with `--no-dev` has no
+  `vendor/bin/phpunit`"). Needs the Containers row ticked first.
+- **Blocks:** `sw-design-solution`, `sw-implement-feature`,
+  `sw-verify-feature` (and its architecture/code-quality/ac-tests sub-skills).
+
+## 3. Node
+
+- **Check:** `node --version`; parse major and minor.
+- **Ticked:** ≥ 20. Warn (do not fail) when < 20.15: the Tender Discovery Tool
+  needs `zlib.crc32` for the xlsx write-back, so `export --xlsx` will not run
+  below 20.15 while everything else does.
+- **Fix:** none — host tool. Report the install advice only: use the
+  project's documented Node version manager, or https://nodejs.org/. Never
+  install it globally on the user's behalf.
+- **Blocks:** the Specs Editor, the Tender Discovery Tool, the KB MCP server
+  (the knowledge-base MCP), the acceptance-test project,
+  Playwright.
+
+## 4. Visual editors (optional)
+
+The Specs Editor and the Tender Discovery Tool are **optional add-ons**, not
+part of this plugin. The installer CLI installs them itself, per host — this
+row never runs a companion package's own install command.
+
+So this row never blocks readiness. It asks.
+
+- **Check:** read `companions[]` from the `status` output the skill already
+  ran in step 1 — each entry's `available`, `installed_for` (the hosts it is
+  placed in), and `install` (the npm command, when missing). Never probe a
+  path and never run a companion package by hand; the CLI owns both.
+- **Ticked:** `[x]` when a companion's `available` is true and
+  `installed_for` includes this host; `[-]` when the user has declined it.
+  Only an unanswered offer shows `[ ]`, and even then it does not hold the
+  table open — report it as optional and move on.
+- **Fix:** offer each missing companion inside step 3's single question,
+  naming what it buys, not how it works: "Specs Editor — review a PRD or
+  tech spec on a live page, with notes, question answers and diagrams.
+  Install?" — and "Tender Discovery Tool — read a client tender workbook,
+  confirm its column mapping and review the analysis on a live page.
+  Install?" On yes, for each accepted one: `npm i -D <package>@0.1.0` (the
+  `package` field from `companions[]`), then re-run
+
+  ```
+  npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 apply --yes
+  ```
+
+  which places one `SKILL.md` per companion into each selected host's own
+  skills directory, records it, and removes it again on uninstall. **Never
+  run the companion package's own `install-skill`** — with no `--target` it
+  defaults to Claude Code's own skills directory, wrong for a Codex, Copilot
+  or Cursor install. Needs the Node row ticked.
+- **On no:** record the decline and do not re-ask on the next run. `apply`
+  keeps reporting that skill as `skipped` — the intended steady state, not a
+  fault. `--editor` on `sw-design-requirements` / `sw-design-solution` /
+  `sw-discover-tender` then stops with one line naming this skill.
+- **Blocks:** Specs Editor missing → `sw-design-requirements --editor`,
+  `sw-design-solution --editor`, the `sw-specs-editor` skill. Tender
+  Discovery Tool missing → `sw-discover-tender --editor` and its `.xlsx`
+  import, plus the `sw-tender-discovery-tool` skill.
+
+## 5. shopware-cli
+
+- **Check:** `command -v shopware-cli`.
+- **Ticked:** present on `PATH`.
+- **Fix:** none — host tool. Report the install advice only: Homebrew cask
+  `shopware-cli` (verified in `sw-verify-feature-architecture`, step 4).
+  Never install it on the user's behalf.
+- **Blocks:** `sw-verify-feature-architecture`, `sw-verify-feature-code-quality`
+  (static analysis, Twig linters), `sw-implement-feature` (per-AC
+  `extension fix`/`extension validate`).
+
+## 6. KB MCP
+
+- **Check:** `mcp__ShopwareDevKnowledgeBase__kb_status` reports the `platform`
+  layer as `implemented`. (Whether the `ShopwareDevKnowledgeBase` entry
+  exists in `.mcp.json` is installer configuration, not checked here — the
+  installer CLI's `status`/`plan` output covers it.)
+- **Ticked:** `platform` `implemented`.
+- **Fix:** the entry itself is installed by the installer CLI (`apply`), not
+  by this skill. The corpus ships already built, inside the
+  `@execuro-sw-ecosystem/sw-dev-knowledge-base-mcp` package — nobody
+  consuming this package builds one. If `platform` is not `implemented`,
+  check the registration first: does `.mcp.json` list the
+  `ShopwareDevKnowledgeBase` entry, and is `sw-dev-knowledge-base-mcp`
+  current? The fix is to re-run the installer CLI's `apply --yes`, or bump
+  the `sw-dev-knowledge-base-mcp` package to a version that ships the
+  corpus — never build one locally.
+- **Blocks:** `sw-design-requirements` (stock-behaviour lookup),
+  `sw-design-solution` step 0.5/step 3 (KB grep), `sw-product-manager`,
+  `sw-shopware-architect`.
+
+## 7. Acceptance-test project
+
+- **Check:** `tests/acceptance/package.json` exists and lists
+  `@shopware-ag/acceptance-test-suite` as a dependency;
+  `tests/acceptance/playwright.config.ts` exists;
+  `tests/acceptance/fixtures/BaseTestFile.ts` exists.
+- **Ticked:** all three present.
+- **Fix (guideline §3.7, host, once):**
+  ```bash
+  mkdir -p tests/acceptance && cd tests/acceptance
+  npm init -y && npm pkg set type=module
+  npm install -D @playwright/test @shopware-ag/acceptance-test-suite dotenv
+  ```
+  then write `playwright.config.ts` and `fixtures/BaseTestFile.ts` from the
+  templates quoted in guideline §3.7 verbatim (do not paraphrase — Playwright
+  fails on a malformed config). Needs the Node row ticked.
+- **Blocks:** `sw-implement-feature` (e2e authoring by `sw-qa-engineer`),
+  `sw-verify-feature-ac-tests` (Playwright execution).
+
+## 8. Playwright browsers
+
+- **Check:** `npx playwright install --dry-run` output (or
+  `~/.cache/ms-playwright`/the project-local browsers path) shows Chromium
+  installed for the Playwright version in `tests/acceptance/package.json`.
+- **Ticked:** Chromium present.
+- **Fix:** `npx playwright install --with-deps chromium` run inside
+  `tests/acceptance` (guideline §3.7). Needs the Acceptance-test project row
+  ticked (the `@playwright/test` version comes from there).
+- **Blocks:** `sw-implement-feature` (e2e execution), `sw-verify-feature-ac-tests`.
+
+## 9. ATS env
+
+- **Check:** `tests/acceptance/.env` exists.
+- **Ticked:** file exists and defines `APP_URL`, `SHOPWARE_ADMIN_USERNAME`,
+  `SHOPWARE_ADMIN_PASSWORD` (the names guideline §3.7's `.env.example` block
+  documents).
+- **Fix:** copy `tests/acceptance/.env.example` to `tests/acceptance/.env` if
+  the example is missing, write it from the guideline §3.7 template first —
+  then ask the user for the real `APP_URL`/admin credentials (or
+  `SHOPWARE_ACCESS_KEY_ID`/`SHOPWARE_SECRET_ACCESS_KEY` as the alternative the
+  template lists) with a structured question tool if one is available, or
+  directly otherwise; never invent values, never print them back once
+  entered. Needs the Acceptance-test project row ticked.
+- **Blocks:** `sw-implement-feature` (e2e execution), `sw-verify-feature-ac-tests`.
+
+## 10. Plugin tests, per `custom/plugins/<Name>`
+
+- **Enumerate:** `ls custom/plugins`; one row per directory found.
+- **Check per plugin:**
+  - PHP: `custom/plugins/<Name>/phpunit.xml.dist` and
+    `custom/plugins/<Name>/tests/TestBootstrap.php` both exist.
+  - Admin JS: only if `custom/plugins/<Name>/src/Resources/app/administration`
+    exists — then also require `custom/plugins/<Name>/package.json` and
+    `custom/plugins/<Name>/jest.admin.config.js` (or the project's equivalent
+    name, e.g. `jest.administration.config.js`).
+  - Storefront JS: only if
+    `custom/plugins/<Name>/src/Resources/app/storefront` exists — then also
+    require `package.json` and `jest.storefront.config.js`.
+- **Ticked:** the PHP pair present, plus each applicable JS pair present.
+- **Fix:** scaffold the missing files from the guideline templates —
+  `phpunit.xml.dist` from §3.3, `tests/TestBootstrap.php` from §3.4 (fill
+  `<Name>`/`<Vendor>` from `composer.json`), Jest config(s) from §3.5 (option
+  (a), plugin-local preset), `package.json` scripts block from §3.5's closing
+  JSON snippet. Needs the Containers row ticked for the `npm install` steps
+  that run inside the container.
+- **Blocks:** `sw-implement-feature` (PHPUnit/Jest execution for that
+  plugin's ACs), `sw-verify-feature` (and its sub-skills, for that plugin).
+
+## 11. Project wiki
+
+- **Check:** `docs/project-wiki/` exists.
+- **Ticked:** directory present.
+- **Fix:** invoke skill `sw-document-feature --setup` (Skill tool) — it asks
+  its own flavour questions and writes the scaffold; do not replicate that
+  logic here.
+- **Blocks:** `sw-document-feature`.
+
+## 12. `.gitignore`
+
+- **Check:** `.gitignore` contains all six lines:
+  ```
+  /specs/.editor/
+  /specs/.rfp/
+  tests/acceptance/node_modules/
+  tests/acceptance/.env
+  tests/acceptance/test-results/
+  var/verification-screenshots/
+  ```
+  (`/specs/.editor/` and `/specs/.rfp/` are already present in this project's
+  `.gitignore`; check the other four independently. `.sw-ai-sdk/` is not on
+  this list — the installer CLI adds that one itself.)
+
+  Do **not** add `specs/<rfp-basename>/`. The tender tool's normalised source
+  export and its `import-map.json` live there and are committed on purpose —
+  they are what the analysis reads, hashes and exports from. Only the transient
+  half (snapshot, proposed map) goes to the ignored `/specs/.editor/`.
+- **Ticked:** all six present (exact path forms, not just a substring match
+  on directory name).
+- **Fix:** append whichever of the six lines are missing, each under a short
+  comment naming its owner (specs-editor, sw-discover-tender, acceptance-test
+  project, verify-ac-tests screenshots). Idempotent — safe to re-run.
+- **Blocks:** nothing directly; unticked means the next `git status` will
+  show generated/secret files as untracked.

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

@@ -0,0 +1,64 @@
+---
+name: sw-verify-feature
+description: Verify a feature implementation against its technical spec (specs/NNNN-slug-spec.md) by running three independent verifiers in parallel — AC test coverage/health, architecture/guideline compliance, and code quality/static analysis — then cross-checking their verdicts into one final per-AC pass/not pass/partly report. Wired as the final step of sw-implement-feature; can also be run standalone to (re)check a feature. Not to be confused with the existing "verify-implementation" skill, which is a mock and should be ignored.
+when_to_use: Trigger phrases — "verify spec 0007", "check if this feature is done", "run full verification for this feature", "is epic 1 actually passing".
+argument-hint: [specs/NNNN-slug-spec.md]
+allowed-tools: Read Write Glob Grep Agent
+---
+
+# sw-verify-feature
+
+Independently verify that an implementation actually satisfies its spec. This is the completeness gate — do not soften a `not pass` into a `partly` to be agreeable.
+
+This skill is a pure orchestrator: it does not run tests, read code for compliance, or execute static analysis itself. It spawns three specialist verifier skills in parallel, each of which performs its own verification with its own tools, then cross-checks their independent verdicts into one report, written to `specs/NNNN-slug-verification.md` using `reference/verification-report-template.md`.
+
+## Read-only contract
+
+This skill observes and reports. It never changes the project code: no source/test file created, edited or deleted, no fix applied, no migration run, no git action. The one file this skill is allowed to write is its own output report at `specs/NNNN-slug-verification.md` (create or overwrite). Anything found wrong in the project is a report line handed to `sw-implement-feature`, never a fix. The same contract binds every agent this skill spawns — pass it verbatim in each brief.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| Path to `specs/NNNN-slug-spec.md` | Verify this spec against the current codebase |
+| Nothing | Ask the user for the spec path |
+
+## Procedure
+
+### 1. Load the AC lists
+
+Read the spec's acceptance criteria — this is the reference list used in step 3 to catch a verifier that silently drops an AC.
+
+Also read the source PRD: same `NNNN-slug` as the spec, at `specs/NNNN-slug.md` (drop the `-spec` suffix). Read its §7 Acceptance Criteria — this is the AC-n list the feature was originally scoped to. This skill runs independently of `sw-implement-feature` (it can verify a manually-implemented feature just as well, and doubles as this skill's own test), so it cannot assume the spec still matches the PRD it was derived from; that assumption is exactly what this check exists to catch.
+
+If the PRD file doesn't exist, note `PRD not found — traceability check skipped` in the final report's Overall Verdict and skip the PRD comparison in step 3.
+
+Otherwise, diff the two `AC-n` lists. Any AC-n in the PRD but absent from the spec is a **traceability gap**: it was never carried into the implementation plan, so none of the three verifiers below can find or test it. Record these now — they are forced into the per-AC table in step 3 as `not pass`, not silently dropped for being out of the spec's own list.
+
+### 2. Spawn the three verifiers in parallel
+
+**Shopware version — detect once, here, before spawning anything, never assume:** `vendor/shopware/core/composer.json` `version` → `composer.lock` → `composer.json` constraint ("unconfirmed"); PHP from the project runtime (`compose.yaml`, `.ddev/config.yaml`, `Dockerfile`), not the host. Pass version + source to every spawned agent; unknown → ask the user. Also invoke `sw-setup` once, here — before spawning anything.
+
+In a single message, make three `Agent` tool calls (one per verifier), each delegated to a general-purpose worker sub-agent since it just needs to invoke a skill and relay its output — do not use `fork`, these need no conversation context. Each prompt must contain:
+
+- The spec path.
+- The detected Shopware/PHP version and its evidence, plus the `sw-setup` table text.
+- The read-only contract above, verbatim.
+- The exact instruction: invoke the `Skill` tool with the named skill below, passing the spec path, the detected version and evidence, and the `sw-setup` table as `args`, then return that skill's complete report output verbatim — no summarizing, no reformatting, no adding or dropping lines.
+
+The three skills, one per Agent call:
+
+1. `sw-verify-feature-ac-tests`
+2. `sw-verify-feature-architecture`
+3. `sw-verify-feature-code-quality`
+
+Never call these three sequentially — they run concurrently. If one Agent call fails to spawn or errors out, note it and continue with the other two; do not block the run on a single failed spawn (report that dimension as `not consulted — <reason>` in step 4 instead of silently omitting it).
+
+
+### 3-5. Reconcile and report
+
+Follow `reference/reconcile-and-report.md` in this skill's directory: cross-check the
+three verifiers into one per-AC pass / partly / not pass verdict, collect the
+whole-feature gate lines, and write the report from
+`reference/verification-report-template.md`. Never report a verdict a verifier did not
+support, and never re-run a verifier's work yourself.

package/skills/sw-verify-feature/reference/reconcile-and-report.md

@@ -0,0 +1,42 @@
+# Reconciling the verifiers and writing the report
+
+Entered once all three verifiers have returned. Steps 3-5 of `sw-verify-feature`: cross-check the three verdicts into one per-AC result, collect the whole-feature gate lines, and write the report.
+
+### 3. Reconcile per-AC verdicts
+
+Each verifier reports its own `AC-n | pass/partly/not pass | ...` line. For every AC in the union of the spec's list and the PRD's list (step 1):
+
+- AC-n exists in the PRD but not in the spec → final verdict `not pass`, failing dimension `traceability`, note `AC missing from spec — never implemented or tested`. Do not ask a verifier for it; none can see an AC the spec never mentioned.
+- Else, for an AC-n present in the spec:
+  - If any verifier reports `not pass` for that AC → final verdict `not pass`.
+  - Else if any verifier reports `partly` → final verdict `partly`.
+  - Else (all three report `pass`) → final verdict `pass`.
+  - If a verifier's report has no line at all for an AC that exists in the spec → treat that as `not pass` from that verifier (a missing line is not a pass by omission).
+
+Carry forward the specific reason from whichever verifier(s) triggered the downgrade — the final report must say *which* dimension failed (tests / architecture / code quality / traceability), not just that something did.
+
+While reconciling, also tally the PRD AC coverage counts used in step 5's gate line: how many PRD ACs land on `pass` (a passing test found), how many are `not pass`/`partly` specifically because of the `tests` dimension (a test exists but fails, or is flagged unhealthy), and how many are `traceability` (no test possible — AC absent from spec) or otherwise have no test located at all (from `sw-verify-feature-ac-tests`'s Coverage column). These three counts — passed / failed / absent — are what makes the PRD comparison useful; a single "N ACs not pass" number would hide which of the three it is.
+
+### 4. Collect the whole-feature gate lines
+
+Beyond the per-AC lines, each verifier also reports gates that don't map to a single AC. Carry all of them into the final report unchanged:
+
+- From `sw-verify-feature-ac-tests`: the Test Health Report (flagged tests).
+- From `sw-verify-feature-architecture`: the Project guidelines line, the shopware-cli Twig linters (`admin-twig`/`storefront-twig`) line.
+- From `sw-verify-feature-code-quality`: the PHPStan/ESLint/Stylelint/sw-cli line, the PHPUnit regression line, its own Project guidelines line (merge with the architecture skill's if identical, keep both if they differ).
+- The PRD AC coverage tally from step 3 (skip this line entirely if the PRD file wasn't found — do not report `0/0`).
+
+### 5. Report
+
+Fill `reference/verification-report-template.md` verbatim and write it to `specs/NNNN-slug-verification.md`, where `NNNN-slug` matches the spec being verified (e.g. `specs/0007-checkout-notes-verification.md` for `specs/0007-checkout-notes-spec.md`). If the file already exists from a previous run, overwrite it — this report is a snapshot of the latest run, not an append-only log.
+
+- **§1 Per-AC Verdicts** — one row per AC in the union list from step 1 (spec ∪ PRD), reconciled per step 3 above. An AC that only exists in the PRD still gets a row here, marked `not pass` / `traceability`.
+- **§2 Whole-Feature Gates** — the gate lines collected in step 4, each prefixed by its source verifier (`[tests]`, `[architecture]`, `[code-quality]`), copied verbatim from what each verifier reported, plus the `[tests] PRD AC coverage: <passed>/<total> passed, <failed> failed, <absent> absent` line from step 3's tally (`failed` = test exists but fails/flagged, `absent` = no test located, including ACs missing from the spec entirely).
+- **§3 Test Health Report** — copied verbatim from `sw-verify-feature-ac-tests`'s report.
+- **§4 Overall Verdict** — one paragraph: fully verified, or the count of ACs not passing/partly plus whether every whole-feature gate passed. End with `Verifiers consulted: tests, architecture, code-quality` (list only the ones that actually ran; note any `not consulted — <reason>`).
+
+Never mark the feature complete if any AC is `not pass` or any whole-feature gate reports `fail`. A `not run`/`not active` gate does not block the AC verdicts, but the overall verdict must say so explicitly rather than reading as fully verified. `partly` always carries the one-sentence reason from the verifier that reported it.
+
+**Status tags (only exception to the read-only contract).** Per AC verdict you may set the inline tag directly after the bold id in the spec and PRD: `pass` → `[done]`, `partly` → `[partly]`, `not pass` → remove the tag (open). Change only that line; no other edit to either document.
+
+After writing the file, also relay the same content as your final response — the file is the durable record, the chat response is so the caller (e.g. `sw-implement-feature`) sees the result immediately without a separate read.