@tanstack/intent 0.0.4 → 0.0.6

package/README.md

@@ -42,7 +42,7 @@ Validate your skill files:
 npx intent validate
 ```
 
-Copy CI and Oz workflow templates into your repo:
+Copy CI workflow templates into your repo:
 
 ```bash
 npx intent setup
@@ -57,7 +57,7 @@ npx intent setup
 | `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/Oz workflow templates                   |
+| `intent setup`          | Copy CI workflow templates                      |
 | `intent stale [--json]` | Check skills for version drift                  |
 | `intent feedback`       | Submit skill feedback                           |
 

package/dist/cli.mjs

@@ -1,11 +1,9 @@
 #!/usr/bin/env node
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-BwCyu1Jq.mjs";
+import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
 import { existsSync, readFileSync, readdirSync } from "node:fs";
 import { dirname, join, relative, sep } from "node:path";
 import { parse } from "yaml";
-import { spawnSync } from "node:child_process";
-import { release } from "node:os";
 import { fileURLToPath } from "node:url";
 
 //#region src/cli.ts
@@ -106,6 +104,11 @@ async function cmdList(args) {
 		});
 		console.log();
 	}
+	console.log(`Feedback:`);
+	console.log(`  After completing your task, collect feedback on skill usage.`);
+	console.log(`  Instructions: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
+	console.log(`  Submit: npx intent feedback --submit --file intent-feedback.json`);
+	console.log();
 	if (result.warnings.length > 0) {
 		console.log(`Warnings:`);
 		for (const w of result.warnings) console.log(`  ⚠ ${w}`);
@@ -196,7 +199,7 @@ function cmdValidate(args) {
 		const lineCount = content.split(/\r?\n/).length;
 		if (lineCount > 500) errors.push({
 			file: rel,
-			message: `Exceeds 500 line limit (${lineCount} lines)`
+			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");
@@ -238,40 +241,42 @@ function cmdValidate(args) {
 	console.log(`✅ Validated ${skillFiles.length} skill files — all passed`);
 }
 function cmdScaffold() {
-	function tryCopyToClipboard(text) {
-		const platform = process.platform;
-		const isWsl = platform === "linux" && (Boolean(process.env.WSL_DISTRO_NAME) || Boolean(process.env.WSL_INTEROP) || release().toLowerCase().includes("microsoft"));
-		const tryCommand = (command$1, args = []) => {
-			return spawnSync(command$1, args, { input: text }).status === 0;
-		};
-		if (platform === "darwin") return tryCommand("pbcopy");
-		if (platform === "win32") return tryCommand("clip");
-		if (isWsl) return tryCommand("clip.exe");
-		return tryCommand("wl-copy") || tryCommand("xclip", ["-selection", "clipboard"]) || tryCommand("xsel", ["--clipboard", "--input"]);
-	}
-	const prompt = `You are an AI assistant helping a library maintainer scaffold Intent skills.
+	console.log(`You are an AI assistant helping a library maintainer scaffold Intent skills.
 You MUST use the Intent meta skills in this exact order and follow their output requirements.
 
-Before you start, ask the maintainer for their skills root path.
-- Default: skills/
-- If they choose a different path, replace "skills/" in all output paths below.
+Before you start, ask the maintainer:
+1. Skills root path (default: skills/). If custom, replace "skills/" in all paths below.
+2. Is this a monorepo? If yes, you need the following layout:
+   - Domain map artifacts live at the REPO ROOT: _artifacts/domain_map.yaml, _artifacts/skill_spec.md, _artifacts/skill_tree.yaml
+   - Skills live INSIDE EACH PACKAGE: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
+   - Each publishable package needs:
+     a. @tanstack/intent as a devDependency
+     b. A bin entry: "bin": { "intent": "./bin/intent.js" }
+     c. The shim file at bin/intent.js (run npx @tanstack/intent setup --shim in each package)
+     d. "skills" and "bin" in the package.json "files" array, with "!skills/_artifacts" to exclude artifacts
+   - Ask the maintainer which packages should get skills (usually client SDKs and primary framework adapters)
 
 1) Meta skill: domain-discovery
    - Input: library name, repo URL, docs URL(s), scope constraints, target audience.
-   - Output files (exact paths):
-     - skills/_artifacts/domain_map.yaml
-     - skills/_artifacts/skill_spec.md
+   - Output files:
+     - Single-repo: skills/_artifacts/domain_map.yaml, skills/_artifacts/skill_spec.md
+     - Monorepo: _artifacts/domain_map.yaml, _artifacts/skill_spec.md (at repo root)
+   - Domain discovery covers the WHOLE library. One domain map for the entire monorepo.
    - These artifacts are maintainer-owned and should be committed to the repo.
 
 2) Meta skill: tree-generator
-   - Input: skills/_artifacts/domain_map.yaml + skills/_artifacts/skill_spec.md
-   - Output file (exact path):
-     - skills/_artifacts/skill_tree.yaml
+   - Input: domain map + skill spec artifacts
+   - Output file: _artifacts/skill_tree.yaml (same location as domain map)
+   - The skill tree must specify which PACKAGE each skill belongs to.
+   - For monorepos, the tree maps skills to packages: each skill entry should include
+     a "package" field (e.g. packages/client, packages/react-client).
 
 3) Meta skill: generate-skill
-   - Input: skills/_artifacts/skill_tree.yaml
-   - Output files (exact path pattern):
-     - skills/<domain>/<skill>/SKILL.md
+   - Input: skill tree
+   - Output files:
+     - Single-repo: skills/<domain>/<skill>/SKILL.md
+     - Monorepo: packages/<pkg>/skills/<domain>/<skill>/SKILL.md
+   - Skills are written into the package they describe, not a shared root.
 
 Guidance for the maintainer:
 - If any input is missing, ask for it.
@@ -280,20 +285,15 @@ Guidance for the maintainer:
 - Use the library's actual terminology from docs and source.
 
 At the end, produce a single Markdown feedback doc with three sections (Domain Discovery, Tree Generator, Generate Skill).
-Ask if the maintainer wants to edit it, then ask if you should send it as a GitHub issue to TanStack/intent.
-Use the issue title: [meta-feedback] intent meta skill.
+Ask if the maintainer wants to edit it, then submit it via: npx @tanstack/intent feedback --meta --submit --file <path>
 
 Finish with a short checklist:
-- Run npx intent validate
-- Commit skills/ and skills/_artifacts/ (artifacts are repo-only)
-- Exclude skills/_artifacts/ from package publishing
-- Add README snippet: If you use an AI agent, run npx intent init
-`;
-	console.log("🚀 Intent Scaffold Prompt");
-	console.log("✨ Copy the prompt below into your AI agent:\n");
-	console.log(prompt);
-	if (tryCopyToClipboard(prompt)) console.log("\n✅ Copied prompt to clipboard");
-	else console.log("\n⚠ Tip: Manually copy the prompt above into your agent");
+- Run npx @tanstack/intent validate in each package directory (or for single-repo: at the root)
+- Commit skills/ and artifacts
+- Exclude artifacts from package publishing (add "!skills/_artifacts" to the "files" array in each package.json)
+- For monorepos: ensure each package has @tanstack/intent as devDependency, bin entry, and shim
+- Add README snippet: If you use an AI agent, run npx @tanstack/intent init
+`);
 }
 const USAGE = `TanStack Intent CLI
 
@@ -303,7 +303,7 @@ Usage:
   intent validate [<dir>]        Validate skill files (default: skills/)
   intent init                    Set up intent discovery in agent configs
   intent scaffold                Print maintainer scaffold prompt
-  intent setup [--workflows] [--oz] [--all]  Copy CI/Oz templates into your repo
+  intent setup [--workflows] [--all]  Copy CI templates into your repo
   intent stale                   Check skills for staleness
   intent feedback --submit --file <path>           Submit skill feedback
   intent feedback --meta --submit --file <path>    Submit meta-skill feedback`;
@@ -320,7 +320,7 @@ switch (command) {
 		cmdValidate(commandArgs);
 		break;
 	case "init": {
-		const { runInit, detectAgentConfigs } = await import("./init-DEzzXm9j.mjs");
+		const { runInit, detectAgentConfigs } = await import("./init-BU1ZnUbK.mjs");
 		const initRoot = process.cwd();
 		const result = runInit(initRoot);
 		for (const f of result.injected) console.log(`✓ Added intent block to ${f}`);
@@ -340,7 +340,7 @@ switch (command) {
 		break;
 	case "stale": {
 		const { checkStaleness } = await import("./staleness-B5gUj7FR.mjs");
-		const { scanForIntents: scanStale } = await import("./scanner-fAWJUn6Q.mjs");
+		const { scanForIntents: scanStale } = await import("./scanner-DkShtCWX.mjs");
 		let staleResult;
 		try {
 			staleResult = await scanStale();
@@ -372,7 +372,7 @@ switch (command) {
 		break;
 	}
 	case "feedback": {
-		const { runFeedback } = await import("./feedback-FIUBOL0g.mjs");
+		const { runFeedback } = await import("./feedback-PR8JNBfM.mjs");
 		runFeedback(commandArgs);
 		break;
 	}

package/dist/{feedback-DKreHfB1.mjs → feedback-BTSaBAS_.mjs}

@@ -87,7 +87,6 @@ const VALID_META_SKILLS = [
 	"skill-staleness-check"
 ];
 const VALID_AGENTS = [
-	"oz",
 	"claude-code",
 	"cursor",
 	"copilot",
@@ -259,10 +258,10 @@ function runFeedback(args) {
 				break;
 			case "file":
 				console.log(`✓ ${result$1.detail}`);
-				console.log(`Open a GitHub Discussion at https://github.com/${META_FEEDBACK_REPO}/discussions/new?category=Feedback`);
+				console.log(`You can manually open an issue at https://github.com/${META_FEEDBACK_REPO}/issues with this content.`);
 				break;
 			case "stdout":
-				console.log("--- Meta-feedback markdown (copy/paste to discussion) ---");
+				console.log("--- Meta-feedback markdown (copy/paste to issue) ---");
 				console.log(result$1.detail);
 				break;
 		}

package/dist/{feedback-FIUBOL0g.mjs → feedback-PR8JNBfM.mjs}

@@ -1,3 +1,3 @@
-import { a as runFeedback, c as toMarkdown, i as resolveFrequency, l as validateMetaPayload, n as hasGhCli, o as submitFeedback, r as metaToMarkdown, s as submitMetaFeedback, t as containsSecrets, u as validatePayload } from "./feedback-DKreHfB1.mjs";
+import { a as runFeedback, c as toMarkdown, i as resolveFrequency, l as validateMetaPayload, n as hasGhCli, o as submitFeedback, r as metaToMarkdown, s as submitMetaFeedback, t as containsSecrets, u as validatePayload } from "./feedback-BTSaBAS_.mjs";
 
 export { runFeedback };

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-kbQfN_is.mjs";
-import { n as runSetup } from "./setup-N5dttGp_.mjs";
+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-B20LP96b.mjs";
+import { n as runSetup } from "./setup-D2Bwubpw.mjs";
 
 //#region src/scanner.d.ts
 declare function scanForIntents(root?: string): Promise<ScanResult>;

package/dist/index.mjs

@@ -1,8 +1,8 @@
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.mjs";
-import { t as scanForIntents } from "./scanner-BwCyu1Jq.mjs";
+import { t as scanForIntents } from "./scanner-OmHt14bs.mjs";
 import { t as checkStaleness } from "./staleness-lP6B0O4z.mjs";
-import { c as toMarkdown, i as resolveFrequency, l as validateMetaPayload, n as hasGhCli, o as submitFeedback, r as metaToMarkdown, s as submitMetaFeedback, t as containsSecrets, u as validatePayload } from "./feedback-DKreHfB1.mjs";
-import { a as runInit, i as readProjectConfig, n as hasIntentBlock, o as writeProjectConfig, r as injectIntentBlock, t as detectAgentConfigs } from "./init-DNxmjQfU.mjs";
-import { t as runSetup } from "./setup-CNGz26qL.mjs";
+import { c as toMarkdown, i as resolveFrequency, l as validateMetaPayload, n as hasGhCli, o as submitFeedback, r as metaToMarkdown, s as submitMetaFeedback, t as containsSecrets, u as validatePayload } from "./feedback-BTSaBAS_.mjs";
+import { a as runInit, i as readProjectConfig, n as hasIntentBlock, o as writeProjectConfig, r as injectIntentBlock, t as detectAgentConfigs } from "./init-DUiDMMrN.mjs";
+import { t as runSetup } from "./setup-BvrZZLsA.mjs";
 
 export { checkStaleness, containsSecrets, detectAgentConfigs, findSkillFiles, hasGhCli, hasIntentBlock, injectIntentBlock, metaToMarkdown, parseFrontmatter, readProjectConfig, resolveFrequency, runInit, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload, writeProjectConfig };

package/dist/{init-DEzzXm9j.mjs → init-BU1ZnUbK.mjs}

@@ -1,3 +1,3 @@
-import { a as runInit, i as readProjectConfig, n as hasIntentBlock, o as writeProjectConfig, r as injectIntentBlock, t as detectAgentConfigs } from "./init-DNxmjQfU.mjs";
+import { a as runInit, i as readProjectConfig, n as hasIntentBlock, o as writeProjectConfig, r as injectIntentBlock, t as detectAgentConfigs } from "./init-DUiDMMrN.mjs";
 
 export { detectAgentConfigs, runInit };

package/dist/{init-DNxmjQfU.mjs → init-DUiDMMrN.mjs}

@@ -14,6 +14,8 @@ const INTENT_BLOCK = `## Intent Skills
 This project uses TanStack Intent. Run \`npx intent list\` to discover
 available AI coding skills. Before working with a library that has skills,
 read the relevant SKILL.md file at the path shown in the list output.
+After completing a task that used skills, collect and submit feedback
+following the instructions in the list output.
 `;
 const DEFAULT_CONFIG = { feedback: { frequency: "every-5" } };
 function detectAgentConfigs(root) {

package/dist/intent-library.mjs

@@ -90,6 +90,11 @@ async function cmdList() {
 		});
 		console.log();
 	}
+	console.log(`Feedback:`);
+	console.log(`  After completing your task, collect feedback on skill usage.`);
+	console.log(`  Instructions: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
+	console.log(`  Submit: npx intent feedback --submit --file intent-feedback.json`);
+	console.log();
 	if (result.warnings.length > 0) {
 		console.log(`Warnings:`);
 		for (const w of result.warnings) console.log(`  ⚠ ${w}`);

package/dist/library-scanner.d.mts

@@ -1,4 +1,4 @@
-import { l as SkillEntry } from "./types-kbQfN_is.mjs";
+import { l as SkillEntry } from "./types-B20LP96b.mjs";
 
 //#region src/library-scanner.d.ts
 interface LibraryPackage {

package/dist/scanner-DkShtCWX.mjs

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

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

@@ -26,6 +26,30 @@ function validateIntentField(_pkgName, intent) {
 		requires
 	};
 }
+/**
+* Derive an IntentConfig from standard package.json fields when no explicit
+* `intent` field is present. A package with a `skills/` directory signals
+* intent support; `repo` and `docs` are derived from `repository` and
+* `homepage`.
+*/
+function deriveIntentConfig(pkgJson) {
+	let repo = null;
+	if (typeof pkgJson.repository === "string") repo = pkgJson.repository;
+	else if (pkgJson.repository && typeof pkgJson.repository === "object" && typeof pkgJson.repository.url === "string") {
+		repo = pkgJson.repository.url;
+		repo = repo.replace(/^git\+/, "").replace(/\.git$/, "").replace(/^https?:\/\/github\.com\//, "");
+	}
+	const docs = typeof pkgJson.homepage === "string" ? pkgJson.homepage : void 0;
+	if (!repo) return null;
+	const intentPartial = pkgJson.intent;
+	const requires = intentPartial && Array.isArray(intentPartial.requires) ? intentPartial.requires.filter((r) => typeof r === "string") : void 0;
+	return {
+		version: 1,
+		repo,
+		docs: docs ?? "",
+		requires
+	};
+}
 function discoverSkills(skillsDir, _baseName) {
 	const skills = [];
 	function walk(dir) {
@@ -132,9 +156,9 @@ async function scanForIntents(root) {
 		}
 		const pkgName = typeof pkgJson.name === "string" ? pkgJson.name : "unknown";
 		const pkgVersion = typeof pkgJson.version === "string" ? pkgJson.version : "0.0.0";
-		const intent = validateIntentField(pkgName, pkgJson.intent);
+		const intent = validateIntentField(pkgName, pkgJson.intent) ?? deriveIntentConfig(pkgJson);
 		if (!intent) {
-			warnings.push(`${pkgName} has a skills/ directory but missing or invalid "intent" field in package.json`);
+			warnings.push(`${pkgName} has a skills/ directory but could not determine repo/docs from package.json (add a "repository" field or explicit "intent" config)`);
 			continue;
 		}
 		const skills = discoverSkills(skillsDir, pkgName);

package/dist/{setup-CNGz26qL.mjs → setup-BvrZZLsA.mjs}

@@ -67,16 +67,13 @@ function generateShim(root, result) {
 function runSetup(root, metaDir, args) {
 	const doAll = args.includes("--all");
 	const doWorkflows = doAll || args.includes("--workflows");
-	const doOz = doAll || args.includes("--oz");
 	const doShim = doAll || args.includes("--shim");
-	const defaultAll = !doWorkflows && !doOz && !doShim;
+	const defaultAll = !doWorkflows && !doShim;
 	const installWorkflows = doWorkflows || defaultAll;
-	const installOz = doOz || defaultAll;
 	const installShim = doShim || defaultAll;
 	const vars = detectVars(root);
 	const result = {
 		workflows: [],
-		oz: [],
 		skipped: [],
 		shim: null
 	};
@@ -86,14 +83,8 @@ function runSetup(root, metaDir, args) {
 		result.workflows = copied;
 		result.skipped.push(...skipped);
 	}
-	if (installOz) {
-		const { copied, skipped } = copyTemplates(join(templatesDir, "oz"), join(root, ".intent", "oz"), vars);
-		result.oz = 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.oz) console.log(`✓ Copied Oz prompt: ${f}`);
 	for (const f of result.skipped) console.log(`  Already exists: ${f}`);
 	if (result.shim) {
 		console.log(`✓ Generated intent shim: ${result.shim}`);
@@ -101,8 +92,8 @@ function runSetup(root, metaDir, args) {
 		console.log(`    "bin": { "intent": "./bin/intent.js" }`);
 		console.log(`\n  Add bin/intent.js to your package.json "files" array.`);
 	}
-	if (result.workflows.length === 0 && result.oz.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 || result.oz.length > 0) {
+	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}`);

package/dist/{setup-N5dttGp_.d.mts → setup-D2Bwubpw.d.mts}

@@ -1,7 +1,6 @@
 //#region src/setup.d.ts
 interface SetupResult {
   workflows: string[];
-  oz: string[];
   skipped: string[];
   shim: string | null;
 }

package/dist/setup.d.mts

@@ -1,2 +1,2 @@
-import { n as runSetup, t as SetupResult } from "./setup-N5dttGp_.mjs";
+import { n as runSetup, t as SetupResult } from "./setup-D2Bwubpw.mjs";
 export { SetupResult, runSetup };

package/dist/setup.mjs

@@ -1,3 +1,3 @@
-import { t as runSetup } from "./setup-CNGz26qL.mjs";
+import { t as runSetup } from "./setup-BvrZZLsA.mjs";
 
 export { runSetup };

package/dist/{types-kbQfN_is.d.mts → types-B20LP96b.d.mts}

@@ -48,7 +48,7 @@ interface FeedbackPayload {
   userComments?: string;
 }
 type MetaSkillName = 'domain-discovery' | 'tree-generator' | 'generate-skill' | 'skill-staleness-check';
-type AgentName = 'oz' | 'claude-code' | 'cursor' | 'copilot' | 'codex' | 'other';
+type AgentName = 'claude-code' | 'cursor' | 'copilot' | 'codex' | 'other';
 interface MetaFeedbackPayload {
   metaSkill: MetaSkillName;
   library: string;

package/meta/domain-discovery/SKILL.md

@@ -57,7 +57,26 @@ reading exhaustively yet.
    guidance, read it. This is high-signal for what the maintainer
    considers important
 
-### 1b — Note initial impressions
+### 1b — Read peer dependency constraints
+
+Check `package.json` for `peerDependencies` and `peerDependenciesMeta`.
+For each major peer dependency (React, Vue, Svelte, Next.js, etc.):
+
+1. Note the version range required
+2. Read the peer's docs for integration constraints that affect this
+   library: SSR/hydration rules, component lifecycle boundaries,
+   browser-only APIs, singleton patterns, connection limits
+3. Log framework-specific failure modes — these are the highest-impact
+   failure modes and cannot be discovered from the library's own source
+
+Examples of peer-dependency-driven failure modes:
+
+- SSR: calling browser-only APIs during server render
+- React: breaking hook rules in library wrapper components
+- Connection limits: opening multiple WebSocket connections per tab
+- Singleton patterns: creating multiple client instances in dev mode
+
+### 1c — Note initial impressions
 
 Log (but do not group yet):
 
@@ -191,7 +210,11 @@ Move concept inventory items into groups. Two items belong together when:
 - They share a lifecycle, configuration scope, or architectural tradeoff
 - Getting one wrong tends to produce bugs in the other
 
-Target 4–7 domains. These are conceptual groupings, not the final skills.
+Let library complexity drive the domain count — a focused library may need
+only 2–3 domains, while a large framework may need 7+. Validate by asking:
+"Would a developer working on a single feature need to load skills from
+multiple domains? If so, merge those domains." These are conceptual
+groupings, not the final skills.
 
 Do not create a group for:
 
@@ -202,6 +225,14 @@ Do not create a group for:
 
 Name each domain as work being performed, not what the library provides.
 
+**Validation step:** After grouping, check each domain by asking:
+"Would a developer working on a single feature need to load skills from
+multiple domains?" If yes, merge those domains. Group by developer tasks
+(what they're trying to accomplish), not by architecture (how the library
+is organized internally). For example, prefer "writing data" over
+"producer lifecycle" — the former matches a developer's intent, the latter
+matches the codebase structure.
+
 ### 3b — Map domains × tasks → skills
 
 Merge your conceptual domains with the maintainer's task list from
@@ -268,6 +299,14 @@ For each skill, extract failure modes that pass all three tests:
 
 Target 3 failure modes per skill minimum. Complex skills target 5–6.
 
+**Code patterns.** Every failure mode should include `wrong_pattern` and
+`correct_pattern` fields with short code snippets (3–10 lines each).
+The wrong pattern is what an agent would generate; the correct pattern
+is the fix. These feed directly into SKILL.md Common Mistakes sections
+as wrong/correct code pairs. If the failure mode is purely conceptual
+(e.g. an architectural choice) rather than a code pattern, omit both
+fields and explain in `mechanism` instead.
+
 **Cross-skill failure modes.** Some failure modes belong to multiple
 skills. A developer doing SSR work and a developer doing state management
 both need to know about "stale state during hydration" — they load
@@ -465,6 +504,11 @@ Update `status: draft` to `status: reviewed`.
 If the maintainer uses a custom skills root, replace `skills/` in the paths
 below with their chosen directory.
 
+**Monorepo layout:** For monorepos, domain map artifacts go at the REPO ROOT
+(e.g. `_artifacts/domain_map.yaml`) since they describe the whole library.
+Skills are generated per-package later by the tree-generator and generate-skill
+steps.
+
 ### 1. skills/\_artifacts/domain_map.yaml
 
 ```yaml
@@ -510,6 +554,10 @@ skills:
     failure_modes:
       - mistake: '[5-10 word phrase]'
         mechanism: '[one sentence]'
+        wrong_pattern: | # the code an agent would incorrectly generate
+          [short code snippet showing the mistake]
+        correct_pattern: | # the code that should be generated instead
+          [short code snippet showing the fix]
         source: '[doc page, source file, issue link, or maintainer interview]'
         priority: '[CRITICAL | HIGH | MEDIUM]'
         status: '[active | fixed-but-legacy-risk | removed]'

package/meta/feedback-collection/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: skill-feedback-collection
+description: >
+  Collect structured feedback about skill usage after completing a coding task.
+  Activate at the end of any session where one or more SKILL.md files were
+  loaded. Captures agent signals (gaps, errors, corrections, human interventions)
+  and brief human input, then submits via the intent feedback CLI.
+metadata:
+  version: '1.0'
+  category: meta-tooling
+  output_artifacts:
+    - intent-feedback.json
+---
+
+# Skill Feedback Collection
+
+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.
+
+---
+
+## Phase 1 — Automated Signal Collection
+
+Review your own session transcript. No human interaction needed yet.
+
+### 1a: Gap detection
+
+Identify moments where the skill was silent and you had to bridge the gap
+yourself — via code reading, search, trial-and-error, or general knowledge.
+
+For each gap, note:
+
+- What you needed to do
+- What the skill should have told you
+- How you solved it (code reading, web search, guessing)
+
+### 1b: Error/correction tracking
+
+Identify moments where the skill prescribed an approach that produced an error.
+
+For each error, note:
+
+- What the skill said to do
+- The error or incorrect behavior that resulted
+- The fix you applied
+
+### 1c: Human intervention events
+
+Identify moments where the human clarified, corrected, or overrode your approach.
+
+For each intervention, note:
+
+- What you were doing when the human intervened
+- What the human said or changed
+- Whether the skill could have prevented this
+
+### 1d: Step duration anomalies
+
+Identify steps that consumed disproportionate effort compared to their apparent
+complexity. These signal that the skill should provide a template, snippet, or
+more detailed guidance.
+
+---
+
+## Phase 2 — Human Interview
+
+Ask the human up to 4 questions. Keep it brief — skip questions if the session
+already provided clear answers. Respect if they decline.
+
+1. "Was anything unclear about what was happening during the task?"
+2. "Did anything feel frustrating or take longer than expected?"
+3. "Were you uncertain about the output quality at any point?"
+4. "Anything you'd want done differently next time?"
+
+Derive `userRating` from overall sentiment:
+
+- Mostly positive → `good`
+- Mixed signals → `mixed`
+- Mostly negative → `bad`
+
+If the human gives an explicit rating, use that instead.
+
+---
+
+## Phase 3 — Build the Payload
+
+Construct one JSON payload per skill used. The schema must match exactly:
+
+```json
+{
+  "skill": "<skill name from SKILL.md frontmatter>",
+  "package": "<npm package name that contains the skill>",
+  "skillVersion": "<metadata.version from SKILL.md frontmatter, or library_version>",
+  "task": "<one-sentence summary of what the human asked you to do>",
+  "whatWorked": "<patterns/instructions from the skill that were accurate and helpful>",
+  "whatFailed": "<errors from 1b — what the skill got wrong>",
+  "missing": "<gaps from 1a — what the skill should have covered>",
+  "selfCorrections": "<fixes you applied from 1b + interventions from 1c>",
+  "userRating": "good | mixed | bad",
+  "userComments": "<optional — direct quotes or paraphrased human input from Phase 2>"
+}
+```
+
+### Field derivation guide
+
+| Field             | Source                                                             |
+| ----------------- | ------------------------------------------------------------------ |
+| `skill`           | Frontmatter `name` field of the SKILL.md you loaded                |
+| `package`         | The npm package the skill lives in (e.g. `@tanstack/query-intent`) |
+| `skillVersion`    | Frontmatter `metadata.version` or `library_version`                |
+| `task`            | Summarize the human's original request in one sentence             |
+| `whatWorked`      | List skill sections/patterns that were correct and useful          |
+| `whatFailed`      | From 1b — skill instructions that produced errors                  |
+| `missing`         | From 1a — gaps where the skill was silent                          |
+| `selfCorrections` | From 1b fixes + 1c human interventions, combined                   |
+| `userRating`      | From Phase 2 sentiment analysis or explicit rating                 |
+| `userComments`    | From Phase 2 answers, keep brief                                   |
+
+### Example
+
+```json
+{
+  "skill": "tanstack-query/core",
+  "package": "@anthropic/tanstack-query-intent",
+  "skillVersion": "1.0",
+  "task": "Add optimistic updates to a mutation with rollback on error",
+  "whatWorked": "Setup pattern was correct. onMutate/onError/onSettled lifecycle was accurate.",
+  "whatFailed": "Cache key format used array syntax that doesn't match v5 — had to switch to queryOptions pattern.",
+  "missing": "No guidance on TypeScript generics for mutation variables. Had to read source.",
+  "selfCorrections": "Fixed cache key format. Human corrected the rollback type to include undefined.",
+  "userRating": "mixed",
+  "userComments": "The optimistic update pattern was helpful but the cache key thing wasted 10 minutes."
+}
+```
+
+If multiple skills were loaded, produce one payload per skill. Only include
+skills that were actually used during the session — skip any that were loaded
+but never referenced.
+
+---
+
+## Phase 4 — Submit
+
+1. Save the payload to `intent-feedback.json` in the project root.
+   If multiple skills, save as a JSON array.
+
+2. Submit:
+
+   ```bash
+   npx intent feedback --submit --file intent-feedback.json
+   ```
+
+3. If the submission succeeds, delete `intent-feedback.json`.
+
+4. If it fails, tell the human and leave the file for manual retry.