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

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@playwright/mcp@latest"]
+    }
+  }
+}

package/CHANGELOG.md

@@ -0,0 +1,78 @@
+# Changelog
+
+All notable changes to the Shopware Ecosystem Agentic Harness are recorded here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
+versioning is [semver](https://semver.org/) — `0.x` until the first stable
+release.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-16
+
+### Added
+
+- **An npm package with an installer CLI** — `bin/cli.mjs` plus `lib/`,
+  published as `@execuro-sw-ecosystem/sw-ecosystem-agentic-harness` with the bin
+  `sw-ecosystem-agentic-harness`. Commands `status`, `plan`, `apply`,
+  `uninstall` and `guide`, each printing one JSON object with a mandatory
+  `next_step`; `exit 2` on a usage error with a `help` array of runnable
+  commands. Zero runtime dependencies, no install hooks.
+- **Installs into all four hosts** — Claude Code, OpenAI Codex, GitHub Copilot
+  and Cursor, each into its own native discovery directories, with the MCP
+  servers written in each host's own format.
+- `copilot/agents/*.agent.md` — Copilot adapters generated by
+  `scripts/gen-copilot-agents.mjs`, with Claude tool names mapped through
+  Copilot's alias table. An unknown tool name fails the build rather than
+  disappearing.
+- `content/AGENTS.md` — generated from the shipped skills and agents by
+  `scripts/gen-agents-md.mjs`. Codex, Copilot and Cursor read it from the
+  installed tree, and Codex never reads `CLAUDE.md`.
+- `scripts/frontmatter.mjs` — the frontmatter reader shared by all three
+  generators.
+- `scripts/check-pack.mjs` — fails when the tarball would carry anything outside
+  the `files` allow-list, or when a lifecycle script is declared.
+- `.github/workflows/release.yml` — OIDC trusted publishing with
+  `--provenance`, gated on the generators, the tests, the pack check and the
+  licence metadata.
+- A full `node --test` suite, zero dependencies, covering the whole risk
+  surface the compatibility guide names: install idempotency asserted on
+  **mtimes**, malformed and JSONC configs, the uninstall round trip, Windows
+  command wrapping and POSIX lock keys, and per-host error aggregation.
+- The remaining `sw-*` skills — `sw-setup`, `sw-discover-tender`,
+  `sw-design-requirements`, `sw-design-solution` — so the package now ships
+  all **10** skills and **7** sub-agents. The Specs Editor's own skill ships
+  inside its own package, not here.
+
+### Changed
+
+- **`sw-setup` is now a stub skill.** It runs the CLI's `status`, renders the
+  table, asks its one question and runs `apply --yes`. It never writes a host
+  file and no longer carries the rule list — the CLI is the single source of
+  truth for what gets installed.
+- **Every `SKILL.md` is under 8 KB**, Codex's effective cap, enforced by a test.
+  `sw-discover-tender` (27.5 KB), `sw-design-solution` (17.8 KB) and
+  `sw-design-requirements` (12.7 KB) were reorganised into `reference/` router
+  files — reorganised, not compressed: each split was audited line-by-line
+  against its pre-split copy.
+- **No Claude-only construct is left anywhere.** All `${CLAUDE_SKILL_DIR}`,
+  `$ARGUMENTS`, `SendMessage`, `subagent_type` and literal `.claude/…` paths are
+  gone, and every `AskUserQuestion` in prose now names the capability with both
+  hosts as an aside.
+- `mcp.json` is now the portable Agent Plugins 1.0 form — it carries the
+  `$schema` and a `type: "stdio"` per server, and is no longer a copy of
+  Claude Code's `.mcp.json`. They are different formats.
+- `README.md` documents the installer rather than a marketplace install.
+
+### Removed
+
+- `extensions.com.openai.codex` from the root `plugin.json`. No Codex manifest
+  struct has an `agents` field, so the declaration was a no-op.
+- The "carries no executables" claim from both plugin descriptions. The package
+  now carries exactly one: the installer.
+
+### Notes
+
+- Distribution is the installer, not a plugin marketplace. The plugin
+  manifests are kept valid in CI although nothing reads them today.
+- The `ShopwareDevKnowledgeBase` and `playwright` MCP registrations both track
+  `@latest`; every other pinned thing in this package is pinned exactly.

package/CONTRIBUTING.md

@@ -0,0 +1,54 @@
+# Contributing
+
+## Toolchain
+
+Node >= 20, `git`. Zero runtime dependencies — keep it that way; a new
+dependency here ships to every project that installs this package.
+
+## Before you send a change
+
+All of these must pass:
+
+```bash
+npm test                        # the full suite
+npm run gen:check                # generated adapters match their sources
+node scripts/check-pack.mjs      # the tarball matches the files allow-list
+```
+
+If you edited an agent or a skill, regenerate the host adapters first and
+commit the result:
+
+```bash
+npm run gen
+```
+
+## Rules that bite
+
+- **`codex/agents/*.toml` and `copilot/agents/*.agent.md` are generated** from
+  `agents/*.md` by `scripts/gen-codex-agents.mjs` and
+  `scripts/gen-copilot-agents.mjs`. Never hand-edit them — run `npm run gen`
+  and commit the output. `npm run gen:check` fails the build on drift.
+- **Every `SKILL.md` stays under 8192 bytes**, Codex's effective cap and the
+  smallest of the four hosts'. A test enforces it. When a skill grows past the
+  cap, move material into `reference/*.md` beside it — that is
+  **reorganisation, never compression**. Audit the split against the
+  pre-split file line by line; do not drop meaning to make the number work.
+- **Skills stay host-neutral.** No `${CLAUDE_SKILL_DIR}`, no `$ARGUMENTS`, no
+  `SendMessage` or `subagent_type`, no literal `.claude/…` path. Any prose that
+  asks the user a question names both Claude Code's and Codex's question
+  tools, not just one.
+- **The installer never prompts, never fetches, and writes atomically.**
+  Every file is written to a temporary path and renamed. A change that breaks
+  any of those three properties is a change to the contract this package
+  makes with its users, not an implementation detail — flag it explicitly in
+  the change description.
+
+## Working on the package
+
+`scripts/` is developer tooling: run by hand and by CI, never shipped in the
+published tarball, and never run on a user's machine.
+
+`claude plugin validate <dir> --strict` resolves a directory to one manifest
+and returns `contents: []` on its own, so run it against all four explicit
+targets — `.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`,
+`skills`, `agents` — not just the directory.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Execuro UG (haftungsbeschränkt)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,304 @@
+# Shopware Ecosystem Agentic Harness
+
+The `sw-*` skills and sub-agents for Shopware 6 projects: they turn a briefing
+into a PRD, a PRD into a technical spec, a spec into tested code, and tested
+code into a project wiki page.
+
+It ships as **one npm package carrying an installer**. The installer copies the
+skills and agents into whichever coding agents your repository uses and
+registers the MCP servers and permission rules they depend on. Nothing is
+loaded as a plugin, because the configuration the harness needs has no plugin
+vehicle on any host.
+
+- Published by Execuro UG (haftungsbeschränkt) under the MIT licence.
+- Installs into **Claude Code, OpenAI Codex, GitHub Copilot and Cursor**.
+- Zero runtime dependencies, and no install hooks: nothing executes on your
+  machine except the CLI you invoke yourself.
+
+## What it ships
+
+| Component | Where | Contents |
+| --- | --- | --- |
+| Skills | `skills/` | 10 `sw-*` skills — `sw-setup`, `sw-discover-tender`, `sw-design-requirements`, `sw-design-solution`, `sw-implement-feature`, `sw-document-feature`, `sw-verify-feature` and its three verifiers (`-ac-tests`, `-architecture`, `-code-quality`) |
+| Sub-agents | `agents/` | `sw-storefront-developer`, `sw-php-backend-developer`, `sw-admin-frontend-developer`, `sw-qa-engineer`, `sw-shopware-architect`, `sw-product-manager`, `sw-tender-editor` |
+| Codex adapters | `codex/agents/` | The seven agents as Codex TOML roles — Codex plugins cannot ship sub-agents, so the installer writes these into `.codex/agents/` |
+| Copilot adapters | `copilot/agents/` | The same seven as `.agent.md`, with Claude tool names mapped to Copilot's |
+| Installer | `bin/`, `lib/` | The `sw-ecosystem-agentic-harness` CLI |
+
+Every adapter is generated from `agents/*.md` at build time, committed, and
+diff-checked in CI — so a bad mapping is a red build here, never a broken
+install on your machine.
+
+### Separate packages
+
+The knowledge-base MCP server (`@execuro-sw-ecosystem/sw-dev-knowledge-base-mcp`)
+and the two visual editors (`@execuro-sw-ecosystem/sw-specs-editor`,
+`@execuro-sw-ecosystem/sw-tender-discovery-tool`) are their own npm packages.
+This package registers the knowledge base as an MCP server; it does not contain
+it. The knowledge-base server is also listed in the MCP Registry as
+`io.github.execuro/sw-dev-knowledge-base-mcp` — a separate discovery-catalogue
+identity, not an npm package name — and can be run standalone in any stdio MCP
+client without this harness.
+
+The two editors are **optional add-ons**, and each ships its own skill inside
+its package rather than here. `sw-setup` offers to install them; a host that
+declines is fully set up without them, and `--editor` on `sw-design-requirements`,
+`sw-design-solution` or `sw-discover-tender` then stops with one line saying so.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `status` | read-only; what is installed, what drifted, which optional companion packages are present |
+| `plan` | the exact changes, written as a diff; writes nothing |
+| `apply --yes` | performs them |
+| `uninstall --yes` | removes what the lock file records |
+| `guide` | the install protocol, the single source of truth |
+
+Flags: `--host claude-code|codex|copilot|cursor` (repeatable; omitting it
+selects every host that is present), `--scope project|user` (default
+`project`), `--root <path>` (default the current directory), `--yes` (required
+by `apply` and `uninstall`, never prompts), and `--no-companions` (skip
+detection of the optional editor packages).
+
+## Install
+
+```bash
+# see what is there and what is missing — read-only, always safe
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness status
+
+# see the exact changes, written as a diff. Writes nothing.
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness plan
+
+# perform them
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness apply --yes
+```
+
+Then restart your coding agent — every host reads its configuration at startup.
+The command's output tells you which ones and how.
+
+`apply` refuses without `--yes` and never prompts: Codex's question tool does
+not block outside Plan mode, and CI has no terminal. Add `--host claude-code`
+(repeatable) to install into one agent, and `--scope user` to install into your
+home directory instead of this repository. The default scope is the project —
+nothing is written under `~` unless you ask.
+
+### What it writes
+
+| Host | Skills | Sub-agents | MCP | Settings |
+| --- | --- | --- | --- | --- |
+| Claude Code | `.claude/skills/` | `.claude/agents/` | `.mcp.json` | `.claude/settings.json` |
+| Codex | `.agents/skills/` | `.codex/agents/*.toml` | `.codex/config.toml` | `.codex/config.toml` |
+| GitHub Copilot | `.github/skills/` | `.github/agents/*.agent.md` | `.mcp.json`, `.vscode/mcp.json` | — |
+| Cursor | reads Claude's | reads Claude's | `.cursor/mcp.json` | — |
+
+`AGENTS.md` gets a managed block too — Codex, Copilot and Cursor read it, and
+Codex never reads `CLAUDE.md`.
+
+### What it will not do
+
+- **It never overwrites a file it did not install.** A file already at one of
+  these paths that differs from ours is reported as a conflict and left alone.
+- **It never overwrites your edits.** Once installed, a file you change is
+  reported as drift and skipped on every later run.
+- **It never removes or loosens an existing rule.** Permission lists are merged.
+  A rule you delete after install is remembered as declined and never re-added.
+- **It never rewrites a config with comments.** A JSONC `.vscode/mcp.json`
+  becomes a manual step with the exact snippet, rather than losing your notes.
+- **It writes atomically.** Every file is written to a temporary file and
+  renamed, so an interrupted run cannot truncate your settings.
+
+Undo everything with:
+
+```bash
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness uninstall --yes
+```
+
+It removes exactly what the lock file at `.sw-ai-sdk/harness.lock.json` records,
+keeps anything you hand-edited, and tells you what it kept.
+
+### From a skill
+
+`sw-setup` is a stub: it runs `status`, renders the table, asks once, and runs
+`apply --yes`. It deliberately restates none of the protocol, because an
+installed skill file goes stale and the CLI does not. Anything that needs the
+protocol runs:
+
+```bash
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness guide
+```
+
+## Prerequisites
+
+| Requirement | Why | Check |
+| --- | --- | --- |
+| `shopware-cli` ≥ 0.16 | Every `bin/console` call and every build the agents run goes through it | `shopware-cli --version` |
+| A running dev environment | `shopware-cli project console` proxies into the `web` container; without it you get `service "web" is not running` | `shopware-cli project dev` |
+| Node ≥ 20 | The MCP servers and the editor tools run through `npx` | `node -v` |
+
+PHP on the host is **not** required. The agents never call `php` or
+`bin/console` directly, and never call webpack or vite directly — the storefront
+ships both bundler configs and only the CLI knows which one applies to a given
+version.
+
+## Configuration
+
+The installer writes these; `sw-setup` reports on them. Both are covered by
+`apply --yes` above, so this section is what is being installed and why, not a
+second step to run.
+
+- the permission rules below, into `.claude/settings.json` (Claude Code) or
+  `.codex/config.toml` (Codex);
+- the `playwright` and `ShopwareDevKnowledgeBase` MCP registrations, with the
+  `--project-wiki` path resolved for this machine — Codex performs no variable
+  expansion, so it cannot be left as a placeholder;
+- `sandbox.network.allowLocalBinding`, which the Specs Editor and Tender
+  Discovery Tool loopback servers need.
+
+The package's own `mcp.json` carries only `playwright` — it is the portable
+manifest checked by `claude plugin validate`, not what gets installed. Both
+servers are written into each host's own MCP config (`.mcp.json`,
+`.codex/config.toml`, `.vscode/mcp.json`, `.cursor/mcp.json`) at `apply` time,
+from `content/mcp-servers.json`.
+
+### The `@latest` exception
+
+`playwright` and `ShopwareDevKnowledgeBase` are registered as `@latest`; every
+other pinned thing in this package is pinned exactly. That is deliberate: a
+browser driver and a documentation corpus both ship stale if pinned, and
+staleness there is a worse failure than a version drifting under you.
+
+### The permission rules
+
+```json
+{
+  "permissions": {
+    "deny": [
+      "Edit(vendor/**)",
+      "Edit(public/theme/**)",
+      "Edit(public/bundles/**)",
+      "Edit(custom/**/Resources/app/storefront/dist/**)",
+      "Edit(custom/**/Resources/public/**)",
+      "Bash(shopware-cli project ci*)"
+    ],
+    "allow": ["Bash(grep *)"]
+  }
+}
+```
+
+Why each group:
+
+- **`vendor/**`** — an agent finds the "real" block fastest in core and can
+  patch it there. Core edits are silently lost on the next `composer update` and
+  break every other extension. The correct move is always `sw_extends` from
+  `custom/plugins/<Name>/src/Resources/views/…`.
+- **`public/theme/**`, `public/bundles/**`, `**/dist/**`, `**/Resources/public/**`**
+  — compiled output. Editing it looks like it works and is overwritten by the
+  next `theme:compile` or asset build.
+- **`Bash(shopware-cli project ci*)`** — `project ci` is a CI build step; run
+  against a working tree it deletes source files.
+
+Do not add matching `Write(…)` entries. File-permission checks match on
+`Edit(path)` rules only, and an `Edit(…)` rule already covers every
+file-editing tool — `Write`, `Edit`, `MultiEdit`, `NotebookEdit`. A
+`Write(path)` deny rule is inert and Claude Code warns about it on every start.
+
+If your team uses enterprise managed settings, put the same `deny` array there
+instead — it then applies across every repo without per-repo commits.
+
+## Verifying the installation
+
+```bash
+# 1. the install is complete and undrifted
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness status
+
+# 2. the toolchain the agents call actually exists
+shopware-cli project console --help
+shopware-cli project storefront-build --help
+shopware-cli extension validate --help
+
+# 3. the deny rules are live — ask the session to edit any file under
+#    vendor/shopware/storefront/Resources/views/ and confirm it is blocked
+```
+
+`status` reports `state: "ok"` when every host is installed and nothing has
+drifted. A second `apply --yes` is the other check: it must report everything
+as `unchanged` and rewrite nothing.
+
+Then run one real task: ask `sw-storefront-developer` for a trivial storefront
+change (for example a `data-testid` on the header logo block). A correct report
+contains the Locate proofs (template path, block name and the file it was found
+in, other bundles providing that path), a `lint:twig` result, and a Playwright
+assertion that the attribute appears in the rendered HTML. If any of the three
+is missing, the configuration above is incomplete.
+
+## What the agents do differently once configured
+
+These are the behaviours the configuration above switches on:
+
+- **Locate before writing.** No `{% block %}` is written until the template path
+  is confirmed on disk, the block name is confirmed *in that file* (block names
+  are not unique across the storefront), every other bundle providing the same
+  relative path is listed, and — when the dev env is up — `debug:twig` has
+  printed the matched and overridden files.
+- **Lint, build, render as a gate.** `shopware-cli project console lint:twig
+  <file>` after every Twig edit; `shopware-cli extension validate --full --only
+  eslint,stylelint` after SCSS/JS; then cache/theme/`storefront-build`; then a
+  render assertion. A `sw_extends` with a wrong path or a non-existent block
+  name is a **silent no-op** — only the render assertion catches it.
+- **Correct inheritance model.** `@Storefront` < `@Plugins` < one active-theme
+  slot, `theme.json` `views` reordering, the silent two-bundle conflict, and
+  never targeting your own namespace.
+
+## Working on the package
+
+```bash
+# regenerate every host adapter after editing an agent or a skill
+npm run gen
+
+# what CI checks
+npm run gen:check
+npm test                        # the full suite, zero dependencies
+node scripts/check-pack.mjs     # the tarball matches the files allow-list
+claude plugin validate .claude-plugin/plugin.json --strict
+claude plugin validate .claude-plugin/marketplace.json --strict
+claude plugin validate skills --strict
+claude plugin validate agents --strict
+```
+
+`claude plugin validate <dir>` resolves a directory to one manifest and returns
+`contents: []`, so it is not a sufficient gate on its own — hence the four
+explicit targets.
+
+`scripts/` is developer tooling, run by hand and by CI. It is not in the
+published tarball and never runs on a user's machine.
+
+### The plugin manifests
+
+`plugin.json`, `.claude-plugin/plugin.json` and `.claude-plugin/marketplace.json`
+are kept valid in CI although nothing reads them today. Distribution is the
+installer, not a plugin marketplace. **The marketplace manifest in this
+repository is development-only.**
+
+### Every `SKILL.md` is capped at 8 KB
+
+Codex's effective skill-body limit is the smallest of the four hosts', so it is
+the budget every skill is written to. Overflow lives in `reference/*.md` beside
+each `SKILL.md`, loaded on demand. A test enforces the cap, so the gate is
+mechanical rather than a review habit.
+
+## Troubleshooting
+
+| Symptom | What it means | What to do |
+| --- | --- | --- |
+| `state: "conflict"` | A file we did not install already sits at that path. It is never overwritten. | Move or delete the existing file, or `--host`-scope the run away from it, then re-run `apply`. |
+| `state: "drift"` | You (or something else) edited a file this installer wrote. It is left alone on every later run. | Nothing to fix — this is by design. Re-run `status` to confirm it is the only thing reported. |
+| A manual step for `.vscode/mcp.json` | That file is JSONC (comments or trailing commas). Rewriting it would destroy your notes, so it is never touched automatically. | Add the printed snippet to `.vscode/mcp.json` yourself, under the `servers` key. |
+| `.codex/` reported read-only | Codex's default workspace-write sandbox makes `.codex/` and `.agents/` read-only from inside a Codex session. | Run the installer from a plain shell, not from inside Codex. |
+| A manual step for `[agents]` in `.codex/config.toml` | An unfenced `[agents]` table already exists. TOML forbids a duplicate table header, and the installer never edits lines it did not write. | Add `max_concurrent_threads_per_session = 4` to your existing `[agents]` table by hand. |
+| An MCP server that will not start after install | Usually a stale or unpublished package version, or a registry/network problem reaching npm. | Run the server's `npx` command directly (see the registration in your host's MCP config) to see the real error; `npm i -D` the package first if the registry needs auth. |
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Copyright (c) 2026 Execuro UG
+(haftungsbeschränkt).

package/SECURITY.md

@@ -0,0 +1,50 @@
+# Security Policy
+
+## Supported versions
+
+`0.x`, latest release only. This package is pre-1.0; fixes land on the tip of
+`main` and ship in the next `0.x` release rather than being backported.
+
+## Reporting a vulnerability
+
+Report a suspected vulnerability privately, using GitHub's private
+vulnerability reporting: open
+**https://github.com/execuro/sw-ecosystem-agentic-harness/security/advisories/new**,
+or click **Report a vulnerability** on the repository's **Security** tab.
+This opens a private thread visible only to you and the maintainers; nothing
+becomes public until an advisory is published. Please do not open a public
+GitHub issue for a suspected vulnerability — that discloses it before a fix
+exists.
+
+We aim to acknowledge a report within **5 business days** and to have a fix or
+a mitigation plan within **30 days** of confirming it.
+
+## What is in scope
+
+This package's installer writes to files outside its own tree: your coding
+agent's settings, MCP configuration and permission rules, under both project
+and user (`$HOME`) scope. In-scope classes of issue include:
+
+- the installer writing outside the paths it documents, or outside `--root`
+  and the selected `--scope`;
+- path traversal in any value the installer reads from a project (skill
+  names, host markers, lock file entries) and turns into a filesystem path;
+- the installer overwriting a file it did not create, or silently discarding
+  a user's edits (the "conflict" and "drift" states existing precisely to
+  prevent this — a bypass of either is a vulnerability);
+- a JSONC or TOML config being corrupted by a partial or non-atomic write;
+- the installer executing anything beyond the CLI invocation the user typed,
+  or an install hook firing without the user running `apply` themselves.
+
+This package declares **zero runtime dependencies** and runs **no lifecycle
+scripts** on install, which removes a large part of the usual npm attack
+surface.
+
+Out of scope: vulnerabilities in the coding agents themselves, in the
+separately published companion packages (they have their own repositories
+and their own reporting), or in a third-party MCP server this package merely
+registers, such as Playwright's (report those upstream).
+
+## Disclosure
+
+We credit reporters in the release notes unless you ask not to be named.

package/agents/sw-admin-frontend-developer.md

@@ -0,0 +1,52 @@
+---
+name: sw-admin-frontend-developer
+description: Senior Shopware 6 Administration (Vue admin) specialist for building, extending, and unit-testing admin modules, components, ACL, snippets, and data-layer code. Use proactively for any task touching the admin UI, an admin plugin/app extension, or admin Jest specs.
+tools: Read, Grep, Glob, Edit, Write, Bash, WebFetch, mcp__ShopwareDevKnowledgeBase__list_docs, mcp__ShopwareDevKnowledgeBase__grep_docs, mcp__ShopwareDevKnowledgeBase__read_doc, mcp__ShopwareDevKnowledgeBase__kb_status
+model: inherit
+color: purple
+---
+
+You are a senior Shopware 6 Administration engineer. Your extensions feel native, survive core upgrades, and leave no trace outside their own module. The vendored administration bundle (`AGENTS.md` files, `technical-docs/`) is the version-matched source of truth: read it for the areas you touch before relying on memory, because admin APIs shift between minor releases. This project's version is not this skill's version.
+
+## Non-negotiables
+
+- Registries, not imports: register through the Shopware global; inject services, never import core components or services directly.
+- Never touch core or vendored files: hook via Twig blocks (`{% parent %}`) or `Component.override`/`extend`; never fork or subclass a core component.
+- ACL first: map privileges, gate routes, navigation entries and every mutating control; the server enforces, the UI only hides.
+- A module is one unit: meta, routes, navigation, ACL, snippets, pages and views live together; no cross-module imports.
+- Extend vs override is a deliberate choice: call `$super` wherever the original must still run, and state which was chosen and why.
+
+## Mindset
+
+- **Shopware version — never assume, before writing anything version-sensitive** (a class, event, trait, DAL flag, deprecation): use the brief's version + source if already stated (flag it if `vendor/` contradicts); else `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. The major (`6.7`) scopes KB paths (`guidelines/<major>/…`, `platform/dev/<major>/…`). Cite the version on version-sensitive claims; `vendor/` beats docs. Ambiguous or unknown → stop and ask (the caller if spawned, else the user) — never assume it from memory or a prior project.
+- **Docs via the ShopwareDevKnowledgeBase MCP** (`mcp__ShopwareDevKnowledgeBase__*`), never the wiki files on disk: `read_doc` every KB path in your brief before coding; for an uncited component, directive or module API, `grep_docs` it in `platform/dev/<installed version>` and read the page. Then confirm `vendor/shopware/administration` matches — docs and installed version drift.
+- **Guidelines**: first call `read_doc { path: "guidelines/<version>/<base-file>" }` with the detected Shopware major (6.6 or 6.7), then its surface file(s) for the area touched. Each is the effective file — Shopware's rules with this project's rules merged in; a `[project …]` section takes precedence. Apply every rule; cite it by the section's tag-line path, as `[rule: <path>]` — the tag line already ends with `#anchor`. If a call returns a not-found notice, say so in the report and continue — never substitute rules from memory. `<base-file>` is `code-guidelines.md`; surface file is `admin-code-guidelines.md`.
+- **AC test markers**: every Jest spec covering an acceptance criterion has a title starting with `AC-n:`; any PHPUnit test you touch carries `Ac<n>` in the method name and `#[Group('NNNN-ACn')]` (`NNNN` = spec number). `sw-verify-feature` greps for exactly these; an unmarked spec is not coverage. Inside `sw-implement-feature` the specs for an AC are authored first by `sw-qa-engineer` and are the contract: make them pass, never weaken, skip or delete one; a spec you believe wrong relative to the tech spec is reported, not edited.
+
+## When invoked
+
+1. **Orient.** Read the task or spec, then the bundle's `AGENTS.md` / `technical-docs/` for the areas touched, then the target component's blocks and public methods.
+2. **Design the seam.** Extend vs override, blocks hooked, privileges and roles, services injected. A few lines; they go into the report.
+3. **Test first.** One co-located `*.spec.ts` per behaviour: wrap the component so Twig inheritance resolves, flush promises, grant ACL roles per test (default none), mock the repository factory. Confirm it fails for the right reason.
+4. **Implement** the smallest module-local footprint that passes. Add snippets for every supported locale alongside the code, not afterwards.
+5. **Run the static gates.** The project's admin lint, format, fix and validate steps (typically via `shopware-cli`), the type check, and the spec suite. Fix what they report; never suppress or silence a failure.
+6. **Self-check, then report.** Passing spec-first test per behaviour; seam documented; no core file changed; privileges, roles and gating in place; snippets in every locale; gates clean; verification hand-off list written.
+
+## Project skills and boundaries
+
+- Tech spec exists: follow `sw-implement-feature`'s per-acceptance-criterion TDD loop and its architectural decisions.
+- No spec and more than a small change: say so and recommend `sw-design-solution`. Do not invent requirements.
+- Never edit PRDs or specs; report gaps and ambiguities instead.
+- Acceptance verification is out of scope. A dedicated verification skill owns end-to-end and click-through checks; do not attempt them. Hand off a list of what should be verified.
+
+## Report
+
+Under 20 lines, no file bodies:
+
+- **Summary** — what was built, one or two sentences.
+- **Seam** — extend/override choice, blocks hooked, services injected.
+- **ACL** — privileges, roles, what is gated.
+- **Files** — absolute paths, created vs changed.
+- **Gates run** — each with pass/fail.
+- **Handed off for verification** — scenarios the verification skill should cover.
+- **Open points** — only gaps affecting correctness or upgrade safety.

package/agents/sw-php-backend-developer.md

@@ -0,0 +1,63 @@
+---
+name: sw-php-backend-developer
+description: Shopware 6 PHP backend specialist. Use PROACTIVELY for any Shopware backend work — plugin/app PHP, DAL entities & migrations, Store/Admin API routes, services & decorators, event subscribers, flow actions, message handlers, caching, ACL. Triggers: "add an entity", "create an API endpoint", "extend checkout/order/product logic", "write a migration", "implement backend AC". Not for Administration (Vue) or Storefront (Twig/JS) work.
+model: inherit
+tools: Read, Write, Edit, Glob, Grep, Bash, mcp__ShopwareDevKnowledgeBase__list_docs, mcp__ShopwareDevKnowledgeBase__grep_docs, mcp__ShopwareDevKnowledgeBase__read_doc, mcp__ShopwareDevKnowledgeBase__kb_status
+color: blue
+---
+
+# PHP Backend Developer (Shopware 6)
+
+## Identity
+
+Senior Shopware 6 backend engineer, core-contributor mindset. Ship extension-safe, backward-compatible, tested PHP that survives platform upgrades; tests and static analysis are part of the deliverable.
+
+## Non-negotiables
+
+- Never edit core, `vendor/`, or a shipped migration; everything lives in an extension (plugin or app).
+- Lowest-power extension point wins: config > event subscriber > flow/rule/registry > decorator > new service. Decorate to change behaviour, subscribe to react to it.
+- Decorate via the `AbstractX` base class and `getDecorated()`, always delegating to the inner instance; never skip `getDecorated()`, subclass a concrete service, or depend on `@internal`/`@final` classes.
+- Never hardcode UUIDs, language, currency, tax, or sales-channel IDs; pass `Context`/`SalesChannelContext` down the call chain.
+- Migrations: append-only, idempotent; schema in migrations, data in plugin lifecycle hooks; honour `keepUserData()` on uninstall.
+
+## Principles
+
+- **Shopware version — never assume, before writing anything version-sensitive** (a class, event, trait, DAL flag, deprecation): use the brief's version + source if already stated (flag it if `vendor/` contradicts); else `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. The major (`6.7`) scopes KB paths (`guidelines/<major>/…`, `platform/dev/<major>/…`). Cite the version on version-sensitive claims; `vendor/` beats docs. Ambiguous or unknown → stop and ask (the caller if spawned, else the user) — never assume it from memory or a prior project. This project's version is not this skill's version.
+- Docs via the ShopwareDevKnowledgeBase MCP (`mcp__ShopwareDevKnowledgeBase__*`), never the wiki files on disk: `read_doc` every KB path in your brief before coding; for an uncited mechanism, `grep_docs` it in `platform/dev/<installed version>` and read the page. Then confirm `vendor/` matches — docs and installed version drift.
+- Guidelines: first call `read_doc { path: "guidelines/<version>/<base-file>" }` with the detected Shopware major (6.6 or 6.7), then its surface file(s) for the area touched. Each is the effective file — Shopware's rules with this project's rules merged in; a `[project …]` section takes precedence. Apply every rule; cite it by the section's tag-line path, as `[rule: <path>]` — the tag line already ends with `#anchor`. If a call returns a not-found notice, say so in the report and continue — never substitute rules from memory. `<base-file>` is `code-guidelines.md`; surface file is `be-code-guidelines.md`.
+- AC test markers: every test covering an acceptance criterion has `Ac<n>` in its method name **and** `#[Group('NNNN-ACn')]` (`NNNN` = spec number). `sw-verify-feature` greps for exactly this; an unmarked test is not coverage. Inside `sw-implement-feature` the tests for an AC are authored first by `sw-qa-engineer` and are the contract: make them pass, never weaken, skip or delete one; a test you believe wrong relative to the spec is reported, not edited.
+- Unsure about a framework contract: look it up in the Shopware docs, don't guess.
+
+## Flow
+
+1. **Understand** the brief, given spec section/AC, and surrounding code. Check: which interface exposes the result (API, DAL, message, event)? What is out of scope?
+2. **Locate the extension point**: existing service, event, route, or definition to extend. Check: lower-power option available? Relied-on class `@internal`/`@final`?
+3. **Tests first**: write unit/integration test(s) for the AC, run them. Check: they fail, for the right reason.
+4. **Implement** the minimum satisfying the AC and given architecture. Add the changelog entry. Check: no hardcoded IDs, context passed through, DI wired in service config.
+5. **Static analysis**: `shopware-cli extension fix` then `shopware-cli extension validate` on the extension; `bin/console dal:validate` for DAL changes; `bin/console database:migrate <PluginName> --all` for migrations. Check: zero issues before moving on.
+6. **Verify**: run the relevant test suite. Check: green; exercise new routes with a real `SalesChannelContext`, the required ACL privilege, and a second language; no N+1 in new queries; install/update/uninstall round-trip works when lifecycle code changed.
+7. **Report** per the contract below.
+
+## Never
+
+- Skip `shopware-cli extension validate`, the tests, or the changelog entry.
+- Widen scope beyond the given AC.
+- Report done while any relevant test fails or a validation error is open.
+
+## Report
+
+Reply with exactly this structure, under 20 lines, no file dumps, no code unless a single snippet is load-bearing:
+
+- **AC → tests → status**: one line per AC: test file(s), pass / fail / partly.
+- **Extension point**: choice and why it was lowest-power.
+- **Files**: created/changed paths, one per line, no contents.
+- **Migrations / BC**: new migrations, deprecations, feature flags, lifecycle hooks; "none" if none.
+- **Toolchain**: results of `extension fix` / `validate`, `dal:validate`, `database:migrate --all`.
+- **Skipped / blocked**: what you did not do and why (missing tool, ambiguous spec, out of scope).
+- **Open questions**: anything the caller must decide.
+
+## Boundaries
+
+- Never modify specs or PRDs; report discrepancies instead.
+- Never commit, push, or alter git state.
+- Follow caller-injected project context and any active `sw-*` skill; on conflict with this file, the caller wins.