@execuro-sw-ecosystem/sw-ecosystem-agentic-harness 0.1.8 → 0.1.10

package/CHANGELOG.md

@@ -7,6 +7,22 @@ release.
 
 ## [Unreleased]
 
+## [0.1.10] - 2026-09-20
+
+### Changed
+
+- **The design skills follow the Specs Editor's split of PRD and tech-spec
+  workflows.** `sw-design-requirements` and `sw-design-solution` (their
+  `SKILL.md`, editor-mode, editor-gate, readiness and pre-check references) and
+  `README.md` now describe one session per document, with `--doc` naming the
+  document, and a feature's PRD and spec as two independent sessions.
+
+## [0.1.9] - 2026-09-19
+
+### Changed
+
+- `README.md` names `sw-setup` as part of the installation flow. Documentation only.
+
 ## [0.1.8] - 2026-09-19
 
 ### Changed

package/README.md

@@ -100,6 +100,13 @@ writes anything.
 Then restart your coding agent — every host reads its configuration at startup.
 The command's output tells you which ones and how.
 
+Then run the `sw-setup` skill in that agent. The installer only writes the
+harness files; `sw-setup` checks and completes everything else the skills need
+— `vendor/`, Node, `shopware-cli`, the knowledge-base MCP, the acceptance-test
+project and its Playwright browsers, the per-plugin test scaffolding, and the
+optional editor add-ons. It prints one readiness table and is done when every
+row is ticked.
+
 `apply` refuses without `--yes`. Neither `apply` nor `install` prompts for
 consent — typing the verb, or passing `--yes`, is the consent — but with no
 `--agent`, no existing lock and no terminal (Codex's question tool does not
@@ -187,7 +194,9 @@ npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest install-skill --tar
 ```
 
 - `sw-specs-editor` backs the `--editor` flag on `sw-design-requirements` and
-  `sw-design-solution`.
+  `sw-design-solution`. Each flag opens its own single-document session — the PRD
+  and the tech spec never share one — and `sw-design-solution --editor` on a PRD
+  path resolves to the spec, creating it from the template if it does not exist.
 - `sw-tender-discovery-tool` backs the `--editor` flag and the `.xlsx` import
   on `sw-discover-tender`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@execuro-sw-ecosystem/sw-ecosystem-agentic-harness",
-  "version": "0.1.8",
+  "version": "0.1.10",
   "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.8",
+  "version": "0.1.10",
   "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

@@ -28,7 +28,7 @@ Tech decisions belong to `sw-design-solution`. Consult `sw-shopware-architect` (
 | Path to `specs/NNNN-*.md` | **Continue mode** — load, keep its number, advance |
 | Any other file path, or free text | **New PRD** — used as source brief |
 | Nothing | Ask for the feature in one sentence, then proceed |
-| `<path> --editor` | **Editor hand-off** — step 0 checks the optional `sw-specs-editor` skill is installed, then invokes it on `<path>` and stops. Nothing else runs. |
+| `<path> --editor` | **Editor hand-off** — step 0 checks the optional `sw-specs-editor` skill is installed, then invokes it on `<path>` and stops. Nothing else runs. The session edits the PRD only; the tech spec, if it exists, is reference only and has its own session. A `-spec.md` path is refused here. |
 | `<path> --editor-session <url> --batch <file>` | **Editor mode** — continue mode driven by one note batch; see `reference/editor-mode.md` in this skill's directory. |
 
 Images, notes, tickets, transcripts count as sources; extract requirements, discard narrative.
@@ -37,7 +37,7 @@ Images, notes, tickets, transcripts count as sources; extract requirements, disc
 
 ### 0. Editor flags
 
-`--editor` → run the gate in `reference/editor-gate.md` in this skill's directory first; the Specs Editor is optional and may not be installed, in which case stop there. Available → call Skill `sw-specs-editor` with the document path, stop; nothing else runs. `--editor-session` → continue mode under `reference/editor-mode.md` in this skill's directory.
+`--editor` → run the gate in `reference/editor-gate.md` in this skill's directory first; the Specs Editor is optional and may not be installed, in which case stop there. Available → call Skill `sw-specs-editor` with the PRD path, stop; nothing else runs. `--editor-session` → continue mode under `reference/editor-mode.md` in this skill's directory.
 
 ### 1. Establish the target file
 

package/skills/sw-design-requirements/reference/editor-gate.md

@@ -6,7 +6,9 @@ What is checked is the **skill**, `sw-specs-editor`, because that is what `sw-se
 
 Check: is the `sw-specs-editor` skill available in this session?
 
-**Available** → hand off to it with the document path, and stop. Nothing else runs.
+**Available** → hand off to it with the PRD path, and stop. Nothing else runs.
+
+The session it opens serves the **PRD alone** — there is no spec tab and no way to reach the spec from it; the tech spec is a separate session with its own chat, queue and port. The filename is what picks the mode, so the path must be a PRD: given a `-spec.md` path, stop with one line — "That is a tech spec; run `sw-design-solution <path> --editor`." — and hand off nothing.
 
 **Not available** → **stop the run here**. Say, in one line:
 

package/skills/sw-design-requirements/reference/editor-mode.md

@@ -1,15 +1,15 @@
 # Editor mode
 
-Invoked as `<path> --editor-session <url> --batch <batch.json>` — one note batch from the page. Continue mode, same procedure, boundary, anchoring/logging rules, plus:
+Invoked as `<prd path> --editor-session <url> --batch <batch.json>` — one note batch from the page. The session's editable document is the PRD; the tech spec is reference only. Continue mode, same procedure, boundary, anchoring/logging rules, plus:
 
 - **Scoped to the batch.** Never a full pass on open. Step 2 only for concepts/PRDs/plugins the notes touch; edit only named blocks plus whatever answers invalidate; re-score every run; §11 blocks only where the batch exposed a gap.
 - **No terminal questions.** Never invoke a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`). Every gap becomes a §11 question block (`**Q-n**`, 2–4 `- [ ]` options, one `(recommended)`), notes per *Recommended options must be advised*. Max 6/run, ranked by confidence.
-- **Batch input**: read ticks first — a tick with no note is still an answer. Per note: `answer` or `[x]` tick (own answer `- [x] ✎ text`) → anchor per *Anchoring answers*, append §12, delete block. `comment`/`free` → this run's briefing (block-bound: `path`, `line`–`endLine`, verify `md`/`hash`, fall back to `quote`, honour `selection`). `diagram` → update the graph file (below). Technical note → report belongs to the spec, change nothing.
+- **Batch input**: read ticks first — a tick with no note is still an answer. Per note: `answer` or `[x]` tick (own answer `- [x] ✎ text`) → anchor per *Anchoring answers*, append §12, delete block. `comment`/`free` → this run's briefing (block-bound: `path`, `line`–`endLine`, verify `md`/`hash`, fall back to `quote`, honour `selection`). `diagram` → update the graph file (below). Technical note → the spec is **read-only** here, a separate session's document: read it — `batch.reference.path` — to check whether a requirement change invalidates something already specified, and say so in the reply; never edit it, never emit against it. Report that it belongs to the spec session (`sw-design-solution <spec path> --editor`) and change nothing in the PRD beyond a §10 `[decision]`/`[constraint]` bullet the user asserted.
 - **Full pass on request only.** A review request ("check the whole PRD", "reconcile") runs the full flow: step 2, §11 gap review, missing options/marks/notes filled. Otherwise touched questions get options.
-- **Scoped agent runs.** Spawn `sw-product-manager`/`sw-shopware-architect` only when a note touches feasibility, §10, or a §11 block changes (one brief per run); else edit, anchor, log alone.
+- **Scoped agent runs.** Spawn `sw-product-manager`/`sw-shopware-architect` only when a note touches feasibility, §10, or a §11 block changes (one brief per run); else edit, anchor, log alone. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: anchor, log, re-score, reply. No spawn and no step 2; the user is waiting on the page for what is a bookkeeping run.
 - **Preserve on every write:** status tags on item ids (`- **FR-3** [done] …`, also `AC-n`/`BR-n`), the `Diagram:` line, the §11 question blocks and ticks. Rewrite in place; never regenerate.
 - **Diagrams.** Domain diagram: `specs/NNNN-slug.domain.graph.json` (business concepts only). Write/update, run `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest diagram specs/NNNN-slug.domain.graph.json specs/NNNN-slug.domain.excalidraw`, ensure §4 carries `Diagram: specs/NNNN-slug.domain.excalidraw`; never write `.excalidraw` directly, first request only.
-- **Progress.** Before each step, before/after each spawn: `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit progress "<step>" --batch <id> --doc prd`.
+- **Progress.** Before each step, before/after each spawn: `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit progress "<step>" --batch <id> --doc <prd path>` (`--doc` is the document path: it names the session, and a feature's PRD and spec are two of them). Keep them few and short — one line per phase, under ~60 characters, no per-tool narration (`reading notes`, `checking feasibility`, `rewriting §4`). They are the page's only sign of life while a spawn runs, not a log.
 - **Report:** changed blocks, answers (Q ids → anchor), top remaining gap or `none`, confidence %, status, `Agents: <list or none>`.
 
 Graph shape (`bin/cli.mjs diagram` input): `{ "title", "direction": "LR", "groups": [{id,label}], "nodes": [{id,label,type: entity|actor|service|external|event|store, group?, note?}], "edges": [{from,to,label?}] }`.

package/skills/sw-design-requirements/reference/readiness-and-report.md

@@ -4,7 +4,7 @@ Entered at step 5, after the clarification loop settles. Decides how confidence
 
 ### 5. Score and write
 
-Apply `reference/confidence-rubric.md` in this skill's directory. Fill the meta table and §13 — **Weakest dimension** is one sentence, max 25 words, naming the gap and what closes it; the run narrative belongs only in the report, never §13. Status: `In progress` below 90%; `Ready for specification` at 90%+ **and** no open §11 question — absolute, every question changes requirements.
+Apply `reference/confidence-rubric.md` in this skill's directory. Fill the meta table and §13 — **Weakest dimension** is one sentence, max 25 words, naming the gap and what closes it; the run narrative belongs only in the report, never §13. Status: `In progress` below 90%; `Ready for specification` at 90%+ **and** no open §11 question — absolute, every question changes requirements. That exact string is load-bearing: the Specs Editor's PRD page renders its "Ready for Technical Specification" banner off it, so do not reword it and do not invent a third status.
 
 Write the file. In continue mode, update `Updated`, `Confidence`, `Status` and §13; append to §12.
 
@@ -15,6 +15,7 @@ Five lines, no more (six with an architect), each one line:
 - confidence % and status
 - what changed this run (continue mode)
 - remaining gap costing most confidence, or `none`
+- in editor mode, once the status is `Ready for specification`: `Next: sw-design-solution <prd path> --editor` — a statement of what the user runs next, never an offer, and never something this skill starts itself
 - a split recommendation, phrased as a question, only if guidelines warrant one
 - `Architect consulted: <topic> — <one-line verdict>`, only if spawned this run
 

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

@@ -21,7 +21,7 @@ Answers **how**, never **what**/**why**. Never re-litigate, question, or change
 | `specs/NNNN-slug-spec.md` | **Continue mode** — load, keep its number, advance |
 | `specs/NNNN-slug.md` (a PRD) | **New spec** — PRD is the source of truth |
 | Nothing | Ask for the PRD path |
-| `<path> --editor` | **Editor hand-off**, first reference file below |
+| `<path> --editor` | **Editor hand-off**, first reference file below. The path may be the PRD or the spec; it always resolves to `specs/NNNN-slug-spec.md`, created from the template if missing, and the session edits the spec only — the PRD is reference only, with its own session |
 | `<path> --editor-session <url> --batch <file>` | **Editor mode** — see `reference/editor-mode.md` |
 
 ## Procedure

package/skills/sw-design-solution/reference/editor-mode.md

@@ -1,16 +1,16 @@
 # Editor mode
 
-Entered when invoked as `<path> --editor-session <url> --batch <batch.json>` — a note batch, or "create tech spec" with a PRD path. Decides how the procedure differs from the terminal flow: no interactive questions, scoped re-verification, and progress emission.
+Entered when invoked as `<spec path> --editor-session <url> --batch <batch.json>` — one note batch from the page. The session's editable document is always the tech spec; the PRD is reference only. Decides how the procedure differs from the terminal flow: no interactive questions, scoped re-verification, and progress emission.
 
 Same procedure/boundary/verification/ADR rules, plus:
 
-- **Scoped.** Nothing on open. Continue mode: read the batch first, run step 3 only for touched mechanisms, edit only named blocks plus invalidated ones, re-evaluate §7 — no re-verification/new §6 for untouched ACs. Full pass only for `createSpec` or an explicit review request.
+- **Scoped.** Nothing on open. Continue mode: read the batch first, run step 3 only for touched mechanisms, edit only named blocks plus invalidated ones, re-evaluate §7 — no re-verification/new §6 for untouched ACs. Full pass only on an explicit review or draft request, **or when the spec is still the untouched skeleton §0 wrote** (no ACs in §3) — that first batch runs the complete flow, step 0.5 and version detection included.
 - **No terminal questions.** Never ask via a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`). Every ask → §6 block: `**Q-n**`, 2–4 `- [ ]` options, one `(recommended)`, agent notes `  - [<agent>] <stance>: <reason>` under the judged option. Max 6/run. Tags: `[adr] <title>` → `A: Extract` / `B: Keep`; `[gate] Open ADRs <ids>` → `A: Wait (recommended)` / `B: Override`; step-0.5's two `[gate]` titles verbatim → `A: Bootstrap first (recommended)` / `B: Proceed unverified`. Unanswered `[gate]` → *In progress*, never auto-override.
-- **Batch input.** Ticks first — a ticked question with no note is still an answer. `answer`/`[x]` tick → anchor, append Decision Log, delete block (`[adr]` sub-step 3, `[gate]` sub-step 5). `comment`/`free` → this run's briefing (block-bound `path`/`line`–`endLine`/`md`/`quote`/`hash`; verify `md` matches, fall back to `quote`; `selection` → rework only that text). `diagram` → update the graph file. *What*/*why* notes belong to the PRD. First write migrates a pre-template spec; blocks get missing options only when touched.
-- **Scoped runs.** Re-spawn architect only for an overturned/new decision, QA only for a changed test plan, `sw-product-manager` only for feasibility — together still one message; else edit/verify/anchor/log alone, name agents.
+- **Batch input.** Ticks first — a ticked question with no note is still an answer. `answer`/`[x]` tick → anchor, append Decision Log, delete block (`[adr]` sub-step 3, `[gate]` sub-step 5). `comment`/`free` → this run's briefing (block-bound `path`/`line`–`endLine`/`md`/`quote`/`hash`; verify `md` matches, fall back to `quote`; `selection` → rework only that text). `diagram` → update the graph file. *What*/*why* notes belong to the PRD: read it freely — `batch.reference.path` — as the source of truth for reconciliation, but it is **read-only** here, a separate session's document. Never write it, never anchor an answer into it, never emit against it; report the note in the reply ("this changes FR-4 — take it to the PRD session, `sw-design-requirements <prd path> --editor`") and change nothing. First write migrates a pre-template spec or §0's skeleton; blocks get missing options only when touched.
+- **Scoped runs.** Re-spawn architect only for an overturned/new decision, QA only for a changed test plan, `sw-product-manager` only for feasibility — together still one message; else edit/verify/anchor/log alone, name agents. **Light batch** — every note is an `answer` or a tick, or the batch is chat only: anchor, log, reply. No spawn and no step 3; the user is waiting on the page for what is a bookkeeping run.
 - **Preserve:** status tags (`- **AC-2** [partly] (FR-3)`, `- **Decision:** [done] …`), `Diagram:` line, §6 blocks/ticks — rewrite in place, never regenerate.
 - **Diagrams.** `specs/NNNN-slug-spec.architecture.graph.json`; run `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest diagram specs/NNNN-slug-spec.architecture.graph.json specs/NNNN-slug-spec.architecture.excalidraw`, keep §2's `Diagram:` line — never write it directly.
-- **Progress.** `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit --since <step-0.5 start> progress "<step>" --batch <id> --doc spec` before/after each step/spawn; `--since` prefixes `+m:ss`.
+- **Progress.** `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest emit --since <step-0.5 start> progress "<step>" --batch <id> --doc <spec path>` (`--doc` is the document path: it names the session, and a feature's PRD and spec are two of them) before/after each step/spawn; `--since` prefixes `+m:ss`. Keep them few and short — one line per phase, under ~60 characters, no per-tool narration. They are the page's only sign of life while a spawn runs, not a log.
 - **Report:** changed blocks; answers (Q ids → anchor); first unmet §7 criterion or `none`; status/confidence/`Open ADRs`; `Agents: <list or none>`; `Timing:`.
 
 Graph shape: `{ title, direction: "LR", groups: [{id,label}], nodes: [{id,label,type: entity|actor|service|external|event|store,group?,note?}], edges: [{from,to,label?}] }`.

package/skills/sw-design-solution/reference/pre-check-and-target.md

@@ -4,11 +4,19 @@ Entered before touching the target file. Decides how to handle `--editor`/`--edi
 
 ### 0. Editor flags
 
-`--editor` → **first action**: is the `sw-specs-editor` skill available? It is an optional add-on, installed by `sw-setup`, not part of this plugin. Available → run it on `<document path>` and stop — no PRD/spec read, no version detection, no lookup, no agent spawn. Not available → **stop here** with one line — "The Specs Editor is not installed. Run `sw-setup` to add it, or re-run without `--editor`." — and do not fall back to non-editor mode or write the spec. The Specs Editor opens the page and waits; this skill runs again (*Editor mode*) only when the user sends notes. `--editor-session` → run the procedure below under *Editor mode*, scoped to the batch.
+`--editor` → **first action**, in this order. An editor session edits **one** document and is named from its filename, so the target has to be the *spec* path and the file has to exist before the page opens.
+
+1. **Resolve to the spec path.** `…-spec.md` → that is it. `specs/NNNN-slug.md` (a PRD) → `specs/NNNN-slug-spec.md`, same `NNNN`/slug, per §1's one-spec-per-PRD rule. Anything else → stop with one line naming the two shapes.
+2. **Gate, before creating anything.** Is the `sw-specs-editor` skill available? It is an optional add-on, installed by `sw-setup`, not part of this plugin. Not available → **stop here** with one line — "The Specs Editor is not installed. Run `sw-setup` to add it, or re-run without `--editor`." — and do not fall back to non-editor mode, and do not leave a skeleton behind for a page that will never open.
+3. **Spec missing → write the skeleton.** Copy `reference/tech-spec-template.md`, section numbers and titles verbatim, every body `_TBD_`; fill only `PRD: specs/NNNN-slug.md`, `Status: In progress`, `Confidence: 0%`, `Updated: <today>`. Still no PRD/spec read, no version detection, no lookup, no agent spawn, no AC drafting — this is a deterministic file write, a file to open, not a first draft.
+4. **Hand off with the spec path** and stop.
+5. If step 3 created the file, add one line: "Created the spec skeleton at `<path>`. Send a note on the page — e.g. 'draft the spec' — to fill it."
+
+The Specs Editor opens the page and waits; this skill runs again (*Editor mode*) only when the user sends notes. The PRD is **not** part of that session: it is reference only, and business changes go back to its own session (`sw-design-requirements <prd path> --editor`). `--editor-session` → run the procedure below under *Editor mode*, scoped to the batch.
 
 ### 0.5 Pre-check
 
-Once, before touching the target file. Note the ISO start time (`date -u +%Y-%m-%dT%H:%M:%SZ`) — step 8's Timing line and editor progress prefixes use it.
+Once, before touching the target file. Note the ISO start time (`date -u +%Y-%m-%dT%H:%M:%SZ`) — step 8's Timing line and editor progress prefixes use it. In editor mode it runs on the **first batch**, not on the hand-off: §0's skeleton write precedes it and reads nothing.
 
 - **Check:** invoke `sw-setup` once; rows vendor/ and KB MCP must be ticked. Never proceed past an unticked row without the user's answer.
 - **Terminal, on failure:** the setup skill's own question settles it — declined → proceed with `(unverified — vendor/ not installed)` / `(unverified — KB unavailable)`, blocks readiness, as before.
@@ -16,4 +24,4 @@ Once, before touching the target file. Note the ISO start time (`date -u +%Y-%m-
 
 ### 1. Establish the target file
 
-New spec: `specs/NNNN-slug-spec.md`, reusing the PRD's `NNNN`/`slug` — one per PRD. Create from `reference/tech-spec-template.md` in this skill's directory, section numbers/titles unchanged. Header: PRD path, `shopware/core` version + KB directory, plugin (`custom/plugins/<Name>`, `<Vendor>\<Name>`, existing domain plugin or new one named after the feature's domain). Plugin never `_TBD_` at readiness. Continue mode: keep path, never renumber/duplicate; pre-template spec → migrate this run, say so in the report.
+New spec: `specs/NNNN-slug-spec.md`, reusing the PRD's `NNNN`/`slug` — one per PRD. Create from `reference/tech-spec-template.md` in this skill's directory, section numbers/titles unchanged. In editor mode §0 already established (and may have skeletoned) this file; the first batch migrates a skeleton exactly as it migrates a pre-template spec. Header: PRD path, `shopware/core` version + KB directory, plugin (`custom/plugins/<Name>`, `<Vendor>\<Name>`, existing domain plugin or new one named after the feature's domain). Plugin never `_TBD_` at readiness. Continue mode: keep path, never renumber/duplicate; pre-template spec → migrate this run, say so in the report.