@tanstack/intent 0.0.1

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

@@ -0,0 +1,53 @@
+# 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

@@ -0,0 +1,69 @@
+# 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

@@ -0,0 +1,47 @@
+# 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

@@ -0,0 +1,48 @@
+# 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

@@ -0,0 +1,86 @@
+# 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/notify-playbooks.yml

@@ -0,0 +1,52 @@
+# notify-intent.yml — Drop this into your library repo's .github/workflows/
+#
+# Fires a repository_dispatch event to TanStack/intent whenever docs or
+# source files change on merge to main. This triggers the skill staleness
+# check workflow in the intent repo.
+#
+# Requirements:
+#   - A fine-grained PAT with contents:write on TanStack/intent stored
+#     as the INTENT_NOTIFY_TOKEN repository secret.
+#
+# Template variables (replaced by `intent setup`):
+#   {{PACKAGE_NAME}}  — e.g. @tanstack/query
+#   {{DOCS_PATH}}     — e.g. docs/**
+#   {{SRC_PATH}}      — e.g. packages/query-core/src/**
+
+name: Notify Intent
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '{{DOCS_PATH}}'
+      - '{{SRC_PATH}}'
+
+jobs:
+  notify:
+    name: Notify TanStack Intent
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - name: Collect changed files
+        id: changes
+        run: |
+          FILES=$(git diff --name-only HEAD~1 HEAD | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          echo "files=$FILES" >> "$GITHUB_OUTPUT"
+
+      - name: Dispatch to intent repo
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.INTENT_NOTIFY_TOKEN }}
+          repository: TanStack/intent
+          event-type: skill-check
+          client-payload: |
+            {
+              "package": "{{PACKAGE_NAME}}",
+              "sha": "${{ github.sha }}",
+              "changed_files": ${{ steps.changes.outputs.files }}
+            }

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

@@ -0,0 +1,98 @@
+# 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 || '' }}

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

@@ -0,0 +1,52 @@
+# validate-skills.yml — Drop this into your library repo's .github/workflows/
+#
+# Validates skill files on PRs that touch the skills/ directory.
+# Ensures frontmatter is correct, names match paths, and files stay under
+# the 500-line limit.
+
+name: Validate Skills
+
+on:
+  pull_request:
+    paths:
+      - 'skills/**'
+      - '**/skills/**'
+
+jobs:
+  validate:
+    name: Validate skill files
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install intent CLI
+        run: npm install -g @tanstack/intent
+
+      - name: Find and validate skills
+        run: |
+          # Find all directories containing SKILL.md files
+          SKILLS_DIR=""
+          if [ -d "skills" ]; then
+            SKILLS_DIR="skills"
+          elif [ -d "packages" ]; then
+            # Monorepo — find skills/ under packages
+            for dir in packages/*/skills; do
+              if [ -d "$dir" ]; then
+                echo "Validating $dir..."
+                intent validate "$dir"
+              fi
+            done
+            exit 0
+          fi
+
+          if [ -n "$SKILLS_DIR" ]; then
+            intent validate "$SKILLS_DIR"
+          else
+            echo "No skills/ directory found — skipping validation."
+          fi