@givolt/i3-composer-agent 2.2.0 → 2.2.1

package/scripts/validate-artifact-paths.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * validate-artifact-paths.js
+ *
+ * Guards the spec -> plan -> build pipeline against silent artifact-path drift.
+ *
+ * The `/spec` and `/plan` commands (producers) write their artifacts to a set
+ * of paths that the `/build` command and the spec/plan skills (consumers) read
+ * back. When a producer moves an artifact without updating the consumers — as
+ * in PR #93, which pointed `/spec` and `/plan` at docs/features/[name]/ while
+ * `/build` still required SPEC.md and tasks/plan.md — the pipeline breaks, and
+ * nothing else in CI catches it (command parity only compares descriptions).
+ *
+ * This validator enforces one canonical set of spec/plan/todo artifact paths
+ * across every file in the pipeline. Changing the convention means updating
+ * ARTIFACT_ALLOWLIST *and* every guarded file in the same change; CI fails
+ * until they agree.
+ *
+ * Scope is deliberately narrow: only spec/plan/todo artifacts, only the files
+ * that define the pipeline. It is not a general markdown path linter.
+ *
+ * Exit codes: 0 = all clear, 1 = one or more drifted paths.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+
+// The canonical spec/plan/todo artifact paths. These are the only artifact
+// file paths the pipeline files may reference. To change the convention, edit
+// this list and update every guarded file to match — CI enforces the pairing.
+const ARTIFACT_ALLOWLIST = new Set([
+  'SPEC.md',        // spec, project root (produced by /spec, read by /build)
+  'docs/SPEC.md',   // spec, alternate location accepted by /build
+  'tasks/plan.md',  // plan (produced by /plan, read by /build)
+  'tasks/todo.md',  // task list (produced by /plan)
+]);
+
+// The files that make up the spec -> plan -> build pipeline. Absent files are
+// skipped, not failed: this validator checks path consistency, not presence.
+//
+// The command bodies exist once per host surface (validate-commands.js checks
+// that the three sets stay in step on descriptions, but their prompt bodies
+// are allowed to differ), so a producer or consumer can drift on one surface
+// while the Claude Code copy stays correct. Every surface is guarded here.
+const GUARDED_FILES = [
+  // Claude Code commands
+  '.claude/commands/spec.md',
+  '.claude/commands/plan.md',
+  '.claude/commands/build.md',
+  // Gemini CLI commands
+  '.gemini/commands/spec.toml',
+  '.gemini/commands/planning.toml',
+  '.gemini/commands/build.toml',
+  // Root command set (Antigravity, Codex, and other TOML-based hosts)
+  'commands/spec.toml',
+  'commands/planning.toml',
+  'commands/build.toml',
+  // Skills the commands invoke
+  'skills/i3-spec-driven-development/SKILL.md',
+  'skills/i3-planning-and-task-breakdown/SKILL.md',
+  // Docs that tell users where the artifacts live
+  'docs/getting-started.md',
+  'docs/adoption-guide.md',
+  'docs/copilot-setup.md', // its prompt-file aliases name the artifacts directly
+];
+
+// Matches a path-like token ending in a spec/plan/todo artifact filename,
+// including an optional directory prefix with bracket placeholders like
+// docs/features/[feature-name]/spec.md. Case-insensitive so SPEC.md and a
+// drifted spec.md are both caught, then compared against the allowlist.
+const ARTIFACT_RE = /(?:[A-Za-z0-9._[\]-]+\/)*(?:spec|plan|todo)\.md/gi;
+
+GUARDED_FILES.push(...GUARDED_FILES.filter(relative => /(?:^|\/)commands\//.test(relative)).map(relative => relative.replace(/(commands\/)([^/]+)(\.md|\.toml)$/, '$1i3-$2$3')));
+
+function findViolations(relPath) {
+  const abs = path.join(ROOT, relPath);
+  if (!fs.existsSync(abs)) return null; // skipped
+
+  const violations = [];
+  const lines = fs.readFileSync(abs, 'utf8').split(/\r?\n/);
+  lines.forEach((line, i) => {
+    const matches = line.match(ARTIFACT_RE);
+    if (!matches) return;
+    for (const match of matches) {
+      if (!ARTIFACT_ALLOWLIST.has(match)) {
+        violations.push({ line: i + 1, match });
+      }
+    }
+  });
+  return violations;
+}
+
+function main() {
+  console.log('Checking spec/plan/todo artifact paths...\n');
+
+  let checked = 0;
+  let errors = 0;
+
+  for (const relPath of GUARDED_FILES) {
+    const violations = findViolations(relPath);
+    if (violations === null) continue; // file not present, skip
+    checked++;
+
+    if (violations.length === 0) {
+      console.log(`  ✓  ${relPath}`);
+    } else {
+      console.log(`  ✗  ${relPath}`);
+      for (const { line, match } of violations) {
+        console.log(`       L${line}: ${match} — not an approved spec/plan/todo artifact path`);
+        errors++;
+      }
+    }
+  }
+
+  const status = errors > 0 ? 'FAILED' : 'PASSED';
+  console.log(`\n${checked} files checked — ${errors} error(s) — ${status}`);
+
+  if (errors > 0) {
+    console.log('\nThe spec -> plan -> build pipeline expects one set of artifact paths.');
+    console.log('Either use a path from ARTIFACT_ALLOWLIST, or change the convention');
+    console.log('across every guarded file and update the allowlist in the same change.');
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/validate-commands.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+/**
+ * validate-commands.js
+ *
+ * Guards against silent drift across the three slash-command directories:
+ *   .claude/commands/  (.md — Claude Code)
+ *   .gemini/commands/  (.toml — Gemini CLI)
+ *   commands/          (.toml — Antigravity CLI)
+ *
+ * Checks (errors block CI):
+ *   - Every command present in one directory exists in all three
+ *   - The 'description' field is identical across all three equivalents
+ *   - Claude command frontmatter is valid YAML, not merely splittable
+ *
+ * What this does NOT check:
+ *   Prompt body differences are intentional — each tool has its own
+ *   syntax ($ARGUMENTS, i3-composer-agent: prefixes, GEMINI.md vs CLAUDE.md).
+ *
+ * Exit codes: 0 = all clear, 1 = one or more errors
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// The same frontmatter-validity rules validate-skills applies to SKILL.md.
+// `descriptionFromMd` below splits each line on its first colon, exactly as the
+// skill reader used to, so a command whose frontmatter is not valid YAML passes
+// every check here — and Claude Code parses that frontmatter when the command is
+// loaded. The #494 thread verified all 25 SKILL.md files AND the command files by
+// hand; this makes the second half a check too.
+const { frontmatterYamlErrors } = require(path.join(__dirname, 'lib', 'skill-lint.js'));
+
+// ─── Config ───────────────────────────────────────────────────────────────────
+
+const ROOT = path.resolve(__dirname, '..');
+
+const DIRS = {
+  claude:     { dir: path.join(ROOT, '.claude', 'commands'), ext: '.md'   },
+  gemini:     { dir: path.join(ROOT, '.gemini', 'commands'), ext: '.toml' },
+  antigravity:{ dir: path.join(ROOT, 'commands'),            ext: '.toml' },
+};
+
+// Commands where the file stem differs between Claude and the TOML dirs.
+// Key = Claude stem, value = TOML stem.
+const NAME_MAP = {
+  plan: 'planning',
+  'i3-plan': 'i3-planning',
+};
+const NAME_MAP_REVERSE = Object.fromEntries(
+  Object.entries(NAME_MAP).map(([k, v]) => [v, k])
+);
+
+// ─── Parsers ──────────────────────────────────────────────────────────────────
+
+function descriptionFromMd(filePath) {
+  const content = fs.readFileSync(filePath, 'utf8');
+  const match   = content.match(/^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*\r?\n/);
+  if (!match) return null;
+  for (const line of match[1].split(/\r?\n/)) {
+    const colonIdx = line.indexOf(':');
+    if (colonIdx === -1) continue;
+    if (line.slice(0, colonIdx).trim() === 'description') {
+      return line.slice(colonIdx + 1).trim().replace(/^['"]|['"]$/g, '');
+    }
+  }
+  return null;
+}
+
+function descriptionFromToml(filePath) {
+  const content     = fs.readFileSync(filePath, 'utf8');
+  const doubleMatch = content.match(/^description\s*=\s*"((?:[^"\\]|\\.)*)"/m);
+  if (doubleMatch) return doubleMatch[1].replace(/\\"/g, '"');
+  const singleMatch = content.match(/^description\s*=\s*'([^']*)'/m);
+  return singleMatch ? singleMatch[1] : null;
+}
+
+// ─── Loader ───────────────────────────────────────────────────────────────────
+
+function loadCommands({ dir, ext }) {
+  if (!fs.existsSync(dir)) return {};
+  return Object.fromEntries(
+    fs.readdirSync(dir)
+      .filter(f => f.endsWith(ext))
+      .map(f => {
+        const stem = path.basename(f, ext);
+        const full = path.join(dir, f);
+        try {
+          const desc = ext === '.md' ? descriptionFromMd(full) : descriptionFromToml(full);
+          return [stem, desc];
+        } catch (e) {
+          console.log(`  ✗  ${stem} — cannot read file: ${e.message}`);
+          return [stem, null];
+        }
+      })
+  );
+}
+
+// ─── Main ─────────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log("校验各宿主命令目录、元数据和描述一致性。");
+  const byTool = {
+    claude:      loadCommands(DIRS.claude),
+    gemini:      loadCommands(DIRS.gemini),
+    antigravity: loadCommands(DIRS.antigravity),
+  };
+
+  // Canonical command list: use Claude stems as the reference.
+  // Map each Claude stem to its TOML equivalent for lookup.
+  const claudeStems = Object.keys(byTool.claude).sort();
+  const allTomlStems = new Set([
+    ...Object.keys(byTool.gemini),
+    ...Object.keys(byTool.antigravity),
+  ]);
+  const allCanonicalStems = new Set([
+    ...claudeStems,
+    ...[...allTomlStems].map(s => NAME_MAP_REVERSE[s] ?? s),
+  ]);
+
+  let errors = 0;
+
+  // ── Parity check ────────────────────────────────────────────────────────────
+  console.log('Checking command parity...');
+
+  // Commands in Claude not found in TOML dirs
+  for (const stem of claudeStems) {
+    const tomlStem = NAME_MAP[stem] ?? stem;
+    const missing  = [];
+    if (!(tomlStem in byTool.gemini))      missing.push('.gemini/commands');
+    if (!(tomlStem in byTool.antigravity)) missing.push('commands');
+    if (missing.length) {
+      console.log(`  ✗  ${stem} — missing in: ${missing.join(', ')}`);
+      errors++;
+    } else {
+      console.log(`  ✓  ${stem}${stem !== tomlStem ? ` (${tomlStem} in toml dirs)` : ''}`);
+    }
+  }
+
+  // Commands in TOML dirs not found in Claude
+  for (const stem of [...allTomlStems].sort()) {
+    const claudeStem = NAME_MAP_REVERSE[stem] ?? stem;
+    if (!(claudeStem in byTool.claude)) {
+      console.log(`  ✗  ${stem} — present in toml dirs but missing in .claude/commands`);
+      errors++;
+    }
+  }
+
+  // ── Claude frontmatter validity ─────────────────────────────────────────────
+  // Only the .md directory: the TOML dirs are parsed by a real TOML parser
+  // already, so a malformed one surfaces as a missing description above.
+  console.log('\nChecking Claude command frontmatter...');
+
+  for (const stem of claudeStems) {
+    const full = path.join(DIRS.claude.dir, `${stem}${DIRS.claude.ext}`);
+    let yamlErrors = [];
+    try {
+      yamlErrors = frontmatterYamlErrors(fs.readFileSync(full, 'utf8'));
+    } catch (e) {
+      console.log(`  ✗  ${stem} — cannot read file: ${e.message}`);
+      errors++;
+      continue;
+    }
+    if (yamlErrors.length === 0) {
+      console.log(`  ✓  ${stem}`);
+      continue;
+    }
+    console.log(`  ✗  ${stem}`);
+    for (const message of yamlErrors) {
+      console.log(`       ${message}`);
+      errors++;
+    }
+  }
+
+  // ── Description sync check ──────────────────────────────────────────────────
+  console.log('\nChecking description sync...');
+
+  for (const claudeStem of claudeStems) {
+    const tomlStem   = NAME_MAP[claudeStem] ?? claudeStem;
+    const descClaude = byTool.claude[claudeStem];
+    const descGemini = byTool.gemini[tomlStem];
+    const descAgy    = byTool.antigravity[tomlStem];
+
+    const malformed = [
+      ['.claude/commands', byTool.claude, claudeStem],
+      ['.gemini/commands', byTool.gemini, tomlStem],
+      ['commands/', byTool.antigravity, tomlStem],
+    ].filter(([, commands, stem]) => Object.prototype.hasOwnProperty.call(commands, stem) && commands[stem] == null);
+
+    if (malformed.length) {
+      console.log(`  ✗  ${claudeStem}`);
+      for (const [toolDir, , stem] of malformed) {
+        console.log(`       ${toolDir}/${stem} — missing or malformed description`);
+      }
+      errors++;
+      continue;
+    }
+
+    if (descClaude == null || descGemini == null || descAgy == null) {
+      // Missing file already flagged by parity check
+      continue;
+    }
+
+    const allMatch = descClaude === descGemini && descGemini === descAgy;
+
+    if (allMatch) {
+      console.log(`  ✓  ${claudeStem}`);
+    } else {
+      console.log(`  ✗  ${claudeStem}`);
+      console.log(`       .claude:      ${descClaude}`);
+      console.log(`       .gemini:      ${descGemini}`);
+      console.log(`       commands/:    ${descAgy}`);
+      errors++;
+    }
+  }
+
+  const status = errors > 0 ? 'FAILED' : 'PASSED';
+  console.log(`\n${allCanonicalStems.size} commands checked — ${errors} error(s) — ${status}`);
+
+  if (errors > 0) process.exit(1);
+}
+
+main();

package/scripts/validate-reference-links.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * validate-reference-links.js
+ *
+ * Guards links from skills to the shared `references/` checklists.
+ *
+ * Those checklists live in the repo-root `references/` directory, but every
+ * SKILL.md used to link them as `references/<file>.md` — a path relative to
+ * the skill's own directory, which is two levels below the root. All 18 links
+ * across 11 skills resolved to files that do not exist, in the repo and in
+ * every plugin-install layout (~/.claude/plugins/cache/..., ~/.codex/...).
+ * Agents that followed the guidance — for example i3-using-agent-skills pointing
+ * at the Definition of Done — hit a file-not-found and stalled.
+ *
+ * Nothing else in CI catches this: validate-artifact-paths.js is scoped to
+ * spec/plan/todo artifacts and is explicitly not a general markdown linter.
+ *
+ * The rule enforced here: every `references/*.md` link in a SKILL.md must
+ * resolve to an existing file relative to that skill's own directory. This
+ * accepts both conventions in CLAUDE.md — shared checklists reached via
+ * `../../references/`, and a skill's own colocated `references/` directory.
+ *
+ * The markdown files inside a skill's own `references/` directory get the
+ * same check, with each link resolved from the file that contains it. They
+ * sit one directory deeper than SKILL.md, so from there the shared checklists
+ * are `../../../references/`: the same off-by-a-level mistake, one level down.
+ *
+ * A `#fragment` after such a link must match a heading in the target file,
+ * slugged the way GitHub renders anchors. The file existing is not enough:
+ * renaming a heading breaks every link to it while the path still resolves.
+ *
+ * Scope is deliberately narrow: only `references/*.md` links, only SKILL.md
+ * and `skills/<name>/references/*.md` files. It is not a general markdown
+ * path linter — skills legitimately mention paths that do not exist yet
+ * (`tasks/todo.md`, `PERF.md`, `docs/ideas/[idea-name].md`), and those must
+ * not fail the build.
+ *
+ * Fenced code blocks are exempt for the same reason. Text inside a fence is
+ * an example, not a link an agent will follow — and this rule in particular
+ * has to be documentable: the failure message below tells authors to write
+ * `../../references/<file>.md` rather than `references/<file>.md`, which no
+ * skill could show as an example without failing the very check explaining it.
+ *
+ * Exit codes: 0 = all clear, 1 = one or more unresolvable links.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { stripFencedCodeBlocks } = require('./lib/skill-lint');
+
+const ROOT = path.resolve(__dirname, '..');
+const SKILLS_DIR = path.join(ROOT, 'skills');
+
+// Matches a link to a references/ markdown file, with any number of leading
+// `../` segments: `references/x.md`, `../../references/x.md`. Anchored on a
+// non-path character so `myreferences/x.md` does not match. An optional
+// `#fragment` is captured separately.
+const REFERENCE_LINK_RE = /(?<![A-Za-z0-9._/-])((?:\.\.\/)*references\/[A-Za-z0-9._-]+\.md)(?:#([\p{L}\p{N}_-]+))?/gu;
+
+// GitHub's heading anchor: the rendered text, lowercased, with everything but
+// letters, numbers, `_`, `-` and spaces dropped, then spaces turned to hyphens.
+function slugify(heading) {
+  const text = heading
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1') // links and images keep their text
+    .replace(/<[^>]+>/g, '');                  // inline HTML renders no text
+  return text.toLowerCase().replace(/[^\p{L}\p{M}\p{N}_\- ]/gu, '').replace(/ /g, '-');
+}
+
+// The anchors a file's ATX headings produce, outside fenced blocks. A repeated
+// slug gets `-1`, `-2`, ... as on GitHub.
+function headingAnchors(file) {
+  const anchors = new Set();
+  const seen = new Map();
+  for (const line of stripFencedCodeBlocks(fs.readFileSync(file, 'utf8')).split('\n')) {
+    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}`);
+    seen.set(slug, count + 1);
+  }
+  return anchors;
+}
+
+// A link is resolved from the directory of the file that contains it.
+function findViolations(file) {
+  const violations = [];
+  const baseDir = path.dirname(file);
+  // Share the linter's fence rules; blanked lines preserve diagnostic positions.
+  const lines = stripFencedCodeBlocks(fs.readFileSync(file, 'utf8')).split('\n');
+
+  lines.forEach((line, i) => {
+    for (const match of line.matchAll(REFERENCE_LINK_RE)) {
+      const [, link, anchor] = match;
+      const target = path.resolve(baseDir, link);
+      if (!fs.existsSync(target)) {
+        violations.push({ line: i + 1, link, target });
+      } else if (anchor && !headingAnchors(target).has(anchor)) {
+        violations.push({ line: i + 1, link, target, anchor });
+      }
+    }
+  });
+
+  return violations;
+}
+
+// The markdown files directly inside a skill's own references/ directory.
+function skillReferenceFiles(skillDir) {
+  const dir = path.join(skillDir, 'references');
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) return [];
+  return fs.readdirSync(dir)
+    .filter((name) => name.endsWith('.md'))
+    .sort()
+    .map((name) => path.join(dir, name))
+    .filter((file) => fs.statSync(file).isFile());
+}
+
+function toPosix(file) {
+  return path.relative(ROOT, file).split(path.sep).join('/');
+}
+
+function main() {
+  console.log('Checking references/ links in skills...\n');
+
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.log('No skills/ directory — nothing to check.');
+    return;
+  }
+
+  let checked = 0;
+  let errors = 0;
+  let referenceFileErrors = 0;
+  let anchorErrors = 0;
+
+  const skillNames = fs.readdirSync(SKILLS_DIR).sort();
+  for (const name of skillNames) {
+    const skillDir = path.join(SKILLS_DIR, name);
+    const skillFile = path.join(skillDir, 'SKILL.md');
+    if (!fs.statSync(skillDir).isDirectory() || !fs.existsSync(skillFile)) continue;
+
+    checked++;
+    for (const file of [skillFile, ...skillReferenceFiles(skillDir)]) {
+      const violations = findViolations(file);
+
+      if (violations.length === 0) {
+        console.log(`  ✓  ${toPosix(file)}`);
+        continue;
+      }
+
+      console.log(`  ✗  ${toPosix(file)}`);
+      for (const { line, link, target, anchor } of violations) {
+        errors++;
+        if (anchor) {
+          console.log(`       L${line}: ${link}#${anchor} — no heading in ${toPosix(target)} produces #${anchor}`);
+          anchorErrors++;
+          continue;
+        }
+        console.log(`       L${line}: ${link} — resolves to ${toPosix(target)}, which does not exist`);
+        if (file !== skillFile) referenceFileErrors++;
+      }
+    }
+  }
+
+  const status = errors > 0 ? 'FAILED' : 'PASSED';
+  console.log(`\n${checked} skills checked — ${errors} error(s) — ${status}`);
+
+  if (errors > 0) {
+    if (errors > anchorErrors) {
+      console.log('\nLinks to references/ are resolved from the directory of the file that contains them.');
+      console.log('Shared checklists live in the repo-root references/, two levels up from a SKILL.md:');
+      console.log('use `../../references/<file>.md`, not `references/<file>.md`.');
+      if (referenceFileErrors > 0) {
+        console.log('From a file inside skills/<name>/references/ they are three levels up:');
+        console.log('use `../../../references/<file>.md`.');
+      }
+    }
+    if (anchorErrors > 0) {
+      console.log("\nAnchors are matched against GitHub's heading slugs: the heading text lowercased,");
+      console.log('punctuation dropped, spaces turned to hyphens, and -1, -2, ... for repeated headings.');
+    }
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/validate-skills.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * 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
+ * (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.
+ *
+ * Exit codes: 0 = all clear, 1 = one or more errors
+ */
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+const { lintSkill } = require('./lib/skill-lint');
+
+const SKILLS_DIR = path.resolve(__dirname, '..', 'skills');
+
+// ─── Main ────────────────────────────────────────────────────────────────────
+
+function main() {
+  console.log("校验技能元数据、触发条件、完整章节与交叉引用（错误会阻止发行）。");
+  if (!fs.existsSync(SKILLS_DIR)) {
+    console.error(`ERROR: skills directory not found at ${SKILLS_DIR}`);
+    process.exit(1);
+  }
+
+  const skillDirs = fs.readdirSync(SKILLS_DIR)
+    .filter(d => fs.statSync(path.join(SKILLS_DIR, d)).isDirectory())
+    .sort();
+
+  const knownSkills = new Set(skillDirs);
+
+  let totalErrors   = 0;
+  let totalWarnings = 0;
+
+  for (const dirName of skillDirs) {
+    const { errors, warnings, exempt } = lintSkill(dirName, SKILLS_DIR, knownSkills);
+    totalErrors   += errors.length;
+    totalWarnings += warnings.length;
+
+    if (errors.length === 0 && warnings.length === 0) {
+      const tag = exempt ? ' (section checks exempt)' : '';
+      console.log(`  ✓  ${dirName}${tag}`);
+    } else {
+      const icon = errors.length > 0 ? '  ✗ ' : '  ⚠ ';
+      console.log(`${icon} ${dirName}`);
+      for (const msg of errors)   console.log(`       ERROR: ${msg}`);
+      for (const msg of warnings) console.log(`       WARN:  ${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}`);
+
+  if (totalErrors > 0) process.exit(1);
+}
+
+// Surface unexpected failures (fs errors, bad symlinks, …) as a structured
+// one-line CI error instead of an uncaught stack trace.
+try {
+  main();
+} catch (err) {
+  console.error(`\nERROR: validate-skills failed unexpectedly: ${err.message}`);
+  process.exit(1);
+}

package/scripts/validate-versions.js

@@ -0,0 +1,35 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const { readFileSync } = require("node:fs");
+
+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;
+}
+
+const expectedVersion = readManifestVersion("plugin.json");
+if (!expectedVersion) {
+  throw new Error("plugin.json is missing a version field");
+}
+
+for (const manifestPath of manifestPaths) {
+  const version = readManifestVersion(manifestPath);
+  if (version !== expectedVersion) {
+    throw new Error(
+      `${manifestPath} has version ${version ?? "<missing>"}; expected ${expectedVersion}`,
+    );
+  }
+}
+
+console.log(`All plugin manifests use version ${expectedVersion}.`);