@givolt/i3-composer-agent 2.2.2 → 2.3.0

package/scripts/validate-reference-links-test.js

@@ -0,0 +1,513 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+const { afterEach, test } = require('node:test');
+
+const VALIDATOR = path.join(__dirname, 'validate-reference-links.js');
+const sandboxes = [];
+
+function makeSandbox() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-skills-validate-reference-links-test-'));
+  const scriptsDir = path.join(root, 'scripts');
+  fs.mkdirSync(scriptsDir, { recursive: true });
+  fs.copyFileSync(VALIDATOR, path.join(scriptsDir, 'validate-reference-links.js'));
+  fs.mkdirSync(path.join(scriptsDir, 'lib'));
+  fs.copyFileSync(path.join(__dirname, 'lib', 'skill-lint.js'), path.join(scriptsDir, 'lib', 'skill-lint.js'));
+  sandboxes.push(root);
+  return root;
+}
+
+function writeFile(root, relativePath, content) {
+  const file = path.join(root, relativePath);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+}
+
+function run(root) {
+  return spawnSync(process.execPath, [path.join(root, 'scripts', 'validate-reference-links.js')], {
+    cwd: root,
+    encoding: 'utf8',
+  });
+}
+
+afterEach(() => {
+  for (const root of sandboxes.splice(0)) {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+});
+
+test('passes when a skill reaches the shared checklist two levels up', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
+  writeFile(
+    root,
+    'skills/i3-using-agent-skills/SKILL.md',
+    'See `../../references/definition-of-done.md`.\n'
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('fails when a skill links the shared checklist as if it were colocated', () => {
+  // The regression: references/ lives at the repo root, but the link is
+  // resolved from skills/<name>/, so it points two levels too deep.
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
+  writeFile(
+    root,
+    'skills/i3-using-agent-skills/SKILL.md',
+    'See `references/definition-of-done.md`.\n'
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+  assert.match(
+    result.stdout,
+    /L1: references\/definition-of-done\.md — resolves to skills\/i3-using-agent-skills\/references\/definition-of-done\.md/
+  );
+  assert.match(result.stdout, /use `\.\.\/\.\.\/references\/<file>\.md`/);
+});
+
+test('checks markdown link syntax, not just backtick mentions', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
+  writeFile(root, 'skills/i3-using-agent-skills/SKILL.md', 'See [DoD](references/definition-of-done.md).\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /L1: references\/definition-of-done\.md/);
+});
+
+test('passes when a skill colocates its own references directory', () => {
+  // CLAUDE.md allows self-contained skills to keep references under
+  // skills/<name>/references/. Those links are correct as written.
+  const root = makeSandbox();
+  writeFile(root, 'skills/dataviz/references/palette.md', '# Palette\n');
+  writeFile(root, 'skills/dataviz/SKILL.md', 'See `references/palette.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('passes when a skill reference file reaches the shared checklist three levels up', () => {
+  // A file under skills/<name>/references/ sits one directory deeper than
+  // SKILL.md, so the shared checklists are three levels up from it, not two.
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n');
+  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
+  writeFile(
+    root,
+    'skills/hardening/references/patterns.md',
+    'Shared checklists live in `../../../references/security-checklist.md`.\n'
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /✓ {2}skills\/hardening\/references\/patterns\.md/);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('fails when a skill reference file links the shared checklist with the SKILL.md prefix', () => {
+  // The same off-by-a-level mistake this validator exists to catch, made from
+  // inside the skill's references/ directory: the link is resolved from the
+  // file that contains it, so `../../` stops at skills/.
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n');
+  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
+  writeFile(
+    root,
+    'skills/hardening/references/patterns.md',
+    ['# Patterns', '', 'See `../../references/security-checklist.md`.', ''].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /✓ {2}skills\/hardening\/SKILL\.md/);
+  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/patterns\.md/);
+  assert.match(
+    result.stdout,
+    /L3: \.\.\/\.\.\/references\/security-checklist\.md — resolves to skills\/references\/security-checklist\.md/
+  );
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+  assert.match(result.stdout, /use `\.\.\/\.\.\/\.\.\/references\/<file>\.md`/);
+});
+
+test('keeps the same narrow rule inside a skill reference file', () => {
+  // Same exemptions as SKILL.md: fenced examples, sibling files named without
+  // a references/ prefix, and artifacts that do not exist yet.
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n');
+  writeFile(root, 'skills/hardening/SKILL.md', 'See [patterns](references/patterns.md).\n');
+  writeFile(
+    root,
+    'skills/hardening/references/patterns.md',
+    [
+      'Record findings in `SECURITY.md` or `docs/threat-model.md`. See also `other-patterns.md`.',
+      '',
+      '```markdown',
+      '[wrong on purpose](../../references/security-checklist.md)',
+      '```',
+      '',
+    ].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('counts errors from SKILL.md and its reference files together', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n');
+  writeFile(root, 'skills/hardening/SKILL.md', 'See `references/security-checklist.md`.\n');
+  writeFile(root, 'skills/hardening/references/a.md', 'See `../../references/security-checklist.md`.\n');
+  writeFile(root, 'skills/hardening/references/b.md', 'See `../../../references/security-checklist.md`.\n');
+  writeFile(root, 'skills/hardening/references/notes.txt', 'See ../../references/security-checklist.md\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/a\.md/);
+  assert.match(result.stdout, /✓ {2}skills\/hardening\/references\/b\.md/);
+  assert.doesNotMatch(result.stdout, /notes\.txt/);
+  assert.match(result.stdout, /1 skills checked — 2 error\(s\) — FAILED/);
+});
+
+test('fails when a link points at a checklist that no longer exists', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
+  writeFile(root, 'skills/i3-shipping-and-launch/SKILL.md', 'See `../../references/renamed.md`.\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /L1: \.\.\/\.\.\/references\/renamed\.md/);
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+});
+
+test('ignores paths that are not references/ links', () => {
+  // Skills legitimately name artifacts the user has yet to create. Widening
+  // this validator into a general markdown linter would fail the build on them.
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# Definition of Done\n');
+  writeFile(
+    root,
+    'skills/i3-planning-and-task-breakdown/SKILL.md',
+    [
+      'Save the task list to `tasks/todo.md` and the plan to `tasks/plan.md`.',
+      'Record findings in `PERF.md` or `docs/ideas/[idea-name].md`.',
+      'Related: `skills/i3-incremental-implementation/SKILL.md`.',
+      'See `../../references/definition-of-done.md`.',
+      '',
+    ].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('reports every unresolvable link, not just the first per skill', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n');
+  writeFile(root, 'references/performance-checklist.md', '# Performance\n');
+  writeFile(
+    root,
+    'skills/i3-code-review-and-quality/SKILL.md',
+    ['See `references/security-checklist.md`.', 'And `references/performance-checklist.md`.', ''].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 2 error\(s\) — FAILED/);
+});
+
+test('a link inside a fenced block is an example, not a link to resolve', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/definition-of-done.md', '# DoD\n');
+  writeFile(
+    root,
+    'skills/i3-using-agent-skills/SKILL.md',
+    [
+      'Shared checklists live two levels up:',
+      '',
+      'See `../../references/definition-of-done.md`.',
+      '',
+      'Do not write it this way:',
+      '',
+      '```markdown',
+      '[Definition of Done](references/definition-of-done.md)',
+      '```',
+      '',
+    ].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('fence exemption follows CommonMark rather than a bare ``` match', () => {
+  const root = makeSandbox();
+  writeFile(
+    root,
+    'skills/i3-using-agent-skills/SKILL.md',
+    [
+      '~~~markdown',
+      '[a](references/missing-a.md)',
+      '```',                                  // wrong marker: must not close the ~~~ block
+      '[b](references/missing-b.md)',
+      '~~~',
+      '',
+      '   ```markdown',                       // three-space indent is still a fence
+      '[c](references/missing-c.md)',
+      '   `````',                             // a longer closer is legal
+      '',
+    ].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /0 error\(s\) — PASSED/);
+});
+
+test('a real broken link outside any fence is still reported', () => {
+  const root = makeSandbox();
+  writeFile(
+    root,
+    'skills/i3-using-agent-skills/SKILL.md',
+    [
+      '```markdown',
+      '[shown as an example](references/example-only.md)',
+      '```',
+      '',
+      'See `references/definition-of-done.md`.',   // genuinely wrong, outside the fence
+      '',
+    ].join('\n')
+  );
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+  assert.match(result.stdout, /L5: references\/definition-of-done\.md/);
+});
+
+for (const [ending, newline] of [['LF', '\n'], ['CRLF', '\r\n']]) {
+  test(`inline backticks do not hide subsequent broken links (${ending})`, () => {
+    const root = makeSandbox();
+    writeFile(root, 'skills/example/SKILL.md', [
+      '```js``` is inline code, not a fence opener.',
+      'See [missing](references/missing.md).',
+      '',
+    ].join(newline));
+
+    const result = run(root);
+
+    assert.equal(result.status, 1, result.stdout + result.stderr);
+    assert.match(result.stdout, /L2: references\/missing\.md/);
+    assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+  });
+
+  for (const marker of ['```', '~~~']) {
+    test(`trailing text does not close a ${marker} fence (${ending})`, () => {
+      const root = makeSandbox();
+      writeFile(root, 'skills/example/SKILL.md', [
+        marker + 'markdown',
+        marker + ' still part of the example',
+        '[example](references/example-only.md)',
+        marker + ' \t',
+        '[real link](references/missing.md)',
+        '',
+      ].join(newline));
+
+      const result = run(root);
+
+      assert.equal(result.status, 1, result.stdout + result.stderr);
+      assert.match(result.stdout, /L5: references\/missing\.md/);
+      assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+      assert.doesNotMatch(result.stdout, /example-only\.md/);
+    });
+  }
+}
+
+test('tilde fence info strings may contain backticks', () => {
+  const root = makeSandbox();
+  writeFile(root, 'skills/example/SKILL.md', [
+    '~~~example `code`',
+    '[example](references/example-only.md)',
+    '~~~',
+    '',
+  ].join('\n'));
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+// Anchors. A `#fragment` after a references/ link must match a heading in the
+// target file, slugged the way GitHub does it. Without this, renaming a heading
+// silently breaks every link to it while the file itself still exists.
+
+function hardeningSkill(root, link) {
+  writeFile(root, 'skills/hardening/SKILL.md', `See [patterns](${link}).\n`);
+}
+
+test('passes when an anchor matches a heading in the target file', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#cross-site-scripting-xss');
+  writeFile(root, 'skills/hardening/references/patterns.md', '# Patterns\n\n## Cross-Site Scripting (XSS)\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+  assert.match(result.stdout, /1 skills checked — 0 error\(s\) — PASSED/);
+});
+
+test('fails when an anchor matches no heading in the target file', () => {
+  // The file exists, so the existing check is satisfied; only the fragment is stale.
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#injection');
+  writeFile(root, 'skills/hardening/references/patterns.md', '# Patterns\n\n## Injection attacks\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(
+    result.stdout,
+    /L1: references\/patterns\.md#injection — no heading in skills\/hardening\/references\/patterns\.md produces #injection/
+  );
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+  assert.match(result.stdout, /GitHub's heading slugs/);
+  // The path was right, so the path hint would only mislead.
+  assert.doesNotMatch(result.stdout, /use `\.\.\/\.\.\/references/);
+});
+
+test('a repeated heading gets a -1 suffix, as on GitHub', () => {
+  const root = makeSandbox();
+  writeFile(root, 'skills/hardening/SKILL.md', [
+    'See [first](references/patterns.md#example).',
+    'See [second](references/patterns.md#example-1).',
+    'See [third](references/patterns.md#example-2).',
+    '',
+  ].join('\n'));
+  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example\n');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /L3: references\/patterns\.md#example-2 — no heading/);
+  assert.doesNotMatch(result.stdout, /L[12]:/);
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+});
+
+test('slugs come from the rendered heading text, not its markdown', () => {
+  // Real headings in the pack carry emphasis, code spans and links.
+  const root = makeSandbox();
+  writeFile(root, 'skills/hardening/SKILL.md', [
+    'See [a](references/patterns.md#why-this-is-not-a-ship-job).',
+    'See [b](references/patterns.md#owasp-top-10).',
+    'See [c](references/patterns.md#snake_case-names-stay).',
+    'See [d](references/patterns.md#closing-hashes).',
+    '',
+  ].join('\n'));
+  writeFile(root, 'skills/hardening/references/patterns.md', [
+    '### Why this is *not* a `/ship` job',
+    '## [OWASP](https://owasp.org/Top10/) Top 10',
+    '## snake_case names stay',
+    '## Closing hashes ##',
+    '',
+  ].join('\n'));
+
+  const result = run(root);
+
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('a heading-like line inside a fenced block is not an anchor', () => {
+  // Bash comments in a fenced example look like H1s.
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#chrome-devtools');
+  writeFile(root, 'skills/hardening/references/patterns.md', [
+    '# Patterns',
+    '',
+    '```bash',
+    '# Chrome DevTools',
+    '```',
+    '',
+  ].join('\n'));
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /#chrome-devtools — no heading/);
+});
+
+test('anchors resolve from a reference file to a shared checklist', () => {
+  const root = makeSandbox();
+  writeFile(root, 'references/security-checklist.md', '# Security\n\n## OWASP Top 10 Quick Reference\n');
+  hardeningSkill(root, 'references/patterns.md');
+  writeFile(root, 'skills/hardening/references/patterns.md', [
+    'See `../../../references/security-checklist.md#owasp-top-10-quick-reference`.',
+    'See `../../../references/security-checklist.md#destructive-path-operations`.',
+    '',
+  ].join('\n'));
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /✗ {2}skills\/hardening\/references\/patterns\.md/);
+  assert.match(result.stdout, /L2: \.\.\/\.\.\/\.\.\/references\/security-checklist\.md#destructive-path-operations — no heading in references\/security-checklist\.md/);
+  assert.doesNotMatch(result.stdout, /L1:/);
+});
+
+test('a missing file is reported once, not again for its anchor', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/renamed.md#injection');
+
+  const result = run(root);
+
+  assert.equal(result.status, 1, result.stdout + result.stderr);
+  assert.match(result.stdout, /L1: references\/renamed\.md — resolves to skills\/hardening\/references\/renamed\.md, which does not exist/);
+  assert.match(result.stdout, /1 skills checked — 1 error\(s\) — FAILED/);
+});
+
+
+test('heading slugs remain unique when a literal suffix collides with an allocated slug', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#example-1-1');
+  // A hyphen in the literal heading makes its base slug collide with Example's suffix.
+  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example\n\n## Example-1\n');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});
+
+test('a duplicate skips a slug occupied by an earlier literal heading', () => {
+  const root = makeSandbox();
+  hardeningSkill(root, 'references/patterns.md#example-2');
+  writeFile(root, 'skills/hardening/references/patterns.md', '## Example\n\n## Example-1\n\n## Example\n');
+  const result = run(root);
+  assert.equal(result.status, 0, result.stdout + result.stderr);
+});

package/scripts/validate-reference-links.js

@@ -77,8 +77,10 @@ function headingAnchors(file) {
     const match = line.match(/^ {0,3}#{1,6}[ \t]+(.*?)(?:[ \t]+#+)?[ \t]*$/);
     if (!match) continue;
     const slug = slugify(match[1]);
-    const count = seen.get(slug) || 0;
-    anchors.add(count === 0 ? slug : `${slug}-${count}`);
+    let count = seen.get(slug) || 0;
+    let anchor = count === 0 ? slug : `${slug}-${count}`;
+    while (anchors.has(anchor)) anchor = `${slug}-${++count}`;
+    anchors.add(anchor);
     seen.set(slug, count + 1);
   }
   return anchors;

package/scripts/validate-skills.js

@@ -3,7 +3,8 @@
  * validate-skills.js
  *
  * CLI that validates every skill in skills/ against the rules in
- * docs/skill-anatomy.md. The rules themselves live in scripts/lib/skill-lint.js
+ * docs/skill-anatomy.md, and every persona in agents/ against the three rules
+ * in docs/agents.md. The rules themselves live in scripts/lib/skill-lint.js
  * (a single source of truth, importable and unit-testable); this file is a thin
  * wrapper that walks the skills directory, runs the linter, prints the report,
  * and sets the exit code.
@@ -16,9 +17,10 @@
 const fs   = require('fs');
 const path = require('path');
 
-const { lintSkill } = require('./lib/skill-lint');
+const { lintSkill, lintPersona } = require('./lib/skill-lint');
 
 const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
+const AGENTS_DIR = path.resolve(__dirname, '..', 'agents');
 
 // ─── Main ────────────────────────────────────────────────────────────────────
 
@@ -54,8 +56,29 @@ function main() {
     }
   }
 
+  // ── Personas ─────────────────────────────────────────────────────────────
+  // agents/<name>.md files are consumed as subagents and spawned by name from
+  // commands, so they get the same frontmatter contract plus a closing
+  // Composition section (docs/agents.md). An index file such as README.md is
+  // not a persona and is skipped.
+  const personaFiles = fs.existsSync(AGENTS_DIR)
+    ? fs.readdirSync(AGENTS_DIR).filter(f => f.endsWith('.md') && !/^readme\.md$/i.test(f)).sort()
+    : [];
+
+  if (personaFiles.length > 0) console.log('');
+  for (const fileName of personaFiles) {
+    const { errors } = lintPersona(fileName, AGENTS_DIR);
+    totalErrors += errors.length;
+    if (errors.length === 0) {
+      console.log(`  ✓  agents/${fileName}`);
+    } else {
+      console.log(`  ✗  agents/${fileName}`);
+      for (const msg of errors) console.log(`       ERROR: ${msg}`);
+    }
+  }
+
   const status = totalErrors > 0 ? 'FAILED' : totalWarnings > 0 ? 'PASSED WITH WARNINGS' : 'PASSED';
-  console.log(`\n${skillDirs.length} skills checked — ${totalErrors} error(s), ${totalWarnings} warning(s) — ${status}`);
+  console.log(`\n${skillDirs.length} skills and ${personaFiles.length} personas checked — ${totalErrors} error(s), ${totalWarnings} warning(s) — ${status}`);
 
   if (totalErrors > 0) process.exit(1);
 }

package/scripts/validate-versions-test.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const assert = require("node:assert/strict");
+const { readFileSync } = require("node:fs");
+const test = require("node:test");
+
+const manifestPaths = [
+  "package.json",
+  "plugin.json",
+  ".codex-plugin/plugin.json",
+  ".claude-plugin/plugin.json",
+  ".claude-plugin/marketplace.json",
+  ".agents/plugins/marketplace.json",
+];
+
+function readManifestVersion(manifestPath) {
+  const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  return manifest.version ?? manifest.plugins?.[0]?.version;
+}
+
+test("all plugin manifests use the root plugin.json version", () => {
+  const expectedVersion = readManifestVersion("plugin.json");
+  assert.ok(expectedVersion, "plugin.json must define a version");
+
+  for (const manifestPath of manifestPaths) {
+    assert.equal(
+      readManifestVersion(manifestPath),
+      expectedVersion,
+      `${manifestPath} must use version ${expectedVersion}`,
+    );
+  }
+});

package/skills/i3-documentation-and-adrs/SKILL.md

@@ -268,6 +268,14 @@ Special consideration for AI agent context:
 - **ADRs** — Help agents understand why past decisions were made (prevents re-deciding)
 - **Inline gotchas** — Prevent agents from falling into known traps
 
+## Prose Review
+
+After checking the technical content, review the prose for the people who will use it. Clearer wording must not change the decision or its limits.
+
+1. Mark the details that must survive the edit: names, numbers and units, commands, paths, links, conditions, trade-offs, and uncertainty. Check them against the available code and decision context; flag anything you cannot substantiate.
+2. Replace stock introductions, promotional adjectives, and repeated summaries with the concrete information the reader needs. Do not replace an unsupported claim with an invented example or a stronger guarantee. Keep necessary technical repetition and the project's established terminology.
+3. Compare the edited document with the original and its sources. Restore any lost qualifier or caveat, verify command and code examples still work as documented, and explain any unresolved factual question rather than polishing it away.
+
 ## Common Rationalizations
 
 | Rationalization | Reality |
@@ -298,3 +306,4 @@ After documenting:
 - [ ] Known gotchas are documented inline where they matter
 - [ ] No commented-out code remains
 - [ ] Rules files (CLAUDE.md etc.) are current and accurate
+- [ ] Prose edits preserve source details, decision trade-offs, and qualifiers without adding unsupported guarantees

package/skills/i3-frontend-ui-engineering/SKILL.md

@@ -29,6 +29,10 @@ Build production-quality user interfaces that are accessible, performant, and vi
 - Adding interactivity or state management
 - Fixing visual or UX issues
 
+## Applicable Prototype Baselines
+
+When the project has `.i3-ui-prototypes.json`, read the prototype entry applicable to the UI module being changed, then its `baseline.json`, `design-system/MASTER.md`, tokens and page rules. Preserve approved design and interaction decisions; explain conflicts with new requirements instead of silently changing them. New pages reuse the selected template and component conventions. Changes to global tokens, navigation, component behavior or business states go through the `i3-ui-prototype` workflow and corresponding review. HTML review prototypes need explicit component mapping when implemented in another framework. Verify affected production pages in the browser; a prototype manifest check alone does not prove production fidelity. Projects without an applicable baseline retain this skill's existing workflow.
+
 ## Component Architecture
 
 ### File Structure
@@ -91,7 +95,7 @@ export function TaskItem({ task, onToggle, onDelete }: TaskItemProps) {
 ```tsx
 // Container: handles data
 export function TaskListContainer() {
-  const { tasks, isLoading, error } = useTasks();
+  const { tasks, isLoading, error, refetch } = useTasks();
 
   if (isLoading) return <TaskListSkeleton />;
   if (error) return <ErrorState message="Failed to load tasks" retry={refetch} />;