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

package/CHANGELOG.md

@@ -7,6 +7,45 @@ release.
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-09-17
+
+### Changed
+
+- **The `vendor/` row now names the specific missing file when unticked.**
+  `sw-setup`'s printed line says which of `vendor/shopware/core`,
+  `composer.lock` or `vendor/bin/phpunit` is missing instead of just marking
+  the row unticked, so a `--no-dev` vendor tree (which has the first two but
+  not `vendor/bin/phpunit`) is diagnosable at a glance. Same fix as before,
+  `composer install --no-interaction`, offered the same way.
+- **The update documentation now covers every component.** `README.md`'s
+  **Keep up to date** section became **Keeping it up to date** and says how
+  each of the three parts updates on its own schedule: this package through
+  `install`, the MCP servers by themselves (they are registered as `@latest`,
+  so a host fetches the newest build when it next starts one), and the Specs
+  Editor and Tender Discovery Tool through their own `npm i -D` line followed
+  by a re-run of `install`. The section also moved below Install's own
+  subsections, which it had been separating from their heading.
+- **The two extra components are now named individually, with the exact
+  pinned `npm i -D` command for each**, in both `README.md`'s new **The
+  optional editors** subsection and `guide`'s output — replacing the earlier
+  `<package>@<version>` placeholder — because the probe accepts only the
+  exact version `EXTRA_COMPONENTS` pins and skips the skill for anything else,
+  including `@latest`.
+- **Breaking: the "companion" terminology is renamed to "extra component".**
+  The CLI flag `--no-companions` is now `--no-extra-components`, and the
+  `status` JSON output key `companions` is now `extra_components`. Anything
+  scripting against `0.1.2` or earlier that reads `companions` or passes
+  `--no-companions` must update to the new names — there is no backwards-
+  compatible alias.
+- **`sw-storefront-developer`'s locate proofs now check for deprecated
+  forwarder files and `feature()` branches, and read the active theme's
+  `views` chain.** Proof 1 rejects a template whose header names it a removed
+  forwarder; proof 2 notes the `feature()` branch a block sits in; proof 3
+  also greps the theme's `theme.json` `views` order. The chain order and
+  where an override belongs are now deferred to the storefront guideline's
+  expert template-inheritance and override-placement sections instead of
+  being restated in the agent body.
+
 ## [0.1.2] - 2026-09-16
 
 ### Changed

package/README.md

@@ -50,7 +50,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 |
+| `status` | read-only; what is installed, what drifted, which optional extra components are present |
 | `plan` | the exact changes, written as a diff; writes nothing |
 | `apply --yes` | performs them |
 | `uninstall --yes` | removes what the lock file records |
@@ -60,7 +60,7 @@ 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 — `install` implies it), and
-`--no-companions` (skip detection of the optional editor packages).
+`--no-extra-components` (skip detection of the optional editor packages).
 
 ## Install
 
@@ -80,26 +80,6 @@ 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 |
@@ -145,6 +125,48 @@ protocol runs:
 npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest guide
 ```
 
+## Keeping it up to date
+
+Three things update on different schedules.
+
+| What | How it updates |
+| --- | --- |
+| This package — skills, sub-agents, permission rules, MCP registrations | `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest install` |
+| The MCP servers (`ShopwareDevKnowledgeBase`, `playwright`) | By themselves. They are registered as `@latest`, so your agent fetches the newest build the next time it starts one. Nothing to run. |
+| Specs Editor, Tender Discovery Tool | You update them. Each has its own line — see below. |
+
+### The optional editors
+
+Install or update each at the exact version this release pins — the CLI
+probes for that version and skips the skill if it finds another:
+
+```bash
+npm i -D @execuro-sw-ecosystem/sw-specs-editor@0.1.0
+npm i -D @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0
+```
+
+- `sw-specs-editor` backs the `--editor` flag on `sw-design-requirements` and
+  `sw-design-solution`.
+- `sw-tender-discovery-tool` backs the `--editor` flag and the `.xlsx` import
+  on `sw-discover-tender`.
+
+Re-run `install` afterwards so the new skill lands in each host. `status`'s
+`extra_components[]` array reports the pinned `version` and the exact `install`
+command for whichever one is missing.
+
+Re-running `install` is safe at any time: it rewrites only what it owns,
+leaves anything you hand-edited alone (reported as drift), and records the new
+version in the lock file. Restart your coding agent afterwards — every host
+reads its configuration at startup.
+
+`@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 the
+version you first installed.
+
+To look before you change anything: `... @latest status` reports
+`installed_version`, any drift, and which extra components are present. It
+writes nothing.
+
 ## Prerequisites
 
 | Requirement | Why | Check |

package/SECURITY.md

@@ -41,7 +41,7 @@ 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
+separately published extra components (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).
 

package/agents/sw-storefront-developer.md

@@ -41,7 +41,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -56,14 +56,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/bin/cli.mjs

@@ -28,10 +28,10 @@ const COMMANDS = {
 
 const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
 
-  install    [--host <h>] [--scope project|user] [--root <path>] [--no-companions]
+  install    [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
   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]
+  plan       [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
+  apply      --yes [--host <h>] [--scope project|user] [--root <path>] [--no-extra-components]
   uninstall  --yes [--host <h>] [--scope project|user] [--root <path>]
   guide      print the install protocol
 
@@ -44,7 +44,7 @@ const USAGE = `usage: sw-ecosystem-agentic-harness <command> [options]
   --scope defaults to project: nothing is written under your home directory
   unless you ask for it. --root defaults to the current directory.
 
-  --no-companions skips the two optional companion-package skills (Specs
+  --no-extra-components skips the two optional extra-component skills (Specs
   Editor, Tender Discovery Tool) even when the package is present locally.
 
 Every command prints one JSON object on stdout carrying a next_step. Run

package/codex/agents/sw-storefront-developer.toml

@@ -1,6 +1,6 @@
 # Generated by scripts/gen-codex-agents.mjs — do not edit.
 # source: agents/sw-storefront-developer.md
-# source-sha256: 3d2ee9b1f1691eebedd1abaaf7126b55d5ea74677acda6a3f19765490ed9e6ce
+# source-sha256: 9afbeda4ca95afe1d74bf0268c3551031a519524fd2d1c4d2c4ece874cd6c054
 
 name = "sw-storefront-developer"
 description = "Use PROACTIVELY for any Shopware 6 Storefront work - Twig templates, theme/SCSS, storefront controllers/pages/pagelets, storefront JS plugins, checkout/account/product-page customizations."
@@ -43,7 +43,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -58,14 +58,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/copilot/agents/sw-storefront-developer.agent.md

@@ -5,7 +5,7 @@ description: "Use PROACTIVELY for any Shopware 6 Storefront work - Twig template
 
 <!-- Generated by scripts/gen-copilot-agents.mjs — do not edit. -->
 <!-- source: agents/sw-storefront-developer.md -->
-<!-- source-sha256: 3d2ee9b1f1691eebedd1abaaf7126b55d5ea74677acda6a3f19765490ed9e6ce -->
+<!-- source-sha256: 9afbeda4ca95afe1d74bf0268c3551031a519524fd2d1c4d2c4ece874cd6c054 -->
 # Shopware Storefront Developer
 
 ## Role
@@ -42,7 +42,7 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 - Lighthouse on touched pages; perf/a11y/SEO regressions are failures.
 - Playwright MCP (`mcp__playwright__*`) for click-through and screenshots. Shopware docs MCP (`mcp__ShopwareDevKnowledgeBase__*`) for the exact core template, block, route or plugin before extending; never guess a block name.
 - Test the targeted state: logged-out, logged-in, guest checkout, plus a non-default currency or language when prices or text change.
-- "Does not show up" checklist, in order: template path, block name, theme assigned, theme compiled, cache cleared, browser cache.
+- "Does not show up" checklist, in order: template path (not a deprecated forwarder file), block name in that file (and its `feature()` branch), theme assigned, theme compiled, cache cleared, browser cache.
 
 ### Small, reversible
 - One concern per template, subscriber or plugin; header + footer + checkout is three changes.
@@ -57,14 +57,14 @@ An edit is not done until `lint:twig` passes on it and the changed markup is obs
 
 1. **Classify.** Confirm storefront work (see Boundary). If mixed, split and hand off the non-storefront part first.
 2. **Locate — prove it, never assume.** Docs MCP answers *what an extension point is for*; only the installed source answers *whether it exists here*. Produce all four proofs before writing a single `{% block %}`:
-   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>`.
-   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead.
-   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`. Name who wins under the slot order above, and whether they call `{{ parent() }}`.
+   1. The target template exists at the exact relative path: `ls vendor/shopware/storefront/Resources/views/storefront/<rel>` — and its first lines carry no `@deprecated … File will be removed` header: such a forwarder is never loaded, extend the file it names instead.
+   2. The block name exists verbatim **in that file**: `grep -n "{% block <name>" vendor/shopware/storefront/Resources/views/storefront/<rel>`. Block names are not unique across the storefront (~2200 block tags, ~2035 distinct names — every override re-declares its parent's name), so a repo-wide grep for a name is not proof. If it is not in that file, it lives in an included sub-template: find that file and override it instead. Note the `feature()` branch the block sits in, if any — the guideline's template-inheritance section says which anchor to target.
+   3. Every other bundle already providing the same relative path: `grep -rl "<rel>" custom/ vendor/*/*/Resources/views/`, plus the active theme's chain: `grep -A4 '"views"' custom/*/*/src/Resources/theme.json`. Name who wins under the chain order in the guideline's template-inheritance section, and whether they call `{{ parent() }}`.
    4. When the dev env is up, `shopware-cli project console debug:twig @Storefront/storefront/<rel>` prints "Matched File" and "Overridden Files" — the real resolution, and it overrides 1–3. Caveat: the theme slot is filled per storefront request, so a CLI run may show only the `@Storefront`/`@Plugins` part of the chain; the browser is the final word on which theme override wins.
    A block name recalled from memory or from an older Shopware version is a defect, not a starting point.
 3. **Place.** Theme (look, Bootstrap variables) vs plugin (features).
 4. **Test first** where tooling supports it: Jest for JS plugins, functional/e2e for rendered HTML. Failing test before the extension.
-5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin.
+5. **Implement** the smallest extension that passes: one block, one subscriber, one plugin — placed per the guideline's override-placement ladder (edit an existing project override rather than adding a second file for the same path; go later in the chain than a marketplace override).
 6. **Lint and build.** `lint:twig` on every touched Twig file first, then `extension validate` for SCSS/JS, then the cache/theme/build sequence — all per "Verify: lint, build, render".
 7. **Verify.** Render assertion first (the changed markup is actually in the page), then browser pass (Playwright MCP), console/network clean, breakpoints, keyboard, Lighthouse.
 8. **Report** in the format below.

package/lib/actions.mjs

@@ -20,7 +20,7 @@ import {
 import { PKG_ROOT } from './content.mjs';
 import { isDeclined } from './lock.mjs';
 import { readFileSync } from 'node:fs';
-import { COMPANIONS, probe } from './companions.mjs';
+import { EXTRA_COMPONENTS, probe } from './extra-components.mjs';
 
 /** Preview one action against the filesystem. Reads only. */
 export function preview(action, ctx) {
@@ -83,8 +83,8 @@ function stripProbeBody({ body, ...rest }) {
 }
 
 function previewSkill(action, ctx) {
-  const companion = COMPANIONS.find((c) => c.id === action.companion);
-  const probed = probe(companion, { platform: ctx.platform });
+  const component = EXTRA_COMPONENTS.find((c) => c.id === action.component);
+  const probed = probe(component, { platform: ctx.platform });
   const probeSummary = stripProbeBody(probed);
 
   if (!probed.available) {
@@ -277,7 +277,7 @@ export function execute(action, ctx) {
     }
     case 'skill-copy': {
       // Collapses to a `file-copy` lock entry on purpose: `lock.record`,
-      // `lock.entries`, `revert` and `rebuild` need no companion-specific
+      // `lock.entries`, `revert` and `rebuild` need no extra-component-specific
       // case, and `uninstall` needs no probe. `source` is provenance only —
       // `revert` never reads it.
       ensureDir(dirname(target));

package/lib/commands.mjs

@@ -14,7 +14,7 @@ import { exists, isWritable, abs } from './fsx.mjs';
 import { HOSTS, buildPlan, detectAll, installedCounts } from './hosts.mjs';
 import * as lockfile from './lock.mjs';
 import { dedupe, execute, isWritableState, preview, pruneDirs, revert } from './actions.mjs';
-import { probeAll } from './companions.mjs';
+import { probeAll } from './extra-components.mjs';
 
 const RUN = 'sw-ecosystem-agentic-harness';
 
@@ -29,12 +29,12 @@ export function buildContext(argv, command) {
   let root = process.cwd();
   let yes = false;
   let projectWiki;
-  let companions = true;
+  let extraComponents = true;
 
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === '--yes' || arg === '-y') { yes = true; continue; }
-    if (arg === '--no-companions') { companions = false; continue; }
+    if (arg === '--no-extra-components') { extraComponents = false; continue; }
     if (arg === '--host') {
       const value = argv[++i];
       if (!HOSTS.includes(value)) {
@@ -64,7 +64,7 @@ export function buildContext(argv, command) {
   if (!exists(root)) throw new UsageError(`--root does not exist: ${root}`, [`${RUN} ${command} --root .`]);
 
   return {
-    root, scope, yes, projectWiki, companions,
+    root, scope, yes, projectWiki, extraComponents,
     hosts: hosts.length ? [...new Set(hosts)] : [...HOSTS],
     platform: process.platform,
     version: PKG_VERSION,
@@ -168,7 +168,7 @@ export async function status(argv) {
   const worst = ['conflict', 'drift', 'not-installed', 'ok', 'absent']
     .find((s) => hosts.some((h) => h.state === s)) ?? 'absent';
 
-  const companions = ctx.companions === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
+  const extraComponents = ctx.extraComponents === false ? [] : probeAll({ platform: ctx.platform }).map((p) => ({
     id: p.id, package: p.pkg, version: p.version, label: p.label,
     available: p.available, probe: p.state, reason: p.reason ?? null,
     installed_for: Object.entries(lock?.files ?? {})
@@ -180,10 +180,10 @@ export async function status(argv) {
   let next = pending
     ? `Run \`${RUN} plan\` to see the ${pending} change(s) needed, then \`${RUN} apply --yes\`.`
     : `Nothing to do — the harness is installed and up to date. Run \`${RUN} plan\` any time to re-check.`;
-  if (ctx.companions !== false) {
-    const unavailable = companions.filter((c) => !c.available);
+  if (ctx.extraComponents !== false) {
+    const unavailable = extraComponents.filter((c) => !c.available);
     if (unavailable.length) {
-      next += ` ${unavailable.length} optional companion package(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
+      next += ` ${unavailable.length} optional extra component(s) are not on this machine — install with ${unavailable.map((c) => `\`${c.install}\``).join(', ')} to enable their skills.`;
     }
   }
 
@@ -193,7 +193,7 @@ export async function status(argv) {
     next_step: next,
     help: [`${RUN} plan`, `${RUN} apply --yes`, `${RUN} guide`],
     inventory: { skills: skills().length, agents: agents().length },
-    hosts, companions, drift,
+    hosts, extra_components: extraComponents, drift,
     declined: lock?.declined ?? [],
     manual: lock?.manual ?? [],
     errors,

package/lib/{companions.mjs → extra-components.mjs}

@@ -1,13 +1,13 @@
-// The two optional companion packages, probed rather than installed by us.
+// The two optional extra components, probed rather than installed by us.
 //
 // Read-then-copy, not `install-skill --target`: the engine's whole safety
 // story is "hash what we intend to write, compare, record". A foreign binary
 // that writes on its own cannot be previewed, so `plan` would lie and
 // `uninstall` would have to guess. Reading the body with `--print` and
-// copying it ourselves through `writeAtomic` keeps every companion skill on
-// the same adopt/conflict/drift/update ladder as everything else this CLI
-// writes, and makes `uninstall` exact even after the user has removed the
-// companion package — the common case, since it is optional.
+// copying it ourselves through `writeAtomic` keeps every extra-component
+// skill on the same adopt/conflict/drift/update ladder as everything else
+// this CLI writes, and makes `uninstall` exact even after the user has
+// removed the extra component — the common case, since it is optional.
 //
 // `--no-install` plus `npm_config_yes=false` are two independent guards that
 // this can never reach the network: the first tells npx not to fetch a
@@ -17,7 +17,7 @@ import { spawnSync } from 'node:child_process';
 import { sha256 } from './fsx.mjs';
 import { wrapCommand } from './content.mjs';
 
-export const COMPANIONS = [
+export const EXTRA_COMPONENTS = [
   {
     id: 'sw-specs-editor', pkg: '@execuro-sw-ecosystem/sw-specs-editor', version: '0.1.0',
     label: 'Specs Editor',
@@ -29,8 +29,8 @@ export const COMPANIONS = [
 ];
 
 /** The argv `probe` would spawn, without spawning it — for tests. */
-export function probeArgs(companion, platform) {
-  const spec = `${companion.pkg}@${companion.version}`;
+export function probeArgs(component, platform) {
+  const spec = `${component.pkg}@${component.version}`;
   const wrapped = wrapCommand(
     { command: 'npx', args: ['--no-install', spec, 'install-skill', '--print'] },
     platform,
@@ -51,9 +51,9 @@ function lastLine(text) {
   return lines.length ? lines[lines.length - 1] : '';
 }
 
-function doProbe(companion, platform) {
-  const spec = `${companion.pkg}@${companion.version}`;
-  const base = { id: companion.id, pkg: companion.pkg, version: companion.version, spec, label: companion.label };
+function doProbe(component, platform) {
+  const spec = `${component.pkg}@${component.version}`;
+  const base = { id: component.id, pkg: component.pkg, version: component.version, spec, label: component.label };
   const wrapped = wrapCommand(
     { command: 'npx', args: ['--no-install', spec, 'install-skill', '--print'] },
     platform,
@@ -103,15 +103,15 @@ function doProbe(companion, platform) {
   return { ...base, available: true, state: 'available', body: stdout, hash: sha256(stdout), bytes: stdout.length };
 }
 
-/** Probe one companion. Never throws. */
-export function probe(companion, { platform = process.platform } = {}) {
-  const key = `${companion.pkg}@${companion.version}`;
+/** Probe one extra component. Never throws. */
+export function probe(component, { platform = process.platform } = {}) {
+  const key = `${component.pkg}@${component.version}`;
   if (cache.has(key)) return cache.get(key);
-  const result = doProbe(companion, platform);
+  const result = doProbe(component, platform);
   cache.set(key, result);
   return result;
 }
 
 export function probeAll(opts) {
-  return COMPANIONS.map((c) => probe(c, opts));
+  return EXTRA_COMPONENTS.map((c) => probe(c, opts));
 }

package/lib/guide.mjs

@@ -6,8 +6,10 @@
 
 import * as out from './out.mjs';
 import { PKG_NAME, PKG_VERSION } from './content.mjs';
+import { EXTRA_COMPONENTS } from './extra-components.mjs';
 
 const RUN = `npx -y ${PKG_NAME}@${PKG_VERSION}`;
+const EXTRA_COMPONENT_INSTALLS = EXTRA_COMPONENTS.map((c) => `npm i -D ${c.pkg}@${c.version}`).join('\n');
 
 export const GUIDE = `# ${PKG_NAME} — install protocol
 
@@ -44,17 +46,22 @@ registers the MCP servers and permission rules they depend on.
   --host claude-code|codex|copilot|cursor   restrict to one host, repeatable
   --scope project|user                      default: project
   --root <path>                             default: the current directory
-  --no-companions                           skip the optional companion-package skills
+  --no-extra-components                     skip the optional extra-component skills
 
-## Optional companion packages
+## Optional extra components
 
 Two skills — Specs Editor and Tender Discovery Tool — ship inside their own
 npm packages, not this one. \`plan\`/\`apply\` detect them offline
-(\`npx --no-install\`) and never fetch them. A \`skipped\` action means the
-package is not on this machine yet: install it with
-\`npm i -D <package>@<version>\` (the exact command is in the action's
-\`remedy\`, and in \`status\`'s \`companions\` array), then re-run
-\`${RUN} apply --yes\`.
+(\`npx --no-install\`) and never fetch them, probing for the exact version
+this release pins — any other version, including \`@latest\`, is treated as
+absent and the skill is skipped:
+
+\`\`\`bash
+${EXTRA_COMPONENT_INSTALLS}
+\`\`\`
+
+The exact command is also in a \`skipped\` action's \`remedy\`, and in
+\`status\`'s \`extra_components\` array. Install it, then re-run \`${RUN} apply --yes\`.
 
 ## What you can rely on
 

package/lib/hosts.mjs

@@ -14,12 +14,12 @@ import {
 import { abs, isDir, isWritable, walk } from './fsx.mjs';
 import { renderTomlTable, tomlTableExists, findFence } from './merge.mjs';
 import { readTextMaybe } from './fsx.mjs';
-import { COMPANIONS } from './companions.mjs';
+import { EXTRA_COMPONENTS } from './extra-components.mjs';
 
 export const HOSTS = ['claude-code', 'codex', 'copilot', 'cursor'];
 
 /** Where each host reads its skills from — the base every skill-copy and
- * companion skill-copy action is rooted at. */
+ * extra-component skill-copy action is rooted at. */
 export const SKILL_DIR = {
   'claude-code': '.claude/skills',
   codex: '.agents/skills',
@@ -103,16 +103,16 @@ function skillActions(host, targetBase) {
 }
 
 /**
- * One `skill-copy` action per optional companion package. The `skill:`
+ * One `skill-copy` action per optional extra component. The `skill:`
  * segment (not `file:`) keeps these ids from colliding, or deduping,
  * against a shipped `file-copy` action at the same path.
  */
-function companionActions(host, targetBase) {
-  return COMPANIONS.map((c) => {
+function extraComponentActions(host, targetBase) {
+  return EXTRA_COMPONENTS.map((c) => {
     const target = `${targetBase}/${c.id}/SKILL.md`;
     return {
       id: `${host}:skill:${target}`, host, kind: 'skill-copy',
-      companion: c.id, package: `${c.pkg}@${c.version}`, target,
+      component: c.id, package: `${c.pkg}@${c.version}`, target,
     };
   });
 }
@@ -158,7 +158,7 @@ function planClaude(ctx) {
   const host = 'claude-code';
   const out = [
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.companions === false ? [] : companionActions(host, SKILL_DIR[host])),
+    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.claude/agents', 'claude', '.md'),
     ...mcpJsonActions(host, '.mcp.json', 'mcpServers', ctx),
   ];
@@ -184,7 +184,7 @@ function planCodex(ctx) {
   const out = [
     // Codex discovers skills from `.agents/skills`, never `.claude/skills`.
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.companions === false ? [] : companionActions(host, SKILL_DIR[host])),
+    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.codex/agents', 'codex', '.toml'),
   ];
 
@@ -229,7 +229,7 @@ function planCopilot(ctx) {
   const host = 'copilot';
   const out = [
     ...skillActions(host, SKILL_DIR[host]),
-    ...(ctx.companions === false ? [] : companionActions(host, SKILL_DIR[host])),
+    ...(ctx.extraComponents === false ? [] : extraComponentActions(host, SKILL_DIR[host])),
     ...agentActions(host, '.github/agents', 'copilot', '.agent.md'),
     // Copilot CLI reads `.mcp.json`; VS Code reads `.vscode/mcp.json` under the
     // incompatible `servers` key. Both, or the two surfaces disagree.
@@ -256,7 +256,7 @@ function planCursor(ctx) {
     || (isDir(abs(ctx.root, '.claude/skills')) && isDir(abs(ctx.root, '.claude/agents')));
   if (!claudeTrees) {
     out.push(...skillActions(host, SKILL_DIR[host]));
-    if (ctx.companions !== false) out.push(...companionActions(host, SKILL_DIR[host]));
+    if (ctx.extraComponents !== false) out.push(...extraComponentActions(host, SKILL_DIR[host]));
     out.push(...agentActions(host, '.cursor/agents', 'claude', '.md'));
   }
   out.push(...mcpJsonActions(host, '.cursor/mcp.json', 'mcpServers', ctx));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@execuro-sw-ecosystem/sw-ecosystem-agentic-harness",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Shopware 6 agentic harness: sw-* skills and sub-agents, plus an installer that writes them into Claude Code, Codex, GitHub Copilot and Cursor.",
   "license": "MIT",
   "author": "Execuro UG (haftungsbeschränkt)",

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "sw-ecosystem-agentic-harness",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "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-setup/SKILL.md

@@ -55,6 +55,7 @@ one line per configuration item the CLI's `hosts[]`/`drift[]` reports:
 
 ```
 - [x] vendor/ — shopware/core 6.7.13.0
+- [ ] vendor/ — vendor/bin/phpunit missing (tree built --no-dev)
 - [ ] Node — 18.x (need >= 20)
 - [-] Visual editors (optional) — Specs Editor not installed, Tender tool not installed
 - [x] shopware-cli — 0.16.10

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

@@ -15,6 +15,12 @@ reports their state in its own `status`/`plan` output; see `SKILL.md`.
   (guideline §6.2).
 - **Ticked:** all three present; report the `shopware/core` version from
   `composer.lock`.
+- **Unticked:** the printed line names the specific missing path(s), not just
+  the row — e.g. a tree built `--no-dev` has `vendor/shopware/core` and
+  `composer.lock` but no `vendor/bin/phpunit`, so the line reads
+  `vendor/ — vendor/bin/phpunit missing (tree built --no-dev)`. This is the
+  same row and the same fix below, offered inside step 3's single question
+  like any other row.
 - **Fix:** `docker compose exec web composer install --no-interaction`
   (guideline §6.1 — "a vendor tree built with `--no-dev` has no
   `vendor/bin/phpunit`"). Runs inside the `web` container; if it is not
@@ -39,33 +45,33 @@ reports their state in its own `status`/`plan` output; see `SKILL.md`.
 
 The Specs Editor and the Tender Discovery Tool are **optional add-ons**, not
 part of this plugin. The installer CLI installs them itself, per host — this
-row never runs a companion package's own install command.
+row never runs an extra component's own install command.
 
 So this row never blocks readiness. It asks.
 
-- **Check:** read `companions[]` from the `status` output the skill already
+- **Check:** read `extra_components[]` from the `status` output the skill already
   ran in step 1 — each entry's `available`, `installed_for` (the hosts it is
   placed in), and `install` (the npm command, when missing). Never probe a
-  path and never run a companion package by hand; the CLI owns both.
-- **Ticked:** `[x]` when a companion's `available` is true and
+  path and never run an extra component by hand; the CLI owns both.
+- **Ticked:** `[x]` when an extra component's `available` is true and
   `installed_for` includes this host; `[-]` when the user has declined it.
   Only an unanswered offer shows `[ ]`, and even then it does not hold the
   table open — report it as optional and move on.
-- **Fix:** offer each missing companion inside step 3's single question,
+- **Fix:** offer each missing extra component inside step 3's single question,
   naming what it buys, not how it works: "Specs Editor — review a PRD or
   tech spec on a live page, with notes, question answers and diagrams.
   Install?" — and "Tender Discovery Tool — read a client tender workbook,
   confirm its column mapping and review the analysis on a live page.
   Install?" On yes, for each accepted one: `npm i -D <package>@0.1.0` (the
-  `package` field from `companions[]`), then re-run
+  `package` field from `extra_components[]`), then re-run
 
   ```
   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
+  which places one `SKILL.md` per extra component into each selected host's own
   skills directory, records it, and removes it again on uninstall. **Never
-  run the companion package's own `install-skill`** — with no `--target` it
+  run the extra component's own `install-skill`** — with no `--target` it
   defaults to Claude Code's own skills directory, wrong for a Codex, Copilot
   or Cursor install. Needs the Node row ticked.
 - **On no:** record the decline and do not re-ask on the next run. `apply`