@tanstack/intent 0.1.0 → 0.2.0

package/meta/generate-skill/SKILL.md

@@ -52,7 +52,9 @@ SKILL.md into that package's skills directory (e.g.
 `packages/client/skills/core/SKILL.md`), not a shared root.
 
 1. **Skill name** — format `library-group/skill-name` (e.g. `tanstack-query/core`,
-   `tanstack-router/loaders`, `db/core/live-queries`)
+   `tanstack-router/loaders`, `db/core/live-queries`). This is the skill's
+   directory path: its **last segment** becomes the frontmatter `name` (a
+   spec-legal leaf), and the full path is where the `SKILL.md` lives.
 2. **Skill description** — what the skill covers and when an agent should load it
 3. **Source documentation** — the docs, guides, API references, and/or source
    files to distill from
@@ -118,7 +120,7 @@ cannot already know:
 
 Before writing the skill body, search the library's GitHub repo for issues
 and discussions relevant to THIS skill's topic. This step is important for
-both initial generation and regeneration — community feedback reveals
+both initial generation and regeneration — issue discussions reveal
 failure modes that docs miss.
 
 **Search strategy:**
@@ -170,17 +172,18 @@ domain-discovery — use those directly.
 
 ```yaml
 ---
-name: [library]/[skill-name]
+name: '[skill-name]'
 description: >
   [1–3 sentences. What this skill covers and exactly when an agent should
   load it. Written for the agent — include the keywords an agent would
   encounter when it needs this skill. Dense routing key.]
-type: core
-library: [library]
-library_version: "[version this targets]"
+metadata:
+  type: core
+  library: '[library]'
+  library_version: '[version this targets]'
 sources:
-  - "[Owner/repo]:docs/[path].md"
-  - "[Owner/repo]:src/[path].ts"
+  - '[Owner/repo]:docs/[path].md'
+  - '[Owner/repo]:src/[path].ts'
 ---
 ```
 
@@ -188,14 +191,15 @@ sources:
 
 ```yaml
 ---
-name: [library]/[parent]/[skill-name]
+name: '[skill-name]'
 description: >
   [1–3 sentences. What this sub-topic covers and when to load it.]
-type: sub-skill
-library: [library]
-library_version: "[version]"
+metadata:
+  type: sub-skill
+  library: '[library]'
+  library_version: '[version]'
 sources:
-  - "[Owner/repo]:docs/[path].md"
+  - '[Owner/repo]:docs/[path].md'
 ---
 ```
 
@@ -203,29 +207,39 @@ sources:
 
 ```yaml
 ---
-name: [library]/[framework]
+name: '[framework]'
 description: >
   [1–3 sentences. Framework-specific bindings. Name the hooks, components,
   providers.]
-type: framework
-library: [library]
-framework: [react | vue | solid | svelte | angular]
-library_version: "[version]"
+metadata:
+  type: framework
+  library: '[library]'
+  framework: '[react | vue | solid | svelte | angular]'
+  library_version: '[version]'
 requires:
-  - [library]/core
+  - '[library]/core'
 sources:
-  - "[Owner/repo]:docs/framework/[framework]/[path].md"
+  - '[Owner/repo]:docs/framework/[framework]/[path].md'
 ---
 ```
 
 ### Frontmatter rules
 
+- `name` is the spec-legal leaf segment — lowercase letters, numbers, and
+  hyphens only — and matches the skill's parent directory. It carries no
+  slashes; the namespace lives in the skill's directory path instead.
+- Intent-specific scalars (`type`, `library`, `library_version`, `framework`)
+  live under the `metadata` map. The Agent Skills spec permits only `name`,
+  `description`, `license`, `compatibility`, `metadata`, and `allowed-tools`
+  at the top level, so emitting these scalars at the top level fails
+  validation.
 - `description` must be written so the agent loads this skill at the right
   time — not too broad (triggers on everything) and not too narrow (never
   triggers). Pack with function names, option names, concept keywords.
 - `sources` uses the format `Owner/repo:relative-path`. Glob patterns are
   supported (e.g. `TanStack/query:docs/framework/react/guides/*.md`).
-- `library_version` is the version of the source library this skill targets.
+- `metadata.library_version` is the version of the source library this skill
+  targets.
 - `requires` lists skills that must be loaded before this one.
 
 ---
@@ -443,11 +457,4 @@ Output is consumed by all major AI coding agents. To ensure consistency:
 - Critical info at start or end of sections (not buried in middle)
 - Each SKILL.md is self-contained except for declared `requires`
 
----
-
-## Meta-skill feedback
-
-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

@@ -287,14 +287,15 @@ framework-agnostic concepts and contains the sub-skill registry.
 
 ```yaml
 ---
-name: [lib]-core
+name: '[lib]-core'
 description: >
   [1–3 sentences. What this library does and the framework-agnostic
   concepts it provides. Pack with keywords: function names, config
   options, concepts. This is a routing key, not a human summary.]
-type: core
-library: [lib]
-library_version: "[version this targets]"
+metadata:
+  type: core
+  library: '[lib]'
+  library_version: '[version this targets]'
 ---
 ```
 
@@ -332,16 +333,17 @@ One SKILL.md per domain. Follow this structure exactly.
 
 ```yaml
 ---
-name: [lib]-core/[domain-slug]
+name: '[domain-slug]'
 description: >
   [1–3 sentences. What this domain covers AND when to load it. Name
   specific functions, options, or APIs. Dense routing key.]
-type: sub-skill
-library: [lib]
-library_version: "[version]"
+metadata:
+  type: sub-skill
+  library: '[lib]'
+  library_version: '[version]'
 sources:
-  - "[repo]:docs/[path].md"
-  - "[repo]:src/[path].ts"
+  - '[repo]:docs/[path].md'
+  - '[repo]:src/[path].ts'
 ---
 ```
 
@@ -452,17 +454,18 @@ framework-specific patterns and mistakes.
 
 ```yaml
 ---
-name: react-[lib]
+name: 'react-[lib]'
 description: >
   [1–3 sentences. React-specific bindings for [library]. Name the hooks,
   components, and providers. Mention React-specific patterns like SSR
   hydration if applicable.]
-type: framework
-library: [lib]
-framework: react
-library_version: "[version]"
+metadata:
+  type: framework
+  library: '[lib]'
+  framework: react
+  library_version: '[version]'
 requires:
-  - [lib]-core
+  - '[lib]-core'
 ---
 ```
 
@@ -499,18 +502,18 @@ with the framework frontmatter:
 
 ```yaml
 ---
-name: react-[lib]/[domain-slug]
+name: '[domain-slug]'
 description: >
   [React-specific description for this domain.]
-type: sub-skill
-library: [lib]
-framework: react
-library_version: "[version]"
+metadata:
+  type: sub-skill
+  library: '[lib]'
+  framework: react
+  library_version: '[version]'
 requires:
-  - [lib]-core
-  - [lib]-core/[domain-slug]
+  - '[lib]-core'
+  - '[lib]-core/[domain-slug]'
 ---
-
 This skill builds on [lib]-core/[domain-slug]. Read the core skill first.
 ```
 
@@ -556,19 +559,19 @@ framework hooks and providers).
 
 ```yaml
 ---
-name: compositions/[lib-a]-[lib-b]
+name: '[lib-a]-[lib-b]'
 description: >
   [How lib-a and lib-b wire together. Name the specific integration
   points: functions, hooks, patterns.]
-type: composition
-library_version: "[version of primary lib]"
+metadata:
+  type: composition
+  library_version: '[version of primary lib]'
 requires:
-  - [lib-a]-core
-  - react-[lib-a]
-  - [lib-b]-core
-  - react-[lib-b]
+  - '[lib-a]-core'
+  - 'react-[lib-a]'
+  - '[lib-b]-core'
+  - 'react-[lib-b]'
 ---
-
 This skill requires familiarity with both [lib-a] and [lib-b].
 Read their core and framework skills first.
 ```
@@ -601,15 +604,16 @@ for these skill types.
 
 ```yaml
 ---
-name: react-[lib]/security
+name: security
 description: >
   Go-live security validation for [library]. Checks [specific concerns].
-type: security
-library: [lib]
-framework: react
-library_version: '[version]'
+metadata:
+  type: security
+  library: '[lib]'
+  framework: react
+  library_version: '[version]'
 requires:
-  - react-[lib]
+  - 'react-[lib]'
 ---
 ```
 
@@ -702,7 +706,7 @@ Run when:
 - The library has released a new version
 - A maintainer reports skills produce outdated code
 - A changelog or migration guide has been published since skill creation
-- Feedback reports indicate skill content is inaccurate
+- Issue reports indicate skill content is inaccurate
 
 ### Step 1 — Detect staleness
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tanstack/intent",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Ship compositional knowledge for AI coding agents alongside your npm packages",
   "license": "MIT",
   "type": "module",
@@ -28,14 +28,13 @@
   "dependencies": {
     "cac": "^6.7.14",
     "jsonc-parser": "^3.3.1",
-    "semver": "^7.7.4",
-    "yaml": "2.8.3"
+    "semver": "^7.8.4",
+    "yaml": "2.9.0"
   },
   "devDependencies": {
     "@types/semver": "^7.7.1",
-    "@verdaccio/node-api": "6.0.0-6-next.76",
-    "tsdown": "^0.19.0",
-    "verdaccio": "^6.3.2"
+    "tsdown": "^0.22.2",
+    "verdaccio": "^6.7.2"
   },
   "scripts": {
     "build": "tsdown src/index.ts src/cli.ts src/setup.ts src/core.ts --format esm --dts",

package/dist/artifact-coverage-BfJ7f-S9.mjs

@@ -1,3 +0,0 @@
-import { t as readIntentArtifacts } from "./artifact-coverage-nGwun1tt.mjs";
-
-export { readIntentArtifacts };

package/dist/source-policy-y3sktvzu.mjs

@@ -1,9 +0,0 @@
-import "./utils-9fhWAVua.mjs";
-import "./skill-paths-B-j0dWDA.mjs";
-import "./scanner-CRCZwhKS.mjs";
-import "./workspace-patterns-BffPlZ1D.mjs";
-import "./project-context-DBSibDPb.mjs";
-import "./excludes-DG83YEzb.mjs";
-import { a as checkLoadAllowed, i as applySourcePolicy, n as EMPTY_NOTE, o as readSkillSourcesConfig, r as MIGRATION_NOTICE, s as scanForPolicedIntents, t as ALLOW_ALL_NOTICE } from "./source-policy-DaImacFt.mjs";
-
-export { scanForPolicedIntents };

package/dist/staleness-BoFc6DMh.mjs

@@ -1,5 +0,0 @@
-import "./utils-9fhWAVua.mjs";
-import "./artifact-coverage-nGwun1tt.mjs";
-import { n as checkStaleness, r as readPackageName, t as buildWorkspaceCoverageSignals } from "./staleness-DVFARTES.mjs";
-
-export { buildWorkspaceCoverageSignals, checkStaleness, readPackageName };

package/dist/utils-CSPzvaFu.mjs

@@ -1,3 +0,0 @@
-import { a as listNestedNodeModulesPackageDirs, c as parseFrontmatter, i as getDeps, l as resolveDepDir, n as detectGlobalNodeModules, o as listNodeModulesPackageDirs, r as findSkillFiles, s as nodeReadFs, t as createFsIdentityCache, u as toPosixPath } from "./utils-9fhWAVua.mjs";
-
-export { createFsIdentityCache, detectGlobalNodeModules, findSkillFiles, getDeps, listNestedNodeModulesPackageDirs, listNodeModulesPackageDirs, nodeReadFs, parseFrontmatter, resolveDepDir, toPosixPath };

package/dist/workspace-patterns-Bjq_cXww.mjs

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

package/meta/feedback-collection/SKILL.md

@@ -1,234 +0,0 @@
----
-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 directly via gh CLI or provides manual
-  submission instructions.
-metadata:
-  version: '2.0'
-  category: meta-tooling
----
-
-# 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.
-
-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
-
-Review your own session transcript. No human interaction needed yet.
-
-### 1a: Skills inventory
-
-Before analyzing gaps and errors, inventory all skills that were available
-during the session:
-
-- **Loaded and used:** Skills you read and actively followed.
-- **Available but not loaded:** Skills that were installed (discoverable via
-  `npx @tanstack/intent@latest list`) but you never read. This is important — many issues stem from
-  the agent not loading the right skill, not from the skill itself being wrong.
-
-### 1b: 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)
-
-### 1c: 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
-
-### 1d: 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
-
-### 1e: 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 Feedback
-
-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]
-
-## Skills Inventory
-
-**Loaded and used:**
-
-- [list each skill the agent read and actively followed during the session]
-
-**Available but not loaded:**
-
-- [list skills that were installed/available but the agent never read]
-
-## What Worked
-
-[patterns/instructions from the skill that were accurate and helpful]
-
-## What Failed
-
-[from 1c — skill instructions that produced errors]
-
-## Missing
-
-[from 1b — gaps where the skill should have covered]
-
-## Self-Corrections
-
-[from 1c fixes + 1d human interventions, combined]
-
-## User Comments
-
-[optional — direct quotes or paraphrased human input from Phase 2]
-```
-
-### 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             |
-| Skills Inventory | Which skills were loaded vs. available but not loaded (see below)  |
-| What Worked      | List skill sections/patterns that were correct and useful          |
-| What Failed      | From 1c — skill instructions that produced errors                  |
-| Missing          | From 1b — gaps where the skill was silent                          |
-| Self-Corrections | From 1c fixes + 1d human interventions, combined                   |
-| Rating           | From Phase 2 sentiment analysis or explicit rating                 |
-| User Comments    | From Phase 2 answers, keep brief                                   |
-
----
-
-## Phase 4 — Submit
-
-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.
-
-### Link to existing issues/discussions
-
-Before creating a new issue, search the target repo for existing issues or
-discussions that match the feedback. Use `gh search issues` or the GitHub
-web search with keywords from the "What Failed" and "Missing" sections.
-
-- If an **open issue** already describes the same problem, comment on it
-  with the feedback instead of creating a duplicate. Reference the skill
-  name and version in your comment.
-- If a **closed issue** describes a problem the skill still gets wrong
-  (regression or stale skill content), reference the closed issue in the
-  new feedback issue body: `Related to #[number] — this was fixed in the
-library but the skill still describes the old behavior.`
-- If a **discussion thread** covers the same topic, link to it in the
-  feedback issue body so maintainers can see the community context.
-
-This prevents duplicate issues and gives maintainers richer context for
-improving skills.
-
-### 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:
-
-```bash
-gh issue create --repo [owner/repo] --title "Skill Feedback: [skill-name] ([rating])" --label "skill:[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.
-
-If submission succeeds, delete the feedback file.
-
-### If `gh` CLI is not available
-
-Tell the human:
-
-> "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."