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

package/lib/render.mjs

@@ -0,0 +1,365 @@
+// The human view of a result body.
+//
+// Every command still builds exactly the same JSON object it always did — that
+// object is the model. This module is the view: pure `body -> string`
+// functions, no I/O, no process state, so the whole renderer is testable
+// without a terminal and without running an install.
+//
+// Design rules, in the order they matter:
+//
+//   1. Nothing changed is ONE line. A file count is not news to a human, and
+//      "274 unchanged" reads like a failure to someone who typed `install`.
+//   2. Something changed is reported per agent, in the user's vocabulary —
+//      skills and sub-agents by name, config files by path.
+//   3. Conflicts, drift, manual steps and failures are never collapsed into a
+//      count: those are the only cases the user has to act on, so each one
+//      names its file and its remedy.
+//   4. Never name an agent this project has not installed. A Claude Code user
+//      is not told about Codex, Cursor or Copilot.
+//
+// Zero dependencies: bare ANSI, and only when the caller says the stream is a
+// terminal.
+
+/** Human labels for the four supported coding agents. */
+export const LABELS = {
+  'claude-code': 'Claude Code',
+  codex: 'Codex',
+  copilot: 'GitHub Copilot',
+  cursor: 'Cursor',
+};
+
+/** What each agent needs before it reads the configuration we just wrote. */
+export const RESTART = {
+  'claude-code': 'Restart Claude Code, or run `/mcp` in the running session',
+  codex: 'Restart `codex` — .codex/config.toml is read once at startup',
+  copilot: 'Reload the VS Code window (Developer: Reload Window) for .vscode/mcp.json',
+  cursor: 'Restart Cursor so it re-reads .cursor/mcp.json',
+};
+
+function label(id) {
+  return LABELS[id] ?? id;
+}
+
+// ------------------------------------------------------------------ styling
+
+const CODES = { bold: '1', dim: '2', red: '31', green: '32', yellow: '33' };
+
+/** A theme whose functions are the identity when colour is off. */
+function theme(color) {
+  const wrap = (code) => (color ? (s) => `\x1b[${code}m${s}\x1b[0m` : (s) => s);
+  const t = {};
+  for (const [name, code] of Object.entries(CODES)) t[name] = wrap(code);
+  return t;
+}
+
+// --------------------------------------------------------------- primitives
+
+const MAX_NAMES = 6;
+
+/** "a, b, c and 4 more" — a list a person reads, not a dump. */
+function names(list) {
+  const max = MAX_NAMES;
+  const all = [...list];
+  if (all.length <= max) return all.join(', ');
+  return `${all.slice(0, max).join(', ')} and ${all.length - max} more`;
+}
+
+function plural(n, one, many = `${one}s`) {
+  return `${n} ${n === 1 ? one : many}`;
+}
+
+/**
+ * What a target is, in the words a user thinks in. A skill is one thing to
+ * them even though it is a directory of files; a config file is its path.
+ */
+export function classify(target) {
+  const skill = /(?:^|\/)skills\/([^/]+)\//.exec(target);
+  if (skill) return { kind: 'skill', name: skill[1] };
+  const agent = /(?:^|\/)agents\/([^/]+)$/.exec(target);
+  if (agent) return { kind: 'agent', name: agent[1].replace(/(\.agent)?\.(md|toml)$/, '') };
+  return { kind: 'file', name: target };
+}
+
+const VERBS = {
+  create: 'added', created: 'added',
+  update: 'updated', updated: 'updated',
+  removed: 'removed', reverted: 'reverted',
+};
+
+const SHARED = '__shared__';
+
+/**
+ * Group the actions in `states` by agent, then by verb, then by what kind of
+ * thing they are. Returns `[{ id, buckets: Map<verb, {skills, agents, files}> }]`
+ * in the order the agents first appear.
+ */
+export function groupChanges(actions = [], states) {
+  const wanted = new Set(states);
+  const order = [];
+  const groups = new Map();
+  for (const action of actions) {
+    if (!wanted.has(action.state)) continue;
+    const id = !action.host || action.host === 'shared' ? SHARED : action.host;
+    if (!groups.has(id)) { groups.set(id, new Map()); order.push(id); }
+    const buckets = groups.get(id);
+    const verb = VERBS[action.state] ?? action.state;
+    if (!buckets.has(verb)) buckets.set(verb, { skill: new Set(), agent: new Set(), file: new Set() });
+    const bucket = buckets.get(verb);
+    const { kind, name } = classify(action.target);
+    // Several actions can target one config file (one per JSON pointer);
+    // the user changed one file, so it is named once.
+    bucket[kind].add(name);
+    (bucket.targets ??= []).push(action.target);
+  }
+  return order.map((id) => ({ id, buckets: groups.get(id) }));
+}
+
+function bucketLines(verb, bucket, { verbose }, t) {
+  const lines = [];
+  if (verbose) {
+    for (const target of bucket.targets ?? []) lines.push(`    ${t.dim(verb)} ${target}`);
+    return lines;
+  }
+  if (bucket.skill.size) lines.push(`    ${verb} ${plural(bucket.skill.size, 'skill')}: ${names(bucket.skill)}`);
+  if (bucket.agent.size) lines.push(`    ${verb} ${plural(bucket.agent.size, 'sub-agent')}: ${names(bucket.agent)}`);
+  if (bucket.file.size) lines.push(`    ${verb} ${names(bucket.file)}`);
+  return lines;
+}
+
+function groupLines(groups, opts, t) {
+  const lines = [];
+  for (const { id, buckets } of groups) {
+    lines.push(`  ${t.bold(id === SHARED ? 'Project files' : label(id))}`);
+    for (const [verb, bucket] of buckets) lines.push(...bucketLines(verb, bucket, opts, t));
+  }
+  return lines;
+}
+
+// ------------------------------------------------------------------- issues
+
+/** Everything the user has to act on, flattened into one shape. */
+function issues(body) {
+  const found = [];
+  for (const a of body.actions ?? []) {
+    if (a.state === 'conflict' || a.state === 'drift' || a.state === 'failed') {
+      found.push({ kind: a.state, target: a.target, reason: a.reason, remedy: a.remedy });
+    }
+  }
+  for (const d of body.drift ?? []) {
+    found.push({ kind: d.state ?? 'drift', target: d.target, reason: d.reason, remedy: d.remedy });
+  }
+  for (const m of body.manual ?? []) {
+    found.push({ kind: 'manual', target: m.target ?? m.file, reason: m.reason, remedy: m.remedy });
+  }
+  for (const e of body.errors ?? []) {
+    found.push({ kind: 'failed', target: e.target ?? label(e.host), reason: e.error });
+  }
+  // The same file can reach us from both `actions` and `drift`; say it once.
+  const seen = new Set();
+  return found.filter((i) => {
+    const key = `${i.kind}:${i.target}`;
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+const ISSUE_TITLE = {
+  conflict: 'conflict', drift: 'edited since install',
+  manual: 'manual step', failed: 'failed',
+};
+
+function issueLines(list, t) {
+  if (!list.length) return [];
+  const paint = (kind) => (kind === 'drift' || kind === 'manual' ? t.yellow : t.red);
+  const lines = [`  ${t.bold('Needs your attention')}`];
+  for (const i of list) {
+    lines.push(`    ${paint(i.kind)(ISSUE_TITLE[i.kind] ?? i.kind)}  ${i.target}`);
+    if (i.reason) lines.push(`      ${i.reason}`);
+    if (i.remedy) lines.push(`      ${t.dim('fix:')} ${i.remedy}`);
+  }
+  return lines;
+}
+
+// ------------------------------------------------------------------ restart
+
+function restartLines(body, changedIds, t) {
+  const ids = changedIds.length
+    ? changedIds
+    : (body.agents ?? []).map((a) => a.id).filter((id) => RESTART[id]);
+  const uniq = [...new Set(ids)].filter((id) => RESTART[id]);
+  return uniq.map((id) => `  ${t.dim('→')} ${RESTART[id]}`);
+}
+
+// ------------------------------------------------------------ apply/install
+
+function renderApply(body, opts, t) {
+  const s = body.summary ?? {};
+  const changed = (s.created ?? 0) + (s.updated ?? 0);
+  const problems = issues(body);
+  const migrated = body.migrated ?? [];
+
+  if (changed === 0 && problems.length === 0 && migrated.length === 0) {
+    // ONE line. Nothing changed means nothing to restart and nothing to read.
+    return `${t.green('✓')} Shopware agentic harness: already up to date — nothing to change.\n`;
+  }
+
+  const groups = groupChanges(body.actions, ['created', 'updated']);
+  const changedIds = groups.map((g) => g.id).filter((id) => id !== SHARED);
+  const verb = (s.updated ?? 0) === 0 ? 'Installed' : 'Updated';
+  const lines = [];
+  if (changed) lines.push(`${t.green('✓')} ${verb} the Shopware agentic harness.`);
+  else if (problems.length) lines.push(`${t.yellow('!')} Nothing was written — see below.`);
+  // Only tidy-up ran: the install itself was already current.
+  else lines.push(`${t.green('✓')} Shopware agentic harness: already up to date.`);
+  if (groups.length) {
+    lines.push('');
+    lines.push(...groupLines(groups, opts, t));
+  }
+  if (migrated.length) {
+    lines.push('');
+    for (const m of migrated) lines.push(`  ${t.dim('·')} ${m.target}: ${m.detail}`);
+  }
+  if (problems.length) {
+    lines.push('');
+    lines.push(...issueLines(problems, t));
+  }
+  if (changed) {
+    lines.push('');
+    lines.push(...restartLines(body, changedIds, t));
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// -------------------------------------------------------------------- plan
+
+function renderPlan(body, opts, t) {
+  const s = body.summary ?? {};
+  const changes = (s.create ?? 0) + (s.update ?? 0);
+  const problems = issues(body);
+  if (changes === 0 && problems.length === 0) {
+    return `${t.green('✓')} Nothing to do — every target is already up to date.\n`;
+  }
+  const lines = [];
+  // `plan` with nothing selected previews every supported agent. Say so, or
+  // the list silently names agents this project never installed.
+  if (/previews all four/i.test(body.next_step ?? '')) {
+    lines.push(t.dim('No agent selected and no recorded install — previewing every supported agent.'));
+  }
+  lines.push(`${plural(changes, 'change')} would be made. Nothing was written.`);
+  const groups = groupChanges(body.actions, ['create', 'update']);
+  if (groups.length) {
+    lines.push('');
+    lines.push(...groupLines(groups, opts, t));
+  }
+  if (problems.length) {
+    lines.push('');
+    lines.push(...issueLines(problems, t));
+  }
+  if (changes) {
+    lines.push('');
+    lines.push(`  ${t.dim('→')} Run \`sw-ecosystem-agentic-harness apply --yes\` to perform them.`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// ------------------------------------------------------------------ status
+
+/** An agent is only ours to talk about once it has actually been installed. */
+function installedAgents(body) {
+  return (body.agents ?? []).filter((a) => ['ok', 'drift', 'conflict'].includes(a.state));
+}
+
+function renderStatus(body, opts, t) {
+  const mine = installedAgents(body);
+  const problems = issues(body);
+
+  if (!mine.length) {
+    return `${t.yellow('!')} No coding agent is set up in this project yet.\n`
+      + `  ${t.dim('→')} ${body.help?.[0] ?? 'sw-ecosystem-agentic-harness install'}\n`;
+  }
+
+  const worst = ['conflict', 'drift'].find((state) => mine.some((a) => a.state === state));
+  const lines = [];
+  lines.push(worst
+    ? `${t.yellow('!')} Shopware agentic harness ${body.installed_version ?? body.version} — ${plural(problems.length, 'item')} ${problems.length === 1 ? 'needs' : 'need'} attention.`
+    : `${t.green('✓')} Shopware agentic harness ${body.installed_version ?? body.version} — installed and up to date.`);
+
+  for (const a of mine) {
+    const counts = [];
+    if (a.installed?.skills) counts.push(plural(a.installed.skills, 'skill'));
+    if (a.installed?.agents) counts.push(plural(a.installed.agents, 'sub-agent'));
+    lines.push(`  ${t.bold(label(a.id))}${counts.length ? `: ${counts.join(', ')}` : ''}`);
+    for (const note of a.notes ?? []) lines.push(`    ${t.dim(note)}`);
+  }
+
+  if (problems.length) {
+    lines.push('');
+    lines.push(...issueLines(problems, t));
+  }
+
+  return `${lines.join('\n')}\n`;
+}
+
+// --------------------------------------------------------------- uninstall
+
+function renderUninstall(body, opts, t) {
+  const s = body.summary ?? {};
+  const gone = (s.removed ?? 0) + (s.reverted ?? 0);
+  if (gone === 0 && !(body.kept ?? []).length) {
+    return `${t.green('✓')} Nothing to remove — this project has no recorded install.\n`;
+  }
+  const lines = [`${t.green('✓')} Removed the Shopware agentic harness — `
+    + `${plural(s.removed ?? 0, 'file')} removed, ${plural(s.reverted ?? 0, 'config block')} reverted.`];
+  if ((body.kept ?? []).length) {
+    lines.push('');
+    lines.push(`  ${t.bold('Kept, because you edited them')}`);
+    for (const k of body.kept) lines.push(`    ${k.target}`);
+  }
+  lines.push('');
+  lines.push(`  ${t.dim('→')} Restart your coding agent(s) so they drop the removed configuration.`);
+  return `${lines.join('\n')}\n`;
+}
+
+// ------------------------------------------------------------------ errors
+
+function renderProblem(body, opts, t) {
+  const lines = [`${t.red('✗')} ${body.error}`];
+  for (const e of body.errors ?? []) {
+    lines.push(`    ${e.target ?? label(e.host)} — ${e.error}`);
+  }
+  const problems = issues({ ...body, errors: [] });
+  if (problems.length) {
+    lines.push('');
+    lines.push(...issueLines(problems, t));
+  }
+  if (body.help?.length) {
+    lines.push('');
+    lines.push(`  ${t.bold('Try')}`);
+    for (const h of body.help) lines.push(`    ${h}`);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+// ---------------------------------------------------------------- dispatch
+
+const RENDERERS = {
+  install: renderApply,
+  apply: renderApply,
+  plan: renderPlan,
+  status: renderStatus,
+  uninstall: renderUninstall,
+};
+
+/**
+ * `body` is the exact object `--json` prints. `opts.verbose` prints the
+ * per-file detail the JSON carries; `opts.color` enables ANSI.
+ */
+export function render(body, opts = {}) {
+  if (!body || typeof body !== 'object') return '';
+  const t = theme(opts.color === true);
+  if (body.ok === false) return renderProblem(body, opts, t);
+  const renderer = RENDERERS[body.command];
+  if (!renderer) return `${body.next_step ?? ''}\n`;
+  return renderer(body, opts, t);
+}

package/package.json

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

@@ -3,7 +3,7 @@ name: sw-design-requirements
 description: Turn a briefing — chat text or a file, covering one or more features — into a lean, business-only PRD stored as specs/NNNN-slug.md. Runs an interactive clarification loop for the requirement gaps and inconsistencies that actually change the requirements, then scores a weighted confidence %. Use when asked to write, draft, refine, continue, or score a PRD / requirements doc / feature brief for this Shopware project. Never writes a tech spec or answers architecture questions — that's sw-design-solution.
 when_to_use: Trigger phrases — "write a PRD", "draft requirements", "turn this brief into a PRD", "continue PRD 0003", "is this PRD ready for specification", "raise the confidence on this PRD", "requirements for <feature>".
 argument-hint: '[file-path | briefing text | specs/NNNN-slug.md to continue] [--editor]'
-allowed-tools: Read Write Edit Glob Grep AskUserQuestion Agent Skill Bash(ls *) Bash(mkdir -p specs) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@0.1.0 *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+allowed-tools: Read Write Edit Glob Grep AskUserQuestion Agent Skill Bash(ls *) Bash(mkdir -p specs) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@latest *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 
 ---
 

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

@@ -2,7 +2,7 @@
 
 Runs before the `--editor` hand-off (step 0). The Specs Editor is an **optional** add-on: it is not part of this plugin, and a host that never installed it is a supported, normal setup. `sw-setup` offers to install it.
 
-What is checked is the **skill**, `sw-specs-editor`, because that is what `sw-setup` installs and what the hand-off calls. The skill brings the CLI with it — it invokes `npx -y @execuro-sw-ecosystem/sw-specs-editor@0.1.0`, which fetches the package on first use.
+What is checked is the **skill**, `sw-specs-editor`, because that is what `sw-setup` installs and what the hand-off calls. The skill brings the CLI with it — it invokes `npx -y @execuro-sw-ecosystem/sw-specs-editor@latest`, which fetches the package on first use.
 
 Check: is the `sw-specs-editor` skill available in this session?
 

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

@@ -8,8 +8,8 @@ Invoked as `<path> --editor-session <url> --batch <batch.json>` — one note bat
 - **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.
 - **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@0.1.0 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@0.1.0 emit progress "<step>" --batch <id> --doc prd`.
+- **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`.
 - **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-solution/SKILL.md

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

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

@@ -9,8 +9,8 @@ Same procedure/boundary/verification/ADR rules, plus:
 - **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.
 - **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@0.1.0 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@0.1.0 emit --since <step-0.5 start> progress "<step>" --batch <id> --doc spec` before/after each step/spawn; `--since` prefixes `+m:ss`.
+- **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`.
 - **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-discover-tender/SKILL.md

@@ -3,7 +3,7 @@ name: sw-discover-tender
 description: Analyse a client tender (RFP, RFI or RFQ) for a Shopware 6 project into one markdown sidecar, <source basename>-analysis.md. Every requirement row gets a class against the installed Shopware version (stock / config / plugin / custom), a three-point person-day estimate, one line of mechanism and proposed scope-lock assumptions the partner accepts by ticking checkboxes — in the file or on the Tender Discovery Tool page (`--editor`); the next run reconciles the ticks, dissolves answered questions and re-estimates. At Ready to submit it exports one CSV per client table with compliance, comment and effort filled in the client's columns. Scope and PD only — never costs, prices, licence fees or budgets. Never designs the solution — that's sw-design-solution.
 when_to_use: Trigger phrases — "scope this RFP", "analyse the tender", "answer the RFI", "discover RFP 0001", "continue RFP 0001", "reconcile RFP 0001", "export the response for RFP 0001", "is RFP 0001 ready to submit", "open RFP 0001 in the browser", "open the tender tool", "sw-discover-tender specs/rfp-0001-x-analysis.md --editor".
 argument-hint: '[tender file or folder of exports (.xlsx|.md|.txt|.csv|.pdf) | specs/rfp-NNNN-slug-analysis.md to continue] [--editor] [--batch <n|all>] [--export]'
-allowed-tools: Read Write Edit Glob Grep Agent AskUserQuestion Bash(ls *) Bash(mkdir -p specs) Bash(mkdir -p specs/.rfp *) Bash(shasum -a 256 *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 *) Bash(open *) Bash(xdg-open *) Bash(tail *) Bash(grep *) Bash(printf *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
+allowed-tools: Read Write Edit Glob Grep Agent AskUserQuestion Bash(ls *) Bash(mkdir -p specs) Bash(mkdir -p specs/.rfp *) Bash(shasum -a 256 *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest *) Bash(open *) Bash(xdg-open *) Bash(tail *) Bash(grep *) Bash(printf *) mcp__ShopwareDevKnowledgeBase__list_docs mcp__ShopwareDevKnowledgeBase__grep_docs mcp__ShopwareDevKnowledgeBase__read_doc mcp__ShopwareDevKnowledgeBase__kb_status
 ---
 
 # sw-discover-tender
@@ -24,7 +24,7 @@ One markdown sidecar per tender, `<source basename>-analysis.md`: class, three-p
 | Argument | Behaviour |
 | --- | --- |
 | `.md` / `.txt` / `.csv` / `.pdf`, or a folder of such exports | New tender: extract, analyse, write `<basename>-analysis.md` next to the source |
-| `.xlsx` | Import first, per `reference/procedure.md` step 1 ".xlsx import": `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 import` proposes a mapping (install gate: `reference/editor-session.md` §0), confirmed via `--editor` or a one-line yes/no, before the normalised source and the analysis are set. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops |
+| `.xlsx` | Import first, per `reference/procedure.md` step 1 ".xlsx import": `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest import` proposes a mapping (install gate: `reference/editor-session.md` §0), confirmed via `--editor` or a one-line yes/no, before the normalised source and the analysis are set. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops |
 | `.docx` | Stop. One line: export every requirement table as CSV UTF-8 (or paste it as markdown tables, header row kept) and rerun with that file or folder |
 | `*-analysis.md` | Continue: reconcile, advance, rewrite in place |
 | `--export`, or "export the response for RFP NNNN" | Continue, then run step 9 if the gate holds |

package/skills/sw-discover-tender/reference/editor-session.md

@@ -5,7 +5,7 @@ The Tender Discovery Tool: a local live page for one analysis document. The skil
 **The protocol is not in this file.** Run
 
 ```
-npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 guide
+npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest guide
 ```
 
 and follow it: it is the single source for the xlsx import, start, the batch kinds, poll, emit, redelivery and close, and every command ends with a `next_step:` line. An installed copy of any of that goes stale against a newer CLI. This file adds only what `guide` cannot know — the install gate, the row-batch setting, which opening batch to post, the subagent brief, the follow-up queueing grammar and the close report.
@@ -58,7 +58,7 @@ Invoke it with the Skill tool: skill "sw-discover-tender", args "<analysis path>
 Append the session's row-batch setting to the args when it is not the default: <--batch n | --batch all>.
 If the Skill tool is not available to you, read the SKILL.md of the `sw-discover-tender` skill and follow it exactly, including its "Editor mode" section.
 Rules: never ask the user a question with a structured question tool (Claude Code: `AskUserQuestion`; Codex: `request_user_input`); every gap becomes a §5 block with options; emit progress with
-  npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 emit progress "<step>" --batch <id>
+  npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest emit progress "<step>" --batch <id>
   before each procedure step and before/after each agent wave; never change a [x] or [-] except by reconciling it; keep every [ ] line whose
   Evidence / risk or Risk to says "partner"; frozen accepted/rejected lines stay byte-identical; never edit the client's file.
 Context — last chat entries (newest last):
@@ -111,5 +111,5 @@ Invoked by the editor session (`reference/editor-session.md` in this skill's dir
 - **Notes.** `comment` notes carry `block`, `blockKind`, `path` (section breadcrumb), `line`–`endLine`, `md` (the block's source line), `quote`, `hash` and sometimes `selection` (the exact text the user highlighted). Open the file at that range under that path, confirm the text matches `md`, fall back to searching for `quote` when lines shifted. By `blockKind`: `req` → the note questions the class, mechanism or estimate: re-spawn the architect for that row only and rewrite the `req` line; `assume` / `global` → rewrite the statement as a new `[ ]` line (a frozen line is never edited; a proposed line may be replaced in place), or adjust `PD saved` when the note is about the figure; `clarify` → the decision text; `question` → reword or re-option the block (keep its id); `section` / `paragraph` / `row` → that text. `free` notes and `chat` are the briefing for the run. No PD figure ever comes from the page: a note asking for a different number is an architect question, not a hand edit.
 - **A note on a row still `queued` or `analysing`** is not an immediate re-spawn: carry it into that row's own estimate batch and answer it there.
 - **Preserve on every write.** Frozen `accepted <date>` / `rejected <date>` lines byte-identical; every `[x]` / `[-]` untouched except by reconciling it; partner-proposed `[ ]` lines; `X-n` exclusions the page added; §1.1, §1.2, §8, §9 and the nine section headings; the frontmatter block. Rewrite lines in place, never regenerate from the template. Every write must leave the document parseable — the page re-renders on each one.
-- **Progress.** `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 emit progress "<step>" --batch <id>` before each procedure step and before and after each spawn wave; the page shows it. Row status carries the rest: `queued` → `analysing` → `estimated`.
+- **Progress.** `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest emit progress "<step>" --batch <id>` before each procedure step and before and after each spawn wave; the page shows it. Row status carries the rest: `queued` → `analysing` → `estimated`.
 - **Report.** The 8-line report of step 8 with its `next:` line (plus the 3 export lines); the editor posts it to the page. Never paste the document into the report.

package/skills/sw-discover-tender/reference/procedure.md

@@ -14,7 +14,7 @@
 
 `ls specs`. Keep `rfp-NNNN-` from the input name; else `NNNN` = highest existing + 1, zero-padded, slug = kebab-case `<client>-<project>`. An xlsx is imported and its mapping confirmed first (below). `shasum -a 256` every source file into frontmatter `source`; for an xlsx, the workbook, `import-map.json` and every CSV. Continue mode: keep path, number and slug; never renumber, never a second file for the same tender.
 
-**.xlsx import.** Install gate first, per `reference/editor-session.md` §0: the `sw-tender-discovery-tool` skill must be installed; missing → stop, do not import. `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 import --source <file>` reads the workbook (hidden and `_` sheets never leave it) and proposes a mapping — which tabs are requirement tables, where each header sits, what each column means, which tokens the dropdowns allow. **With `--editor`** the user confirms it on the steering screen. **Without it**, print the proposed table the command listed, ask the user in one line whether it is right, and on a yes run `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 import --source <file> --map --accept-proposed`; if a tab or a column is wrong, say so and rerun with `--editor`. Either way the confirmed `import-map.json` and the normalised `<source dir>/<basename>/<pos>-<sheet-slug>.csv` are then the source, and the analysis lands next to the workbook. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops.
+**.xlsx import.** Install gate first, per `reference/editor-session.md` §0: the `sw-tender-discovery-tool` skill must be installed; missing → stop, do not import. `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest import --source <file>` reads the workbook (hidden and `_` sheets never leave it) and proposes a mapping — which tabs are requirement tables, where each header sits, what each column means, which tokens the dropdowns allow. **With `--editor`** the user confirms it on the steering screen. **Without it**, print the proposed table the command listed, ask the user in one line whether it is right, and on a yes run `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest import --source <file> --map --accept-proposed`; if a tab or a column is wrong, say so and rerun with `--editor`. Either way the confirmed `import-map.json` and the normalised `<source dir>/<basename>/<pos>-<sheet-slug>.csv` are then the source, and the analysis lands next to the workbook. A refusal (encrypted, `.xls`, `.xlsb`) is relayed verbatim and the run stops.
 
 ### 2. Reconcile — first step of every continue run, before any spawn
 
@@ -93,6 +93,6 @@ When the gate below holds, one more line: "Generate the response CSV?" Then end.
 - **Assemble and check, delegated**: one `sw-tender-editor` per client table, all in one message, cap 10, brief `§ASSEMBLE`. Each concatenates its cluster CSVs behind the client's header row into `<source basename>-response-<n>-<table-slug>.csv` (`<n>` and slug from the Source map) and runs the file checks: row count and id sequence equal the source table; header equals the client's; every compliance value in the allowed list; every effort cell a number, or empty with the blocked comment; no `A-`, `CQ-`, `Q-`, `RC-`, `.a`, `.c`, `PD saved`, `EUR`, `€`; no proposed or rejected assumption text; constant column count. Any failure → the agent deletes the file and returns the failing check. The orchestrator never reads the CSVs.
 - **Check the sums** itself, from the returned per-table effort sums: they must equal §2 per priority. Mismatch → delete the files, report the check.
 - **Write back.** Frontmatter `export: {date, files, source_sha256, stale: false}`; one `C-n`: `Response exported: <files> files, <rows> rows, Must <n> PD`.
-- **Workbook copy.** After every response CSV passes its checks, run `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@0.1.0 export --xlsx --source <file>`: it writes `<source basename>-response.xlsx`, a copy of the client's own workbook with compliance, comment and effort filled in from those CSVs, styles and dropdowns intact. The client's original is never written. Only for an xlsx tender with a confirmed mapping; a CSV/markdown tender stops at the CSVs.
+- **Workbook copy.** After every response CSV passes its checks, run `npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest export --xlsx --source <file>`: it writes `<source basename>-response.xlsx`, a copy of the client's own workbook with compliance, comment and effort filled in from those CSVs, styles and dropdowns intact. The client's original is never written. Only for an xlsx tender with a confirmed mapping; a CSV/markdown tender stops at the CSVs.
 - **Report** three lines: files with row counts · Must / Should / Could as exported · checks passed or the failing check.
 - Same analysis and same source give byte-identical files.

package/skills/sw-setup/SKILL.md

@@ -1,8 +1,8 @@
 ---
 name: sw-setup
-description: Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki, `.gitignore` and whether the SW AH npm packages are current, plus the installer CLI's own configuration/drift status. Stops when every row is ticked. When rows are missing, asks one yes/no question and delegates the fix to the installer CLI. Use when asked to set up the project, check if the environment is ready, or bootstrap the tests. Never designs, implements or verifies a feature itself — that's sw-design-solution, sw-implement-feature and sw-verify-feature, which call this skill first. Never writes a host configuration file itself — that's the installer CLI.
+description: Print one environment-readiness table for the project's development/test setup — vendor/, Node, the editor CLIs, shopware-cli, the KB MCP, the acceptance-test project, Playwright browsers, its .env, per-plugin test scaffolding, the project wiki, `.gitignore` and whether the SW AH npm packages are current, plus the installer CLI's own configuration/drift status. Stops when every row is ticked. When rows are missing, asks one yes/no question and delegates the fix to the installer CLI. Use when asked to set up the project, check if the environment is ready, or bootstrap the tests. Never designs, implements or verifies a feature itself — that's sw-design-solution, sw-implement-feature and sw-verify-feature, which call this skill first. Never writes a coding agent's configuration file itself — that's the installer CLI.
 when_to_use: Trigger phrases — "set up the project", "is the environment ready", "bootstrap the tests", "sw-setup".
-allowed-tools: Read Glob Grep AskUserQuestion Skill Bash mcp__ShopwareDevKnowledgeBase__kb_status Bash(npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest *)
+allowed-tools: Read Glob Grep AskUserQuestion Skill Bash mcp__ShopwareDevKnowledgeBase__kb_status Bash(npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest *) Bash(npx -y @execuro-sw-ecosystem/sw-specs-editor@latest *) Bash(npx -y @execuro-sw-ecosystem/sw-tender-discovery-tool@latest *)
 ---
 
 # sw-setup
@@ -40,25 +40,27 @@ table from this run's output — it does not re-run `sw-setup`'s checks.
 Run:
 
 ```
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest status --json
 ```
 
-It prints one JSON object (`ok`, `next_step`, `help`, and its own
-`hosts[]`/`drift[]` configuration state). Alongside it, run every
+`--json` is mandatory for every call this skill makes: without it the CLI
+prints a human summary, not the object below. It prints one JSON object
+(`ok`, `next_step`, `help`, and its own `agents[]`/`drift[]` configuration
+state). Alongside it, run every
 environment row's check from `reference/rows.md` in this skill's directory —
 read-only, seconds each: file/directory existence, one version command, one
-`kb_status` call, three `npm view` registry lookups (Package updates row) —
-the one part of step 1 that touches the network, so it is the slow part.
+`kb_status` call, one `npm view` registry lookup (Package updates row) — the
+one part of step 1 that touches the network, so it is the slow part.
 Never write, never install, never ask a question in this step.
 
 Print one checkbox list, one line per row — the environment rows first, then
-one line per configuration item the CLI's `hosts[]`/`drift[]` reports:
+one line per configuration item the CLI's `agents[]`/`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
+- [-] Visual editors (optional) — Specs Editor installed, Tender tool declined
 - [x] shopware-cli — 0.16.10
 - [x] KB MCP — platform: implemented
 - [ ] Acceptance-test project — tests/acceptance/ missing
@@ -66,7 +68,7 @@ one line per configuration item the CLI's `hosts[]`/`drift[]` reports:
 - [ ] ATS env — tests/acceptance/.env missing
 - [x] Plugin tests — AhCheckout: phpunit + jest ok
 - [ ] Project wiki — docs/project-wiki/ missing
-- [ ] Package updates — harness 0.1.0 → 0.1.3, Specs Editor not installed
+- [ ] Package updates — harness 0.1.0 → 0.1.3
 - [ ] Installer config — .mcp.json entry: drift (from CLI status)
 ```
 
@@ -88,7 +90,7 @@ For a missing/drifted configuration row, do not research or plan the fix
 yourself — the CLI's `plan` command already has it:
 
 ```
-npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest plan
+npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest plan --json
 ```
 
 List the concrete steps in plain words: environment-row fixes in order
@@ -104,7 +106,7 @@ if you have one (Claude Code: `AskUserQuestion`; Codex: `request_user_input`,
 which is non-blocking outside Plan mode — so end the turn after asking).
 Options:
 - **Yes, run it** — run the environment-row fixes in order, then
-  `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest apply --yes`
+  `npx -y @execuro-sw-ecosystem/sw-ecosystem-agentic-harness@latest apply --yes --json`
   for the configuration changes, then re-run step 1 and print the final table.
 - **No, stop** — stop; the table from step 1 is already on screen.
 
@@ -124,11 +126,11 @@ Options:
   the corpus ships already built inside the
   `@execuro-sw-ecosystem/sw-dev-knowledge-base-mcp` package. If `platform` is
   not `implemented`, the fix is to check the registration (re-run the
-  installer CLI's `apply --yes`) or update that package — never build a
+  installer CLI's `apply --yes --json`) or update that package — never build a
   corpus here. Neither is replicated in this skill.
-- This skill never writes a host configuration file itself (`.mcp.json`,
-  permission grants, `.gitignore` lines). Every such write goes through the
-  installer CLI's `apply --yes`, run only after the user's yes.
+- This skill never writes a coding agent's configuration file itself
+  (`.mcp.json`, permission grants, `.gitignore` lines). Every such write goes
+  through the installer CLI's `apply --yes --json`, after the user's yes.
 
 ### 5. Report
 
@@ -144,6 +146,6 @@ line:
 
 `reference/rows.md` in this skill's directory — the twelve environment rows:
 check command(s), what "ticked" means, the fix steps verbatim from the
-guideline, and which skills the row blocks. Host configuration state (what
+guideline, and which skills the row blocks. Agent configuration state (what
 gets installed into `.mcp.json`, permissions, `.gitignore`) is not in this
 file — it comes from the installer CLI's `status`/`plan`/`apply` output.