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

package/CHANGELOG.md

@@ -7,6 +7,30 @@ release.
 
 ## [Unreleased]
 
+## [0.1.2] - 2026-09-16
+
+### Changed
+
+- **Install/update instructions now anchor to `@latest`.** Every `npx`
+  invocation of this package in `README.md`, `sw-setup`'s `SKILL.md` and
+  `reference/rows.md` uses `@execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest`
+  instead of a bare package name or a frozen version — a bare invocation can
+  resolve to a stale copy already in the `npx` cache or `node_modules`. Added
+  a **Keep up to date** section to `README.md` and a **Keeping it current**
+  section to `guide`'s output.
+
+## [0.1.1] - 2026-09-16
+
+### Added
+
+- **An `install` command** — `apply --yes` under a friendlier one-step name.
+  Typing the verb is the consent, so it never prompts and needs no `--yes`; the
+  scriptable `apply --yes` is unchanged and stays what skills and CI call.
+
+### Fixed
+
+- CI and the GitHub Pages setup for the plugin marketplace.
+
 ## [0.1.0] - 2026-09-16
 
 ### Added

package/README.md

@@ -49,6 +49,7 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 
 | Command | What it does |
 | --- | --- |
+| `install` | installs into every detected host; the same as `apply --yes` |
 | `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 |
@@ -58,22 +59,18 @@ declines is fully set up without them, and `--editor` on `sw-design-requirements
 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).
+by `apply` and `uninstall`, never prompts — `install` implies it), 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
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install
 ```
 
+Want to look first? `status` is read-only and `plan` prints the diff; neither
+writes anything.
+
 Then restart your coding agent — every host reads its configuration at startup.
 The command's output tells you which ones and how.
 
@@ -83,6 +80,26 @@ not block outside Plan mode, and CI has no terminal. Add `--host claude-code`
 home directory instead of this repository. The default scope is the project —
 nothing is written under `~` unless you ask.
 
+## Keep up to date
+
+The same command updates:
+
+```bash
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install
+```
+
+It rewrites what it owns, leaves anything you hand-edited alone (reported as
+drift), and records the new version in the lock file. The `@latest` matters:
+without it, `npx` can reuse a copy already in its cache or in this project's
+`node_modules`, so you would silently keep running whatever version you first
+installed. Restart your coding agent afterwards, same as a first install.
+
+Want to check what you have first? `... @latest status` reports
+`installed_version` and any drift, and writes nothing. The Specs Editor and
+Tender Discovery Tool are separate packages and update on their own `npm i -D
+<package>@<version>` line — `status`'s `companions` array names the exact
+command for each.
+
 ### What it writes
 
 | Host | Skills | Sub-agents | MCP | Settings |
@@ -111,7 +128,7 @@ Codex never reads `CLAUDE.md`.
 Undo everything with:
 
 ```bash
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness uninstall --yes
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest uninstall --yes
 ```
 
 It removes exactly what the lock file at `.sw-ai-sdk/harness.lock.json` records,
@@ -125,7 +142,7 @@ 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
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
 ```
 
 ## Prerequisites
@@ -210,7 +227,7 @@ instead — it then applies across every repo without per-repo commits.
 
 ```bash
 # 1. the install is complete and undrifted
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status
 
 # 2. the toolchain the agents call actually exists
 shopware-cli project console --help

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

@@ -1,6 +1,6 @@
 ---
 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.
+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

package/agents/sw-tender-editor.md

@@ -1,6 +1,6 @@
 ---
 name: sw-tender-editor
-description: Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next.
+description: Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next.
 tools: Read, Write, Edit, Glob, Grep
 ---
 

package/bin/cli.mjs

@@ -21,18 +21,23 @@ const COMMANDS = {
   status: async () => (await import('../lib/commands.mjs')).status,
   plan: async () => (await import('../lib/commands.mjs')).plan,
   apply: async () => (await import('../lib/commands.mjs')).apply,
+  install: async () => (await import('../lib/commands.mjs')).install,
   uninstall: async () => (await import('../lib/commands.mjs')).uninstall,
   guide: async () => (await import('../lib/guide.mjs')).main,
 };
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
+  install    [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
   status     [--host <h>] [--scope project|user] [--root <path>]
   plan       [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
   apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
   uninstall  --yes [--host <h>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
+  install is apply --yes under a friendlier name: the whole install in one
+  command, no --yes needed — typing the verb is the consent.
+
   <h> is one of: claude-code, codex, copilot, cursor. Repeat --host to select
   several; omitting it selects every host that is present.
 

package/codex/agents/sw-php-backend-developer.toml

@@ -1,9 +1,9 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-php-backend-developer.md
-# source-sha256: 1d248ea38a0118ce2ebcea32f8dc780934bb6228e29c1b034baa1b3c43e102ea
+# source-sha256: ea82533b10d08e276f3c82da3555fd49f66b4141850990bca3e7e878fe07df61
 
 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."
+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."
 
 developer_instructions = '''
 

package/codex/agents/sw-tender-editor.toml

@@ -1,9 +1,9 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-tender-editor.md
-# source-sha256: 72f167887e7d97164c0c7bb2ed03e23dd041fb868746857744bcd255909a03d5
+# source-sha256: 288b5d684f40ea62aa2b6021cfa3109a7f664fc2365f32109bcd9d1f94eb8a2c
 
 name = "sw-tender-editor"
-description = "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
+description = "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
 
 developer_instructions = '''
 

package/content/AGENTS.md

@@ -16,7 +16,7 @@ procedure, and the detail lives in `reference/*.md` files beside its
 | `sw-discover-tender` | Analyse a client tender (RFP, RFI or RFQ) for a Shopware 6 project into one markdown sidecar, <source basename>-analysis.md. |
 | `sw-document-feature` | Document one Shopware project feature into the LLM-wiki under docs/project-wiki/ — one feature page per surface (administration/ and/or storefront/), the "why" row in the domain index, ADR pages only promoted from the WIP ADR files sw-design-solution extracted into specs/ once they are accepted and built (with an organised table of contents) or provided by the user (never invented). |
 | `sw-implement-feature` | 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. |
-| `sw-setup` | 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. |
+| `sw-setup` | Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki and `.gitignore`, plus the installer CLI's own configuration/drift status. |
 | `sw-verify-feature` | 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. |
 | `sw-verify-feature-ac-tests` | Verify that a feature's acceptance criteria are backed by tests that actually exist, actually pass, and actually test what their name/comment/PHPDoc claims. |
 | `sw-verify-feature-architecture` | Verify that a feature's implementation matches the architectural decisions its spec made, and complies with Shopware's own Core conventions plus any written Project guidelines this repo defines. |
@@ -45,7 +45,7 @@ and installs the harness configuration — permission rules and the MCP
 server registrations — through the installer CLI:
 
 ```
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status
 ```
 
 The Shopware knowledge base is served by the `ShopwareDevKnowledgeBase`

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

@@ -1,12 +1,12 @@
 ---
 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."
+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."
 tools: [read, edit, search, execute]
 ---
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-php-backend-developer.md -->
-<!-- source-sha256: 1d248ea38a0118ce2ebcea32f8dc780934bb6228e29c1b034baa1b3c43e102ea -->
+<!-- source-sha256: ea82533b10d08e276f3c82da3555fd49f66b4141850990bca3e7e878fe07df61 -->
 # PHP Backend Developer (Shopware 6)
 
 ## Identity

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

@@ -1,12 +1,12 @@
 ---
 name: "sw-tender-editor"
-description: "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment: every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
+description: "Mechanical file worker for the sw-discover-tender skill — extracts requirement tables from a tender's source export into cluster files, merges PM/architect/QA cluster reports into finished §4 row blocks, splices those blocks into the analysis sidecar, and assembles and checks the final response CSVs. Deterministic, no judgment — every value it writes comes from a named input file, never from memory or estimation. Not for research, feasibility checks, effort estimation or any judgment call — that is `sw-product-manager`, `sw-shopware-architect` and `sw-qa-engineer`'s work; this agent only reshapes what they already produced into the file the skill needs next."
 tools: [read, edit, search]
 ---
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-tender-editor.md -->
-<!-- source-sha256: 72f167887e7d97164c0c7bb2ed03e23dd041fb868746857744bcd255909a03d5 -->
+<!-- source-sha256: 288b5d684f40ea62aa2b6021cfa3109a7f664fc2365f32109bcd9d1f94eb8a2c -->
 # sw-tender-editor
 
 ## Identity

package/lib/actions.mjs

@@ -14,8 +14,8 @@ import {
   abs, ensureDir, readMaybe, readTextMaybe, removeDirIfEmpty, removeFile, rel, sha256, writeAtomic,
 } from './fsx.mjs';
 import {
-  canonical, deletePointer, fenceInner, findFence, getPointer, mergeArrayUnique, parseJsonLoose,
-  removeArrayValues, removeFence, serializeJson, setPointer, upsertFence,
+  canonical, deletePointer, fenceInner, findFence, getPointer, mergeArrayUnique, normalizeEol,
+  parseJsonLoose, removeArrayValues, removeFence, serializeJson, setPointer, upsertFence,
 } from './merge.mjs';
 import { PKG_ROOT } from './content.mjs';
 import { isDeclined } from './lock.mjs';
@@ -226,8 +226,9 @@ function previewFence(action, ctx) {
   const found = readTextMaybe(target);
   const createdFile = found === null;
   // Hash what will actually sit inside the fence, warning line included, so it
-  // can be compared with what `findFence` reads back.
-  const hash = sha256(fenceInner(action.body, action.syntax));
+  // can be compared with what `findFence` reads back. Normalised to LF first —
+  // a fence's identity does not depend on the target file's line-ending style.
+  const hash = sha256(normalizeEol(fenceInner(action.body, action.syntax)));
   const locked = ctx.lock?.fences?.find(
     (f) => f.file === action.target && f.block === action.block,
   );
@@ -243,7 +244,7 @@ function previewFence(action, ctx) {
     return { ...base, prior: null, state: 'create',
       detail: createdFile ? 'creates the file with a managed block' : 'appends a managed block' };
   }
-  const priorHash = sha256(existing.inner);
+  const priorHash = sha256(normalizeEol(existing.inner));
   if (priorHash === hash) return { ...base, prior: priorHash, state: 'unchanged', created_file: locked?.created_file ?? false, detail: 'up to date' };
   if (locked && locked.hash !== priorHash) {
     return { ...base, prior: priorHash, state: 'drift', created_file: locked.created_file,
@@ -401,7 +402,7 @@ export function revert(entry, ctx) {
       if (found === null) return { state: 'missing', target: entry.target, reason: 'already gone' };
       const fence = findFence(found.text, entry.block);
       if (!fence) return { state: 'missing', target: entry.target, reason: 'our block is already gone' };
-      if (sha256(fence.inner) !== entry.hash) {
+      if (sha256(normalizeEol(fence.inner)) !== entry.hash) {
         return { state: 'kept', target: entry.target, reason: 'content inside the managed fence was hand-edited' };
       }
       const { next } = removeFence(found.text, entry.block);

package/lib/commands.mjs

@@ -245,17 +245,17 @@ const RESTART_HELP = {
   cursor: 'Restart Cursor so it re-reads .cursor/mcp.json',
 };
 
-export async function apply(argv) {
+export async function apply(argv, label = 'apply') {
   const ctx = buildContext(argv, 'apply');
   if (!ctx.yes) {
-    return out.usage('apply', 'apply refuses to write without --yes',
+    return out.usage(label, 'apply refuses to write without --yes',
       [`${RUN} plan`, `${RUN} apply --yes`]);
   }
 
   let lock;
   try { lock = loadLock(ctx) ?? lockfile.empty(ctx.scope); } catch (e) {
     if (e instanceof lockfile.LockVersionError) {
-      return out.failure('apply', e.message, {
+      return out.failure(label, e.message, {
         next_step: `Upgrade the package: npm i -D ${PKG_NAME}@latest`,
         help: [`npm i -D ${PKG_NAME}@latest`],
       });
@@ -266,7 +266,7 @@ export async function apply(argv) {
   // An apply we cannot record is an apply we cannot undo. Refuse up front
   // rather than leave the user with files and no way back.
   if (!isWritable(abs(ctx.root, LOCK_FILE))) {
-    return out.failure('apply', `cannot write the lock file at ${LOCK_FILE}`, {
+    return out.failure(label, `cannot write the lock file at ${LOCK_FILE}`, {
       next_step: `Make ${ctx.root} writable, then re-run \`${RUN} apply --yes\`.`,
       help: [`${RUN} status`],
     });
@@ -345,9 +345,12 @@ export async function apply(argv) {
     summary, lock_file: LOCK_FILE, next_step: next, help,
     hosts: [...perHost.values()], actions: results, manual, errors,
   });
-  return summary.failed ? out.failure('apply', `${summary.failed} change(s) failed`, body) : out.ok('apply', body);
+  return summary.failed ? out.failure(label, `${summary.failed} change(s) failed`, body) : out.ok(label, body);
 }
 
+/** `install` is `apply --yes`: typing the verb is the consent. */
+export const install = (argv) => apply(['--yes', ...argv], 'install');
+
 // --------------------------------------------------------------- uninstall
 
 export async function uninstall(argv) {

package/lib/guide.mjs

@@ -11,26 +11,32 @@ const RUN = `npx -y ${PKG_NAME}@${PKG_VERSION}`;
 
 export const GUIDE = `# ${PKG_NAME} — install protocol
 
-This CLI installs the Shopware agentic harness — 11 \`sw-*\` skills and 7
+This CLI installs the Shopware agentic harness — 10 \`sw-*\` skills and 7
 \`sw-*\` sub-agents — into whichever coding agents this repository uses, and
 registers the MCP servers and permission rules they depend on.
 
 ## The loop
 
-1. \`${RUN} status\`
-   Read-only. Reports which hosts are present, what is already installed, and
-   anything that has drifted since it was installed. Always safe.
+1. \`${RUN} install\`
+   The whole install in one command. It refuses to prompt — Codex's question
+   tool does not block outside Plan mode, and CI has no terminal — so the verb
+   itself is the consent. Same as \`apply --yes\`.
 
-2. \`${RUN} plan\`
+2. \`${RUN} status\`
+   Read-only, optional. Reports which hosts are present, what is already
+   installed, and anything that has drifted since it was installed. Always safe.
+
+3. \`${RUN} plan\`
    Prints the exact set of changes and writes nothing. Every entry says what it
    would do and why. Show this to the user before applying.
 
-3. \`${RUN} apply --yes\`
-   Performs the changes. It refuses without \`--yes\`; there is no prompt,
-   because Codex's question tool does not block outside Plan mode and CI has no
+4. \`${RUN} apply --yes\`
+   The scriptable name for the same write \`install\` performs — use it for
+   re-runs and repairs. It refuses without \`--yes\`; there is no prompt, because
+   Codex's question tool does not block outside Plan mode and CI has no
    terminal.
 
-4. \`${RUN} uninstall --yes\`
+5. \`${RUN} uninstall --yes\`
    Removes what the lock file records and reverts the managed config blocks.
 
 ## Flags
@@ -82,6 +88,14 @@ Every host reads its configuration at startup. The result's \`help\` array
 names the restart or reload each one needs — pass it on to the user rather
 than assuming the change is already live.
 
+## Keeping it current
+
+This guide is version ${PKG_VERSION}. To install or upgrade to the newest
+published version, run \`npx -y ${PKG_NAME}@latest install\`. Omitting
+\`@latest\` can reuse a copy already in the \`npx\` cache or this project's
+\`node_modules\`, so you would silently stay on whatever version you first
+installed.
+
 ## If you are a skill
 
 Call this CLI. Do not re-implement any of it, and do not copy this text into a
@@ -91,8 +105,8 @@ skill file — run \`${RUN} guide\` and follow what it says now.
 export async function main() {
   return out.ok('guide', {
     version: PKG_VERSION,
-    next_step: `${RUN} status`,
-    help: [`${RUN} status`, `${RUN} plan`, `${RUN} apply --yes`],
+    next_step: `${RUN} install`,
+    help: [`${RUN} install`, `${RUN} status`, `${RUN} plan`, `${RUN} apply --yes`],
     guide: GUIDE,
   });
 }

package/lib/merge.mjs

@@ -17,6 +17,16 @@
 
 export const FENCE_ID = 'sw-ecosystem-agentic-harness';
 
+/**
+ * Collapse CRLF (and stray CR) to LF. A fence's identity is what sits between
+ * its markers, not the line-ending style the target file happens to use —
+ * `writeAtomic` writes back whatever EOL the file already had, so hashing raw
+ * bytes would make the same content look edited on a CRLF checkout.
+ */
+export function normalizeEol(text) {
+  return text.replace(/\r\n/g, '\n').replace(/\r/g, '');
+}
+
 // ---------------------------------------------------------------- JSON
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@execuro-sw-ecosystem/sw-ecosystem-agentic-harness",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shopware 6 agentic harness: sw-* skills and sub-agents, plus an installer that writes them into Claude Code, Codex, GitHub Copilot and Cursor.",
   "license": "MIT",
   "author": "Execuro UG (haftungsbeschränkt)",
@@ -49,7 +49,7 @@
   "scripts": {
     "gen": "node scripts/gen-codex-agents.mjs && node scripts/gen-copilot-agents.mjs && node scripts/gen-agents-md.mjs",
     "gen:check": "node scripts/gen-codex-agents.mjs --check && node scripts/gen-copilot-agents.mjs --check && node scripts/gen-agents-md.mjs --check",
-    "test": "node --test test/*.test.mjs scripts/*.test.mjs",
+    "test": "node -e \"const{spawnSync}=require('node:child_process');const{readdirSync}=require('node:fs');const list=(dir)=>readdirSync(dir).filter((f)=>f.endsWith('.test.mjs')).map((f)=>dir+'/'+f);const files=[...list('test'),...list('scripts')];const r=spawnSync(process.execPath,['--test',...files],{stdio:'inherit'});process.exit(r.status??1);\"",
     "check:mcp": "node scripts/check-mcp.mjs"
   },
   "publishConfig": {

package/plugin.json

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

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

@@ -2,7 +2,7 @@
 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]
+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
 
 ---

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

@@ -2,7 +2,7 @@
 name: sw-design-solution
 description: Turn a PRD (specs/NNNN-slug.md) into a technical spec at specs/NNNN-slug-spec.md. Applies TDD — every acceptance criterion gets an implementation plan and e2e coverage, with Shopware toolchain (shopware-cli/PHPStan/ESLint/Stylelint) conventions baked into decisions up front. Runs a clarification loop for the gaps that change the implementation plan, and on the user's say-so extracts project-wide architecture/stack decisions into ADR files (specs/NNNN-slug-adr-<topic>.md) that gate readiness while proposed. Pre-checks vendor/ and the KB before it starts. Use when asked to write, draft, refine, or continue a tech spec / implementation plan. Never edits the source PRD or answers business/requirements questions — that's sw-design-requirements.
 when_to_use: Trigger phrases — "write the tech spec for PRD 0007", "create an implementation plan for this PRD", "draft the spec", "continue spec 0007", "is this spec ready for implementation".
-argument-hint: [specs/NNNN-slug.md | specs/NNNN-slug-spec.md] [--editor]
+argument-hint: '[specs/NNNN-slug.md | specs/NNNN-slug-spec.md] [--editor]'
 allowed-tools: Read Write Edit Glob Grep AskUserQuestion Agent Skill Bash(ls *) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@0.1.0 *) WebSearch WebFetch mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 

package/skills/sw-discover-tender/SKILL.md

@@ -2,7 +2,7 @@
 name: sw-discover-tender
 description: Analyse a client tender (RFP, RFI or RFQ) for a Shopware 6 project into one markdown sidecar, <source basename>-analysis.md. Every requirement row gets a class against the installed Shopware version (stock / config / plugin / custom), a three-point person-day estimate, one line of mechanism and proposed scope-lock assumptions the partner accepts by ticking checkboxes — in the file or on the Tender Discovery Tool page (`--editor`); the next run reconciles the ticks, dissolves answered questions and re-estimates. At Ready to submit it exports one CSV per client table with compliance, comment and effort filled in the client's columns. Scope and PD only — never costs, prices, licence fees or budgets. Never designs the solution — that's sw-design-solution.
 when_to_use: Trigger phrases — "scope this RFP", "analyse the tender", "answer the RFI", "discover RFP 0001", "continue RFP 0001", "reconcile RFP 0001", "export the response for RFP 0001", "is RFP 0001 ready to submit", "open RFP 0001 in the browser", "open the tender tool", "sw-discover-tender specs/rfp-0001-x-analysis.md --editor".
-argument-hint: [tender file or folder of exports (.xlsx|.md|.txt|.csv|.pdf) | specs/rfp-NNNN-slug-analysis.md to continue] [--editor] [--batch <n|all>] [--export]
+argument-hint: '[tender file or folder of exports (.xlsx|.md|.txt|.csv|.pdf) | specs/rfp-NNNN-slug-analysis.md to continue] [--editor] [--batch <n|all>] [--export]'
 allowed-tools: Read Write Edit Glob Grep Agent AskUserQuestion Bash(ls *) Bash(mkdir -p specs) Bash(mkdir -p specs/.rfp *) Bash(shasum -a 256 *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 *) Bash(open *) Bash(xdg-open *) Bash(tail *) Bash(grep *) Bash(printf *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 

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

@@ -2,7 +2,7 @@
 name: sw-document-feature
 description: Document one Shopware project feature into the LLM-wiki under docs/project-wiki/ — one feature page per surface (administration/ and/or storefront/), the "why" row in the domain index, ADR pages only promoted from the WIP ADR files sw-design-solution extracted into specs/ once they are accepted and built (with an organised table of contents) or provided by the user (never invented). Sources are a PRD (specs/NNNN-slug.md), its tech spec (specs/NNNN-slug-spec.md), or the current chat. Runs a mandatory built-check gate first — pages for functionality that does not exist in custom/ or vendor/ are written only after the user explicitly enforces it, and then carry the ⚠️ NOT BUILT block. Never restates code; references paths, extension points, decisions, config. Not for writing PRDs or specs — that's sw-design-requirements / sw-design-solution.
 when_to_use: Trigger phrases — "document this feature", "write the wiki page for spec 0007", "document PRD specs/0003-…", "add docs for <feature>", "update the wiki for <feature>", "put this in the project wiki", "record this as a project coding rule", "override/waive this guideline for our project".
-argument-hint: [path to PRD or spec | empty = use chat] [--setup]
+argument-hint: '[path to PRD or spec | empty = use chat] [--setup]'
 allowed-tools: Read Glob Grep Bash Write Edit Agent AskUserQuestion mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 

package/skills/sw-document-feature/reference/setup-wiki.md

@@ -27,7 +27,12 @@ On repair the flavor is never asked — derive it: `docs/project-wiki/_config.ym
 
 ## 2. Questions (init only)
 
-One call to a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`), asked once ever per wiki. Question 2 is included only when the answer to question 1 is Jekyll — if the tool cannot express that dependency, ask question 1 alone first, then 2–3 in a second call.
+Asked once ever per wiki with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`), in **two calls, never one**:
+
+- **Call 1 — question 1 on its own.** Wait for the answer.
+- **Call 2 — questions 2 and 3 together, and only when the answer to question 1 was Jekyll.** On Vanilla there is no second call at all: the flavor is the only answer needed.
+
+Questions 2 and 3 exist solely to fill `_config.yml`, which the Vanilla flavor does not have. Never put them in the same call as question 1 — no structured question tool can make an option list conditional on another answer in the same call, so a single call asks every user to pick a GitHub Pages deployment style, `baseurl` and all, before anyone has established that the wiki is a Jekyll site.
 
 - **Question 1 — "docs/project-wiki/ does not exist yet — set it up as a Jekyll/GitHub Pages site or a plain Markdown wiki?"**
   - Option 1, label "Jekyll / GitHub Pages (Recommended)": adds `_config.yml`, so pages render as a themed site with left sidebar navigation and search (Just the Docs, via `remote_theme:`), plus a Liquid-generated ADR table on top of the hand-maintained ADR index; ready to publish via GitHub Pages or `jekyll serve`.
@@ -136,7 +141,7 @@ On Jekyll, always name the resolved `baseurl` in that row, and when it was left
 ## Dry-run examples
 
 - **Empty project, no flag** (`composer.json` name `acme/webshop`, lock `6.7.13.0`, origin `git@github.com:acme/webshop-docs.git`): detect → no directory → ask §2 → Jekyll + own repository + default title → resolve `acme/webshop`, `6.7.13`, today, `baseurl: "/webshop-docs"` → announce → sub-agent writes 16 files → table: 16 created, `flavor | Jekyll / GitHub Pages · baseurl "/webshop-docs"`, no drift check (`guidelines/documentation-guidelines.md` was just created) → continue at step 1.
-- **Empty project, user picks Vanilla**: questions 2–3 are skipped (no `_config.yml` to configure) → 15 writes, overlay files from `reference/scaffold/vanilla/` → table: 15 created, `flavor | Vanilla / plain Markdown` → continue at step 1.
+- **Empty project, user picks Vanilla**: the second call never happens — questions 2–3 are never shown (no `_config.yml` to configure) → 15 writes, overlay files from `reference/scaffold/vanilla/` → table: 15 created, `flavor | Vanilla / plain Markdown` → continue at step 1.
 - **`--setup`, existing wiki with `domains/platform/logging.md` deleted**: repair → flavor derived from `_config.yml` → 1 write → drift check → table: 1 created, kept count, no `flavor` row → stop. Business domains, feature pages and the hand-edited `_config.yml` untouched.
 - **`--setup`, complete wiki**: nothing missing → drift check only → table: N kept → stop.
 - **No flag, complete wiki**: this file is never opened.

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

@@ -2,7 +2,7 @@
 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]
+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
 ---
 

package/skills/sw-setup/SKILL.md

@@ -1,8 +1,8 @@
 ---
 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.
+description: Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki 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 *)
+allowed-tools: Read Glob Grep AskUserQuestion Skill Bash mcp__ShopwareDevKnowledgeBase__kb_status Bash(npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest *)
 ---
 
 # sw-setup
@@ -20,7 +20,7 @@ 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
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
 ```
 
 This skill only renders the CLI's output as a table and relays its one
@@ -40,21 +40,20 @@ table from this run's output — it does not re-run `sw-setup`'s checks.
 Run:
 
 ```
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest 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.
+read-only, seconds each: file/directory existence, 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
@@ -86,11 +85,11 @@ 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
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest plan
 ```
 
 List the concrete steps in plain words: environment-row fixes in order
-(Containers → vendor/ → Visual editors → KB MCP → Acceptance-test project →
+(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.
 
@@ -100,7 +99,7 @@ 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`
+  `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest 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.
 
@@ -112,8 +111,9 @@ Options:
   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.
+- A fix that runs inside a container says so in the step list; if the
+  container is not running at execution time it stops and reports that —
+  sw-setup never starts the developer's stack itself.
 - 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
@@ -137,7 +137,7 @@ line:
 
 ## Reference files
 
-`reference/rows.md` in this skill's directory — the twelve environment rows:
+`reference/rows.md` in this skill's directory — the eleven 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

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

@@ -6,18 +6,7 @@ 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/
+## 1. vendor/
 
 - **Check:** `vendor/shopware/core` exists, `composer.lock` exists,
   `vendor/bin/phpunit` exists — file presence only, never a host
@@ -28,11 +17,12 @@ reports their state in its own `status`/`plan` output; see `SKILL.md`.
   `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.
+  `vendor/bin/phpunit`"). Runs inside the `web` container; if it is not
+  running, stop and report that — sw-setup never starts the stack itself.
 - **Blocks:** `sw-design-solution`, `sw-implement-feature`,
   `sw-verify-feature` (and its architecture/code-quality/ac-tests sub-skills).
 
-## 3. Node
+## 2. Node
 
 - **Check:** `node --version`; parse major and minor.
 - **Ticked:** ≥ 20. Warn (do not fail) when < 20.15: the Tender Discovery Tool
@@ -45,7 +35,7 @@ reports their state in its own `status`/`plan` output; see `SKILL.md`.
   (the knowledge-base MCP), the acceptance-test project,
   Playwright.
 
-## 4. Visual editors (optional)
+## 3. 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
@@ -70,7 +60,7 @@ So this row never blocks readiness. It asks.
   `package` field from `companions[]`), then re-run
 
   ```
-  npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@0.1.0 apply --yes
+  npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest apply --yes
   ```
 
   which places one `SKILL.md` per companion into each selected host's own
@@ -87,7 +77,7 @@ So this row never blocks readiness. It asks.
   Discovery Tool missing → `sw-discover-tender --editor` and its `.xlsx`
   import, plus the `sw-tender-discovery-tool` skill.
 
-## 5. shopware-cli
+## 4. shopware-cli
 
 - **Check:** `command -v shopware-cli`.
 - **Ticked:** present on `PATH`.
@@ -98,7 +88,7 @@ So this row never blocks readiness. It asks.
   (static analysis, Twig linters), `sw-implement-feature` (per-AC
   `extension fix`/`extension validate`).
 
-## 6. KB MCP
+## 5. KB MCP
 
 - **Check:** `mcp__ShopwareDevKnowledgeBase__kb_status` reports the `platform`
   layer as `implemented`. (Whether the `ShopwareDevKnowledgeBase` entry
@@ -118,7 +108,7 @@ So this row never blocks readiness. It asks.
   `sw-design-solution` step 0.5/step 3 (KB grep), `sw-product-manager`,
   `sw-shopware-architect`.
 
-## 7. Acceptance-test project
+## 6. Acceptance-test project
 
 - **Check:** `tests/acceptance/package.json` exists and lists
   `@shopware-ag/acceptance-test-suite` as a dependency;
@@ -137,7 +127,7 @@ So this row never blocks readiness. It asks.
 - **Blocks:** `sw-implement-feature` (e2e authoring by `sw-qa-engineer`),
   `sw-verify-feature-ac-tests` (Playwright execution).
 
-## 8. Playwright browsers
+## 7. Playwright browsers
 
 - **Check:** `npx playwright install --dry-run` output (or
   `~/.cache/ms-playwright`/the project-local browsers path) shows Chromium
@@ -148,7 +138,7 @@ So this row never blocks readiness. It asks.
   ticked (the `@playwright/test` version comes from there).
 - **Blocks:** `sw-implement-feature` (e2e execution), `sw-verify-feature-ac-tests`.
 
-## 9. ATS env
+## 8. ATS env
 
 - **Check:** `tests/acceptance/.env` exists.
 - **Ticked:** file exists and defines `APP_URL`, `SHOPWARE_ADMIN_USERNAME`,
@@ -163,7 +153,7 @@ So this row never blocks readiness. It asks.
   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>`
+## 9. Plugin tests, per `custom/plugins/<Name>`
 
 - **Enumerate:** `ls custom/plugins`; one row per directory found.
 - **Check per plugin:**
@@ -181,12 +171,13 @@ So this row never blocks readiness. It asks.
   `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.
+  JSON snippet. The `npm install` steps run inside the `web` container; if it
+  is not running, stop and report that — sw-setup never starts the stack
+  itself.
 - **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
+## 10. Project wiki
 
 - **Check:** `docs/project-wiki/` exists.
 - **Ticked:** directory present.
@@ -195,7 +186,7 @@ So this row never blocks readiness. It asks.
   logic here.
 - **Blocks:** `sw-document-feature`.
 
-## 12. `.gitignore`
+## 11. `.gitignore`
 
 - **Check:** `.gitignore` contains all six lines:
   ```

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

@@ -2,7 +2,7 @@
 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]
+argument-hint: '[specs/NNNN-slug-spec.md]'
 allowed-tools: Read Write Glob Grep Agent
 ---
 

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

@@ -2,7 +2,7 @@
 name: sw-verify-feature-ac-tests
 description: Verify that a feature's acceptance criteria are backed by tests that actually exist, actually pass, and actually test what their name/comment/PHPDoc claims. Classifies tests by type (API/PHPUnit, Admin Panel/Playwright, Storefront/Playwright, CLI/PHPUnit), runs a test-health audit to catch false, mismatched, or unhealthy tests, then reports per-AC Coverage and Execution as pass / partly / not pass. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
 when_to_use: Trigger phrases — "verify AC tests for spec 0007", "audit test health for this feature", "are these tests actually testing what they claim", "check test coverage for epic 1".
-argument-hint: [specs/NNNN-slug-spec.md]
+argument-hint: '[specs/NNNN-slug-spec.md]'
 allowed-tools: Read Glob Grep Bash mcp__playwright__browser_navigate mcp__playwright__browser_click mcp__playwright__browser_type mcp__playwright__browser_fill_form mcp__playwright__browser_snapshot mcp__playwright__browser_take_screenshot mcp__playwright__browser_wait_for mcp__playwright__browser_console_messages mcp__playwright__browser_network_requests mcp__playwright__browser_evaluate mcp__playwright__browser_select_option mcp__playwright__browser_press_key mcp__playwright__browser_hover mcp__playwright__browser_tabs mcp__playwright__browser_close
 ---
 

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

@@ -2,7 +2,7 @@
 name: sw-verify-feature-architecture
 description: Verify that a feature's implementation matches the architectural decisions its spec made, and complies with Shopware's own Core conventions plus any written Project guidelines this repo defines. Reports per-AC pass/partly/not pass with the specific guideline or mismatch behind any non-pass. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
 when_to_use: Trigger phrases — "verify architecture for spec 0007", "does this implementation follow the spec's design", "check Core/Project guideline compliance for this feature", "architecture audit for epic 1".
-argument-hint: [specs/NNNN-slug-spec.md]
+argument-hint: '[specs/NNNN-slug-spec.md]'
 allowed-tools: Read Glob Grep Bash mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 

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

@@ -2,7 +2,7 @@
 name: sw-verify-feature-code-quality
 description: Verify the code-quality gate for a feature — identifies which tool suites actually apply (PHPStan, ESLint, Stylelint, sw-cli structural validation via shopware-cli, PHPUnit regression), executes them, and checks the touched files against written Core and Project guidelines' quality/style clauses (naming, duplication, dead code, unneeded complexity). Reports whole-plugin gate results plus any per-AC quality defect found in that AC's files. One of three parallel verifiers spawned by sw-verify-feature; can also be run standalone.
 when_to_use: Trigger phrases — "verify code quality for spec 0007", "run static analysis for this feature", "does this pass PHPStan/ESLint", "code quality gate for epic 1".
-argument-hint: [specs/NNNN-slug-spec.md]
+argument-hint: '[specs/NNNN-slug-spec.md]'
 allowed-tools: Read Glob Grep Bash mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---