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

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

@@ -0,0 +1,64 @@
+---
+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]
+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
+---
+
+# sw-document-feature
+
+Turn one feature — from its PRD/spec or from the chat — into wiki pages under `docs/project-wiki/`. The wiki's own rules win over anything here: read `docs/project-wiki/guidelines/documentation-guidelines.md` before writing and fill pages from the templates in `reference/templates/` in this skill's directory (the single source of page shapes).
+
+## Hard rules
+
+- **Gate before ink.** Nothing under `docs/project-wiki/` is created or edited before step 3 has produced its evidence table and a verdict, per the mandatory gate defined in `reference/built-check.md`.
+- **Never restate code.** Class listings, method signatures, DI wiring, Twig markup are pointed to by path, not reproduced. At most a one-line snippet if unavoidable.
+- **One surface per page.** `administration/<feature>.md` and `storefront/<feature>.md` only; never `admin/`, `backend/`, `api/`, never a page without a surface. The "why" lives once, in the domain index feature row.
+- **User answers are anchored, never quoted.** Rewrite them into the page's own voice and add one line to the page's *Decision Log* (see `reference/page-rules.md`).
+- **ADRs are never invented.** `docs/project-wiki/adr/` is the single source of truth and holds only accepted + built ADRs — promoted once from the WIP files `specs/NNNN-slug-adr-<topic>.md` written by `sw-design-solution` (the spec's `[adr] <path>` lines point at them; procedure in `reference/adr-promotion.md`), or provided by the user in chat as accepted (title + context/decision/consequences; anything not accepted is sent to `specs/` as WIP). Never from "precedent", significance, or its own judgment; never written to `specs/`; an existing docs ADR is never overwritten. Everything else goes to Developer › Decisions or the index "Why" column; `[potential ADR]` items are only listed in the report under "ADR candidates (not created)" — no question mid-run unless the user asked about ADRs.
+- **Never paste a page body into chat.** The final report is at most six lines.
+
+## Inputs
+
+| Argument | Behaviour |
+| --- | --- |
+| `specs/NNNN-slug.md` (PRD) | Read it; locate the spec `specs/NNNN-*-spec.md` by number, then slug |
+| `specs/NNNN-slug-spec.md` (spec) | Read it; locate the PRD `specs/NNNN-slug.md` (same number, slug without `-spec`) |
+| Both paths | Read both |
+| Nothing | **Chat mode** — the current discussion is the source; `prd: null`, `spec: null` |
+| `--setup` (alone or with a path) | **Setup only** — run step 0, report its table, stop. Nothing is documented. The `sw-setup` Project wiki row invokes this flag as its fix |
+| A path that does not exist | Say so, `ls specs/`, and ask with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`) offering the nearest match (by number or slug) or chat mode. Never guess a file, never silently fall back to chat |
+
+If a counterpart is missing, say so in one line and continue with what exists. In chat mode extract what/why/AC-like statements from the discussion per `reference/source-mapping.md`; ask the user for the feature name in one sentence only if it cannot be inferred.
+
+## Procedure
+
+### 0. Set up the wiki — only when it is missing or `--setup` was passed
+
+Enter `reference/setup-wiki.md` in this skill's directory when the run carries `--setup`, **or** when `docs/project-wiki/` does not exist. It asks its own questions, delegates writing to one sub-agent, and returns the created/kept table. With `--setup` the run stops there; otherwise it continues at step 1.
+
+Wiki present and no `--setup` → skip this step; no structure work happens on a documentation run.
+
+
+### 1-7. Run the documentation steps
+
+Follow `reference/procedure.md` in this skill's directory: resolve inputs, find the
+counterpart, the mandatory built-check gate, domain and surface mapping, writing the
+pages, ADR promotion, project guidelines, the link check and the report.
+
+## Reference files
+
+All under `reference/` in this skill's directory:
+
+- `procedure.md` — steps 1-7 of a documentation run, in order
+- `built-check.md` — the gate: where to search, evidence-table format, verdict rules, the override
+- `page-rules.md` — condensed wiki rules, terminology, Business vs Developer content, Decision Log
+- `source-mapping.md` — PRD / spec / verification report / chat → page sections
+- `domain-guidelines.md` — canonical domains, feature→domain and surface assignment, `platform` boundaries, splitting
+- `adr-promotion.md` — step 5b: discovery of `specs/*-adr-*.md`, accepted + built test, WIP→docs field mapping, TOC block format
+- `templates/feature-page.md`, `templates/domain-index.md`, `templates/adr.md`, `templates/guideline.md` — the page shapes to fill (`adr.md` only for user-provided ADRs; `guideline.md` only for the guideline route, `page-rules.md` "Project guidelines")
+- `setup-wiki.md` — step 0, entered only on `--setup` or a missing wiki: triggers, the setup questions, manifest, detect/init/repair, the sub-agent brief, drift check
+- `scaffold/` — the generic wiki skeleton (16 files for Jekyll, 15 for Vanilla — see `scaffold/vanilla/`) that setup copies from
+
+Wiki sources of truth for rules (do not copy them into this skill): `docs/project-wiki/guidelines/documentation-guidelines.md`, `docs/project-wiki/baseline/glossary.md`.

package/skills/sw-document-feature/reference/adr-promotion.md

@@ -0,0 +1,64 @@
+# ADR promotion
+
+ADR files under `specs/*-adr-*.md` (written by `sw-design-solution`) are **WIP** — proposed, rejected, or accepted but not yet built. `docs/project-wiki/adr/` is the single source of truth and holds **only accepted ADRs whose required changes exist in the code**. This procedure promotes a WIP ADR into `docs/` exactly once; afterwards people may remove the `specs/` copy and everything references `docs/`. Runs on every run that passes the built-check gate (never after a Stop), over **all** WIP files, not only the current feature's. Never writes to `specs/`, never overwrites a docs ADR.
+
+## 1. Discover
+
+- Glob `specs/*-adr-*.md`; skip files without an `id:` key (report them).
+- Every `[adr] <path>` line in the spec being documented must resolve to one of those files **or** to a docs ADR with the same `id`. Neither → report `dangling [adr] links: <path>`.
+- Glob `docs/project-wiki/adr/*.md` (not `index.md`) and index them by `id` — a WIP file whose `id` is already there is **already promoted**: skip, docs wins; if the specs file still exists report `promoted, specs copy can be removed: <path>`.
+
+## 2. Decide per WIP file
+
+| Condition | Outcome | Report bucket |
+|---|---|---|
+| `status` ≠ `accepted` | not promoted | `WIP ADRs: <id> (<status>)` |
+| `accepted`, required changes not found | not promoted | `accepted, awaiting implementation: <id>` |
+| `accepted`, required changes found (or none needed) | **promote** (§3) | `promoted: <id>` |
+
+Built-check for an ADR: its Decision / Consequences sections name the required changes (runtime component, package, service, config key, convention). Search for them as in `built-check.md` — `custom/`, `composer.json`/`composer.lock`/`vendor/`, config — and keep the one-line evidence for the report. An ADR that needs no code (`area: process`, convention-only, or the ADR says so) counts as built.
+
+## 3. Promote (create once)
+
+Target: `docs/project-wiki/adr/<date>-<kebab-topic>.md` — `date` = WIP `date`, `kebab-topic` = the part of `id` after `ADR-NNNN-`. Link depth: from `adr/` a spec link is `../../../specs/…`; from `domains/<d>/<surface>/` an ADR link is `../../../adr/…` and a WIP link `../../../../../specs/…` (five levels to the repo root).
+
+| WIP field / part | Docs ADR |
+|---|---|
+| `title`, `date`, `area`, `tags`, `authors`, `status` (= `accepted`) | Same keys (wiki ADR schema) |
+| — | `nav_order` (next free slot under `adr/index.md`), `parent: Decision records` (added, not carried from the WIP file — WIP files under `specs/` have no nav front matter) |
+| `id`, `prd`, `spec`, `owner` | Same keys, verbatim |
+| its path, run date | `promoted_from: specs/NNNN-slug-adr-<topic>.md`, `promoted: YYYY-MM-DD` |
+| `decision_needed_by`, HTML comment, `<…>` placeholders | Dropped (`_TBD_` is kept) |
+| H1 | Verbatim, followed by one line `Promoted from specs/… on YYYY-MM-DD.` |
+| `**Status:** … **Spec:** […]` meta line | Carried over; spec link rewritten to `../../../specs/…` |
+| Context, Decision, Options considered, Consequences, Alignment (incl. decision-log table) | Carried over, same headings and order; condensed only where the documentation guidelines forbid (no code listings) |
+
+Nothing else is added. Later status changes (`superseded`, `deprecated`) are made by people editing the docs ADR; the skill never touches an existing docs ADR.
+
+## 4. Table of contents (`docs/project-wiki/adr/index.md`)
+
+Keep the Liquid loop, where the wiki uses the Jekyll flavor, and everything outside the markers untouched. Rewrite the block between `<!-- adr-toc:start -->` and `<!-- adr-toc:end -->` every run (if missing, insert them directly under the `## Table of contents` heading, creating it after the Liquid block when absent) from all pages under `adr/` except `index.md`:
+
+1. Summary line `N ADRs — accepted x · superseded y · deprecated z`; with zero ADRs the block contains only `0 ADRs`.
+2. One `#### <area>` per area in canonical order — the domain slugs from `domain-guidelines.md` (catalogues, checkout, orders, customers, content, marketing, sales-channels, automation, settings, integrations), then `platform`, then `process`, unknown areas last alphabetically — each `| Date | ID | Title | Status | Feature |`, newest first by frontmatter `date`. Feature = `[NNNN-slug-spec](../../../specs/NNNN-slug-spec.md)`, or `—` when that path no longer exists.
+
+The line after the block, `WIP ADRs live in specs/*-adr-*.md until accepted and built.`, is hand-maintained and stays. Example:
+
+```
+<!-- adr-toc:start -->
+1 ADRs — accepted 1 · superseded 0 · deprecated 0
+
+#### checkout
+| Date | ID | Title | Status | Feature |
+|---|---|---|---|---|
+| 2026-08-12 | ADR-0005-net-prices | [Net prices per sales channel](2026-08-12-net-prices.md) | accepted | [0005-b2b-pricing-spec](../../../specs/0005-b2b-pricing-spec.md) |
+<!-- adr-toc:end -->
+```
+
+## 5. Feature pages and edge cases
+
+- Developer › Decisions: promoted → `[ADR-id](../../../adr/<file>.md)`; still WIP → `[ADR-id](../../../../../specs/<file>) (WIP, <status>)`.
+- Page Decision Log: `YYYY-MM-DD — ADR <id> promoted from <specs path>` (only on the run that promotes).
+- Two WIP files with the same `id` → promote neither, report the collision. `id` without `ADR-NNNN-` prefix → whole `id` kebab-cased as topic, report it.
+- A docs ADR without `promoted_from` (user-provided, hand-written) is listed in the TOC like any other.
+- Link check (SKILL step 6) covers every promoted page and the TOC block.

package/skills/sw-document-feature/reference/built-check.md

@@ -0,0 +1,71 @@
+# Built-check gate
+
+Run before any file under `docs/project-wiki/` is touched. The question is only: *does this functionality exist in this project?* — not whether it works well.
+
+## 1. Collect search terms
+
+From the PRD, spec, or chat (step 1 of SKILL.md), list every concrete name: extension/plugin/app name (`AcmeCheckout`), entity/table names (`acme_return_request`), PHP classes and services, Admin/Store API routes, Storefront routes, Twig templates/blocks, admin modules/components, snippet keys, system-config keys, feature flags, migration names, test names. Add the feature slug and its main nouns as fallback terms. Fewer than three concrete terms → say so in the table; a search on nouns alone is weak evidence.
+
+## 2. Search — all three sources, always
+
+**A. Custom project code** (`Grep`/`Glob`, case-insensitive, per term):
+
+```
+custom/plugins/ custom/apps/ custom/static-plugins/ src/
+```
+Also `ls custom/plugins custom/apps custom/static-plugins` — an empty directory is a finding.
+
+**B. Installed extension or bundle delivering it:**
+- `composer.json` `require` — packages beyond `shopware/*` that could deliver the feature (store extensions, bundles).
+- `grep -n '"name": "<package>"' composer.lock` and `ls vendor/<vendor>/<package>` to confirm it is actually installed.
+- Live environment, best effort only: `docker compose exec web bin/console plugin:list` and `… app:list` (or `bin/console` directly if it runs locally). If the command is unavailable or the container is down, record `not reachable` — never block or retry in a loop.
+
+**C. Verification report in chat** — an `sw-verify-feature` block with `AC-n | pass / not pass / partly | …` lines for this feature. Absent → `none`.
+
+Search **B** even when **A** found code, and **A** even when **B** did: a spec may describe a feature that a store extension already delivers, or vice versa.
+
+## 3. Evidence table
+
+Print this before any verdict, whatever the outcome:
+
+```
+| Source | Searched | Found |
+|---|---|---|
+| custom/plugins, apps, static-plugins, src/ | AcmeCheckout, acme_delivery_date, delivery-date route, ACME_DELIVERY_DATE_SELECTION | custom/plugins/AcmeCheckout/src/Storefront/… (3 files), migration Migration17…, no tests |
+| composer.json / composer.lock / vendor | delivery date, shipping | nothing beyond shopware/* |
+| bin/console plugin:list / app:list | — | not reachable (container down) |
+| sw-verify-feature report in chat | — | 2026-08-29: AC-1..AC-4 pass, AC-5 not pass |
+```
+
+One row per source; "Searched" lists the terms actually used, "Found" lists paths/packages/lines or `nothing`.
+
+## 4. Verdict
+
+| Verdict | Condition | Page status |
+|---|---|---|
+| `built` | Code found in A **or** installed package in B, **and** a report in C with every AC `pass` | `built` |
+| `partially-built` | Code/package found, but C is missing, or has any `not pass`/`partly`, or only part of the named artefacts exist | `partially-built` + ⚠️ PARTIALLY BUILT block listing missing/failing ACs |
+| `no evidence` | Nothing in A, nothing in B (beyond core), C absent or all `not pass` | STOP → ask (below) |
+
+Hits matter only when they match a **concrete artefact** (extension, entity, class, route, template, key, migration, test). Hits on fallback nouns alone (the feature slug or its generic words), or fewer than three concrete terms with no artefact match, are `no evidence` — they never yield `partially-built` and never skip the gate.
+
+`built` is never granted on code presence alone — the documentation guidelines require the verification report. Without one, code present = `partially-built` and the block says "verification not run". Status → page mapping and block markup: `page-rules.md`.
+
+A chat report with pass lines but **no** code found in A or B is `no evidence` — a report cannot substitute for the artefacts it claims to test; mention the contradiction in the table.
+
+## 5. The override (only on `no evidence`)
+
+Ask with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`), exactly one question:
+
+- Question: "Feature not found in project code — enforce documentation anyway?"
+- Option 1: **Stop (Recommended)** — end the run; the evidence table is the report.
+- Option 2: **Enforce — document as planned/not-built** — continue.
+
+On enforce, every page written this run must have:
+- `status: planned` if a PRD or spec exists in `specs/`, `status: not-built` if neither does (chat mode with nothing on disk).
+- The `> ⚠️ NOT BUILT` block in *Status*, directly after the page's intro prose — exact markup in `page-rules.md` "Flag block": what exists (PRD/spec paths, flags), what is missing (what was searched and not found), reference (spec ACs, "verification not run"), "Checked against the repo on YYYY-MM-DD".
+- *Developer* section labelled "(planned)" describing the *intended* location from the spec.
+- Decision Log line: `YYYY-MM-DD — User enforced documentation although the built-check found no code`.
+- `planned`/`not-built` added to `tags`.
+
+Never continue on `no evidence` without the explicit enforce answer — not when unattended, not when the user "obviously wants docs", not when the spec is marked *Ready for implementation*.

package/skills/sw-document-feature/reference/domain-guidelines.md

@@ -0,0 +1,59 @@
+# Domain guidelines
+
+How the wiki is cut into domains, how a feature is assigned to one, and how surfaces are assigned. The canonical slug list also lives in the scaffolded `docs/project-wiki/domains/index.md`; this file explains it.
+
+## Canonical domains (Shopware-aligned)
+
+| Slug | Domain | Administration modules it maps to | Storefront pages / Store API it maps to |
+|---|---|---|---|
+| `catalogues` | Catalogues | Catalogues → Products, Categories, Properties, Manufacturers, Dynamic product groups, Product reviews (moderation) | Product detail, listing/search/navigation, product availability, variants |
+| `checkout` | Checkout | Settings → Shipping, Payment (method setup), Rule Builder conditions used at checkout | Cart, checkout confirm/finish, shipping/payment selection, `store-api/checkout/*` |
+| `orders` | Orders | Orders → Overview, order detail, documents, state machine | Account → Orders, order detail, returns, `store-api/order*` |
+| `customers` | Customers | Customers → Overview, Customer groups, addresses, B2B/employee roles | Registration, login, account pages, addresses, `store-api/account/*` |
+| `content` | Content | Content → Shopping Experiences, Media, Landing pages, SEO, Snippets | CMS-rendered pages, landing pages, SEO URLs, snippets/translations |
+| `marketing` | Marketing | Marketing → Promotions, Newsletter, Product reviews, Cross-selling | Promotion codes, newsletter forms, reviews, cross-selling sliders |
+| `sales-channels` | Sales Channels | Sales Channels → domains, languages, currencies, countries; Settings → Tax | Channel-specific behaviour (currency/language/country switches, tax display) |
+| `automation` | Automation | Settings → Flow Builder, Rule Builder (rule management), Scheduled tasks, Mail templates | — (effects show up in other domains; page only if the shopper sees a dedicated surface) |
+| `settings` | Settings | Settings → System, Shop settings not owned by another domain | — |
+| `integrations` | Integrations | Settings → Integrations, Import/Export, Webhooks, external system connectors | External-system driven behaviour visible to the shopper (e.g. live stock, external payment redirect) |
+| `platform` | Platform | — | — (see below) |
+
+Domains exist on disk only once a feature needs them (setup, in `setup-wiki.md`, scaffolds only `platform`). Create a domain from `reference/templates/domain-index.md` in this skill's directory, then add its row to `domains/index.md` and to the domain map in `docs/project-wiki/index.md` (`| [Domain](domains/<domain>/index.md) | Purpose |`).
+
+## Assigning a feature to a domain
+
+First rule that matches wins:
+
+1. The source names an extension listed in `domains/platform/extensions-inventory.md` with one owning domain → that domain. (An extension shared by two domains falls through.)
+2. The PRD §4 Domain Impact / spec entities name a Shopware concept or custom entity owned by one domain (table above; glossary "owned by" notes) → that domain.
+3. The actor's main workflow in PRD §3 maps to one Administration module or Storefront page in the table → that domain.
+4. Still two candidates → ask with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`) with both, then a Decision Log line on the page.
+
+Rule of thumb for the tie-breakers: the domain that owns the **data written** wins over the one that only reads it (a return request writes order state → Orders, even though the shopper starts it from the account area).
+
+## The `platform` domain
+
+Contains only cross-cutting infrastructure: extensions inventory, customization guidelines, configuration layers, logging, debugging, environments and deployment. It has no surfaces and no feature pages.
+
+Must **not** go there: anything a merchant or shopper can see or configure per feature (that is a feature page in a business domain), feature-specific config keys (they go in `configuration.md` *as a row*, but the explanation lives on the feature page), feature decisions (Developer › Decisions on the feature page; `adr/` only when marked `[adr]` or user-provided), and Shopware core behaviour (link the docs).
+
+## Project-specific domains
+
+Add one only when a bounded context does not fit the canonical list — a distinct business capability with its own data, its own actors, and its own vocabulary (e.g. a rental workflow, a B2B quotation process, a marketplace vendor portal). Rules:
+
+- Name it with the Shopware term if one exists (`Quotations` if Shopware Commercial names it so); otherwise the business term from the glossary, singular or plural as the business says it.
+- Slug: kebab-case, no version numbers, no vendor or plugin names, no abbreviations (`quotations`, not `b2b-quote-mgmt`).
+- Ownership: exactly one owning extension recorded in the extensions inventory; the domain index states what belongs to neighbouring domains.
+- A departure from the canonical list needs an ADR (`area: process`) provided by the user or marked `[adr]` in the spec. The skill never writes it on its own: it creates the domain, and reports the missing ADR under "ADR candidates (not created)".
+
+## Assigning surfaces
+
+- Merchant acts in the Administration (module, settings, ACL) → `administration/`.
+- Shopper (guest, registered, B2B buyer) acts in the Storefront or via the Store API → `storefront/`.
+- External system or background job → the surface whose flow it serves: Store API calls and storefront-visible effects → `storefront/`; Admin API, imports, scheduled tasks, mail → `administration/`. State this in the page's Developer section.
+- Both actors → two pages, same slug. Ownership of shared parts: entities, migrations, admin modules, Admin API → `administration/`; Storefront controllers, Twig blocks, JS plugins, Store API → `storefront/`; the other half links.
+- Never a page without a surface, never a third surface (`api/`, `backend/`, `headless/`). A headless-only project still uses `storefront/` for Store API-facing behaviour.
+
+## When a domain gets split
+
+Split when its index table needs a second vocabulary to stay readable, when two extensions own disjoint halves of it, or when features in it never link to each other. Move the pages, keep the slugs, add a redirect row (`deprecated` status with a link) in the old index for one release. The split needs an ADR (`area: process`) provided by the user or marked `[adr]` in the spec; the skill does not write one itself — it proceeds and reports the missing ADR as a candidate. Never split on page count alone.

package/skills/sw-document-feature/reference/page-rules.md

@@ -0,0 +1,129 @@
+# Page rules
+
+**Authority.** `docs/project-wiki/guidelines/documentation-guidelines.md` (wiki) is authoritative for reader-facing rules: frontmatter schema, status meanings, folder/surface rules, terminology. This file is authoritative for how the skill derives status and writes pages. Reader-facing rules are referenced here, not copied — when a summary below drifts from the documentation guidelines, the documentation guidelines win and this line gets fixed.
+
+## Templates (in this skill's `reference/templates/` directory, fill them)
+
+| Page | Template | Where |
+|---|---|---|
+| Feature page | `reference/templates/feature-page.md` | `domains/<domain>/<surface>/<feature>.md` |
+| Domain index | `reference/templates/domain-index.md` | `domains/<domain>/index.md` (+ row in `domains/index.md`) |
+| ADR (user-provided, accepted) | `reference/templates/adr.md` | `adr/YYYY-MM-DD-<kebab-title>.md` (listed by the regenerated TOC block of `adr/index.md`) |
+| ADR (promoted from `specs/*-adr-*.md`) | none — per `reference/adr-promotion.md` | `adr/<date>-<kebab-topic>.md` |
+
+Templates own the page *shape* (section order, placeholders); the documentation guidelines own the rules. Delete every `<…>` placeholder; unknown facts become `_TBD_`, never invented.
+
+## Frontmatter (feature page — every key, no omissions)
+
+Schema per the documentation guidelines' "Frontmatter" section. Skill-side derivation:
+
+- `nav_order` — position within the parent domain's Features table (order the feature was added, or the position the user asks for).
+- `parent` — the domain's `title` from `domains/<domain>/index.md` (exact string, case-sensitive).
+- `grand_parent` — always `Domains`.
+- `feature` — PRD slug without `NNNN-` (chat mode: kebab-case, 2–5 words); identical on both surface halves.
+- `status` — only from the gate verdict (below).
+- `extension` — plugin/app/theme name in `custom/`, or the Composer package name (`vendor/name`) when a vendor-installed extension delivers it, or `null`.
+- `spec`, `prd` — the paths read, or `null` (chat mode: both `null`).
+- `verified_against` — `Shopware X.Y.Z` from `composer.json` → `shopware/core`, 4th segment stripped (`"6.7.13.0"` → `Shopware 6.7.13`).
+- `last_synced` — run date, set only on pages touched this run.
+- `tags` — `[<domain>, <surface>]` plus `planned` / `not-built` when applicable.
+- `related` — relative paths only; counterpart surface page (if it exists), `../index.md`, platform pages linked from the body.
+
+## Status derivation (single source: `built-check.md` verdict)
+
+| Evidence | `status` | Block |
+|---|---|---|
+| Code or package present **and** report with every AC `pass` | `built` | none — Status reads "`built` — verified YYYY-MM-DD (AC-1..AC-n pass)" |
+| Code or package present, no report | `partially-built` | ⚠️ PARTIALLY BUILT, "verification not run" |
+| Code or package present, any AC `not pass` / `partly` | `partially-built` | ⚠️ PARTIALLY BUILT, listing those ACs |
+| No code, PRD and/or spec exist (after enforce) | `planned` | ⚠️ NOT BUILT |
+| Nothing found (after enforce) | `not-built` | ⚠️ NOT BUILT |
+
+"Code or package present" = a concrete artefact under `custom/` **or** an installed Composer package (`composer.lock`, `vendor/`). The block is mandatory for every status except `built`.
+
+## Flag block (exact markup — existing pages use it)
+
+In `## Status`, directly after the intro prose under the H1:
+
+```
+> ⚠️ NOT BUILT
+>
+> **What exists in the repo:** <PRD/spec paths, flags, partial code with paths>
+> **What is missing:** <what sw-document-feature searched for and could not find under custom/ or vendor/>
+> **Reference:** <spec AC-1..AC-n, verification report date or "verification not run">. Checked against the repo on YYYY-MM-DD.
+>
+> Do not describe this feature as available. Everything below is the *intended* design from the spec.
+```
+
+`partially-built` uses the same shape with the first line `> ⚠️ PARTIALLY BUILT`, "What is missing" listing the failing/unverified ACs (with the report's note) or the missing artefacts, and the last line "Only the parts listed as existing are available." The *Developer* heading becomes `## Developer (planned)` for `planned`/`not-built` and describes the *intended* location from the spec; for `partially-built` it describes what exists and marks intended parts "(planned)".
+
+## Decision Log (trailing section, per the documentation guidelines)
+
+`## Decision Log` is the **last** section, after *Related*. One line per user decision, override, or status change the page cannot explain by itself, format `YYYY-MM-DD — <what and who>`. Append only — never rewrite earlier lines; omit the section when it would be empty. Lines this skill writes:
+
+- `YYYY-MM-DD — User enforced documentation although the built-check found no code`
+- `YYYY-MM-DD — Status changed <old>→<new> by built-check (<one-line evidence>)`
+- `YYYY-MM-DD — Domain set to <domain> by user (ambiguous between <a> and <b>)`
+- `YYYY-MM-DD — <topic>: <decision> (user)` for any other answer from a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`)
+- `YYYY-MM-DD — ADR <title> recorded as provided by user` / `YYYY-MM-DD — ADR <id> promoted from <specs path>`
+
+An answer is first rewritten into the section it affects (intro prose, Business user, Developer); the log line is the only trace of the question. Never paste the question or the raw reply.
+
+## Shape and length
+
+- Sections in template order: title → intro prose (no "Summary" heading) → Status → Business user → Developer → Related → (Decision Log) → footer line.
+- Intro is 1–2 sentences on **this surface only**, directly under the H1, no bold labels; the why is a link to `../index.md#features`.
+- No paragraph over 4 lines; prefer bullets. Roughly one screen per section — if Developer needs more, the spec is the place and the page links to it.
+- One topic per page; two features → two pages. Relative links only; folder landings are `index.md`, linked explicitly.
+- No `layout` key (applied site-wide from `_config.yml` `defaults:`). `nav_order`, `parent`, `grand_parent` ARE required — see the frontmatter derivation above.
+- Maintenance metadata (scope, last synced, verified against, re-sync) is a single italic line at the *bottom* of the page, never a bold header block under the H1.
+
+## Domain and surface
+
+Canonical domain list, feature→domain rules, surface assignment, and `platform` boundaries: `domain-guidelines.md`. Two domains still tie → ask (same tool) with the candidates and log the answer. Never invent a domain slug; a new domain is created from the domain-index template and rowed in `domains/index.md` and the wiki `index.md` domain map.
+
+## Business user / Developer content
+
+Business user: only what the actor does or sees on this surface — menu paths, fields, states, error behaviour, ACL/role names. No rationale (index "Why" column), no implementation.
+
+Developer, bullets with fixed labels: **Where** · **Extension points used** · **Decisions** (link ADRs) · **Config** (link `../../platform/configuration.md`) · **Debug/observe** (link `../../platform/logging.md`, `../../platform/debugging.md`) · **Gotchas**. Backend-only work is filed here under the triggering surface with one bullet saying so. What not to document: documentation guidelines "Reference code, don't restate it" (point to paths; link Shopware docs via the ShopwareDevKnowledgeBase MCP).
+
+Where decisions go: documentation guidelines "Where decisions go". Skill rule — every unmarked decision (PRD §9 items, spec Decision Log lines, chat decisions) → Developer › Decisions; business rule → index "Why" column. Never `adr/` on the skill's own judgment.
+
+## ADRs
+
+The skill never invents, decides on, or creates an ADR by itself. Exactly two inputs yield one:
+
+1. **WIP ADR file under `specs/`** — `specs/NNNN-slug-adr-<topic>.md` written by `sw-design-solution`; the spec's `[adr] <path>` Decision Log lines and Dependencies table point at it. Promoted once into `adr/` by `adr-promotion.md` when `accepted` and its required changes exist in the code; `docs/` is then the source of truth and the specs copy may be removed by people.
+2. **Provided by the user in chat as accepted** — title + context/decision/consequences, or an explicit "record this as an ADR" for a named decision. Written from `templates/adr.md` verbatim in structure, `status: accepted`, `area` = domain | `platform` | `process`, file `adr/YYYY-MM-DD-<kebab-title>.md`, no `promoted_from` key. Not stated as accepted → tell the user to file it under `specs/` as WIP; nothing is written.
+
+Both get the matching Decision Log line above on the feature page and a Developer › Decisions link (`adr-promotion.md` §5); both are listed by the regenerated TOC block in `adr/index.md`. Anything the skill *thinks* might deserve an ADR (new project-specific domain, domain split, a spec `[potential ADR]` left unextracted) is not written and not asked about mid-run — it is listed in the report as "ADR candidates (not created)"; the user can provide one later.
+
+## Project guidelines
+
+Triggered when a person states a project coding rule directly, or step 5b promotes an ADR whose Decision/Consequences change one — never on the skill's own judgment or "this looks like a rule".
+
+1. Detect the Shopware major from `composer.json`/`composer.lock` (same derivation as `verified_against`), e.g. `6.7`.
+2. Identify the target platform file by name (`architecture-`, `code-`, `qa-guidelines.md`, or a surface file `be-`/`fe-`/`admin-`/`storefront-…guidelines.md`) from what the rule is about.
+3. `read_doc platform/guidelines/<version>/<file>.md` first — never write a `merge:` anchor that was not read from this call. Pick the real heading anchor(s) the rule acts on.
+4. Write or edit `docs/project-wiki/guidelines/<file>.md` from `templates/guideline.md` (no version folder — project guidelines always apply to the installed Shopware version; `verified_against` records it): one `## <heading>` per anchor, `merge:` entry per section (`override`/`extend`/`waive`), `adr:` when the source is a promoted ADR. An anchor not found in the platform file is an addition — no `merge:` entry needed, the section is appended.
+5. Update `docs/project-wiki/guidelines/index.md`: regenerate the block between `<!-- guidelines-toc:start -->` / `<!-- guidelines-toc:end -->` from every file under `guidelines/` except `index.md`, one row `| <file> | <one-line rule summary> |` per file, newest `last_synced` first; text outside the markers stays untouched.
+6. No built-check gate — a guideline is a rule the project has decided on, not a feature to verify as built. `status`/⚠️ blocks do not apply.
+7. Report line: file written/updated, anchors and modes, ADR cited (if any).
+
+## Side pages touched per run
+
+- `domains/<domain>/index.md` feature row (see `source-mapping.md`).
+- `domains/platform/extensions-inventory.md` — a row when the feature introduces an extension not listed.
+- `adr/index.md` — the `<!-- adr-toc:start -->`…`<!-- adr-toc:end -->` block is regenerated every run from all pages under `adr/` (`adr-promotion.md` §4); nothing outside the markers is touched.
+- `guidelines/index.md` — the `<!-- guidelines-toc:start -->`…`<!-- guidelines-toc:end -->` block is regenerated whenever the "Project guidelines" route (above) writes or edits a file under `guidelines/`.
+- `docs/project-wiki/baseline/glossary.md` — a row when the source introduces a new project term.
+- Terminology on every touched page: documentation guidelines "Terminology" + the glossary's "Terms we do not use".
+
+## Link check (end of every run)
+
+For each touched page (promoted ADRs and the TOC block included), extract every relative target (`[..](path)` and `related:` entries, `#anchor` stripped) and resolve it with `test -e` from the page's directory, e.g. `grep -o '](\.[^)#]*' page.md | sed 's/](//'`. Templates, absolute paths, and URLs into this repo are broken by definition. Fix what you can (wrong `../` depth, wrong surface folder), drop what has no target, and list anything unresolved in the report.
+
+## Touch discipline
+
+Update an existing page for the same feature/surface in place; never create a second file. If its `status` contradicts the gate verdict, the gate wins (status, block, Decision Log line). Set `last_synced` only on pages touched this run. Never edit `specs/`.

package/skills/sw-document-feature/reference/procedure.md

@@ -0,0 +1,58 @@
+# The documentation run, step by step
+
+Entered from `sw-document-feature` after step 0. Steps 1-7 run in order. Step 3 is a hard gate: nothing under `docs/project-wiki/` is created or edited until it has produced its evidence table and verdict.
+
+### 1. Resolve inputs
+
+Read the source document(s) or the chat. Collect the names the built-check will search for: extension name, entities, services, routes, templates/Twig blocks, admin modules/components, snippet keys, config keys, feature flags, test names. Note the feature slug: PRD slug without `NNNN-` (chat mode: kebab-case, 2–5 words).
+
+### 2. Find the counterpart
+
+`ls specs/` and match by `NNNN`, then by slug. Read the counterpart. Do not create, edit, or renumber anything under `specs/`.
+
+### 3. Built-check gate (mandatory)
+
+Follow `reference/built-check.md` in this skill's directory exactly: search custom project code, installed extensions (`composer.json`, `composer.lock`/`vendor/`, `bin/console plugin:list` / `app:list` if an environment is reachable — never fail on an unreachable one, note it), and any `sw-verify-feature` report in chat. Produce the evidence table and the verdict: `built`, `partially-built`, or `no evidence`.
+
+**On `no evidence` — STOP.** Print the evidence table, then ask with a structured question tool if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`):
+
+> Feature not found in project code — enforce documentation anyway?
+> - **Stop (Recommended)** — nothing is written; document after implementation.
+> - **Enforce — document as planned/not-built** — pages are written with the ⚠️ NOT BUILT block.
+
+Only the enforce answer continues. Then every page carries `status: planned` (PRD or spec exists) or `not-built` (neither), the ⚠️ NOT BUILT block, a Developer section labelled "(planned)", and the Decision Log line `YYYY-MM-DD — User enforced documentation although the built-check found no code`. A "Stop" answer ends the run with the evidence table as the report.
+
+`partially-built` needs no question but also requires the ⚠️ PARTIALLY BUILT block listing the failing ACs.
+
+### 4. Map domain and surfaces
+
+- Domain and surfaces per `reference/domain-guidelines.md` in this skill's directory: canonical slug list, assignment rules, what never goes into `platform`. Ask (same tool) only if two domains fit equally; anchor the answer in the Decision Log.
+- New domain: create `domains/<domain>/index.md` from `reference/templates/domain-index.md`, add a row to `domains/index.md` and to the domain map in `docs/project-wiki/index.md` (`| [Domain](domains/<domain>/index.md) | Purpose |`).
+
+### 5. Write pages
+
+Apply `reference/page-rules.md` and `reference/source-mapping.md` in this skill's directory. First check the side pages this run touches exist — `domains/index.md`, `domains/platform/extensions-inventory.md`, `adr/index.md`; if one is missing, stop and tell the user to run `sw-document-feature --setup`.
+
+- Feature page(s) from `reference/templates/feature-page.md`, frontmatter complete: `nav_order`, `parent` (the domain's title), `grand_parent: Domains`, `status`, `extension`, `spec`, `prd`, `verified_against` = `Shopware <shopware/core version from composer.json>`, `last_synced` = today, `related`.
+- Feature row in `domains/<domain>/index.md` — the single source of the "why".
+- `domains/platform/extensions-inventory.md` — add a row if the feature introduces an extension not listed.
+- ADR provided by the user in chat and stated as accepted: write it from `reference/templates/adr.md` (structure verbatim), Decision Log line on the page; it lands in the TOC via step 5b. Not stated as accepted → tell the user to file it under `specs/` as WIP. ADRs from `specs/` are handled only by step 5b. Anything else the skill thinks might deserve an ADR is not written — it goes to the report as an ADR candidate.
+- Developer › Decisions references a promoted ADR as `[ADR-id](../../../adr/<file>.md)`, a WIP one as `[ADR-id](../../../../../specs/<file>) (WIP, <status>)`.
+- Existing page for the same feature/surface: update in place, never create a second file. If its `status` contradicts the gate verdict, the gate wins: update status and the ⚠️ block, and append the Decision Log line `YYYY-MM-DD — Status changed <old>→<new> by built-check (<evidence>)`.
+
+### 5b. Promote ADRs
+
+Follow `reference/adr-promotion.md`: glob **all** `specs/*-adr-*.md` (not only this feature's); an `accepted` one whose required changes the built-check finds in the code is promoted once into `docs/project-wiki/adr/<date>-<topic>.md` (already present by `id` → skip, docs wins); everything else is reported as WIP / awaiting implementation. Check the spec's `[adr] <path>` lines resolve, then regenerate the block between `<!-- adr-toc:start -->` / `<!-- adr-toc:end -->` in `adr/index.md`; everything outside the markers stays untouched (including the Liquid table block, on wikis using the Jekyll flavor).
+
+### 5c. Update project guidelines — only when triggered
+
+Triggered when the user states a project coding rule directly, or a promoted ADR (step 5b) changes one — never on the skill's own judgment. Follow `reference/page-rules.md` "Project guidelines". No built-check gate: a guideline is a rule, not a feature.
+
+### 6. Link check
+
+For every touched page, including promoted ADRs and the TOC block, resolve each relative link (`[..](../x.md)`, `related:` entries) against the filesystem, e.g. with `grep -o` + `test -e` from the page's directory. Fix or drop broken links; report any you could not resolve.
+
+### 7. Report
+
+At most six lines: structure check (created files or drift, if any); files written/updated; status per page; gate verdict (with "enforced" if applicable); `ADRs: promoted n · WIP n · awaiting implementation n · removable specs copies n · dangling [adr] links: <paths or none>`, inventory rows, "ADR candidates (not created): …" (`[potential ADR]` items the spec left unextracted; omit when none), open questions; link-check result. Never paste page bodies.
+

package/skills/sw-document-feature/reference/scaffold/README.md

@@ -0,0 +1,78 @@
+---
+title: "Shopware Project Wiki"
+nav_exclude: true
+tags: [readme, meta]
+---
+
+# Shopware Project Wiki
+
+**→ Start reading at [index.md](index.md).** This page explains what the wiki is and how it is
+published; the documentation itself starts at the index.
+
+This is the living documentation for one Shopware 6 project. It is structured and atomic so that
+coding agents (MCP/LLM tooling) can consume it page by page, and written so that the whole team —
+PMs, architects, developers, QA — can read the same pages without a translation layer.
+
+## What is inside
+
+| Folder | What lives there |
+|---|---|
+| [`domains/`](domains/index.md) | Feature documentation, one page per surface (`administration/`, `storefront/`) |
+| [`domains/platform/`](domains/platform/index.md) | Cross-cutting infrastructure: extensions, configuration, logging, debugging, environments |
+| [`baseline/`](baseline/tech-stack.md) | The project's tech stack and its glossary |
+| [`adr/`](adr/index.md) | Accepted architecture and process decisions |
+| [`guidelines/`](guidelines/index.md) | This project's coding rules, inherited from Shopware unless overridden, plus [documentation guidelines](guidelines/documentation-guidelines.md) — the rules every page follows |
+
+Pages are kept in sync by the `sw-document-feature` skill after each feature verification
+(`sw-verify-feature`).
+
+## Publishing with GitHub Pages
+
+The wiki uses [Just the Docs](https://just-the-docs.com/) for its sidebar navigation and search.
+It is pulled in with `remote_theme:`, which GitHub Pages supports on an ordinary branch deploy — no
+Actions workflow and no local build are needed. Which of the two setups applies depends on where
+this folder lives:
+
+**A. Published as its own repository** (this folder is the repository root — the simplest case):
+
+1. Push the folder to its own GitHub repository.
+2. Settings → Pages → Build and deployment: Source **Deploy from a branch**, branch `main` (or
+   `master`), folder **/ (root)**.
+3. `_config.yml` here is the site config, so the theme applies automatically. Set its
+   `baseurl` to the repository name (`/<repo>`), or the theme's CSS and JS will 404.
+
+**B. Published from the parent project repository** (`docs/project-wiki/` inside a larger repo):
+
+GitHub Pages only reads `_config.yml` from the Pages source root (`/` or `/docs`), never from a
+nested folder — so a branch deploy from `/docs` renders these pages **unthemed**, without the
+sidebar. To keep the theme, either publish the wiki as its own repository (setup A), or switch
+Source to **GitHub Actions** and point a Jekyll build at this folder (`actions/jekyll-build-pages`
+with `source: docs/project-wiki`).
+
+**The site renders as unstyled HTML — plain bullet lists and blue links?** The theme loaded but its
+assets 404'd: `baseurl` in `_config.yml` must be `/<repo>` for a project site
+(`https://<org>.github.io/<repo>/`), and empty only for a user/org site or an Actions build. The
+navigation still renders correctly in that state, so the page looks structurally right and entirely
+unstyled.
+
+## Previewing locally
+
+```sh
+gem install bundler jekyll
+cd docs/project-wiki
+bundle exec jekyll serve      # or: jekyll serve
+# open http://127.0.0.1:4000
+```
+
+Minimal `Gemfile` — `github-pages` pins the exact versions GitHub Pages runs, so a local preview
+matches the published site:
+
+```ruby
+source "https://rubygems.org"
+gem "github-pages", group: :jekyll_plugins
+```
+
+---
+
+*Generated {{DATE}} · verified against Shopware {{SHOPWARE_VERSION}} · the rules for pages live in
+[guidelines/documentation-guidelines.md](guidelines/documentation-guidelines.md).*

package/skills/sw-document-feature/reference/scaffold/_config.yml

@@ -0,0 +1,51 @@
+# Jekyll site configuration for the project wiki (GitHub Pages compatible).
+# This folder is the site root: when it is published as its own repository
+# (Settings → Pages → Deploy from a branch → / (root)), this file is the site config.
+
+title: Shopware Project Wiki
+description: What we built in this Shopware project, why, where it lives in the code, and how to run it.
+
+# Just the Docs gives the left sidebar navigation and search. It is not one of the themes selectable
+# via `theme:`, but GitHub Pages supports `remote_theme:` on a plain branch deploy — no Actions
+# workflow needed. Pinned to a tag so a theme release cannot change the site unannounced.
+remote_theme: just-the-docs/just-the-docs@v0.10.1
+
+markdown: kramdown
+
+plugins:
+  - jekyll-remote-theme
+  - jekyll-seo-tag
+
+# A GitHub Pages *project* site (this folder published from a repo whose Pages URL is
+# https://<org>.github.io/<repo>/) needs baseurl set to "/<repo>", or the theme's CSS and JS 404.
+# A user/org site (repo named <org>.github.io) or a build via GitHub Actions needs it empty.
+# The scaffold cannot know the repository name — set this by hand after publishing.
+baseurl: ""
+
+# The sidebar hierarchy comes from each page's nav_order / parent / grand_parent front matter;
+# the layout is applied here so pages stay free of theme-specific keys.
+defaults:
+  - scope:
+      path: ""
+    values:
+      layout: default
+
+search_enabled: true
+search:
+  heading_level: 2
+  previews: 2
+
+heading_anchors: true
+back_to_top: true
+back_to_top_text: "Back to top"
+
+# aux_links:
+#   "Project repository": https://github.com/<org>/<repo>
+# aux_links_new_tab: true
+
+color_scheme: light
+
+exclude:
+  - Gemfile
+  - Gemfile.lock
+  - vendor