@tanstack/intent 0.0.9 → 0.0.12

package/README.md

@@ -2,15 +2,21 @@
 
 Ship compositional knowledge for AI coding agents alongside your npm packages.
 
-Skills are npm packages of knowledge — encoding how tools work together, what patterns apply for which goals, and what to avoid. Skills travel with the tool via `npm update`, not the model's training cutoff.
+## The problem
 
-`@tanstack/intent` is the toolkit for generating, discovering, and maintaining skills for your library.
+Your docs are good. Your types are solid. Your agent still gets it wrong.
 
-## Install
+Docs target humans who browse. Types check individual API calls but can't encode intent. Training data snapshots the ecosystem as it _was_, mixing versions without flagging which applies. Once a breaking change ships, models contain _both_ versions forever with no way to disambiguate.
 
-```bash
-pnpm add -D @tanstack/intent
-```
+The ecosystem already moves toward agent-readable knowledge — Cursor rules, CLAUDE.md files, skills directories. But delivery is stuck in copy-paste: hunt for a community-maintained rules file, paste it into your config, repeat for every tool. No versioning, no update path, no staleness signal.
+
+## Skills: the fourth artifact
+
+You ship code, docs, and types. Skills are the fourth artifact — knowledge encoded for the thing writing most of your code.
+
+Skills are npm packages of knowledge — encoding how tools compose, which patterns fit which goals, and what to avoid. When a library ships skills using `@tanstack/intent`, that knowledge travels with the tool via `npm update` — not the model's training cutoff. Versioned knowledge the maintainer owns, updated when the package updates.
+
+Each skill declares its source docs. When those docs change, the CLI flags the skill for review. One source of truth, one derived artifact that stays in sync.
 
 ## Quick Start
 
@@ -22,6 +28,8 @@ Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .
 npx @tanstack/intent install
 ```
 
+No per-library setup. No hunting for rules files. Install the package, run `intent install`, and the agent understands the tool. Update the package, and skills update too.
+
 List available skills from installed packages:
 
 ```bash
@@ -44,23 +52,36 @@ Validate your skill files:
 npx @tanstack/intent validate
 ```
 
-Copy CI workflow templates into your repo:
+Check for skills that have fallen behind their sources:
+
+```bash
+npx @tanstack/intent stale
+```
+
+Copy CI workflow templates into your repo so validation and staleness checks run on every push:
 
 ```bash
 npx @tanstack/intent setup
 ```
 
+## Keeping skills current
+
+The real risk with any derived artifact is staleness. `npx @tanstack/intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
+
+The feedback loop runs both directions. `npx @tanstack/intent 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 `npm update`.
+
 ## CLI Commands
 
-| Command                 | Description                                         |
-| ----------------------- | --------------------------------------------------- |
-| `intent install`        | Set up skill-to-task mappings in agent config files |
-| `intent list [--json]`  | Discover intent-enabled packages                    |
-| `intent meta`           | List meta-skills for library maintainers            |
-| `intent scaffold`       | Print the guided skill generation prompt            |
-| `intent validate [dir]` | Validate SKILL.md files                             |
-| `intent setup`          | Copy CI templates, generate shim, create labels     |
-| `intent stale [--json]` | Check skills for version drift                      |
+| Command                               | Description                                         |
+| ------------------------------------- | --------------------------------------------------- |
+| `npx @tanstack/intent install`        | Set up skill-to-task mappings in agent config files |
+| `npx @tanstack/intent list [--json]`  | Discover intent-enabled packages                    |
+| `npx @tanstack/intent meta`           | List meta-skills for library maintainers            |
+| `npx @tanstack/intent scaffold`       | Print the guided skill generation prompt            |
+| `npx @tanstack/intent validate [dir]` | Validate SKILL.md files                             |
+| `npx @tanstack/intent setup`          | Copy CI templates, generate shim, create labels     |
+| `npx @tanstack/intent stale [--json]` | Check skills for version drift                      |
+| `npx @tanstack/intent feedback`       | Submit skill feedback                               |
 
 ## License
 

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
+import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
 import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
@@ -101,7 +101,7 @@ function collectPackagingWarnings(root) {
 	if (!pkgJson.bin?.intent) warnings.push("Missing \"bin\": { \"intent\": ... } entry in package.json");
 	const shimJs = join(root, "bin", "intent.js");
 	const shimMjs = join(root, "bin", "intent.mjs");
-	if (!existsSync(shimJs) && !existsSync(shimMjs)) warnings.push("No bin/intent.js or bin/intent.mjs shim found (run: npx @tanstack/intent setup --shim)");
+	if (!existsSync(shimJs) && !existsSync(shimMjs)) warnings.push("No bin/intent.js or bin/intent.mjs shim found (run: npx @tanstack/intent add-library-bin)");
 	const files = pkgJson.files;
 	if (Array.isArray(files)) {
 		if (!files.includes("skills")) warnings.push("\"skills\" is not in the \"files\" array — skills won't be published");
@@ -287,12 +287,11 @@ This produces: individual SKILL.md files.
 
 1. Run \`npx @tanstack/intent validate\` in each package directory
 2. Commit skills/ and artifacts
-3. For each publishable package, run: \`npx @tanstack/intent setup --shim\`
-4. Ensure each package has \`@tanstack/intent\` as a devDependency
-5. Add \`"skills"\`, \`"bin"\` to the \`"files"\` array in each package.json
-6. Add \`"!skills/_artifacts"\` to exclude artifacts from publishing
-7. Create a \`feedback:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
-8. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent install\`"
+3. For each publishable package, run: \`npx @tanstack/intent add-library-bin\`
+4. For each publishable package, run: \`npx @tanstack/intent edit-package-json\`
+5. Ensure each package has \`@tanstack/intent\` as a devDependency
+6. Create a \`feedback:<skill-name>\` label on the GitHub repo for each skill (use \`gh label create\`)
+7. Add a README note: "If you use an AI agent, run \`npx @tanstack/intent install\`"
 `;
 	console.log(prompt);
 }
@@ -304,7 +303,9 @@ Usage:
   intent validate [<dir>]        Validate skill files (default: skills/)
   intent install                  Print a skill that guides your coding agent to set up skill-to-task mappings
   intent scaffold                Print maintainer scaffold prompt
-  intent setup [--workflows] [--shim] [--all]  Copy CI templates and generate shim
+  intent add-library-bin         Generate bin/intent.{js,mjs} bridge file
+  intent edit-package-json       Wire package.json (files, bin) for skill publishing
+  intent setup-github-actions    Copy CI workflow templates to .github/workflows/
   intent stale                   Check skills for staleness`;
 const command = process.argv[2];
 const commandArgs = process.argv.slice(3);
@@ -371,7 +372,7 @@ skills:
 		break;
 	case "stale": {
 		const { checkStaleness } = await import("./staleness-B5gUj7FR.mjs");
-		const { scanForIntents: scanStale } = await import("./scanner-DkShtCWX.mjs");
+		const { scanForIntents: scanStale } = await import("./scanner-DQeiZRzp.mjs");
 		let staleResult;
 		try {
 			staleResult = await scanStale();
@@ -402,9 +403,19 @@ skills:
 		}
 		break;
 	}
-	case "setup": {
-		const { runSetup } = await import("./setup.mjs");
-		runSetup(process.cwd(), getMetaDir(), commandArgs);
+	case "add-library-bin": {
+		const { runAddLibraryBin } = await import("./setup.mjs");
+		runAddLibraryBin(process.cwd());
+		break;
+	}
+	case "edit-package-json": {
+		const { runEditPackageJson } = await import("./setup.mjs");
+		runEditPackageJson(process.cwd());
+		break;
+	}
+	case "setup-github-actions": {
+		const { runSetupGithubActions } = await import("./setup.mjs");
+		runSetupGithubActions(process.cwd(), getMetaDir());
 		break;
 	}
 	default:

package/dist/index.d.mts

@@ -1,5 +1,5 @@
 import { a as IntentProjectConfig, c as ScanResult, d as StalenessReport, i as IntentPackage, l as SkillEntry, n as FeedbackPayload, o as MetaFeedbackPayload, r as IntentConfig, s as MetaSkillName, t as AgentName, u as SkillStaleness } from "./types-BmnI8kFB.mjs";
-import { n as runSetup } from "./setup-BJ4giTKA.mjs";
+import { a as runEditPackageJson, i as runAddLibraryBin, n as EditPackageJsonResult, o as runSetupGithubActions, r as SetupGithubActionsResult, t as AddLibraryBinResult } from "./setup-CANkTz55.mjs";
 
 //#region src/scanner.d.ts
 declare function scanForIntents(root?: string): Promise<ScanResult>;
@@ -44,4 +44,4 @@ declare function findSkillFiles(dir: string): string[];
  */
 declare function parseFrontmatter(filePath: string): Record<string, unknown> | null;
 //#endregion
-export { type AgentName, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { type AddLibraryBinResult, type AgentName, type EditPackageJsonResult, type FeedbackPayload, type IntentConfig, type IntentPackage, type IntentProjectConfig, type MetaFeedbackPayload, type MetaSkillName, type ScanResult, type SetupGithubActionsResult, type SkillEntry, type SkillStaleness, type StalenessReport, checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/index.mjs

@@ -1,7 +1,7 @@
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
+import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
 import { t as checkStaleness } from "./staleness-lP6B0O4z.mjs";
-import { t as runSetup } from "./setup-DGvdyKEq.mjs";
+import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-BYOg-Ii-.mjs";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { execFileSync, execSync } from "node:child_process";
@@ -246,4 +246,4 @@ function submitMetaFeedback(payload, opts) {
 }
 
 //#endregion
-export { checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };
+export { checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runAddLibraryBin, runEditPackageJson, runSetupGithubActions, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/scanner-DQeiZRzp.mjs

@@ -0,0 +1,4 @@
+import "./utils-DH3jY3CI.mjs";
+import { t as scanForIntents } from "./scanner-dIYdkHQ1.mjs";
+
+export { scanForIntents };

package/dist/{scanner-OmHt14bs.mjs → scanner-dIYdkHQ1.mjs}

@@ -125,7 +125,7 @@ async function scanForIntents(root) {
 		};
 	}
 	for (const entry of topEntries) {
-		if (!entry.isDirectory()) continue;
+		if (!entry.isDirectory() && !entry.isSymbolicLink()) continue;
 		const dirPath = join(nodeModulesDir, entry.name);
 		if (entry.name.startsWith("@")) {
 			let scopedEntries;
@@ -138,7 +138,7 @@ async function scanForIntents(root) {
 				continue;
 			}
 			for (const scoped of scopedEntries) {
-				if (!scoped.isDirectory()) continue;
+				if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue;
 				packageDirs.push({ dirPath: join(dirPath, scoped.name) });
 			}
 		} else if (!entry.name.startsWith(".")) packageDirs.push({ dirPath });

package/dist/setup-BYOg-Ii-.mjs

@@ -0,0 +1,197 @@
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+//#region src/setup.ts
+function detectVars(root) {
+	const pkgPath = join(root, "package.json");
+	let pkgJson = {};
+	try {
+		pkgJson = JSON.parse(readFileSync(pkgPath, "utf8"));
+	} catch (err) {
+		if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) console.error(`Warning: could not read ${pkgPath}: ${err instanceof Error ? err.message : err}`);
+	}
+	const name = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
+	const intent = pkgJson.intent;
+	const repo = typeof intent?.repo === "string" ? intent.repo : name.replace(/^@/, "").replace(/\//, "/");
+	const docs = typeof intent?.docs === "string" ? intent.docs : "docs/";
+	let srcPath = `packages/${name.replace(/^@[^/]+\//, "")}/src/**`;
+	if (existsSync(join(root, "src"))) srcPath = "src/**";
+	return {
+		PACKAGE_NAME: name,
+		REPO: repo,
+		DOCS_PATH: docs.endsWith("**") ? docs : docs.replace(/\/$/, "") + "/**",
+		SRC_PATH: srcPath
+	};
+}
+function applyVars(content, vars) {
+	return content.replace(/\{\{PACKAGE_NAME\}\}/g, vars.PACKAGE_NAME).replace(/\{\{REPO\}\}/g, vars.REPO).replace(/\{\{DOCS_PATH\}\}/g, vars.DOCS_PATH).replace(/\{\{SRC_PATH\}\}/g, vars.SRC_PATH);
+}
+function copyTemplates(srcDir, destDir, vars) {
+	const copied = [];
+	const skipped = [];
+	if (!existsSync(srcDir)) return {
+		copied,
+		skipped
+	};
+	mkdirSync(destDir, { recursive: true });
+	for (const entry of readdirSync(srcDir)) {
+		const srcPath = join(srcDir, entry);
+		const destPath = join(destDir, entry);
+		if (existsSync(destPath)) {
+			skipped.push(destPath);
+			continue;
+		}
+		writeFileSync(destPath, applyVars(readFileSync(srcPath, "utf8"), vars));
+		copied.push(destPath);
+	}
+	return {
+		copied,
+		skipped
+	};
+}
+function getShimContent(ext) {
+	return `#!/usr/bin/env node
+// Auto-generated by @tanstack/intent setup
+// Exposes the intent end-user CLI for consumers of this library.
+// Commit this file, then add to your package.json:
+//   "bin": { "intent": "./bin/intent.${ext}" }
+await import('@tanstack/intent/intent-library')
+`;
+}
+function detectShimExtension(root) {
+	try {
+		if (JSON.parse(readFileSync(join(root, "package.json"), "utf8")).type === "module") return "js";
+	} catch (err) {
+		if (!(err && typeof err === "object" && "code" in err && err.code === "ENOENT")) console.error(`Warning: could not read package.json: ${err instanceof Error ? err.message : err}`);
+	}
+	return "mjs";
+}
+function findExistingShim(root) {
+	const shimJs = join(root, "bin", "intent.js");
+	if (existsSync(shimJs)) return shimJs;
+	const shimMjs = join(root, "bin", "intent.mjs");
+	if (existsSync(shimMjs)) return shimMjs;
+	return null;
+}
+function runAddLibraryBin(root) {
+	const result = {
+		shim: null,
+		skipped: null
+	};
+	const existingShim = findExistingShim(root);
+	if (existingShim) {
+		result.skipped = existingShim;
+		console.log(`  Already exists: ${existingShim}`);
+		return result;
+	}
+	const ext = detectShimExtension(root);
+	const shimPath = join(root, "bin", `intent.${ext}`);
+	mkdirSync(join(root, "bin"), { recursive: true });
+	writeFileSync(shimPath, getShimContent(ext));
+	result.shim = shimPath;
+	console.log(`✓ Generated intent shim: ${shimPath}`);
+	console.log(`\n  Run \`npx @tanstack/intent edit-package-json\` to wire package.json.`);
+	return result;
+}
+function runEditPackageJson(root) {
+	const result = {
+		added: [],
+		alreadyPresent: []
+	};
+	const pkgPath = join(root, "package.json");
+	if (!existsSync(pkgPath)) {
+		console.error("No package.json found in " + root);
+		process.exitCode = 1;
+		return result;
+	}
+	const raw = readFileSync(pkgPath, "utf8");
+	let pkg;
+	try {
+		pkg = JSON.parse(raw);
+	} catch (err) {
+		const detail = err instanceof SyntaxError ? err.message : String(err);
+		console.error(`Failed to parse ${pkgPath}: ${detail}`);
+		return result;
+	}
+	const indentMatch = raw.match(/^(\s+)"/m);
+	const indentSize = indentMatch?.[1] ? indentMatch[1].length : 2;
+	if (!Array.isArray(pkg.files)) pkg.files = [];
+	const files = pkg.files;
+	const requiredFiles = (() => {
+		let dir = join(root, "..");
+		for (let i = 0; i < 5; i++) {
+			const parentPkg = join(dir, "package.json");
+			if (existsSync(parentPkg)) {
+				try {
+					const parent = JSON.parse(readFileSync(parentPkg, "utf8"));
+					if (Array.isArray(parent.workspaces) || parent.workspaces?.packages) return true;
+				} catch {}
+				return false;
+			}
+			const next = join(dir, "..");
+			if (next === dir) break;
+			dir = next;
+		}
+		return false;
+	})() ? ["skills", "bin"] : [
+		"skills",
+		"bin",
+		"!skills/_artifacts"
+	];
+	for (const entry of requiredFiles) if (files.includes(entry)) result.alreadyPresent.push(`files: "${entry}"`);
+	else {
+		files.push(entry);
+		result.added.push(`files: "${entry}"`);
+	}
+	const existingShim = findExistingShim(root);
+	let ext;
+	if (existingShim) ext = existingShim.endsWith(".mjs") ? "mjs" : "js";
+	else ext = pkg.type === "module" ? "js" : "mjs";
+	const shimRelative = `./bin/intent.${ext}`;
+	if (typeof pkg.bin === "object" && pkg.bin !== null) {
+		const binObj = pkg.bin;
+		if (binObj.intent) result.alreadyPresent.push(`bin.intent`);
+		else {
+			binObj.intent = shimRelative;
+			result.added.push(`bin.intent: "${shimRelative}"`);
+		}
+	} else if (!pkg.bin) {
+		pkg.bin = { intent: shimRelative };
+		result.added.push(`bin.intent: "${shimRelative}"`);
+	} else if (typeof pkg.bin === "string") {
+		const pkgName = typeof pkg.name === "string" ? pkg.name.replace(/^@[^/]+\//, "") : "unknown";
+		pkg.bin = {
+			[pkgName]: pkg.bin,
+			intent: shimRelative
+		};
+		result.added.push(`bin.intent: "${shimRelative}" (converted bin from string to object)`);
+	}
+	writeFileSync(pkgPath, JSON.stringify(pkg, null, indentSize) + "\n");
+	for (const a of result.added) console.log(`✓ Added ${a}`);
+	for (const a of result.alreadyPresent) console.log(`  Already present: ${a}`);
+	return result;
+}
+function runSetupGithubActions(root, metaDir) {
+	const vars = detectVars(root);
+	const result = {
+		workflows: [],
+		skipped: []
+	};
+	const { copied, skipped } = copyTemplates(join(metaDir, "templates", "workflows"), join(root, ".github", "workflows"), vars);
+	result.workflows = copied;
+	result.skipped = skipped;
+	for (const f of result.workflows) console.log(`✓ Copied workflow: ${f}`);
+	for (const f of result.skipped) console.log(`  Already exists: ${f}`);
+	if (result.workflows.length === 0 && result.skipped.length === 0) console.log("No templates directory found. Is @tanstack/intent installed?");
+	else if (result.workflows.length > 0) {
+		console.log(`\nTemplate variables applied:`);
+		console.log(`  Package:  ${vars.PACKAGE_NAME}`);
+		console.log(`  Repo:     ${vars.REPO}`);
+		console.log(`  Docs:     ${vars.DOCS_PATH}`);
+		console.log(`  Src:      ${vars.SRC_PATH}`);
+	}
+	return result;
+}
+
+//#endregion
+export { runEditPackageJson as n, runSetupGithubActions as r, runAddLibraryBin as t };

package/dist/setup-CANkTz55.d.mts

@@ -0,0 +1,18 @@
+//#region src/setup.d.ts
+interface AddLibraryBinResult {
+  shim: string | null;
+  skipped: string | null;
+}
+interface EditPackageJsonResult {
+  added: string[];
+  alreadyPresent: string[];
+}
+interface SetupGithubActionsResult {
+  workflows: string[];
+  skipped: string[];
+}
+declare function runAddLibraryBin(root: string): AddLibraryBinResult;
+declare function runEditPackageJson(root: string): EditPackageJsonResult;
+declare function runSetupGithubActions(root: string, metaDir: string): SetupGithubActionsResult;
+//#endregion
+export { runEditPackageJson as a, runAddLibraryBin as i, EditPackageJsonResult as n, runSetupGithubActions as o, SetupGithubActionsResult as r, AddLibraryBinResult as t };

package/dist/setup.d.mts

@@ -1,2 +1,2 @@
-import { n as runSetup, t as SetupResult } from "./setup-BJ4giTKA.mjs";
-export { SetupResult, runSetup };
+import { a as runEditPackageJson, i as runAddLibraryBin, n as EditPackageJsonResult, o as runSetupGithubActions, r as SetupGithubActionsResult, t as AddLibraryBinResult } from "./setup-CANkTz55.mjs";
+export { AddLibraryBinResult, EditPackageJsonResult, SetupGithubActionsResult, runAddLibraryBin, runEditPackageJson, runSetupGithubActions };

package/dist/setup.mjs

@@ -1,3 +1,3 @@
-import { t as runSetup } from "./setup-DGvdyKEq.mjs";
+import { n as runEditPackageJson, r as runSetupGithubActions, t as runAddLibraryBin } from "./setup-BYOg-Ii-.mjs";
 
-export { runSetup };
+export { runAddLibraryBin, runEditPackageJson, runSetupGithubActions };

package/meta/domain-discovery/SKILL.md

@@ -42,9 +42,12 @@ path applies (see below).
 
 ### Lightweight path (small libraries)
 
-After Phase 1, if the library has **fewer than 5 client-facing skill
-areas** (e.g. a focused utility library, a single-purpose tool, or a
-library with only 2–3 distinct developer tasks), use a compressed flow:
+After Phase 1, decide whether the library warrants the full five-phase
+flow or the compressed flow below. This is a judgment call — lean toward
+full discovery unless the library is obviously small (single-purpose
+utility, 2–3 distinct developer tasks max). Use a compressed flow when
+the skill surface is small enough that two interview rounds would be
+redundant:
 
 1. **Phase 1** — Quick scan (same as full flow)
 2. **Phase 2+4 combined** — Single interview round. Combine the
@@ -59,6 +62,42 @@ The lightweight path produces identical output artifacts (domain_map.yaml
 and skill_spec.md). It just avoids two separate interview rounds when the
 library is small enough that one round covers everything.
 
+### Hard rules — interview phases are mandatory and interactive
+
+These rules override any other reasoning. No exceptions.
+
+1. **Phases 2 and 4 are interactive interviews conducted with the
+   maintainer.** You must ask the questions specified in each sub-section
+   and wait for the maintainer's response before continuing. Documentation,
+   source code, and other automated analysis are NOT substitutes for the
+   maintainer's answers.
+2. **Every question in Phases 2 and 4 must be asked as an open-ended
+   question and sent as a message to the maintainer.** You must then
+   STOP and WAIT for their reply. Do not answer your own questions. Do
+   not infer answers from documentation. Do not skip questions because
+   you believe you already know the answer.
+3. **Do not convert open-ended questions into multiple-choice,
+   yes/no, or confirmation prompts.** The question templates in each
+   sub-section are open-ended by design. Present them as open-ended
+   questions. The maintainer's unprompted answers surface knowledge that
+   pre-structured options suppress.
+4. **Minimum question counts are enforced.** Each sub-section specifies
+   a question count range (e.g. "2–4 questions"). You must ask at least
+   the minimum number. Asking zero questions in any sub-section is a
+   protocol violation.
+5. **STOP gates are mandatory.** At the boundaries marked `── STOP ──`
+   below, you must halt execution and wait for the maintainer's response
+   or acknowledgment before proceeding. Do not continue past a STOP gate
+   in the same message.
+6. **If the maintainer asks to skip an interview phase**, explain the
+   value of the phase and what will be lost. Proceed with skipping only
+   if they confirm a second time.
+7. **Rich documentation makes interviews MORE valuable, not less.**
+   When docs are comprehensive, the interview surfaces what docs miss:
+   implicit knowledge, AI-specific failure modes, undocumented tradeoffs,
+   and the maintainer's prioritization of what matters most. Never
+   rationalize skipping interviews because documentation is thorough.
+
 ---
 
 ## Phase 1 — Quick scan (autonomous, ~10 minutes)
@@ -105,20 +144,37 @@ Log (but do not group yet):
 - Which frameworks it supports
 - Any existing skill files, agent configs, or intents
 - Whether the library is a monorepo and which packages matter
+- Peer dependency constraints — read `peerDependencies` and
+  `peerDependenciesMeta` from each client-facing package.json to
+  understand version ranges and optional integrations early
+
+Present your initial impressions to the maintainer as a brief summary
+(3–5 bullets). This orients them on what you found and primes them for
+the interview.
+
+**── STOP ── Do not proceed to Phase 2 until the maintainer has
+acknowledged your summary or responded.**
 
 ---
 
-## Phase 2 — High-level interview
+## Phase 2 — High-level interview (interactive — requires maintainer)
 
 The maintainer's mental model of developer tasks IS the skill map. Your
 job in this phase is to extract it — not to propose your own structure.
 
+You must ask the questions below to the maintainer and wait for their
+responses. Do not infer answers from documentation or source code.
+
 ### Rules for Phase 2
 
 1. One topic per message for open-ended questions. You may batch 2–3
    yes/no or short-confirmation questions together.
-2. Take notes silently. Do not summarize back unless asked.
-3. If the maintainer gives a short answer, probe deeper before moving on.
+2. Ask each question as written (you may adapt phrasing to context, but
+   keep questions open-ended — never convert to multiple-choice).
+3. Wait for the maintainer's response after each question before asking
+   the next.
+4. Take notes silently. Do not summarize back unless asked.
+5. If the maintainer gives a short answer, probe deeper before moving on.
 
 ### 2a — Developer tasks (2–4 questions)
 
@@ -135,6 +191,13 @@ Follow up to enumerate distinct tasks:
 > things like 'set up the client', 'implement auth', 'debug sync issues'
 > — each one a separate moment where they'd want focused guidance."
 
+For monorepo libraries, also ask about cross-package tasks:
+
+> "Are there tasks that touch multiple packages in your monorepo? For
+> example, a getting-started flow that requires imports from both the
+> client and server packages? I want to make sure skills that span
+> package boundaries are captured correctly."
+
 ### 2b — Developer journeys (1–2 questions)
 
 Surface lifecycle/journey skills that cross-cut task areas:
@@ -144,13 +207,22 @@ Surface lifecycle/journey skills that cross-cut task areas:
 > a migrate-from-v4 walkthrough. Which of these exist in your docs
 > or would be valuable as standalone skills?"
 
-### 2c — Composition and ecosystem (1–2 questions)
+### 2c — Composition and ecosystem (1–3 questions)
 
 > "Which other libraries does yours compose with most often? Are there
 > integration patterns important enough to warrant their own skill —
 > for example, using your library with [framework/ORM/router]?"
 
-### 2d — Confirm initial skill map
+> "Are there tasks that developers might expect your library to handle,
+> but that are actually handled by a companion library? Which tasks
+> should we explicitly exclude from your library's skills?"
+
+### 2d — Exclude experimental features (1 question)
+
+> "Are there any features that are experimental, unstable, or not yet
+> ready to document for agents? We'll exclude these from the skill set."
+
+### 2e — Confirm initial skill map
 
 Synthesize what you heard into a proposed skill list and present it:
 
@@ -158,6 +230,9 @@ Synthesize what you heard into a proposed skill list and present it:
 > [enumerate skills with one-line descriptions]. Does this match how
 > you think about your library? What would you add, remove, or rename?"
 
+**── STOP ── Do not proceed to Phase 3 until the maintainer has
+reviewed and confirmed (or corrected) the skill list.**
+
 ---
 
 ## Phase 3 — Deep read (autonomous)
@@ -170,7 +245,14 @@ gotchas.
 
 Read in this order. Each step builds context for the next.
 
-1. **Every narrative guide** — the how-to content, not API reference tables
+Before starting, list every file in the docs directory (and subdirectories).
+Use this list as a checklist — every narrative file must be read. Do not
+sample a subset and extrapolate.
+
+1. **Narrative guides** — read as many as needed to build confidence in
+   your understanding. Prioritize getting-started, migration, and guides
+   covering the skill areas from Phase 2. Skip exhaustive reading of large
+   online-only doc sets.
 2. **Migration guides** — highest-yield source for failure modes; every
    breaking change is exactly what agents trained on older versions produce
 3. **API reference** — scan for exports, type signatures, option shapes
@@ -417,20 +499,35 @@ Present the draft to the maintainer before starting Phase 4:
 > [N] skills and [M] failure modes. I've flagged [K] specific gaps where
 > I need your input."
 
+Include the full draft domain_map.yaml in your message so the maintainer
+can review it. Also include a checklist of all docs files you read.
+
+**── STOP ── Do not proceed to Phase 4 until the maintainer has
+reviewed the draft and responded. Their feedback on the draft informs
+the detail interview questions.**
+
 ---
 
-## Phase 4 — Detail interview (builds on Phase 1–3)
+## Phase 4 — Detail interview (interactive — requires maintainer)
 
 You have the maintainer's task map and a deep read. The interview now
 fills gaps, validates your understanding, and surfaces implicit knowledge.
 
+You must ask the questions below to the maintainer and wait for their
+responses. Do not infer answers from documentation or source code —
+even for gaps you think you can answer from your reading.
+
 ### Rules for Phase 4
 
 1. One topic per message for open-ended questions. You may batch 2–3
    yes/no or short-confirmation questions together.
-2. Each question must reference something specific from your reading.
-3. If the maintainer gives a short answer, probe deeper before moving on.
-4. Take notes silently. Do not summarize back unless asked.
+2. Ask each question as written (you may adapt phrasing to context, but
+   keep questions open-ended — never convert to multiple-choice).
+3. Each question must reference something specific from your reading.
+4. Wait for the maintainer's response after each question before asking
+   the next.
+5. If the maintainer gives a short answer, probe deeper before moving on.
+6. Take notes silently. Do not summarize back unless asked.
 
 ### 4a — Draft review (2–3 questions)
 
@@ -538,6 +635,10 @@ Merge interview findings into the draft. For each interview answer:
 4. If it reveals a new skill — add it
 5. If it fills a gap — remove from gaps section
 
+Validate the domain_map.yaml by parsing it with a YAML parser. Check for
+duplicate keys, invalid syntax, and structural correctness. Fix any issues
+before presenting the final artifact.
+
 Update `status: draft` to `status: reviewed`.
 
 ---
@@ -580,6 +681,9 @@ skills:
     domain: '[parent domain slug]'
     description: '[what a developer is doing — matches a specific task/moment]'
     type: '[core | framework | lifecycle | composition]'
+    packages: # required for monorepo; omit for single-package libraries
+      - '[primary package name]'
+      - '[secondary package name, if skill spans multiple packages]'
     covers:
       - '[API/hook/concept 1]'
       - '[API/hook/concept 2]'
@@ -710,6 +814,11 @@ not promotional.]
 | ------------------------------------- | -------------------------------------------------------------------------- |
 | Quick scan before interview           | Never interview without at least reading README and package structure      |
 | High-level interview before deep read | The maintainer's task map informs what you read deeply                     |
+| **Interview phases are interactive**  | Phases 2 and 4 require sending questions to the maintainer and waiting     |
+| **Docs are not a substitute**         | Documentation cannot replace maintainer answers — even comprehensive docs  |
+| **Open-ended questions stay open**    | Never convert interview questions to multiple-choice or yes/no             |
+| **Minimum question counts enforced**  | Each sub-section's minimum count must be met; zero questions = violation   |
+| **STOP gates are mandatory**          | Do not proceed past a STOP gate without maintainer response                |
 | Batch only confirmations              | Yes/no questions may batch 2–3; open-ended questions get their own message |
 | Questions reference findings          | No generic questions — cite what you found                                 |
 | Skills are task-focused               | Each skill matches a developer moment, not a conceptual area               |
@@ -719,6 +828,7 @@ not promotional.]
 | No marketing prose                    | Library description is factual, not promotional                            |
 | domain_map.yaml is valid YAML         | Parseable by any YAML parser                                               |
 | Draft before detail interview         | Present draft for review before Phase 4                                    |
+| **Draft reviewed before Phase 4**     | Maintainer must acknowledge or respond to draft before detail interview    |
 | Agent-specific failures probed        | Always ask AI-agent-specific questions in Phase 4c                         |
 | Compositions discovered from code     | Scan peer deps and examples before asking composition questions            |
 | Cross-skill failure modes tagged      | Failure modes spanning skills list all relevant slugs                      |
@@ -727,6 +837,7 @@ not promotional.]
 | Dense surfaces flagged                | Topics with >10 patterns noted as reference_candidates                     |
 | Lifecycle skills considered           | Suggest journey skills when docs have the material                         |
 | Cross-references mapped               | Skills that illuminate each other get "See also" pointers                  |
+| **All docs files read**               | List docs directory contents and read every narrative file — no sampling   |
 
 ---
 
@@ -736,49 +847,16 @@ This skill is designed to produce consistent results across Claude, GPT-4+,
 Gemini, and open-source models. To achieve this:
 
 - All instructions use imperative sentences, not suggestions
+- Interview phases use explicit STOP gates to prevent models from
+  continuing autonomously past interactive checkpoints
+- Hard rules at the top override any model tendency to rationalize
+  skipping interactive phases when documentation is available
+- Open-ended questions are explicitly protected from conversion to
+  multiple-choice or confirmation prompts, which models default to
+  when they have enough context to pre-populate answers
 - Output formats use YAML (universally parsed) and Markdown tables
   (universally rendered)
 - Examples use concrete values, not placeholders like "[your value here]"
 - Section boundaries use Markdown headers (##) for navigation and --- for
   phase separation
 - No model-specific features (no XML tags in output, no tool_use assumptions)
-
----
-
-## Meta-skill feedback (alpha default)
-
-After finalizing artifacts, create or update a single Markdown feedback draft
-for all three meta skills used in scaffolding. Use this exact template and
-fill only the **Domain Discovery** section now. Leave the other sections in
-place for later steps to complete.
-
-```
-# Intent Meta Skill Feedback
-
-## Domain Discovery
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Tree Generator
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Generate Skill
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Context (optional)
-- Library:
-- Repo:
-- Docs:
-- Notes:
-```
-
-Do not submit feedback yet. Tell the maintainer to carry this draft forward
-to the next meta skill step.

package/meta/feedback-collection/SKILL.md

@@ -17,6 +17,12 @@ Run this at the end of any session where you loaded one or more SKILL.md files.
 The goal is to capture what worked, what didn't, and what was missing — so skill
 maintainers can improve future versions.
 
+This skill also covers **meta-skill feedback** — feedback about the scaffolding
+process itself. When invoked after running domain-discovery, tree-generator, and
+generate-skill, treat those three meta skills as the "skills" being evaluated.
+Capture what worked and what didn't in each scaffolding phase so the meta skills
+can be improved.
+
 ---
 
 ## Phase 1 — Automated Signal Collection
@@ -145,6 +151,27 @@ Determine the target repo from the skill's package. The repo is typically
 derivable from the `repository` field in the package's `package.json`, or
 from the `sources` field in the SKILL.md frontmatter.
 
+### Privacy check
+
+Before submitting, determine whether the user's project is public or private.
+Check with `gh repo view --json visibility` or look for a `private` field in
+the project's `package.json`. If you can't determine visibility, assume private.
+
+**Private repos:** Feedback is submitted to a public issue tracker, so it must
+not contain project-specific details. Before submission:
+
+1. Strip any project-specific code, file paths, internal API names, service
+   URLs, or business logic from all fields
+2. Rewrite the "Task" field to describe the _type_ of task generically
+   (e.g. "set up authenticated data fetching" not "set up auth for our
+   internal billing API at api.acme.corp/billing")
+3. Rewrite "What Failed" and "Missing" entries to reference only the
+   skill's own APIs and patterns, not the user's code
+4. Show the sanitized feedback to the user and ask them to confirm it's
+   safe to submit before proceeding
+
+**Public repos:** No sanitization needed. Proceed directly to submission.
+
 ### If `gh` CLI is available
 
 Submit directly as a GitHub issue:

package/meta/generate-skill/SKILL.md

@@ -79,6 +79,15 @@ skill-tree-generator for the full spec of each type.
 
 ---
 
+### Subagent guidance for batch generation
+
+When generating multiple skills, spawn a separate subagent for each skill
+(or per-package group). Each subagent receives the domain_map.yaml,
+skill_tree.yaml, and the source docs relevant to its skill. This prevents
+context bleed between skills and allows parallel generation.
+
+---
+
 ## Step 2 — Extract content from sources
 
 **Line budget:** Each SKILL.md must stay under 500 lines. Before writing,
@@ -319,6 +328,10 @@ Run every check before outputting. Fix any failures.
 
 ## Step 6 — Output
 
+Before generating, ask the maintainer: "Would you like to review each skill
+individually before I generate the next one, or should I generate all skills
+and you review them together?" Respect their preference.
+
 Output the complete SKILL.md file content. If reference files are needed,
 output those as well with their relative paths.
 
@@ -381,48 +394,9 @@ Output is consumed by all major AI coding agents. To ensure consistency:
 
 ---
 
-## Meta-skill feedback (alpha default)
-
-After generating the first iteration of skills, complete a single Markdown
-feedback draft for all three meta skills used in scaffolding. If a draft
-exists from previous steps, keep it and fill the **Generate Skill** section.
-If no draft exists, create it using this exact template.
-
-```
-
-# Intent Meta Skill Feedback
-
-## Domain Discovery
-
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Tree Generator
-
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Generate Skill
-
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Context (optional)
-
-- Library:
-- Repo:
-- Docs:
-- Notes:
-
-```
+## Meta-skill feedback
 
-Ask the maintainer if they want to edit the feedback. Then ask if you should
-send it as a GitHub issue to TanStack/intent. Use the issue title:
-`[meta-feedback] intent meta skill`. Only submit if they confirm.
+After generating all skills, run the `skill-feedback-collection` skill to
+capture feedback about the scaffolding process (domain-discovery,
+tree-generator, and generate-skill).
 ```

package/meta/tree-generator/SKILL.md

@@ -274,14 +274,9 @@ packages/
 │   └── package.json             # Add "skills" to files array
 ```
 
-Add `"skills"` to each package's `files` array in `package.json` so
-skill files are included in the published npm tarball:
-
-```json
-{
-  "files": ["dist", "src", "skills"]
-}
-```
+Run `intent edit-package-json` to wire each package's `package.json`
+automatically (adds `"skills"`, `"bin"`, and `"!skills/_artifacts"` to the
+`files` array, and adds the `bin` entry if missing).
 
 ### Step 2 — Write the core skill
 
@@ -852,41 +847,3 @@ When updating:
 3. CHANGELOG.md entry
 
 ---
-
-## Meta-skill feedback (alpha default)
-
-After producing the skill tree artifact, update a single Markdown feedback
-draft for all three meta skills used in scaffolding. If a draft exists from
-Domain Discovery, keep it and fill only the **Tree Generator** section. If
-no draft exists, create it using this exact template.
-
-```
-# Intent Meta Skill Feedback
-
-## Domain Discovery
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Tree Generator
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Generate Skill
-- What worked well:
-- What was confusing or missing:
-- Suggestions for improvement:
-- Overall rating: good | mixed | bad
-
-## Context (optional)
-- Library:
-- Repo:
-- Docs:
-- Notes:
-```
-
-Do not submit feedback yet. Carry this draft forward to the generate-skill
-step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.0.9",
+  "version": "0.0.12",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",

package/dist/scanner-DkShtCWX.mjs

@@ -1,4 +0,0 @@
-import "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
-
-export { scanForIntents };

package/dist/setup-BJ4giTKA.d.mts

@@ -1,9 +0,0 @@
-//#region src/setup.d.ts
-interface SetupResult {
-  workflows: string[];
-  skipped: string[];
-  shim: string | null;
-}
-declare function runSetup(root: string, metaDir: string, args: string[]): SetupResult;
-//#endregion
-export { runSetup as n, SetupResult as t };

package/dist/setup-DGvdyKEq.mjs

@@ -1,125 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
-
-//#region src/setup.ts
-function detectVars(root) {
-	const pkgPath = join(root, "package.json");
-	let pkgJson = {};
-	try {
-		pkgJson = JSON.parse(readFileSync(pkgPath, "utf8"));
-	} catch {}
-	const name = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
-	const intent = pkgJson.intent;
-	const repo = typeof intent?.repo === "string" ? intent.repo : name.replace(/^@/, "").replace(/\//, "/");
-	const docs = typeof intent?.docs === "string" ? intent.docs : "docs/";
-	let srcPath = `packages/${name.replace(/^@[^/]+\//, "")}/src/**`;
-	if (existsSync(join(root, "src"))) srcPath = "src/**";
-	return {
-		PACKAGE_NAME: name,
-		REPO: repo,
-		DOCS_PATH: docs.endsWith("**") ? docs : docs.replace(/\/$/, "") + "/**",
-		SRC_PATH: srcPath
-	};
-}
-function applyVars(content, vars) {
-	return content.replace(/\{\{PACKAGE_NAME\}\}/g, vars.PACKAGE_NAME).replace(/\{\{REPO\}\}/g, vars.REPO).replace(/\{\{DOCS_PATH\}\}/g, vars.DOCS_PATH).replace(/\{\{SRC_PATH\}\}/g, vars.SRC_PATH);
-}
-function copyTemplates(srcDir, destDir, vars) {
-	const copied = [];
-	const skipped = [];
-	if (!existsSync(srcDir)) return {
-		copied,
-		skipped
-	};
-	mkdirSync(destDir, { recursive: true });
-	for (const entry of readdirSync(srcDir)) {
-		const srcPath = join(srcDir, entry);
-		const destPath = join(destDir, entry);
-		if (existsSync(destPath)) {
-			skipped.push(destPath);
-			continue;
-		}
-		writeFileSync(destPath, applyVars(readFileSync(srcPath, "utf8"), vars));
-		copied.push(destPath);
-	}
-	return {
-		copied,
-		skipped
-	};
-}
-function getShimContent(ext) {
-	return `#!/usr/bin/env node
-// Auto-generated by @tanstack/intent setup
-// Exposes the intent end-user CLI for consumers of this library.
-// Commit this file, then add to your package.json:
-//   "bin": { "intent": "./bin/intent.${ext}" }
-await import('@tanstack/intent/intent-library')
-`;
-}
-function detectShimExtension(root) {
-	try {
-		if (JSON.parse(readFileSync(join(root, "package.json"), "utf8")).type === "module") return "js";
-	} catch {}
-	return "mjs";
-}
-function findExistingShim(root) {
-	const shimJs = join(root, "bin", "intent.js");
-	if (existsSync(shimJs)) return shimJs;
-	const shimMjs = join(root, "bin", "intent.mjs");
-	if (existsSync(shimMjs)) return shimMjs;
-	return null;
-}
-function generateShim(root, result) {
-	const existingShim = findExistingShim(root);
-	if (existingShim) {
-		result.skipped.push(existingShim);
-		return;
-	}
-	const ext = detectShimExtension(root);
-	const shimPath = join(root, "bin", `intent.${ext}`);
-	mkdirSync(join(root, "bin"), { recursive: true });
-	writeFileSync(shimPath, getShimContent(ext));
-	result.shim = shimPath;
-}
-function runSetup(root, metaDir, args) {
-	const doAll = args.includes("--all");
-	const doWorkflows = doAll || args.includes("--workflows");
-	const doShim = doAll || args.includes("--shim");
-	const noFlagsGiven = !doWorkflows && !doShim;
-	const installWorkflows = doWorkflows || noFlagsGiven;
-	const installShim = doShim || noFlagsGiven;
-	const vars = detectVars(root);
-	const result = {
-		workflows: [],
-		skipped: [],
-		shim: null
-	};
-	const templatesDir = join(metaDir, "templates");
-	if (installWorkflows) {
-		const { copied, skipped } = copyTemplates(join(templatesDir, "workflows"), join(root, ".github", "workflows"), vars);
-		result.workflows = copied;
-		result.skipped.push(...skipped);
-	}
-	if (installShim) generateShim(root, result);
-	for (const f of result.workflows) console.log(`✓ Copied workflow: ${f}`);
-	for (const f of result.skipped) console.log(`  Already exists: ${f}`);
-	if (result.shim) {
-		const shimRelative = result.shim.replace(root + "/", "./");
-		console.log(`✓ Generated intent shim: ${result.shim}`);
-		console.log(`\n  Add to your package.json:`);
-		console.log(`    "bin": { "intent": "${shimRelative}" }`);
-		console.log(`\n  Add "bin" to your package.json "files" array.`);
-	}
-	if (result.workflows.length === 0 && result.shim === null && result.skipped.length === 0) console.log("No templates directory found. Is @tanstack/intent installed?");
-	else if (result.workflows.length > 0) {
-		console.log(`\nTemplate variables applied:`);
-		console.log(`  Package:  ${vars.PACKAGE_NAME}`);
-		console.log(`  Repo:     ${vars.REPO}`);
-		console.log(`  Docs:     ${vars.DOCS_PATH}`);
-		console.log(`  Src:      ${vars.SRC_PATH}`);
-	}
-	return result;
-}
-
-//#endregion
-export { runSetup as t };