@tanstack/intent 0.0.29 → 0.0.33

package/dist/staleness-PdgakrCQ.mjs

@@ -0,0 +1,243 @@
+import { a as parseFrontmatter, n as findSkillFiles } from "./utils-COlDcU72.mjs";
+import { t as readIntentArtifacts } from "./artifact-coverage-wLNVX8yC.mjs";
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+
+//#region src/staleness.ts
+function classifyVersionDrift(oldVer, newVer) {
+	if (oldVer === newVer) return null;
+	const oldParts = oldVer.replace(/[^0-9.]/g, "").split(".").map(Number);
+	const newParts = newVer.replace(/[^0-9.]/g, "").split(".").map(Number);
+	if ((newParts[0] ?? 0) > (oldParts[0] ?? 0)) return "major";
+	if ((newParts[1] ?? 0) > (oldParts[1] ?? 0)) return "minor";
+	if ((newParts[2] ?? 0) > (oldParts[2] ?? 0)) return "patch";
+	return null;
+}
+function readLocalVersion(packageDir) {
+	try {
+		const pkgJson = JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+		return typeof pkgJson.version === "string" ? pkgJson.version : null;
+	} catch {
+		return null;
+	}
+}
+async function fetchNpmVersion(packageName) {
+	try {
+		const res = await fetch(`https://registry.npmjs.org/${encodeURIComponent(packageName)}/latest`);
+		if (!res.ok) return null;
+		const data = await res.json();
+		return typeof data.version === "string" ? data.version : null;
+	} catch {
+		return null;
+	}
+}
+async function fetchCurrentVersion(packageDir, packageName) {
+	return readLocalVersion(packageDir) ?? await fetchNpmVersion(packageName);
+}
+function isStringRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function parseSyncState(value) {
+	if (!value || typeof value !== "object") return null;
+	const raw = value;
+	const parsed = {};
+	if (typeof raw.library_version === "string") parsed.library_version = raw.library_version;
+	if (raw.skills && typeof raw.skills === "object") {
+		const skills = {};
+		for (const [skillName, skillValue] of Object.entries(raw.skills)) {
+			if (!skillValue || typeof skillValue !== "object") continue;
+			const sourcesSha = skillValue.sources_sha;
+			if (sourcesSha !== void 0 && !isStringRecord(sourcesSha)) continue;
+			skills[skillName] = {};
+			if (sourcesSha) skills[skillName].sources_sha = sourcesSha;
+		}
+		parsed.skills = skills;
+	}
+	return parsed;
+}
+function readSyncState(packageDir) {
+	const statePath = join(packageDir, "skills", "sync-state.json");
+	try {
+		return parseSyncState(JSON.parse(readFileSync(statePath, "utf8")));
+	} catch {
+		return null;
+	}
+}
+function readPackageName(packageDir) {
+	const packageJson = readPackageJson(packageDir);
+	return typeof packageJson?.name === "string" ? packageJson.name : relative(process.cwd(), packageDir) || "unknown";
+}
+function readPackageJson(packageDir) {
+	try {
+		return JSON.parse(readFileSync(join(packageDir, "package.json"), "utf8"));
+	} catch {
+		return null;
+	}
+}
+function normalizeFilePath(path) {
+	return resolve(path).split(sep).join("/");
+}
+function normalizeList(values) {
+	return [...new Set(values ?? [])].sort((a, b) => a.localeCompare(b));
+}
+function sameStringList(a, b) {
+	const left = normalizeList(a);
+	const right = normalizeList(b);
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function artifactPackageMatches(artifact, packageDir, packageName, artifactRoot) {
+	const relPackageDir = relative(artifactRoot, packageDir).split(sep).join("/");
+	if (!relPackageDir) return true;
+	if (artifact.packages.includes(packageName)) return true;
+	if (artifact.packages.includes(relPackageDir)) return true;
+	if (artifact.path?.startsWith(`${relPackageDir}/`)) return true;
+	return artifact.packages.length === 0 && artifact.path === void 0;
+}
+function resolveArtifactSkillPaths(artifact, packageDir, artifactRoot) {
+	if (!artifact.path) return [];
+	const candidatePaths = [isAbsolute(artifact.path) ? artifact.path : join(artifactRoot, artifact.path), isAbsolute(artifact.path) ? artifact.path : join(packageDir, artifact.path)];
+	if (artifact.package && artifact.path.startsWith("skills/")) candidatePaths.push(join(artifactRoot, artifact.package, artifact.path));
+	return [...new Set(candidatePaths.map(normalizeFilePath))];
+}
+function findMatchingSkill(artifact, skillMetas, packageDir, artifactRoot) {
+	const skillsByPath = new Map(skillMetas.map((skill) => [normalizeFilePath(skill.filePath), skill]));
+	for (const candidatePath of resolveArtifactSkillPaths(artifact, packageDir, artifactRoot)) {
+		const match = skillsByPath.get(candidatePath);
+		if (match) return match;
+	}
+	const skillsByName = /* @__PURE__ */ new Map();
+	for (const skill of skillMetas) {
+		skillsByName.set(skill.name, skill);
+		skillsByName.set(skill.relName, skill);
+	}
+	return (artifact.slug ? skillsByName.get(artifact.slug) : void 0) ?? (artifact.name ? skillsByName.get(artifact.name) : void 0) ?? null;
+}
+function buildArtifactSignals({ artifactRoot, artifacts, library, packageDir, skillMetas }) {
+	if (!artifacts) return [];
+	const artifactFiles = new Map([...artifacts.skillTrees, ...artifacts.domainMaps].map((file) => [file.path, file]));
+	const signals = artifacts.warnings.map((warning) => ({
+		type: "artifact-parse-warning",
+		library,
+		subject: warning.artifactPath,
+		reasons: [warning.message],
+		needsReview: true,
+		artifactPath: warning.artifactPath
+	}));
+	for (const artifact of artifacts.skills) {
+		if (!artifactPackageMatches(artifact, packageDir, library, artifactRoot)) continue;
+		const subject = artifact.slug ?? artifact.name ?? artifact.path;
+		const matchingSkill = findMatchingSkill(artifact, skillMetas, packageDir, artifactRoot);
+		if (artifact.path && !matchingSkill) {
+			signals.push({
+				type: "artifact-skill-missing",
+				library,
+				subject,
+				reasons: [`artifact skill path does not resolve to a generated SKILL.md (${artifact.path})`],
+				needsReview: true,
+				artifactPath: artifact.artifactPath,
+				skill: artifact.slug ?? artifact.name
+			});
+			continue;
+		}
+		if (!matchingSkill) continue;
+		if (matchingSkill.sources !== void 0 && artifact.sources.length > 0 && !sameStringList(matchingSkill.sources, artifact.sources)) signals.push({
+			type: "artifact-source-drift",
+			library,
+			subject,
+			reasons: ["artifact sources differ from SKILL.md frontmatter sources"],
+			needsReview: true,
+			artifactPath: artifact.artifactPath,
+			skill: matchingSkill.name
+		});
+		const artifactVersion = artifactFiles.get(artifact.artifactPath)?.libraryVersion;
+		if (artifactVersion && matchingSkill.libraryVersion && artifactVersion !== matchingSkill.libraryVersion) signals.push({
+			type: "artifact-library-version-drift",
+			library,
+			subject,
+			reasons: [`artifact library.version (${artifactVersion}) differs from SKILL.md library_version (${matchingSkill.libraryVersion})`],
+			needsReview: true,
+			artifactPath: artifact.artifactPath,
+			skill: matchingSkill.name
+		});
+	}
+	return signals;
+}
+function artifactCoversPackage(artifact, packageDir, packageName, artifactRoot) {
+	const relPackageDir = relative(artifactRoot, packageDir).split(sep).join("/");
+	return artifact.packages.includes(packageName) || artifact.packages.includes(relPackageDir) || artifact.package === packageName || artifact.package === relPackageDir || artifact.path?.startsWith(`${relPackageDir}/`) === true;
+}
+function artifactIgnoresPackage(artifacts, packageDir, packageName, artifactRoot) {
+	const relPackageDir = relative(artifactRoot, packageDir).split(sep).join("/");
+	return artifacts.ignoredPackages.some((ignored) => ignored.packageName === packageName || ignored.packageName === relPackageDir);
+}
+function buildWorkspaceCoverageSignals({ artifactRoot, artifacts, packageDirs }) {
+	if (!artifacts) return [];
+	const signals = [];
+	for (const packageDir of packageDirs) {
+		if (readPackageJson(packageDir)?.private === true) continue;
+		const packageName = readPackageName(packageDir);
+		if (artifactIgnoresPackage(artifacts, packageDir, packageName, artifactRoot)) continue;
+		const hasGeneratedSkill = findSkillFiles(join(packageDir, "skills")).length > 0;
+		const hasArtifactCoverage = artifacts.skills.some((artifact) => artifactCoversPackage(artifact, packageDir, packageName, artifactRoot));
+		if (hasGeneratedSkill || hasArtifactCoverage) continue;
+		signals.push({
+			type: "missing-package-coverage",
+			library: packageName,
+			subject: packageName,
+			reasons: ["workspace package is not represented by generated skills or _artifacts coverage"],
+			needsReview: true,
+			packageName,
+			packageRoot: relative(artifactRoot, packageDir).split(sep).join("/")
+		});
+	}
+	return signals;
+}
+async function checkStaleness(packageDir, packageName, artifactRoot = packageDir) {
+	const skillsDir = join(packageDir, "skills");
+	const library = packageName ?? "unknown";
+	const skillMetas = findSkillFiles(skillsDir).map((filePath) => {
+		const fm = parseFrontmatter(filePath);
+		const relName = relative(skillsDir, filePath).replace(/[/\\]SKILL\.md$/, "").split(sep).join("/");
+		return {
+			name: typeof fm?.name === "string" ? fm.name : relName,
+			relName,
+			filePath,
+			libraryVersion: fm?.library_version,
+			sources: Array.isArray(fm?.sources) ? fm.sources : void 0
+		};
+	});
+	const artifacts = existsSync(join(artifactRoot, "_artifacts")) ? readIntentArtifacts(artifactRoot) : null;
+	const skillVersion = skillMetas.find((s) => s.libraryVersion)?.libraryVersion ?? null;
+	const currentVersion = await fetchCurrentVersion(packageDir, library);
+	const versionDrift = skillVersion && currentVersion ? classifyVersionDrift(skillVersion, currentVersion) : null;
+	const syncState = readSyncState(packageDir);
+	return {
+		library,
+		currentVersion,
+		skillVersion,
+		versionDrift,
+		skills: skillMetas.map((skill) => {
+			const reasons = [];
+			if (currentVersion && skill.libraryVersion && skill.libraryVersion !== currentVersion) reasons.push(`version drift (${skill.libraryVersion} → ${currentVersion})`);
+			const storedShas = syncState?.skills?.[skill.name]?.sources_sha ?? {};
+			if (skill.sources && Object.keys(storedShas).length > 0) {
+				for (const source of skill.sources) if (!storedShas[source]) reasons.push(`new source (${source})`);
+			}
+			return {
+				name: skill.name,
+				reasons,
+				needsReview: reasons.length > 0
+			};
+		}),
+		signals: buildArtifactSignals({
+			artifactRoot,
+			artifacts,
+			library,
+			packageDir,
+			skillMetas
+		})
+	};
+}
+
+//#endregion
+export { checkStaleness as n, readPackageName as r, buildWorkspaceCoverageSignals as t };

package/dist/{types-BTQ9efv-.d.mts → types-_y9b00bI.d.mts}

@@ -15,6 +15,11 @@ interface ScanResult {
     global: NodeModulesScanTarget;
   };
 }
+type ScanScope = 'local' | 'local-and-global' | 'global';
+interface ScanOptions {
+  includeGlobal?: boolean;
+  scope?: ScanScope;
+}
 interface NodeModulesScanTarget {
   path: string | null;
   detected: boolean;
@@ -28,6 +33,7 @@ interface IntentPackage {
   intent: IntentConfig;
   skills: Array<SkillEntry>;
   packageRoot: string;
+  source: 'local' | 'global';
 }
 interface InstalledVariant {
   version: string;
@@ -51,12 +57,59 @@ interface StalenessReport {
   skillVersion: string | null;
   versionDrift: 'major' | 'minor' | 'patch' | null;
   skills: Array<SkillStaleness>;
+  signals: Array<StalenessSignal>;
 }
 interface SkillStaleness {
   name: string;
   reasons: Array<string>;
   needsReview: boolean;
 }
+interface StalenessSignal {
+  type: string;
+  library?: string;
+  subject?: string;
+  reasons: Array<string>;
+  needsReview: boolean;
+  artifactPath?: string;
+  packageName?: string;
+  packageRoot?: string;
+  skill?: string;
+}
+interface IntentArtifactSet {
+  root: string;
+  artifactsDir: string;
+  skillTrees: Array<IntentArtifactFile>;
+  domainMaps: Array<IntentArtifactFile>;
+  skills: Array<IntentArtifactSkill>;
+  ignoredPackages: Array<IntentArtifactCoverageIgnore>;
+  warnings: Array<IntentArtifactWarning>;
+}
+interface IntentArtifactFile {
+  path: string;
+  kind: 'skill-tree' | 'domain-map';
+  libraryName?: string;
+  libraryVersion?: string;
+}
+interface IntentArtifactSkill {
+  artifactPath: string;
+  artifactKind: 'skill-tree' | 'domain-map';
+  name?: string;
+  slug?: string;
+  path?: string;
+  package?: string;
+  packages: Array<string>;
+  sources: Array<string>;
+  covers: Array<string>;
+}
+interface IntentArtifactCoverageIgnore {
+  packageName: string;
+  reason?: string;
+  artifactPath: string;
+}
+interface IntentArtifactWarning {
+  artifactPath: string;
+  message: string;
+}
 interface FeedbackPayload {
   skill: string;
   package: string;
@@ -90,4 +143,4 @@ interface IntentProjectConfig {
   };
 }
 //#endregion
-export { IntentProjectConfig as a, ScanResult as c, StalenessReport as d, IntentPackage as i, SkillEntry as l, FeedbackPayload as n, MetaFeedbackPayload as o, IntentConfig as r, MetaSkillName as s, AgentName as t, SkillStaleness as u };
+export { StalenessReport as _, IntentArtifactSet as a, IntentConfig as c, MetaFeedbackPayload as d, MetaSkillName as f, SkillStaleness as g, SkillEntry as h, IntentArtifactFile as i, IntentPackage as l, ScanResult as m, FeedbackPayload as n, IntentArtifactSkill as o, ScanOptions as p, IntentArtifactCoverageIgnore as r, IntentArtifactWarning as s, AgentName as t, IntentProjectConfig as u, StalenessSignal as v, VersionConflict as y };

package/dist/{workspace-patterns-Cndd-7vB.mjs → workspace-patterns-BN2A_60g.mjs}

@@ -162,6 +162,11 @@ function findPackagesWithSkills(root) {
 		return existsSync(skillsDir) && findSkillFiles(skillsDir).length > 0;
 	});
 }
+function findWorkspacePackages(root) {
+	const patterns = readWorkspacePatterns(root);
+	if (!patterns) return [];
+	return resolveWorkspacePackages(root, patterns);
+}
 
 //#endregion
-export { resolveWorkspacePackages as i, findWorkspaceRoot as n, readWorkspacePatterns as r, findPackagesWithSkills as t };
+export { resolveWorkspacePackages as a, readWorkspacePatterns as i, findWorkspacePackages as n, findWorkspaceRoot as r, findPackagesWithSkills as t };

package/dist/workspace-patterns-x-dLZxx4.mjs

@@ -0,0 +1,4 @@
+import "./utils-COlDcU72.mjs";
+import { a as resolveWorkspacePackages, i as readWorkspacePatterns, n as findWorkspacePackages, r as findWorkspaceRoot, t as findPackagesWithSkills } from "./workspace-patterns-BN2A_60g.mjs";
+
+export { findPackagesWithSkills, findWorkspacePackages, findWorkspaceRoot };

package/meta/templates/workflows/check-skills.yml

@@ -1,11 +1,12 @@
 # check-skills.yml — Drop this into your library repo's .github/workflows/
 #
-# Checks for stale intent skills after a release and opens a review PR
-# if any skills need attention. The PR body includes a prompt you can
-# paste into Claude Code, Cursor, or any coding agent to update them.
+# Checks intent skills after a release and opens or updates one review PR when
+# existing skills, artifact coverage, or workspace package coverage need review.
 #
 # Triggers: new release published, or manual workflow_dispatch.
 #
+# intent-workflow-version: 2
+#
 # Template variables (replaced by `intent setup`):
 #   {{PACKAGE_LABEL}} — e.g. @tanstack/query or my-workspace workspace
 
@@ -22,7 +23,7 @@ permissions:
 
 jobs:
   check:
-    name: Check for stale skills
+    name: Check intent skill coverage
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
@@ -38,106 +39,213 @@ jobs:
       - name: Install intent
         run: npm install -g @tanstack/intent
 
-      - name: Check staleness
+      - name: Check skills
         id: stale
         run: |
-          OUTPUT=$(intent stale --json 2>&1) || true
-          echo "$OUTPUT"
-
-          # Check if any skills need review
-          NEEDS_REVIEW=$(echo "$OUTPUT" | node -e "
-            const input = require('fs').readFileSync('/dev/stdin','utf8');
-            try {
-              const reports = JSON.parse(input);
-              const stale = reports.flatMap(r =>
-                r.skills.filter(s => s.needsReview).map(s => ({ library: r.library, skill: s.name, reasons: s.reasons }))
-              );
-              if (stale.length > 0) {
-                console.log(JSON.stringify(stale));
-              }
-            } catch {}
-          ")
-
-          if [ -z "$NEEDS_REVIEW" ]; then
-            echo "has_stale=false" >> "$GITHUB_OUTPUT"
+          set +e
+          intent stale --json > stale.json
+          STATUS=$?
+          set -e
+
+          cat stale.json
+
+          if [ "$STATUS" -ne 0 ]; then
+            echo "has_review=true" >> "$GITHUB_OUTPUT"
+            echo "check_failed=true" >> "$GITHUB_OUTPUT"
+            cat > review-items.json <<'JSON'
+          [
+            {
+              "type": "stale-check-failed",
+              "library": "{{PACKAGE_LABEL}}",
+              "subject": "intent stale --json",
+              "reasons": ["The stale check command failed. Review the workflow logs before updating skills."]
+            }
+          ]
+          JSON
           else
-            echo "has_stale=true" >> "$GITHUB_OUTPUT"
-            # Escape for multiline GH output
-            EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
-            echo "stale_json<<$EOF" >> "$GITHUB_OUTPUT"
-            echo "$NEEDS_REVIEW" >> "$GITHUB_OUTPUT"
-            echo "$EOF" >> "$GITHUB_OUTPUT"
+            node <<'NODE'
+          const fs = require('fs')
+          const reports = JSON.parse(fs.readFileSync('stale.json', 'utf8'))
+          const items = []
+
+          for (const report of reports) {
+            for (const skill of report.skills ?? []) {
+              if (!skill?.needsReview) continue
+              items.push({
+                type: 'stale-skill',
+                library: report.library,
+                subject: skill.name,
+                reasons: skill.reasons ?? [],
+              })
+            }
+
+            for (const signal of report.signals ?? []) {
+              if (signal?.needsReview === false) continue
+              items.push({
+                type: signal?.type ?? 'review-signal',
+                library: signal?.library ?? report.library,
+                subject:
+                  signal?.packageName ??
+                  signal?.packageRoot ??
+                  signal?.skill ??
+                  signal?.artifactPath ??
+                  signal?.subject ??
+                  report.library,
+                reasons: signal?.reasons ?? [],
+                artifactPath: signal?.artifactPath,
+                packageName: signal?.packageName,
+                packageRoot: signal?.packageRoot,
+                skill: signal?.skill,
+              })
+            }
+          }
+
+          fs.writeFileSync('review-items.json', JSON.stringify(items, null, 2) + '\n')
+          fs.appendFileSync(
+            process.env.GITHUB_OUTPUT,
+            `has_review=${items.length > 0 ? 'true' : 'false'}\n`,
+          )
+          NODE
           fi
 
-      - name: Build summary
-        if: steps.stale.outputs.has_stale == 'true'
-        id: summary
-        run: |
-          node -e "
-            const stale = JSON.parse(process.env.STALE_JSON);
-            const lines = stale.map(s =>
-              '- **' + s.skill + '** (' + s.library + '): ' + s.reasons.join(', ')
-            );
-            const summary = lines.join('\n');
-
-            const prompt = [
-              'Review and update the following stale intent skills for {{PACKAGE_LABEL}}:',
-              '',
-              ...stale.map(s => '- ' + s.skill + ': ' + s.reasons.join(', ')),
-              '',
-              'For each stale skill:',
-              '1. Read the current SKILL.md file',
-              '2. Check what changed in the library since the skill was last updated',
-              '3. Update the skill content to reflect current APIs and behavior',
-              '4. Run \`npx @tanstack/intent validate\` to verify the updated skill',
-            ].join('\n');
-
-            // Write outputs
-            const fs = require('fs');
-            const env = fs.readFileSync(process.env.GITHUB_OUTPUT, 'utf8');
-            const eof = require('crypto').randomBytes(15).toString('base64');
-            fs.appendFileSync(process.env.GITHUB_OUTPUT,
-              'summary<<' + eof + '\n' + summary + '\n' + eof + '\n' +
-              'prompt<<' + eof + '\n' + prompt + '\n' + eof + '\n'
-            );
-          "
-        env:
-          STALE_JSON: ${{ steps.stale.outputs.stale_json }}
+          {
+            echo "review_items<<EOF"
+            cat review-items.json
+            echo "EOF"
+          } >> "$GITHUB_OUTPUT"
 
-      - name: Open review PR
-        if: steps.stale.outputs.has_stale == 'true'
+      - name: Write clean summary
+        if: steps.stale.outputs.has_review == 'false'
+        run: |
+          {
+            echo "### Intent skill review"
+            echo ""
+            echo "No stale skills or coverage gaps found."
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Build review PR body
+        if: steps.stale.outputs.has_review == 'true'
+        run: |
+          node <<'NODE'
+          const fs = require('fs')
+          const items = JSON.parse(fs.readFileSync('review-items.json', 'utf8'))
+          const grouped = new Map()
+
+          for (const item of items) {
+            grouped.set(item.type, (grouped.get(item.type) ?? 0) + 1)
+          }
+
+          const signalRows = [...grouped.entries()]
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([type, count]) => `| \`${type}\` | ${count} |`)
+
+          const itemRows = items.map((item) => {
+            const subject = item.subject ? `\`${item.subject}\`` : '-'
+            const reasons = item.reasons?.length ? item.reasons.join('; ') : '-'
+            return `| \`${item.type}\` | ${subject} | \`${item.library}\` | ${reasons} |`
+          })
+
+          const prompt = [
+            'You are helping maintain Intent skills for this repository.',
+            '',
+            'Goal:',
+            'Resolve the Intent skill review signals below while preserving the existing scope, taxonomy, and maintainer-reviewed artifacts.',
+            '',
+            'Review signals:',
+            JSON.stringify(items, null, 2),
+            '',
+            'Required workflow:',
+            '1. Read the existing `_artifacts/*domain_map.yaml`, `_artifacts/*skill_tree.yaml`, and generated `skills/**/SKILL.md` files.',
+            '2. Read each flagged package package.json, public exports, README/docs if present, and source entry points.',
+            '3. Compare flagged packages against the existing domains, skills, tasks, packages, covers, sources, tensions, and cross-references in the artifacts.',
+            '4. For each signal, decide whether it means existing skill coverage, a missing generated skill, a new skill candidate, out-of-scope coverage, or deferred work.',
+            '',
+            'Maintainer questions:',
+            'Before editing skills or artifacts, ask the maintainer:',
+            '1. For each flagged package, is this package user-facing enough to need agent guidance?',
+            '2. If yes, should it extend an existing skill or become a new skill?',
+            '3. If it extends an existing skill, which current skill should own it?',
+            '4. If it is out of scope, what short reason should be recorded in artifact coverage ignores?',
+            '5. Are any of these packages experimental or unstable enough to exclude for now?',
+            '',
+            'Decision rules:',
+            '- Do not auto-generate skills.',
+            '- Do not create broad new skill areas without maintainer confirmation.',
+            '- Prefer adding package coverage to an existing skill when the package is an implementation variant of an existing domain.',
+            '- Create a new skill only when the package introduces a distinct developer task or failure mode.',
+            '- Preserve current naming, path, and package layout conventions.',
+            '- Keep generated skills under the package-local `skills/` directory.',
+            '- Keep repo-root `_artifacts` as the reviewed plan.',
+            '',
+            'If maintainer confirms updates:',
+            '1. Update the relevant `_artifacts/*domain_map.yaml` or `_artifacts/*skill_tree.yaml`.',
+            '2. Update or create `SKILL.md` files only for confirmed coverage changes.',
+            '3. Keep `sources` aligned between artifact skill entries and SKILL frontmatter.',
+            '4. Bump `library_version` only for skills whose covered source package version changed.',
+            '5. Run `npx @tanstack/intent@latest validate` on touched skill directories.',
+            '6. Summarize every package as one of: existing-skill coverage, new skill, ignored, or deferred.',
+          ].join('\n')
+
+          const body = [
+            '## Intent Skill Review Needed',
+            '',
+            'Intent found skills, artifact coverage, or workspace package coverage that need maintainer review.',
+            '',
+            '### Summary',
+            '',
+            '| Signal | Count |',
+            '| --- | ---: |',
+            ...signalRows,
+            '',
+            '### Review Items',
+            '',
+            '| Signal | Subject | Library | Reason |',
+            '| --- | --- | --- | --- |',
+            ...itemRows,
+            '',
+            '### Agent Prompt',
+            '',
+            'Paste this into your coding agent:',
+            '',
+            '```text',
+            prompt,
+            '```',
+            '',
+            'This PR is a review reminder only. It does not update skills automatically.',
+          ].join('\n')
+
+          fs.writeFileSync('pr-body.md', body + '\n')
+          fs.writeFileSync(process.env.GITHUB_STEP_SUMMARY, body + '\n')
+          NODE
+
+      - name: Open or update review PR
+        if: steps.stale.outputs.has_review == 'true'
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           VERSION="${{ github.event.release.tag_name || 'manual' }}"
           BRANCH="skills/review-${VERSION}"
+          BASE_BRANCH="${{ github.event.repository.default_branch }}"
 
           git config user.name "github-actions[bot]"
           git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-          git checkout -b "$BRANCH"
-          git commit --allow-empty -m "chore: review stale skills for ${VERSION}"
-          git push origin "$BRANCH"
-
-          gh pr create \
-            --title "Review stale skills (${VERSION})" \
-            --body "$(cat <<'PREOF'
-          ## Stale Skills Detected
-
-          The following skills may need updates after the latest release:
-
-          ${{ steps.summary.outputs.summary }}
 
-          ---
-
-          ### Update Prompt
-
-          Paste this into your coding agent (Claude Code, Cursor, etc.):
-
-          ~~~
-          ${{ steps.summary.outputs.prompt }}
-          ~~~
+          git fetch origin "$BRANCH" || true
+          if git show-ref --verify --quiet "refs/remotes/origin/$BRANCH"; then
+            git checkout -B "$BRANCH" "origin/$BRANCH"
+          else
+            git checkout -b "$BRANCH"
+            git commit --allow-empty -m "chore: review intent skills for ${VERSION}"
+            git push origin "$BRANCH"
+          fi
 
-          PREOF
-          )" \
-            --head "$BRANCH" \
-            --base main
+          PR_URL="$(gh pr list --head "$BRANCH" --json url --jq '.[0].url')"
+          if [ -n "$PR_URL" ]; then
+            gh pr edit "$PR_URL" --body-file pr-body.md
+          else
+            gh pr create \
+              --title "Review intent skills (${VERSION})" \
+              --body-file pr-body.md \
+              --head "$BRANCH" \
+              --base "$BASE_BRANCH"
+          fi