@tanstack/intent 0.0.8 → 0.0.10

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
 
@@ -19,35 +25,51 @@ pnpm add -D @tanstack/intent
 Set up skill-to-task mappings in your project's agent config files (CLAUDE.md, .cursorrules, etc.):
 
 ```bash
-npx intent install
+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
-npx intent list
+npx @tanstack/intent list
 ```
 
 ### For library maintainers
 
-Generate skills for your library using the guided scaffold workflow:
+Generate skills for your library by telling your AI coding agent to run:
 
 ```bash
-npx intent scaffold
+npx @tanstack/intent scaffold
 ```
 
+This prints a prompt that walks the agent through domain discovery, skill tree generation, and skill creation — one step at a time with your review at each stage.
+
 Validate your skill files:
 
 ```bash
-npx intent validate
+npx @tanstack/intent validate
 ```
 
-Copy CI workflow templates into your repo:
+Check for skills that have fallen behind their sources:
 
 ```bash
-npx intent setup
+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. `intent stale` flags skills whose source docs have changed, and CI templates catch drift before it ships.
+
+The feedback loop runs both directions. `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                                         |
@@ -59,6 +81,7 @@ npx intent setup
 | `intent validate [dir]` | Validate SKILL.md files                             |
 | `intent setup`          | Copy CI templates, generate shim, create labels     |
 | `intent stale [--json]` | Check skills for version drift                      |
+| `intent feedback`       | Submit skill feedback                               |
 
 ## License
 

package/dist/cli.mjs

@@ -57,7 +57,7 @@ async function cmdList(args) {
 		console.log();
 	}
 	console.log(`Feedback:`);
-	console.log(`  After completing your task, collect feedback on skill usage.`);
+	console.log(`  Submit feedback on skill usage to help maintainers improve the skills.`);
 	console.log(`  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
 	console.log();
 	if (result.warnings.length > 0) {

package/dist/intent-library.mjs

@@ -43,7 +43,7 @@ async function cmdList() {
 		console.log();
 	}
 	console.log(`Feedback:`);
-	console.log(`  After completing your task, collect feedback on skill usage.`);
+	console.log(`  Submit feedback on skill usage to help maintainers improve the skills.`);
 	console.log(`  Load: node_modules/@tanstack/intent/meta/feedback-collection/SKILL.md`);
 	console.log();
 	if (result.warnings.length > 0) {

package/meta/domain-discovery/SKILL.md

@@ -31,7 +31,8 @@ before launch"). Domains are an intermediate conceptual grouping you use
 during analysis; the final skills emerge from the intersection of domains
 and developer tasks.
 
-There are five phases. Always run them in order.
+There are five phases. Always run them in order — unless the lightweight
+path applies (see below).
 
 1. **Quick scan** — orient yourself (autonomous)
 2. **High-level interview** — extract the maintainer's task map
@@ -39,6 +40,25 @@ There are five phases. Always run them in order.
 4. **Detail interview** — gap-targeted questions, AI-agent failures
 5. **Finalize artifacts**
 
+### 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:
+
+1. **Phase 1** — Quick scan (same as full flow)
+2. **Phase 2+4 combined** — Single interview round. Combine the
+   high-level task map questions (Phase 2) with gap-targeted and
+   AI-agent-specific questions (Phase 4) into one interview session
+   of 4–8 questions total. Skip the draft-review step since the skill
+   set is small enough to confirm in one pass.
+3. **Phase 3** — Deep read (same as full flow, but scope is smaller)
+4. **Phase 5** — Finalize artifacts (same as full flow)
+
+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.
+
 ---
 
 ## Phase 1 — Quick scan (autonomous, ~10 minutes)

package/meta/feedback-collection/SKILL.md

@@ -145,6 +145,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

@@ -356,9 +356,9 @@ updates preserve review effort and reduce diff noise.
 
 | Rule | Detail |
 |------|--------|
-| React adapter only (Phase 1) | No Vue, Solid, Svelte, Angular examples unless generating a framework skill for that adapter |
+| Match the library's framework support | Generate framework skills only for adapters the library actually provides. If the library supports only React, only generate React examples. If it supports multiple frameworks, generate one skill per adapter. |
 | All imports use real package names | `@tanstack/react-query`, not `react-query` |
-| No placeholder code | No `// ...`, `[your value]`, or `...rest` |
+| No placeholder code | No `// ...`, `[your value]`, or `...rest`. Idiomatic framework patterns like `{children}` or `{props.title}` in JSX are not placeholders — they are real code and are acceptable. |
 | Agent-first writing | Only write what the agent cannot already know |
 | Examples are minimal | No unnecessary boilerplate or wrapper components |
 | Failure modes are high-value | Focus on plausible-but-broken, not obvious errors |

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

@@ -41,7 +41,7 @@ jobs:
       - name: Check staleness
         id: stale
         run: |
-          OUTPUT=$(npx intent stale --json 2>&1) || true
+          OUTPUT=$(npx @tanstack/intent stale --json 2>&1) || true
           echo "$OUTPUT"
 
           # Check if any skills need review
@@ -89,7 +89,7 @@ jobs:
               '1. Read the current SKILL.md file',
               '2. Check what changed in the library since the skill was last updated',
               '3. Update the skill content to reflect current APIs and behavior',
-              '4. Run \`npx intent validate\` to verify the updated skill',
+              '4. Run \`npx @tanstack/intent validate\` to verify the updated skill',
             ].join('\n');
 
             // Write outputs

package/meta/tree-generator/SKILL.md

@@ -124,6 +124,24 @@ package directory (e.g. `packages/client/skills/core/SKILL.md`). Set the
 `package` field so generate-skill knows where to write the file. The domain
 map artifacts stay at the repo root.
 
+### Minimal library fast path
+
+If the domain map contains **fewer than 5 skills** and no framework
+adapter packages, skip the core overview + sub-skill registry pattern.
+Instead:
+
+- Use **flat structure** — each skill gets its own `skills/[skill-name]/SKILL.md`
+- **No router skill** — the intent CLI `list` command is sufficient for discovery
+- **No core overview skill** — go directly to individual skill files
+- Each skill is type `core` (not `sub-skill`) and stands alone without
+  a parent registry
+- Skip Step 2 (core overview) and Step 3 (sub-skills) — go directly to
+  writing individual skills as standalone core skills using Step 3's body
+  format
+
+This avoids unnecessary scaffolding for focused libraries where the
+overhead of a hierarchical skill tree exceeds the navigation benefit.
+
 ### Step 1 — Plan the file tree
 
 From the domain map, each entry in the `skills` list becomes a SKILL.md
@@ -229,7 +247,8 @@ table) is optional. If the intent CLI provides `list` and `show`
 commands, agents can discover skills directly without a router. Only
 create a router skill if the skill set is large enough (15+) that
 browsing the list is insufficient, or if the nested structure needs
-an entry point to guide agents to the right sub-skill.
+an entry point to guide agents to the right sub-skill. Libraries with
+fewer than 5 skills should never have a router skill.
 
 **Source repository layout for npm distribution:**
 

package/package.json

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