@tanstack/intent 0.0.32 → 0.0.34

package/README.md

@@ -90,10 +90,10 @@ npx @tanstack/intent@latest stale
 
 From a monorepo root, `intent stale` checks every workspace package that ships skills. To scope it to one package, pass a directory like `intent stale packages/router`.
 
-Copy CI workflow templates into your repo so validation and staleness checks run on every push:
+Copy CI workflow templates into your repo so validation and staleness checks can run in GitHub Actions:
 
 ```bash
-npx @tanstack/intent@latest setup-github-actions
+npx @tanstack/intent@latest setup
 ```
 
 ## Compatibility
@@ -108,14 +108,14 @@ npx @tanstack/intent@latest setup-github-actions
 
 ## Monorepos
 
-- Run `npx @tanstack/intent@latest setup-github-actions` from either the repo root or a package directory. Intent detects the workspace root and writes workflows to the repo-level `.github/workflows/` directory.
-- Generated workflows are monorepo-aware: validation loops over workspace packages with skills, staleness checks run from the workspace root, and notify workflows watch package `src/` and docs paths.
+- Run `npx @tanstack/intent@latest setup` from either the repo root or a package directory. Intent detects the workspace root and writes workflows to the repo-level `.github/workflows/` directory.
+- Generated workflows are monorepo-aware: validation loops over workspace packages with skills, and staleness checks run from the workspace root.
 - Run `npx @tanstack/intent@latest validate packages/<pkg>/skills` from the repo root to validate one package without root-level packaging warnings.
-- Run `npx @tanstack/intent@latest stale` from the repo root to check all workspace packages with skills, or `intent stale packages/<pkg>` to check one package.
+- Run `npx @tanstack/intent@latest stale` from the repo root to check workspace packages with skills and public workspace packages missing skill or `_artifacts` coverage, or `intent stale packages/<pkg>` to check one package.
 
 ## Keeping skills current
 
-The real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
+The real risk with any derived artifact is staleness. `npx @tanstack/intent@latest stale` flags skills whose source docs have changed, generated skills that drift from `_artifacts`, and public workspace packages missing coverage. CI templates catch drift before it ships.
 
 The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` lets users submit structured reports when a skill produces wrong output — which skill, which version, what broke. That context flows back to the maintainer, and the fix ships to everyone on the next package update. Every support interaction produces an artifact that prevents the same class of problem for all future users — not just the one who reported it.
 
@@ -129,7 +129,7 @@ The feedback loop runs both directions. `npx @tanstack/intent@latest feedback` l
 | `npx @tanstack/intent@latest meta`                 | List meta-skills for library maintainers            |
 | `npx @tanstack/intent@latest scaffold`             | Print the guided skill generation prompt            |
 | `npx @tanstack/intent@latest validate [dir]`       | Validate SKILL.md files                             |
-| `npx @tanstack/intent@latest setup-github-actions` | Copy CI templates into your repo                    |
+| `npx @tanstack/intent@latest setup`                | Copy CI templates into your repo                    |
 | `npx @tanstack/intent@latest stale [dir] [--json]` | Check skills for version drift                      |
 | `npx @tanstack/intent@latest feedback`             | Submit skill feedback                               |
 

package/dist/artifact-coverage-BAN2W6aH.mjs

@@ -0,0 +1,3 @@
+import { t as readIntentArtifacts } from "./artifact-coverage-wLNVX8yC.mjs";
+
+export { readIntentArtifacts };

package/dist/artifact-coverage-wLNVX8yC.mjs

@@ -0,0 +1,128 @@
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+
+//#region src/artifact-coverage.ts
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function stringValue(value) {
+	return typeof value === "string" && value.trim() ? value : void 0;
+}
+function stringArray(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((entry) => typeof entry === "string");
+}
+function detectArtifactKind(fileName) {
+	if (fileName.endsWith("skill_tree.yaml")) return "skill-tree";
+	if (fileName.endsWith("domain_map.yaml")) return "domain-map";
+	return null;
+}
+function readArtifactYaml(artifactPath, warnings) {
+	let parsed;
+	try {
+		parsed = parse(readFileSync(artifactPath, "utf8"));
+	} catch (err) {
+		warnings.push({
+			artifactPath,
+			message: `Invalid YAML: ${err instanceof Error ? err.message : String(err)}`
+		});
+		return null;
+	}
+	if (!isRecord(parsed)) {
+		warnings.push({
+			artifactPath,
+			message: "Artifact YAML must contain an object at the top level"
+		});
+		return null;
+	}
+	return parsed;
+}
+function parseArtifactFile(artifactPath, kind, parsed) {
+	const library = isRecord(parsed.library) ? parsed.library : {};
+	return {
+		path: artifactPath,
+		kind,
+		libraryName: stringValue(library.name),
+		libraryVersion: stringValue(library.version)
+	};
+}
+function parseSkills(artifactPath, kind, parsed) {
+	if (!Array.isArray(parsed.skills)) return [];
+	const skills = [];
+	for (const skill of parsed.skills) {
+		if (!isRecord(skill)) continue;
+		const packagePath = stringValue(skill.package);
+		const packages = stringArray(skill.packages);
+		if (packagePath) packages.push(packagePath);
+		skills.push({
+			artifactPath,
+			artifactKind: kind,
+			name: stringValue(skill.name),
+			slug: stringValue(skill.slug),
+			path: stringValue(skill.path),
+			package: packagePath,
+			packages: [...new Set(packages)].sort((a, b) => a.localeCompare(b)),
+			sources: stringArray(skill.sources),
+			covers: stringArray(skill.covers)
+		});
+	}
+	return skills;
+}
+function parseCoverageIgnores(artifactPath, parsed) {
+	const ignored = (isRecord(parsed.coverage) ? parsed.coverage : null)?.ignored_packages;
+	if (!Array.isArray(ignored)) return [];
+	const ignores = [];
+	for (const entry of ignored) {
+		if (typeof entry === "string") {
+			if (entry.trim()) ignores.push({
+				packageName: entry,
+				artifactPath
+			});
+			continue;
+		}
+		if (!isRecord(entry)) continue;
+		const packageName = stringValue(entry.name);
+		if (!packageName) continue;
+		ignores.push({
+			packageName,
+			reason: stringValue(entry.reason),
+			artifactPath
+		});
+	}
+	return ignores;
+}
+function readIntentArtifacts(root) {
+	const artifactsDir = join(root, "_artifacts");
+	if (!existsSync(artifactsDir)) return null;
+	const warnings = [];
+	const skillTrees = [];
+	const domainMaps = [];
+	const skills = [];
+	const ignoredPackages = [];
+	for (const entry of readdirSync(artifactsDir, { withFileTypes: true })) {
+		if (!entry.isFile()) continue;
+		const kind = detectArtifactKind(entry.name);
+		if (!kind) continue;
+		const artifactPath = join(artifactsDir, entry.name);
+		const parsed = readArtifactYaml(artifactPath, warnings);
+		if (!parsed) continue;
+		const artifactFile = parseArtifactFile(artifactPath, kind, parsed);
+		if (kind === "skill-tree") skillTrees.push(artifactFile);
+		else domainMaps.push(artifactFile);
+		skills.push(...parseSkills(artifactPath, kind, parsed));
+		ignoredPackages.push(...parseCoverageIgnores(artifactPath, parsed));
+	}
+	return {
+		root,
+		artifactsDir,
+		skillTrees: skillTrees.sort((a, b) => a.path.localeCompare(b.path)),
+		domainMaps: domainMaps.sort((a, b) => a.path.localeCompare(b.path)),
+		skills: skills.sort((a, b) => `${a.artifactPath}:${a.slug ?? a.name ?? ""}`.localeCompare(`${b.artifactPath}:${b.slug ?? b.name ?? ""}`)),
+		ignoredPackages: ignoredPackages.sort((a, b) => a.packageName.localeCompare(b.packageName)),
+		warnings
+	};
+}
+
+//#endregion
+export { readIntentArtifacts as t };

package/dist/cli.mjs

@@ -1,12 +1,12 @@
 #!/usr/bin/env node
 import "./utils-COlDcU72.mjs";
-import "./workspace-patterns-U35B5AO-.mjs";
-import { i as parseSkillUse } from "./skill-use-CXOnncWK.mjs";
-import { r as resolveSkillUse } from "./resolver-aFigTqXi.mjs";
-import { t as resolveProjectContext } from "./project-context-CKG-q4rD.mjs";
-import { a as scanIntentsOrFail, c as fail, i as resolveStaleTargets, l as isCliFailure, n as runInstallCommand, o as scanOptionsFromGlobalFlags, r as getMetaDir, s as printWarnings } from "./install-BmVqcbEi.mjs";
-import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
-import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { n as findWorkspacePackages } from "./workspace-patterns-BN2A_60g.mjs";
+import { i as parseSkillUse } from "./skill-use-BzuuvLM7.mjs";
+import { r as resolveSkillUse } from "./resolver-Whd12ksO.mjs";
+import { t as resolveProjectContext } from "./project-context-alYMNoNa.mjs";
+import { a as scanIntentsOrFail, c as fail, i as resolveStaleTargets, l as isCliFailure, n as runInstallCommand, o as scanOptionsFromGlobalFlags, r as getMetaDir, s as printWarnings } from "./install-QjryhQtg.mjs";
+import { appendFileSync, existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { cac } from "cac";
 
@@ -43,7 +43,7 @@ async function runListCommand(options, scanIntentsOrFail$1) {
 		console.log(JSON.stringify(result, null, 2));
 		return;
 	}
-	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-DCRCp4-C.mjs");
+	const { computeSkillNameWidth, printSkillTree, printTable } = await import("./display-B3vkG99D.mjs");
 	const scanCoverage = formatScanCoverage(result);
 	if (result.packages.length === 0) {
 		console.log("No intent-enabled packages found.");
@@ -245,11 +245,17 @@ async function runSetupGithubActionsCommand(root, metaDir) {
 //#endregion
 //#region src/commands/stale.ts
 async function runStaleCommand(targetDir, options, resolveStaleTargets$1) {
-	const { reports } = await resolveStaleTargets$1(targetDir);
+	if (options.githubReview) {
+		await runGithubReview(targetDir, options, resolveStaleTargets$1);
+		return;
+	}
+	const { reports, workflowAdvisories = [] } = await resolveStaleTargets$1(targetDir);
 	if (options.json) {
 		console.log(JSON.stringify(reports, null, 2));
 		return;
 	}
+	for (const advisory of workflowAdvisories) console.log(advisory);
+	if (workflowAdvisories.length > 0) console.log();
 	if (reports.length === 0) {
 		console.log("No intent-enabled packages found.");
 		return;
@@ -259,14 +265,38 @@ async function runStaleCommand(targetDir, options, resolveStaleTargets$1) {
 		const vLabel = report.skillVersion && report.currentVersion ? ` (${report.skillVersion} → ${report.currentVersion})` : "";
 		console.log(`${report.library}${vLabel}${driftLabel}`);
 		const stale = report.skills.filter((skill) => skill.needsReview);
-		if (stale.length === 0) console.log("  All skills up-to-date");
-		else for (const skill of stale) console.log(`  ⚠ ${skill.name}: ${skill.reasons.join(", ")}`);
+		const signals = report.signals.filter((signal) => signal.needsReview);
+		if (stale.length === 0 && signals.length === 0) console.log("  All skills up-to-date");
+		else {
+			for (const skill of stale) console.log(`  ⚠ ${skill.name}: ${skill.reasons.join(", ")}`);
+			for (const signal of signals) {
+				const subject = signal.packageName ?? signal.packageRoot ?? signal.skill ?? signal.artifactPath ?? signal.subject ?? report.library;
+				console.log(`  ⚠ ${subject}: ${signal.reasons.join(", ")}`);
+			}
+		}
 		console.log();
 	}
 }
+async function runGithubReview(targetDir, options, resolveStaleTargets$1) {
+	const { collectStaleReviewItems, createFailedStaleReviewItem, createWorkflowAdvisoryReviewItems, writeStaleReviewWorkflowFiles } = await import("./workflow-review-Dz_ofcYQ.mjs");
+	const packageLabel = options.packageLabel ?? "workspace";
+	try {
+		const { reports, workflowAdvisories = [] } = await resolveStaleTargets$1(targetDir);
+		const items = [...collectStaleReviewItems(reports), ...createWorkflowAdvisoryReviewItems(packageLabel, workflowAdvisories)];
+		writeStaleReviewWorkflowFiles(items);
+		if (items.length === 0) console.log("No stale skills or coverage gaps found.");
+		else console.log(`Wrote ${items.length} intent skill review item(s).`);
+	} catch (err) {
+		writeStaleReviewWorkflowFiles([createFailedStaleReviewItem(packageLabel)]);
+		const message = err instanceof Error ? err.message : String(err);
+		console.log(`Intent stale check failed: ${message}`);
+		console.log("Wrote a review PR body so maintainers can inspect the logs.");
+	}
+}
 
 //#endregion
 //#region src/commands/validate.ts
+const agentSkillNamePattern = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 function buildValidationFailure(errors, warnings) {
 	const lines = [
 		"",
@@ -301,114 +331,230 @@ function collectPackagingWarnings(context) {
 	}
 	return warnings;
 }
-async function runValidateCommand(dir) {
-	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-dkVvY7D7.mjs")]);
-	const targetDir = dir ?? "skills";
-	const context = resolveProjectContext({
-		cwd: process.cwd(),
-		targetPath: targetDir
-	});
-	const skillsDir = context.targetSkillsDir ?? resolve(process.cwd(), targetDir);
-	if (!existsSync(skillsDir)) fail(`Skills directory not found: ${skillsDir}`);
-	const errors = [];
-	const skillFiles = findSkillFiles(skillsDir);
-	if (skillFiles.length === 0) fail("No SKILL.md files found");
-	for (const filePath of skillFiles) {
-		const rel = relative(process.cwd(), filePath);
-		const content = readFileSync(filePath, "utf8");
-		const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/);
-		if (!match) {
-			errors.push({
-				file: rel,
-				message: "Missing or invalid frontmatter"
-			});
-			continue;
-		}
-		if (!match[1]) {
-			errors.push({
-				file: rel,
-				message: "Missing YAML frontmatter"
-			});
-			continue;
-		}
-		let fm;
-		try {
-			fm = parseYaml(match[1]);
-		} catch (err) {
-			const detail = err instanceof Error ? err.message : String(err);
-			errors.push({
+function formatWarning({ file, message }) {
+	return `${file}: ${message}`;
+}
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function collectAgentSkillSpecWarnings({ filePath, fm, rel }) {
+	const warnings = [];
+	if (typeof fm.name === "string") {
+		if (fm.name.length > 64) warnings.push({
+			file: rel,
+			message: `Agent Skills spec warning: name exceeds 64 characters (${fm.name.length} chars)`
+		});
+		for (const segment of fm.name.split("/")) if (!agentSkillNamePattern.test(segment)) {
+			warnings.push({
 				file: rel,
-				message: `Invalid YAML frontmatter: ${detail}`
+				message: "Agent Skills spec warning: each name segment should use lowercase letters, numbers, and single hyphens only"
 			});
-			continue;
+			break;
 		}
-		if (!fm.name) errors.push({
+		const parentDir = basename(dirname(filePath));
+		if (!fm.name.includes("/") && fm.name !== parentDir) warnings.push({
 			file: rel,
-			message: "Missing required field: name"
+			message: "Agent Skills spec warning: name should match the parent directory name"
 		});
-		if (!fm.description) errors.push({
+	}
+	if (fm.license !== void 0 && (typeof fm.license !== "string" || fm.license.trim().length === 0)) warnings.push({
+		file: rel,
+		message: "Agent Skills spec warning: license should be a non-empty string"
+	});
+	if (fm.compatibility !== void 0) {
+		if (typeof fm.compatibility !== "string" || fm.compatibility.trim().length === 0) warnings.push({
 			file: rel,
-			message: "Missing required field: description"
+			message: "Agent Skills spec warning: compatibility should be a non-empty string"
 		});
-		if (typeof fm.name === "string") {
-			const expectedPath = relative(skillsDir, filePath).replace(/[/\\]SKILL\.md$/, "").split(sep).join("/");
-			if (fm.name !== expectedPath) errors.push({
-				file: rel,
-				message: `name "${fm.name}" does not match directory path "${expectedPath}"`
-			});
-		}
-		if (typeof fm.description === "string" && fm.description.length > 1024) errors.push({
+		else if (fm.compatibility.length > 500) warnings.push({
 			file: rel,
-			message: `Description exceeds 1024 character limit (${fm.description.length} chars)`
+			message: `Agent Skills spec warning: compatibility exceeds 500 characters (${fm.compatibility.length} chars)`
 		});
-		if (fm.type === "framework" && !Array.isArray(fm.requires)) errors.push({
+	}
+	if (fm.metadata !== void 0) {
+		if (!isRecord(fm.metadata)) warnings.push({
 			file: rel,
-			message: "Framework skills must have a \"requires\" field"
+			message: "Agent Skills spec warning: metadata should be a mapping"
 		});
-		const lineCount = content.split(/\r?\n/).length;
-		if (lineCount > 500) errors.push({
+		else if (Object.values(fm.metadata).some((value) => typeof value !== "string")) warnings.push({
 			file: rel,
-			message: `Exceeds 500 line limit (${lineCount} lines). Rewrite for conciseness: move API tables to references/, trim verbose examples, and remove content an agent already knows. Do not simply raise the limit.`
+			message: "Agent Skills spec warning: metadata values should be strings"
+		});
+	}
+	if (fm["allowed-tools"] !== void 0 && typeof fm["allowed-tools"] !== "string") warnings.push({
+		file: rel,
+		message: "Agent Skills spec warning: allowed-tools should be a space-separated string"
+	});
+	return warnings;
+}
+async function runValidateCommand(dir, options = {}) {
+	if (!options.githubSummary) {
+		await runValidateCommandInternal(dir);
+		return;
+	}
+	try {
+		await runValidateCommandInternal(dir);
+		writeGithubValidationSummary({ ok: true });
+	} catch (err) {
+		writeGithubValidationSummary({
+			ok: false,
+			message: validationErrorMessage(err)
 		});
+		throw err;
 	}
-	const artifactsDir = join(skillsDir, "_artifacts");
-	if (!context.isMonorepo && existsSync(artifactsDir)) for (const fileName of [
-		"domain_map.yaml",
-		"skill_spec.md",
-		"skill_tree.yaml"
-	]) {
-		const artifactPath = join(artifactsDir, fileName);
-		if (!existsSync(artifactPath)) {
-			errors.push({
-				file: relative(process.cwd(), artifactPath),
-				message: "Missing required artifact"
+}
+async function runValidateCommandInternal(dir) {
+	const [{ parse: parseYaml }, { findSkillFiles }] = await Promise.all([import("yaml"), import("./utils-dkVvY7D7.mjs")]);
+	const context = resolveProjectContext({
+		cwd: process.cwd(),
+		targetPath: dir
+	});
+	const explicitDir = dir !== void 0;
+	const skillsDirs = explicitDir ? [context.targetSkillsDir ?? resolve(process.cwd(), dir)] : collectDefaultSkillsDirs(context, findSkillFiles);
+	if (explicitDir && !existsSync(skillsDirs[0])) fail(`Skills directory not found: ${skillsDirs[0]}`);
+	const errors = [];
+	const warnings = [];
+	let validatedCount = 0;
+	if (explicitDir && findSkillFiles(skillsDirs[0]).length === 0) fail("No SKILL.md files found");
+	if (skillsDirs.length === 0) {
+		console.log("No skills/ directory found — skipping validation.");
+		return;
+	}
+	for (const skillsDir of skillsDirs) {
+		const skillFiles = findSkillFiles(skillsDir);
+		const validateContext = resolveProjectContext({
+			cwd: process.cwd(),
+			targetPath: skillsDir
+		});
+		for (const filePath of skillFiles) {
+			const rel = relative(process.cwd(), filePath);
+			const content = readFileSync(filePath, "utf8");
+			const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)/);
+			if (!match) {
+				errors.push({
+					file: rel,
+					message: "Missing or invalid frontmatter"
+				});
+				continue;
+			}
+			if (!match[1]) {
+				errors.push({
+					file: rel,
+					message: "Missing YAML frontmatter"
+				});
+				continue;
+			}
+			let fm;
+			try {
+				fm = parseYaml(match[1]);
+			} catch (err) {
+				const detail = err instanceof Error ? err.message : String(err);
+				errors.push({
+					file: rel,
+					message: `Invalid YAML frontmatter: ${detail}`
+				});
+				continue;
+			}
+			if (!fm.name) errors.push({
+				file: rel,
+				message: "Missing required field: name"
 			});
-			continue;
-		}
-		const content = readFileSync(artifactPath, "utf8");
-		if (content.trim().length === 0) {
-			errors.push({
-				file: relative(process.cwd(), artifactPath),
-				message: "Artifact file is empty"
+			if (!fm.description) errors.push({
+				file: rel,
+				message: "Missing required field: description"
 			});
-			continue;
-		}
-		if (fileName.endsWith(".yaml")) try {
-			parseYaml(content);
-		} catch (err) {
-			const detail = err instanceof Error ? err.message : String(err);
-			errors.push({
-				file: relative(process.cwd(), artifactPath),
-				message: `Invalid YAML in artifact file: ${detail}`
+			if (typeof fm.name === "string") {
+				const expectedPath = relative(skillsDir, filePath).replace(/[/\\]SKILL\.md$/, "").split(sep).join("/");
+				if (fm.name !== expectedPath) errors.push({
+					file: rel,
+					message: `name "${fm.name}" does not match directory path "${expectedPath}"`
+				});
+			}
+			if (typeof fm.description === "string" && fm.description.length > 1024) errors.push({
+				file: rel,
+				message: `Description exceeds 1024 character limit (${fm.description.length} chars)`
+			});
+			if (fm.type === "framework" && !Array.isArray(fm.requires)) errors.push({
+				file: rel,
+				message: "Framework skills must have a \"requires\" field"
 			});
+			warnings.push(...collectAgentSkillSpecWarnings({
+				filePath,
+				fm,
+				rel
+			}).map(formatWarning));
+			const lineCount = content.split(/\r?\n/).length;
+			if (lineCount > 500) errors.push({
+				file: rel,
+				message: `Exceeds 500 line limit (${lineCount} lines). Rewrite for conciseness: move API tables to references/, trim verbose examples, and remove content an agent already knows. Do not simply raise the limit.`
+			});
+		}
+		const artifactsDir = join(skillsDir, "_artifacts");
+		if (!validateContext.isMonorepo && existsSync(artifactsDir)) for (const fileName of [
+			"domain_map.yaml",
+			"skill_spec.md",
+			"skill_tree.yaml"
+		]) {
+			const artifactPath = join(artifactsDir, fileName);
+			if (!existsSync(artifactPath)) {
+				errors.push({
+					file: relative(process.cwd(), artifactPath),
+					message: "Missing required artifact"
+				});
+				continue;
+			}
+			const content = readFileSync(artifactPath, "utf8");
+			if (content.trim().length === 0) {
+				errors.push({
+					file: relative(process.cwd(), artifactPath),
+					message: "Artifact file is empty"
+				});
+				continue;
+			}
+			if (fileName.endsWith(".yaml")) try {
+				parseYaml(content);
+			} catch (err) {
+				const detail = err instanceof Error ? err.message : String(err);
+				errors.push({
+					file: relative(process.cwd(), artifactPath),
+					message: `Invalid YAML in artifact file: ${detail}`
+				});
+			}
 		}
+		validatedCount += skillFiles.length;
+		warnings.push(...collectPackagingWarnings(validateContext));
 	}
-	const warnings = collectPackagingWarnings(context);
 	if (errors.length > 0) fail(buildValidationFailure(errors, warnings));
-	console.log(`✅ Validated ${skillFiles.length} skill files — all passed`);
+	console.log(`✅ Validated ${validatedCount} skill files — all passed`);
 	if (warnings.length > 0) console.log();
 	printWarnings(warnings);
 }
+function validationErrorMessage(err) {
+	if (isCliFailure(err)) return err.message;
+	if (err instanceof Error) return err.message;
+	return String(err);
+}
+function writeGithubValidationSummary({ message, ok }) {
+	const summaryPath = process.env.GITHUB_STEP_SUMMARY;
+	if (!summaryPath) return;
+	const lines = ["### Intent skill validation", ""];
+	if (ok) lines.push("Skill validation passed.", "");
+	else lines.push("Skill validation failed.", "", "Why this failed:", "", "Intent validates SKILL.md frontmatter, skill names, required fields, size limits, framework requirements, and artifact files.", "The command output below contains the exact file-level reasons to fix.", "", "Run locally:", "", "```bash", "npx @tanstack/intent@latest validate", "```", "", "Command output:", "", "```text", message ?? "Unknown validation error.", "```", "");
+	appendFileSync(summaryPath, lines.join("\n"));
+}
+function collectDefaultSkillsDirs(context, findSkillFiles) {
+	const skillsDirs = [];
+	const addSkillsDir = (skillsDir) => {
+		if (existsSync(skillsDir) && findSkillFiles(skillsDir).length > 0) skillsDirs.push(skillsDir);
+	};
+	if (context.workspaceRoot && context.cwd === context.workspaceRoot) {
+		addSkillsDir(join(context.workspaceRoot, "skills"));
+		for (const packageDir of findWorkspacePackages(context.workspaceRoot)) addSkillsDir(join(packageDir, "skills"));
+		return [...new Set(skillsDirs)].sort((a, b) => a.localeCompare(b));
+	}
+	addSkillsDir(context.targetSkillsDir ?? (context.packageRoot ? join(context.packageRoot, "skills") : resolve(context.cwd, "skills")));
+	return skillsDirs;
+}
 
 //#endregion
 //#region src/cli.ts
@@ -424,8 +570,8 @@ function createCli() {
 	cli.command("meta [name]", "List meta-skills, or print one by name").usage("meta [name]").example("meta").example("meta domain-discovery").action(async (name) => {
 		await runMetaCommand(name, getMetaDir());
 	});
-	cli.command("validate [dir]", "Validate skill files").usage("validate [dir]").example("validate").example("validate packages/query/skills").action(async (dir) => {
-		await runValidateCommand(dir);
+	cli.command("validate [dir]", "Validate skill files").usage("validate [dir] [--github-summary]").option("--github-summary", "Write a GitHub Actions step summary").example("validate").example("validate packages/query/skills").action(async (dir, options) => {
+		await runValidateCommand(dir, options);
 	});
 	cli.command("install", "Create or update skill loading guidance in an agent config file").usage("install [--map] [--dry-run] [--print-prompt] [--global] [--global-only]").option("--map", "Write explicit skill-to-task mappings").option("--dry-run", "Print the generated block without writing").option("--print-prompt", "Print the legacy agent setup prompt instead of writing").option("--global", "Include global packages after project packages").option("--global-only", "Install mappings from global packages only").example("install").example("install --map").example("install --dry-run").example("install --print-prompt").example("install --global").action(async (options) => {
 		await runInstallCommand(options, scanIntentsOrFail);
@@ -433,12 +579,15 @@ function createCli() {
 	cli.command("scaffold", "Print maintainer scaffold prompt").usage("scaffold").action(() => {
 		runScaffoldCommand(getMetaDir());
 	});
-	cli.command("stale [dir]", "Check skills for staleness in the current package or workspace").usage("stale [dir] [--json]").option("--json", "Output JSON").example("stale").example("stale packages/query").example("stale --json").action(async (targetDir, options) => {
+	cli.command("stale [dir]", "Check skills for staleness in the current package or workspace").usage("stale [dir] [--json] [--github-review]").option("--json", "Output JSON").option("--github-review", "Write GitHub Actions review PR files").option("--package-label <label>", "Fallback package label for review PRs").example("stale").example("stale packages/query").example("stale --json").action(async (targetDir, options) => {
 		await runStaleCommand(targetDir, options, resolveStaleTargets);
 	});
 	cli.command("edit-package-json", "Update package.json files so skills are published").usage("edit-package-json").action(async () => {
 		await runEditPackageJsonCommand(process.cwd());
 	});
+	cli.command("setup", "Copy Intent CI workflow templates into .github/workflows/").usage("setup").action(async () => {
+		await runSetupGithubActionsCommand(process.cwd(), getMetaDir());
+	});
 	cli.command("setup-github-actions", "Copy Intent CI workflow templates into .github/workflows/").usage("setup-github-actions").action(async () => {
 		await runSetupGithubActionsCommand(process.cwd(), getMetaDir());
 	});

package/dist/{display-DCRCp4-C.mjs → display-B3vkG99D.mjs}

@@ -1,5 +1,5 @@
 import "./utils-COlDcU72.mjs";
 import "./skill-paths-8k9K9y26.mjs";
-import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-DUgtRJkt.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-CAof6doy.mjs";
 
 export { computeSkillNameWidth, printSkillTree, printTable };

package/dist/index.d.mts

@@ -1,11 +1,29 @@
-import { a as IntentProjectConfig, c as ScanOptions, d as SkillStaleness, f as StalenessReport, i as IntentPackage, l as ScanResult, n as FeedbackPayload, o as MetaFeedbackPayload, p as VersionConflict, r as IntentConfig, s as MetaSkillName, t as AgentName, u as SkillEntry } from "./types-CsySN6Vw.mjs";
-import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./setup-DDoOLriA.mjs";
+import { _ as StalenessReport, a as IntentArtifactSet, c as IntentConfig, d as MetaFeedbackPayload, f as MetaSkillName, g as SkillStaleness, h as SkillEntry, i as IntentArtifactFile, l as IntentPackage, m as ScanResult, n as FeedbackPayload, o as IntentArtifactSkill, p as ScanOptions, r as IntentArtifactCoverageIgnore, s as IntentArtifactWarning, t as AgentName, u as IntentProjectConfig, v as StalenessSignal, y as VersionConflict } from "./types-DT7Y6TFz.mjs";
+import { i as runEditPackageJson, o as runSetupGithubActions, r as SetupGithubActionsResult, t as EditPackageJsonResult } from "./setup-t1i2o2-h.mjs";
 
 //#region src/scanner.d.ts
 declare function scanForIntents(root?: string, options?: ScanOptions): ScanResult;
 //#endregion
 //#region src/staleness.d.ts
-declare function checkStaleness(packageDir: string, packageName?: string): Promise<StalenessReport>;
+declare function checkStaleness(packageDir: string, packageName?: string, artifactRoot?: string): Promise<StalenessReport>;
+//#endregion
+//#region src/artifact-coverage.d.ts
+declare function readIntentArtifacts(root: string): IntentArtifactSet | null;
+//#endregion
+//#region src/workflow-review.d.ts
+interface StaleReviewItem {
+  type: string;
+  library: string;
+  subject: string;
+  reasons: Array<string>;
+  artifactPath?: string;
+  packageName?: string;
+  packageRoot?: string;
+  skill?: string;
+}
+declare function collectStaleReviewItems(reports: Array<StalenessReport>): Array<StaleReviewItem>;
+declare function createFailedStaleReviewItem(library: string): StaleReviewItem;
+declare function buildStaleReviewBody(items: Array<StaleReviewItem>): string;
 //#endregion
 //#region src/feedback.d.ts
 declare function containsSecrets(text: string): boolean;
@@ -108,4 +126,4 @@ declare class ResolveSkillUseError extends Error {
 declare function isResolveSkillUseError(error: unknown): error is ResolveSkillUseError;
 declare function resolveSkillUse(use: string, scanResult: ScanResult): ResolveSkillResult;
 //#endregion
-export { type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ResolveSkillResult, ResolveSkillUseError, type ResolveSkillUseErrorCode, type ScanOptions, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type SkillUse, SkillUseParseError, type SkillUseParseErrorCode, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, formatSkillUse, getDeps, hasGhCli, isResolveSkillUseError, isSkillUseParseError, metaToMarkdown, parseFrontmatter, parseSkillUse, resolveDepDir, resolveFrequency, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentArtifactCoverageIgnore, type IntentArtifactFile, type IntentArtifactSet, type IntentArtifactSkill, type IntentArtifactWarning, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ResolveSkillResult, ResolveSkillUseError, type ResolveSkillUseErrorCode, type ScanOptions, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type SkillUse, SkillUseParseError, type SkillUseParseErrorCode, type StaleReviewItem, type StalenessReport, type StalenessSignal, buildStaleReviewBody, checkStaleness, collectStaleReviewItems, containsSecrets, createFailedStaleReviewItem, findSkillFiles, formatSkillUse, getDeps, hasGhCli, isResolveSkillUseError, isSkillUseParseError, metaToMarkdown, parseFrontmatter, parseSkillUse, readIntentArtifacts, resolveDepDir, resolveFrequency, resolveSkillUse, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };