@tanstack/intent 0.0.4 → 0.0.6

package/meta/generate-skill/SKILL.md

@@ -47,6 +47,10 @@ You will receive:
 If the maintainer uses a custom skills root, replace `skills/` in any paths
 below with their chosen directory.
 
+**Monorepo:** When the skill tree entry has a `package` field, write the
+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`)
 2. **Skill description** — what the skill covers and when an agent should load it
@@ -77,6 +81,11 @@ skill-tree-generator for the full spec of each type.
 
 ## Step 2 — Extract content from sources
 
+**Line budget:** Each SKILL.md must stay under 500 lines. Before writing,
+estimate the content size. If a skill has 5+ failure modes, 3+ primary
+patterns, and subsystem details, proactively plan reference files during
+extraction — don't wait until the skill exceeds the limit.
+
 Read through the source documentation. Extract only what a coding agent
 cannot already know:
 

package/meta/skill-staleness-check/SKILL.md

@@ -2,10 +2,10 @@
 name: skill-staleness-check
 description: >
   Evaluate intent skills for staleness when source files change in upstream
-  TanStack package repos. Driven by Oz automation on webhook trigger. Matches
-  changed files against metadata.sources, evaluates whether diffs affect
-  documented behavior, rewrites stale skills using skill-generate, checks
-  cross-skill references, and opens PRs. Silent when nothing needs updating.
+  TanStack package repos. Matches changed files against metadata.sources,
+  evaluates whether diffs affect documented behavior, rewrites stale skills
+  using skill-generate, checks cross-skill references, and opens PRs.
+  Silent when nothing needs updating.
 metadata:
   version: '1.0'
   category: meta-tooling
@@ -21,10 +21,10 @@ metadata:
 
 # Skill Staleness Check
 
-You are an Oz automation agent. Your job is to evaluate whether intent
-skills are stale after upstream source changes, and if so, update them and
-open PRs. You act autonomously end-to-end. PRs contain already-updated
-skill content, not suggestions.
+You are a coding agent. Your job is to evaluate whether intent skills are
+stale after upstream source changes, and if so, update them and open PRs.
+You act autonomously end-to-end. PRs contain already-updated skill
+content, not suggestions.
 
 If nothing needs updating, exit silently. No PR, no notification.
 
@@ -279,4 +279,4 @@ node scripts/sync-skills.mjs db --mark-synced --all
 | One cascade level                               | Cross-skill checks go one level deep, not recursive |
 | PRs scoped to one library                       | Never mix libraries in a single PR                  |
 | Version bumps are separate from content updates | A version-only bump doesn't require regeneration    |
-| Commit messages include co-author               | `Co-Authored-By: Oz <oz-agent@warp.dev>`            |
+| Commit messages include co-author               | Include the coding agent's co-author tag            |

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

@@ -0,0 +1,143 @@
+# check-skills.yml — Drop this into your library repo's .github/workflows/
+#
+# Checks for stale intent skills after a release and opens a review PR
+# if any skills need attention. The PR body includes a prompt you can
+# paste into Claude Code, Cursor, or any coding agent to update them.
+#
+# Triggers: new release published, or manual workflow_dispatch.
+#
+# Template variables (replaced by `intent setup`):
+#   {{PACKAGE_NAME}}  — e.g. @tanstack/query
+
+name: Check Skills
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch: {}
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  check:
+    name: Check for stale skills
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install intent
+        run: npm install {{PACKAGE_NAME}}
+
+      - name: Check staleness
+        id: stale
+        run: |
+          OUTPUT=$(npx intent stale --json 2>&1) || true
+          echo "$OUTPUT"
+
+          # Check if any skills need review
+          NEEDS_REVIEW=$(echo "$OUTPUT" | node -e "
+            const input = require('fs').readFileSync('/dev/stdin','utf8');
+            try {
+              const reports = JSON.parse(input);
+              const stale = reports.flatMap(r =>
+                r.skills.filter(s => s.needsReview).map(s => ({ library: r.library, skill: s.name, reasons: s.reasons }))
+              );
+              if (stale.length > 0) {
+                console.log(JSON.stringify(stale));
+              }
+            } catch {}
+          ")
+
+          if [ -z "$NEEDS_REVIEW" ]; then
+            echo "has_stale=false" >> "$GITHUB_OUTPUT"
+          else
+            echo "has_stale=true" >> "$GITHUB_OUTPUT"
+            # Escape for multiline GH output
+            EOF=$(dd if=/dev/urandom bs=15 count=1 status=none | base64)
+            echo "stale_json<<$EOF" >> "$GITHUB_OUTPUT"
+            echo "$NEEDS_REVIEW" >> "$GITHUB_OUTPUT"
+            echo "$EOF" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build summary
+        if: steps.stale.outputs.has_stale == 'true'
+        id: summary
+        run: |
+          node -e "
+            const stale = JSON.parse(process.env.STALE_JSON);
+            const lines = stale.map(s =>
+              '- **' + s.skill + '** (' + s.library + '): ' + s.reasons.join(', ')
+            );
+            const summary = lines.join('\n');
+
+            const prompt = [
+              'Review and update the following stale intent skills for {{PACKAGE_NAME}}:',
+              '',
+              ...stale.map(s => '- ' + s.skill + ': ' + s.reasons.join(', ')),
+              '',
+              'For each stale skill:',
+              '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',
+            ].join('\n');
+
+            // Write outputs
+            const fs = require('fs');
+            const env = fs.readFileSync(process.env.GITHUB_OUTPUT, 'utf8');
+            const eof = require('crypto').randomBytes(15).toString('base64');
+            fs.appendFileSync(process.env.GITHUB_OUTPUT,
+              'summary<<' + eof + '\n' + summary + '\n' + eof + '\n' +
+              'prompt<<' + eof + '\n' + prompt + '\n' + eof + '\n'
+            );
+          "
+        env:
+          STALE_JSON: ${{ steps.stale.outputs.stale_json }}
+
+      - name: Open review PR
+        if: steps.stale.outputs.has_stale == 'true'
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          VERSION="${{ github.event.release.tag_name || 'manual' }}"
+          BRANCH="skills/review-${VERSION}"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$BRANCH"
+          git commit --allow-empty -m "chore: review stale skills for ${VERSION}"
+          git push origin "$BRANCH"
+
+          gh pr create \
+            --title "Review stale skills (${VERSION})" \
+            --body "$(cat <<'PREOF'
+          ## Stale Skills Detected
+
+          The following skills may need updates after the latest release:
+
+          ${{ steps.summary.outputs.summary }}
+
+          ---
+
+          ### Update Prompt
+
+          Paste this into your coding agent (Claude Code, Cursor, etc.):
+
+          ~~~
+          ${{ steps.summary.outputs.prompt }}
+          ~~~
+
+          PREOF
+          )" \
+            --head "$BRANCH" \
+            --base main

package/meta/tree-generator/SKILL.md

@@ -67,7 +67,7 @@ discovery. This produces lower-fidelity output than the full
 skill-domain-discovery skill — prefer running that when time permits.
 
 1. Build a concept inventory (every export, config key, constraint, warning)
-2. Group into 4–7 capability domains using work-oriented names
+2. Group into capability domains using work-oriented names (let library complexity drive the count — 2–3 for focused libraries, more for large frameworks)
 3. Enumerate 10–20 task-focused skills from the intersection of domains
    and developer tasks
 4. Extract 3+ failure modes per skill (plausible, silent, grounded)
@@ -106,6 +106,7 @@ skills:
     type: 'core | sub-skill | framework | lifecycle | composition | security'
     domain: '[domain slug]'
     path: 'skills/[path]/SKILL.md'
+    package: '[package directory, e.g. packages/client]' # monorepo only — which package this skill belongs to
     description: '[1–2 sentence agent-facing routing key]'
     requires:
       - '[other skill slugs]' # omit if none
@@ -118,6 +119,11 @@ skills:
       - 'references/[file].md' # omit if none
 ```
 
+**Monorepo layout:** For monorepos, each skill's `path` is relative to its
+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.
+
 ### Step 1 — Plan the file tree
 
 From the domain map, each entry in the `skills` list becomes a SKILL.md

package/package.json

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

package/dist/scanner-fAWJUn6Q.mjs

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

package/meta/templates/oz/domain-discovery.md

@@ -1,53 +0,0 @@
-# Oz Prompt: Domain Discovery
-
-Use this prompt with `oz agent run` (local) or `warpdotdev/oz-agent-action` (CI)
-to run domain discovery for a library.
-
-## Usage
-
-### Local (interactive — includes maintainer interview)
-
-```bash
-oz agent run --prompt "$(cat this-file.md)"
-```
-
-### CI (compressed — skips interview phases)
-
-Use the `generate-skills-oz.yml` workflow template instead.
-
----
-
-## Prompt
-
-Read the meta-skill at `node_modules/@tanstack/intent/meta/domain-discovery/SKILL.md`
-and follow its instructions for the library described below.
-
-### Library details
-
-- **Package:** [PACKAGE_NAME]
-- **Repository:** [REPO_URL]
-- **Docs path:** [DOCS_PATH]
-- **Primary framework:** [react | vue | solid | svelte | framework-agnostic]
-
-### Instructions
-
-Run the full 5-phase domain discovery process:
-
-1. **Phase 1 — Quick scan:** Orient yourself in the library
-2. **Phase 2 — High-level interview:** Ask the maintainer about developer tasks
-3. **Phase 3 — Deep read:** Read docs and source, build concept inventory
-4. **Phase 4 — Detail interview:** Fill gaps with targeted questions
-5. **Phase 5 — Finalize:** Produce domain_map.yaml and skill_spec.md
-
-Write the output artifacts to the repository root:
-
-- `domain_map.yaml`
-- `skill_spec.md`
-
-### After completion
-
-Tell the user:
-
-- "Domain discovery complete. Artifacts written to domain_map.yaml and skill_spec.md."
-- "Next step: load the tree-generator meta-skill to generate SKILL.md files."
-- "Run `npx intent feedback --meta --interactive` to share how this went."

package/meta/templates/oz/feedback-collection.md

@@ -1,69 +0,0 @@
-# Oz Prompt: Meta-Skill Feedback Collection
-
-Use this prompt to collect structured feedback about the meta-skill experience
-and submit it to TanStack/intent.
-
----
-
-## Prompt
-
-You are collecting feedback about the TanStack Intent meta-skill experience.
-The user just ran one or more meta-skills (domain-discovery, tree-generator,
-generate-skill, or skill-staleness-check) and you need to capture what worked
-and what didn't.
-
-### Questions to ask
-
-Walk through these questions one at a time:
-
-1. **Which meta-skill(s) did you use?**
-   (domain-discovery, tree-generator, generate-skill, skill-staleness-check)
-
-2. **What library were you generating skills for?**
-   (package name and version)
-
-3. **Which AI agent ran the meta-skill?**
-   (oz, claude-code, cursor, copilot, codex, other)
-
-4. **How would you rate the generated artifacts?**
-   (good / mixed / bad)
-   - If domain-discovery: How were the interview questions? Did they surface
-     the right failure modes and domain structure?
-   - If tree-generator: Were the generated SKILL.md files usable? Did the
-     structure match your library?
-   - If generate-skill: Was the individual skill accurate and complete?
-
-5. **What worked well?**
-   (free text — what the meta-skill got right)
-
-6. **What failed or was inaccurate?**
-   (free text — what the agent got wrong, what needed manual fixing)
-
-7. **What's missing?**
-   (free text — suggestions for improving the meta-skill instructions)
-
-8. **Overall rating:** good / mixed / bad
-
-### After collecting answers
-
-1. Format the feedback as JSON matching the MetaFeedbackPayload schema:
-
-```json
-{
-  "metaSkill": "domain-discovery",
-  "library": "@tanstack/query",
-  "agentUsed": "oz",
-  "artifactQuality": "good",
-  "interviewQuality": "mixed",
-  "failureModeQuality": "good",
-  "whatWorked": "...",
-  "whatFailed": "...",
-  "suggestions": "...",
-  "userRating": "mixed"
-}
-```
-
-2. Save to `intent-meta-feedback.json`
-3. Run: `npx intent feedback --meta --file intent-meta-feedback.json`
-4. If `gh` CLI is available, this submits directly to TanStack/intent.
-   Otherwise, it saves a markdown file the user can paste into a GitHub Discussion.

package/meta/templates/oz/skill-update.md

@@ -1,47 +0,0 @@
-# Oz Prompt: Skill Update (Staleness Check)
-
-Use this prompt to check existing skills for staleness after a library
-version change and surgically update any that are outdated.
-
-## Prerequisites
-
-- Existing skills in `skills/` directory
-- `@tanstack/intent` installed
-
----
-
-## Prompt
-
-Read the meta-skill at `node_modules/@tanstack/intent/meta/skill-staleness-check/SKILL.md`
-and follow its instructions.
-
-### Context
-
-- **Package:** [PACKAGE_NAME]
-- **Previous version:** [OLD_VERSION] (check skill frontmatter `library_version`)
-- **Current version:** [NEW_VERSION]
-- **Changelog:** [CHANGELOG_PATH or URL]
-
-### Task
-
-1. Find all SKILL.md files under skills/
-2. Compare each skill's `library_version` against the current version
-3. Read the changelog/migration guide for changes between versions
-4. For each skill, classify the impact: no-impact, version-bump, content-update, breaking
-5. For content updates and breaking changes:
-   - Read the generate-skill meta-skill at
-     `node_modules/@tanstack/intent/meta/generate-skill/SKILL.md`
-   - Use regeneration mode — surgical updates, not full rewrites
-   - Add old patterns as new Common Mistake entries for breaking changes
-6. Bump `library_version` in all updated skill frontmatter
-7. Run `npx intent validate skills/` to verify
-
-### Output
-
-If nothing needs updating, say so and exit.
-
-If skills were updated, summarize:
-
-- Which skills were updated and why
-- What sections changed
-- Any new Common Mistake entries added

package/meta/templates/oz/tree-generation.md

@@ -1,48 +0,0 @@
-# Oz Prompt: Tree Generation
-
-Use this prompt with `oz agent run` (local) or `warpdotdev/oz-agent-action` (CI)
-to generate a complete skill tree from domain discovery artifacts.
-
-## Prerequisites
-
-- `domain_map.yaml` and `skill_spec.md` in the repo (from domain discovery)
-- `@tanstack/intent` installed
-
----
-
-## Prompt
-
-Read the meta-skill at `node_modules/@tanstack/intent/meta/tree-generator/SKILL.md`
-and follow Workflow A (Generate) instructions.
-
-### Inputs
-
-- `domain_map.yaml` — in the repository root
-- `skill_spec.md` — in the repository root
-- Library source documentation is at [DOCS_PATH]
-
-### Task
-
-1. Read domain_map.yaml and skill_spec.md
-2. Plan the file tree based on the skill inventory
-3. Generate all SKILL.md files following the tree-generator spec
-4. Write files under `skills/` in the appropriate package directory
-5. Run `npx intent validate skills/` to verify all files pass
-6. Fix any validation errors
-
-### Output structure
-
-Write skills following the structure recommended in the domain map.
-Ensure every skill from domain_map.yaml has a corresponding SKILL.md file.
-
-### After completion
-
-Tell the user:
-
-- "Skill tree generated. [N] skills written to skills/."
-- "Validation: [PASS/FAIL with details]"
-- "Next steps:"
-  - "1. Review the generated skills for accuracy"
-  - "2. Add `\"skills\"` to your package.json `files` array"
-  - "3. Add the `intent` field to your package.json"
-  - "4. Run `npx intent feedback --meta --interactive` to share how this went"

package/meta/templates/workflows/generate-skills-oz.yml

@@ -1,86 +0,0 @@
-# generate-skills-oz.yml — Drop this into your library repo's .github/workflows/
-#
-# Manual-trigger workflow that runs domain-discovery + tree-generator via
-# Warp Oz to generate a complete skill tree for your library.
-#
-# Requirements:
-#   - WARP_API_KEY repository secret (from Warp Settings > Platform)
-#
-# Template variables (replaced by `intent setup`):
-#   {{PACKAGE_NAME}}  — e.g. @tanstack/query
-#   {{REPO}}          — e.g. TanStack/query
-#   {{DOCS_PATH}}     — e.g. docs/
-
-name: Generate Skills (Oz)
-
-on:
-  workflow_dispatch:
-    inputs:
-      docs_path:
-        description: 'Path to library docs (default from intent config)'
-        required: false
-        default: '{{DOCS_PATH}}'
-        type: string
-      skip_interview:
-        description: 'Skip maintainer interview (compressed discovery)'
-        required: false
-        default: false
-        type: boolean
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  generate:
-    name: Generate skill tree
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install dependencies
-        run: npm install @tanstack/intent yaml
-
-      - name: Run Oz agent
-        uses: warpdotdev/oz-agent-action@v1
-        with:
-          prompt: |
-            You are generating AI coding agent skills for {{PACKAGE_NAME}}.
-
-            ## Setup
-
-            1. Read the meta-skill at node_modules/@tanstack/intent/meta/domain-discovery/SKILL.md
-            2. The library source is in this repo at {{DOCS_PATH}}
-            3. The package name is {{PACKAGE_NAME}} and the repo is {{REPO}}
-
-            ## Task
-
-            Run the domain-discovery skill to produce domain_map.yaml and skill_spec.md.
-            Since this is a CI run with no interactive maintainer, use compressed
-            discovery mode (Phase 1 + Phase 3 only — skip interview phases).
-
-            After producing the domain map, read the meta-skill at
-            node_modules/@tanstack/intent/meta/tree-generator/SKILL.md and
-            run Workflow A to generate the complete skill tree under skills/.
-
-            ## Output
-
-            1. Write domain_map.yaml and skill_spec.md to the repo root
-            2. Write generated SKILL.md files under the appropriate skills/ directory
-            3. Run `npx intent validate skills/` to verify all files pass
-            4. Create a branch `skills/generate-{{PACKAGE_NAME}}` and open a PR with:
-               - Title: "feat: generate intent skills for {{PACKAGE_NAME}}"
-               - Body summarizing what was generated and any gaps flagged
-               - Co-Authored-By: Oz <oz-agent@warp.dev>
-
-            If validation fails, fix the issues before opening the PR.
-          warp_api_key: ${{ secrets.WARP_API_KEY }}
-          profile: ${{ vars.WARP_AGENT_PROFILE || '' }}

package/meta/templates/workflows/update-skills-oz.yml

@@ -1,98 +0,0 @@
-# update-skills-oz.yml — Drop this into your library repo's .github/workflows/
-#
-# Triggered on new version releases. Oz evaluates whether skills need
-# updating based on changelog/migration guide changes, and opens PRs
-# for any stale skills.
-#
-# Requirements:
-#   - WARP_API_KEY repository secret
-#   - Skills must already exist in the repo (run generate-skills-oz first)
-#
-# Template variables (replaced by `intent setup`):
-#   {{PACKAGE_NAME}}  — e.g. @tanstack/query
-#   {{REPO}}          — e.g. TanStack/query
-
-name: Update Skills (Oz)
-
-on:
-  release:
-    types: [published]
-
-  # Manual trigger for testing
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Version to check against (e.g. 5.62.0)'
-        required: false
-        type: string
-
-permissions:
-  contents: write
-  pull-requests: write
-
-jobs:
-  update:
-    name: Check and update skills
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-
-      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-          node-version: 20
-
-      - name: Install dependencies
-        run: npm install @tanstack/intent yaml
-
-      - name: Determine version
-        id: version
-        run: |
-          if [ -n "${{ inputs.version }}" ]; then
-            echo "version=${{ inputs.version }}" >> "$GITHUB_OUTPUT"
-          else
-            echo "version=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
-          fi
-
-      - name: Run Oz agent
-        uses: warpdotdev/oz-agent-action@v1
-        with:
-          prompt: |
-            You are checking whether AI coding agent skills for {{PACKAGE_NAME}}
-            need updating after a new release.
-
-            ## Setup
-
-            1. Read the meta-skill at node_modules/@tanstack/intent/meta/skill-staleness-check/SKILL.md
-            2. The package is {{PACKAGE_NAME}} in repo {{REPO}}
-            3. The new version is ${{ steps.version.outputs.version }}
-
-            ## Task
-
-            Follow the staleness check skill instructions:
-
-            1. Find all SKILL.md files under skills/ in this repo
-            2. Compare each skill's library_version against the new version
-            3. Read the CHANGELOG or migration guide for changes between versions
-            4. Classify each skill: no-impact, version-bump-only, content-update, or breaking-change
-            5. For skills needing updates, read the generate-skill meta-skill at
-               node_modules/@tanstack/intent/meta/generate-skill/SKILL.md and
-               use regeneration mode (surgical updates, not full rewrites)
-
-            ## Output
-
-            If no skills need updating, exit silently — no PR, no noise.
-
-            If skills need updating:
-            1. Update the affected SKILL.md files
-            2. Run `npx intent validate skills/` to verify
-            3. Create branch `skills/update-${{ steps.version.outputs.version }}`
-            4. Open a PR with:
-               - Title: "skill: update for {{PACKAGE_NAME}}@${{ steps.version.outputs.version }}"
-               - Body with: what changed in the source, what changed in skills, review checklist
-               - Co-Authored-By: Oz <oz-agent@warp.dev>
-          warp_api_key: ${{ secrets.WARP_API_KEY }}
-          profile: ${{ vars.WARP_AGENT_PROFILE || '' }}