@tanstack/intent 0.0.6 → 0.0.8

package/dist/index.mjs

@@ -1,8 +1,249 @@
 import { n as parseFrontmatter, t as findSkillFiles } from "./utils-DH3jY3CI.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-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";
+import { t as runSetup } from "./setup-DGvdyKEq.mjs";
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { execFileSync, execSync } from "node:child_process";
 
-export { checkStaleness, containsSecrets, detectAgentConfigs, findSkillFiles, hasGhCli, hasIntentBlock, injectIntentBlock, metaToMarkdown, parseFrontmatter, readProjectConfig, resolveFrequency, runInit, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload, writeProjectConfig };
+//#region src/feedback.ts
+const META_FEEDBACK_REPO = "TanStack/intent";
+const SECRET_PATTERNS = [
+	/(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9_]{36,}/,
+	/(?:sk|pk)[-_](?:live|test)[-_][A-Za-z0-9]{24,}/,
+	/AKIA[0-9A-Z]{16}/,
+	/-----BEGIN (?:RSA |EC )?PRIVATE KEY-----/,
+	/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/,
+	/(?:Bearer|token)\s+[A-Za-z0-9_\-.~+/]{20,}/i,
+	/[A-Za-z0-9]{32,}(?=.*(?:key|secret|token|password))/i
+];
+function containsSecrets(text) {
+	return SECRET_PATTERNS.some((pattern) => pattern.test(text));
+}
+function hasGhCli() {
+	try {
+		execSync("gh --version", { stdio: "ignore" });
+		return true;
+	} catch {
+		return false;
+	}
+}
+function getHomeConfigDir() {
+	return process.env.XDG_CONFIG_HOME ?? join(process.env.HOME ?? process.env.USERPROFILE ?? "", ".config");
+}
+function resolveFrequency(root) {
+	const userConfigPath = join(getHomeConfigDir(), "intent", "config.json");
+	try {
+		const userCfg = JSON.parse(readFileSync(userConfigPath, "utf8"));
+		if (userCfg.feedback?.frequency) return userCfg.feedback.frequency;
+	} catch {}
+	const projectConfigPath = join(root, "intent.config.json");
+	try {
+		const projCfg = JSON.parse(readFileSync(projectConfigPath, "utf8"));
+		if (projCfg.feedback?.frequency) return projCfg.feedback.frequency;
+	} catch {}
+	return "every-5";
+}
+const REQUIRED_FIELDS = [
+	"skill",
+	"package",
+	"skillVersion",
+	"task",
+	"whatWorked",
+	"whatFailed",
+	"missing",
+	"selfCorrections",
+	"userRating"
+];
+function validatePayload(payload) {
+	const errors = [];
+	if (!payload || typeof payload !== "object") return {
+		valid: false,
+		errors: ["Payload must be a JSON object"]
+	};
+	const obj = payload;
+	for (const field of REQUIRED_FIELDS) if (typeof obj[field] !== "string" || obj[field].trim() === "") errors.push(`Missing or empty required field: ${field}`);
+	if (obj.userRating && ![
+		"good",
+		"mixed",
+		"bad"
+	].includes(obj.userRating)) errors.push("userRating must be one of: good, mixed, bad");
+	if (containsSecrets(Object.values(obj).filter((v) => typeof v === "string").join("\n"))) errors.push("Payload appears to contain secrets or tokens — submission rejected");
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+const META_REQUIRED_FIELDS = [
+	"metaSkill",
+	"library",
+	"agentUsed",
+	"artifactQuality",
+	"whatWorked",
+	"whatFailed",
+	"suggestions",
+	"userRating"
+];
+const VALID_META_SKILLS = [
+	"domain-discovery",
+	"tree-generator",
+	"generate-skill",
+	"skill-staleness-check"
+];
+const VALID_AGENTS = [
+	"claude-code",
+	"cursor",
+	"copilot",
+	"codex",
+	"other"
+];
+const VALID_QUALITY_RATINGS = [
+	"good",
+	"mixed",
+	"bad"
+];
+function validateMetaPayload(payload) {
+	const errors = [];
+	if (!payload || typeof payload !== "object") return {
+		valid: false,
+		errors: ["Payload must be a JSON object"]
+	};
+	const obj = payload;
+	for (const field of META_REQUIRED_FIELDS) if (typeof obj[field] !== "string" || obj[field].trim() === "") errors.push(`Missing or empty required field: ${field}`);
+	if (obj.metaSkill && !VALID_META_SKILLS.includes(obj.metaSkill)) errors.push(`metaSkill must be one of: ${VALID_META_SKILLS.join(", ")}`);
+	if (obj.agentUsed && !VALID_AGENTS.includes(obj.agentUsed)) errors.push(`agentUsed must be one of: ${VALID_AGENTS.join(", ")}`);
+	if (obj.artifactQuality && !VALID_QUALITY_RATINGS.includes(obj.artifactQuality)) errors.push("artifactQuality must be one of: good, mixed, bad");
+	if (obj.userRating && !VALID_QUALITY_RATINGS.includes(obj.userRating)) errors.push("userRating must be one of: good, mixed, bad");
+	if (containsSecrets(Object.values(obj).filter((v) => typeof v === "string").join("\n"))) errors.push("Payload appears to contain secrets or tokens — submission rejected");
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+function metaToMarkdown(payload) {
+	const lines = [
+		`# Meta-Skill Feedback: ${payload.metaSkill}`,
+		"",
+		`**Library:** ${payload.library}`,
+		`**Agent:** ${payload.agentUsed}`,
+		`**Artifact quality:** ${payload.artifactQuality}`,
+		`**Rating:** ${payload.userRating}`
+	];
+	if (payload.interviewQuality) lines.push(`**Interview quality:** ${payload.interviewQuality}`);
+	if (payload.failureModeQuality) lines.push(`**Failure mode quality:** ${payload.failureModeQuality}`);
+	lines.push("", "## What Worked", payload.whatWorked, "", "## What Failed", payload.whatFailed, "", "## Suggestions", payload.suggestions);
+	return lines.join("\n") + "\n";
+}
+function toMarkdown(payload) {
+	const lines = [
+		`# Skill Feedback: ${payload.skill}`,
+		"",
+		`**Package:** ${payload.package}`,
+		`**Skill version:** ${payload.skillVersion}`,
+		`**Rating:** ${payload.userRating}`,
+		"",
+		"## Task",
+		payload.task,
+		"",
+		"## What Worked",
+		payload.whatWorked,
+		"",
+		"## What Failed",
+		payload.whatFailed,
+		"",
+		"## Missing",
+		payload.missing,
+		"",
+		"## Self-Corrections",
+		payload.selfCorrections
+	];
+	if (payload.userComments) lines.push("", "## User Comments", payload.userComments);
+	return lines.join("\n") + "\n";
+}
+function submitFeedback(payload, repo, opts) {
+	const md = toMarkdown(payload);
+	if (opts.ghAvailable) try {
+		execFileSync("gh", [
+			"issue",
+			"create",
+			"--repo",
+			repo,
+			"--title",
+			`Skill Feedback: ${payload.skill} (${payload.userRating})`,
+			"--body",
+			"-"
+		], {
+			input: md,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		return {
+			method: "gh",
+			detail: `Submitted issue to ${repo}`
+		};
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`GitHub submission failed: ${msg}`);
+		console.error("Falling back to file output.");
+	}
+	if (opts.outputPath) {
+		writeFileSync(opts.outputPath, md, "utf8");
+		return {
+			method: "file",
+			detail: `Saved to ${opts.outputPath}`
+		};
+	}
+	return {
+		method: "stdout",
+		detail: md
+	};
+}
+function submitMetaFeedback(payload, opts) {
+	const md = metaToMarkdown(payload);
+	if (opts.ghAvailable) try {
+		execFileSync("gh", [
+			"issue",
+			"create",
+			"--repo",
+			META_FEEDBACK_REPO,
+			"--title",
+			`Meta-Skill Feedback: ${payload.metaSkill} (${payload.userRating})`,
+			"--label",
+			`feedback:${payload.metaSkill}`,
+			"--body",
+			"-"
+		], {
+			input: md,
+			stdio: [
+				"pipe",
+				"pipe",
+				"pipe"
+			]
+		});
+		return {
+			method: "gh",
+			detail: `Submitted issue to ${META_FEEDBACK_REPO}`
+		};
+	} catch (err) {
+		const msg = err instanceof Error ? err.message : String(err);
+		console.error(`GitHub submission failed: ${msg}`);
+		console.error("Falling back to file output.");
+	}
+	if (opts.outputPath) {
+		writeFileSync(opts.outputPath, md, "utf8");
+		return {
+			method: "file",
+			detail: `Saved to ${opts.outputPath}`
+		};
+	}
+	return {
+		method: "stdout",
+		detail: md
+	};
+}
+
+//#endregion
+export { checkStaleness, containsSecrets, findSkillFiles, hasGhCli, metaToMarkdown, parseFrontmatter, resolveFrequency, runSetup, scanForIntents, submitFeedback, submitMetaFeedback, toMarkdown, validateMetaPayload, validatePayload };

package/dist/intent-library.mjs

@@ -1,57 +1,9 @@
 #!/usr/bin/env node
 import "./utils-DH3jY3CI.mjs";
-import { t as scanLibrary } from "./library-scanner-D0aP7is_.mjs";
+import { n as printSkillTree, r as printTable, t as computeSkillNameWidth } from "./display-D_XzuGnu.mjs";
+import { t as scanLibrary } from "./library-scanner-V9sTOhrb.mjs";
 
 //#region src/intent-library.ts
-function padColumn(text, width) {
-	return text.length >= width ? text + "  " : text.padEnd(width);
-}
-function printTable(headers, rows) {
-	const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)) + 2);
-	const headerLine = headers.map((h, i) => padColumn(h, widths[i])).join("");
-	const separator = widths.map((w) => "─".repeat(w)).join("");
-	console.log(headerLine);
-	console.log(separator);
-	for (const row of rows) console.log(row.map((cell, i) => padColumn(cell, widths[i])).join(""));
-}
-function printSkillTree(skills, opts) {
-	const roots = [];
-	const children = /* @__PURE__ */ new Map();
-	for (const skill of skills) {
-		const slashIdx = skill.name.indexOf("/");
-		if (slashIdx === -1) roots.push(skill.name);
-		else {
-			const parent = skill.name.slice(0, slashIdx);
-			if (!children.has(parent)) children.set(parent, []);
-			children.get(parent).push(skill);
-		}
-	}
-	if (roots.length === 0) {
-		for (const skill of skills) if (!roots.includes(skill.name)) roots.push(skill.name);
-	}
-	for (const rootName of roots) {
-		const rootSkill = skills.find((s) => s.name === rootName);
-		if (!rootSkill) continue;
-		printSkillLine(rootName, rootSkill, 4, opts);
-		for (const sub of children.get(rootName) ?? []) printSkillLine(sub.name.slice(sub.name.indexOf("/") + 1), sub, 6, opts);
-	}
-}
-function printSkillLine(displayName, skill, indent, opts) {
-	const nameStr = " ".repeat(indent) + displayName;
-	const padding = " ".repeat(Math.max(2, opts.nameWidth - nameStr.length));
-	const typeCol = opts.showTypes ? (skill.type ? `[${skill.type}]` : "").padEnd(14) : "";
-	console.log(`${nameStr}${padding}${typeCol}${skill.description}`);
-}
-function computeSkillNameWidth(allPackageSkills) {
-	let max = 0;
-	for (const skills of allPackageSkills) for (const s of skills) {
-		const slashIdx = s.name.indexOf("/");
-		const displayName = slashIdx === -1 ? s.name : s.name.slice(slashIdx + 1);
-		const indent = slashIdx === -1 ? 4 : 6;
-		max = Math.max(max, indent + displayName.length);
-	}
-	return max + 2;
-}
 async function cmdList() {
 	let result;
 	try {
@@ -92,8 +44,7 @@ async function cmdList() {
 	}
 	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(`  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
 	console.log();
 	if (result.warnings.length > 0) {
 		console.log(`Warnings:`);

package/dist/library-scanner.d.mts

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

package/dist/library-scanner.mjs

@@ -1,4 +1,4 @@
 import "./utils-DH3jY3CI.mjs";
-import { t as scanLibrary } from "./library-scanner-D0aP7is_.mjs";
+import { t as scanLibrary } from "./library-scanner-V9sTOhrb.mjs";
 
 export { scanLibrary };

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

@@ -47,30 +47,47 @@ function copyTemplates(srcDir, destDir, vars) {
 		skipped
 	};
 }
-const SHIM_CONTENT = `#!/usr/bin/env node
+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.js" }
+//   "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 shimPath = join(root, "bin", "intent.js");
-	if (existsSync(shimPath)) {
-		result.skipped.push(shimPath);
+	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, SHIM_CONTENT);
+	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 defaultAll = !doWorkflows && !doShim;
-	const installWorkflows = doWorkflows || defaultAll;
-	const installShim = doShim || defaultAll;
+	const noFlagsGiven = !doWorkflows && !doShim;
+	const installWorkflows = doWorkflows || noFlagsGiven;
+	const installShim = doShim || noFlagsGiven;
 	const vars = detectVars(root);
 	const result = {
 		workflows: [],
@@ -87,10 +104,11 @@ function runSetup(root, metaDir, args) {
 	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": "./bin/intent.js" }`);
-		console.log(`\n  Add bin/intent.js to your package.json "files" array.`);
+		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) {

package/dist/setup.d.mts

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

package/dist/setup.mjs

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

package/meta/domain-discovery/SKILL.md

@@ -337,7 +337,30 @@ only considers one side.
 Target 2–4 tensions. If you find none, the skills may be too isolated —
 revisit whether you're missing cross-connections.
 
-### 3f — Identify gaps
+### 3f — Map cross-references
+
+Beyond tensions (conflicts) and shared failure modes, identify skills
+that illuminate each other without conflicting. A cross-reference means:
+"an agent loading skill A would produce better code if it knew about
+skill B." These become "See also" pointers in the generated SKILL.md
+files.
+
+For each pair, note:
+
+- Which skill references which (can be bidirectional)
+- Why awareness of the other skill improves output
+
+Examples:
+
+- A quickstart skill references the security checklist ("after setup, audit")
+- A state management skill references an SSR skill ("state hydration
+  requires understanding SSR lifecycle")
+- A data writing skill references a data reading skill ("writes affect
+  how queries invalidate")
+
+Output these in the `cross_references` section of domain_map.yaml.
+
+### 3g — Identify gaps
 
 For each skill, explicitly list what you could NOT determine from docs
 and source alone. These become interview questions in Phase 4.
@@ -351,7 +374,7 @@ Common gaps:
 - "GitHub issues show confusion about X but docs don't address it"
 - "I found two patterns for doing X — unclear which is current/preferred"
 
-### 3g — Discover composition targets
+### 3h — Discover composition targets
 
 Scan `package.json` for peer dependencies, optional dependencies, and
 `peerDependenciesMeta`. Scan example directories and integration tests
@@ -363,7 +386,7 @@ for import patterns. For each frequently co-used library, log:
 
 These become targeted composition questions in Phase 4e.
 
-### 3h — Produce the draft
+### 3i — Produce the draft
 
 Write the full `domain_map.yaml` (format in Output Artifacts below) with
 a `status: draft` field. Flag every gap in the `gaps` section.
@@ -405,7 +428,7 @@ Follow up on any corrections. Then:
 
 ### 4b — Gap-targeted questions (3–8 questions)
 
-For each gap flagged in Phase 3f, ask a specific question. These are not
+For each gap flagged in Phase 3g, ask a specific question. These are not
 generic — they reference what you found:
 
 **Instead of:** "What do developers get wrong?"
@@ -472,7 +495,7 @@ These surface knowledge that doesn't appear in any docs:
 
 ### 4e — Composition questions (if library interacts with others)
 
-Use what you discovered in Phase 3g. For each integration target
+Use what you discovered in Phase 3h. For each integration target
 identified from peer dependencies and example code, ask targeted
 questions:
 
@@ -573,6 +596,11 @@ tensions:
     description: '[what conflicts — one sentence]'
     implication: '[what an agent gets wrong when it only considers one side]'
 
+cross_references:
+  - from: '[skill-slug]'
+    to: '[skill-slug]'
+    reason: '[why loading one skill benefits from awareness of the other]'
+
 gaps:
   - skill: '[skill slug]'
     question: '[what still needs input]'
@@ -618,6 +646,12 @@ not promotional.]
 | -------------- | ------------------- | ----------------------- |
 | [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] |
 
+## Cross-References
+
+| From   | To     | Reason                                    |
+| ------ | ------ | ----------------------------------------- |
+| [slug] | [slug] | [why awareness of one improves the other] |
+
 ## Subsystems & Reference Candidates
 
 | Skill  | Subsystems                     | Reference candidates       |
@@ -672,6 +706,7 @@ not promotional.]
 | Subsystems flagged                    | Skills with 3+ adapters/backends list them as subsystems                   |
 | 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                  |
 
 ---
 

package/meta/feedback-collection/SKILL.md

@@ -4,12 +4,11 @@ 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.
+  and brief human input, then submits directly via gh CLI or provides manual
+  submission instructions.
 metadata:
-  version: '1.0'
+  version: '2.0'
   category: meta-tooling
-  output_artifacts:
-    - intent-feedback.json
 ---
 
 # Skill Feedback Collection
@@ -83,74 +82,86 @@ 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>"
-}
-```
+## Phase 3 — Build the Feedback
 
-### Field derivation guide
+Write one Markdown feedback file per skill used. Only include skills that were
+actually used during the session — skip any that were loaded but never
+referenced.
+
+### Template
+
+```markdown
+# Skill Feedback: [skill name from SKILL.md frontmatter]
+
+**Package:** [npm package name that contains the skill]
+**Skill version:** [metadata.version or library_version from frontmatter]
+**Rating:** [good | mixed | bad]
+
+## Task
+
+[one-sentence summary of what the human asked you to do]
+
+## What Worked
+
+[patterns/instructions from the skill that were accurate and helpful]
+
+## What Failed
+
+[from 1b — skill instructions that produced errors]
+
+## Missing
 
-| 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."
-}
+[from 1a — gaps where the skill should have covered]
+
+## Self-Corrections
+
+[from 1b fixes + 1c human interventions, combined]
+
+## User Comments
+
+[optional — direct quotes or paraphrased human input from Phase 2]
 ```
 
-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.
+### Field derivation guide
+
+| Field            | Source                                                             |
+| ---------------- | ------------------------------------------------------------------ |
+| Skill name       | Frontmatter `name` field of the SKILL.md you loaded                |
+| Package          | The npm package the skill lives in (e.g. `@tanstack/query-intent`) |
+| Skill version    | Frontmatter `metadata.version` or `library_version`                |
+| Task             | Summarize the human's original request in one sentence             |
+| What Worked      | List skill sections/patterns that were correct and useful          |
+| What Failed      | From 1b — skill instructions that produced errors                  |
+| Missing          | From 1a — gaps where the skill was silent                          |
+| Self-Corrections | From 1b fixes + 1c human interventions, combined                   |
+| Rating           | From Phase 2 sentiment analysis or explicit rating                 |
+| User Comments    | From Phase 2 answers, keep brief                                   |
 
 ---
 
 ## Phase 4 — Submit
 
-1. Save the payload to `intent-feedback.json` in the project root.
-   If multiple skills, save as a JSON array.
+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.
+
+### If `gh` CLI is available
+
+Submit directly as a GitHub issue:
+
+```bash
+gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "feedback:[skill-name]" --body-file intent-feedback.md
+```
+
+If the label doesn't exist, omit the `--label` flag — don't let a missing
+label block submission.
 
-2. Submit:
+If submission succeeds, delete the feedback file.
 
-   ```bash
-   npx intent feedback --submit --file intent-feedback.json
-   ```
+### If `gh` CLI is not available
 
-3. If the submission succeeds, delete `intent-feedback.json`.
+Tell the human:
 
-4. If it fails, tell the human and leave the file for manual retry.
+> "I've written skill feedback to `intent-feedback.md`. To submit it,
+> open an issue at https://github.com/[owner/repo]/issues and paste the
+> contents."