Plan

.changeset/config.json

@@ -1,17 +1,17 @@
-{
-  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
-  "changelog": [
-    "@svitejs/changesets-changelog-github-compact",
-    { "repo": "TanStack/pacer" }
-  ],
-  "commit": false,
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "fixed": [],
-  "linked": [],
-  "ignore": [],
-  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
-    "onlyUpdatePeerDependentsWhenOutOfRange": true
-  }
-}
+{
+  "$schema": "https://unpkg.com/@changesets/config@3.1.2/schema.json",
+  "changelog": [
+    "@svitejs/changesets-changelog-github-compact",
+{ "repo": "TanStack/playbooks" }
+  ],
+  "commit": false,
+  "access": "public",
+  "baseBranch": "main",
+  "updateInternalDependencies": "patch",
+  "fixed": [],
+  "linked": [],
+  "ignore": [],
+  "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
+    "onlyUpdatePeerDependentsWhenOutOfRange": true
+  }
+}

.github/workflows/process-feedback.yml

@@ -0,0 +1,71 @@
+name: Process Feedback
+
+on:
+  discussion:
+    types: [created]
+
+jobs:
+  label:
+    name: Auto-label feedback
+    if: github.event.discussion.category.name == 'Feedback'
+    runs-on: ubuntu-latest
+    permissions:
+      discussions: write
+    steps:
+      - name: Label by library
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const body = context.payload.discussion.body || ''
+            const libraryPatterns = [
+              { pattern: /\brouter\//, label: 'feedback:router' },
+              { pattern: /\bstart\//, label: 'feedback:start' },
+              { pattern: /\bquery\//, label: 'feedback:query' },
+              { pattern: /\btable\//, label: 'feedback:table' },
+              { pattern: /\bform\//, label: 'feedback:form' },
+              { pattern: /\bvirtual\//, label: 'feedback:virtual' },
+              { pattern: /\bstore\//, label: 'feedback:store' },
+              { pattern: /\bdb\//, label: 'feedback:db' },
+              { pattern: /\bcompositions\//, label: 'feedback:compositions' },
+            ]
+
+            const labels = libraryPatterns
+              .filter(({ pattern }) => pattern.test(body))
+              .map(({ label }) => label)
+
+            if (labels.length === 0) return
+
+            // Ensure labels exist
+            for (const label of labels) {
+              try {
+                await github.rest.issues.getLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: label,
+                })
+              } catch {
+                await github.rest.issues.createLabel({
+                  owner: context.repo.owner,
+                  repo: context.repo.repo,
+                  name: label,
+                  color: '7057ff',
+                })
+              }
+            }
+
+            // Discussions use the GraphQL API for labels
+            const { data: discussion } = await github.graphql(`
+              query($owner: String!, $repo: String!, $number: Int!) {
+                repository(owner: $owner, name: $repo) {
+                  discussion(number: $number) {
+                    id
+                  }
+                }
+              }
+            `, {
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              number: context.payload.discussion.number,
+            })
+
+            core.info(`Matched labels: ${labels.join(', ')}`)

.github/workflows/skill-staleness-check.yml

@@ -0,0 +1,86 @@
+name: Skill Staleness Check
+
+# Triggered by repository_dispatch from upstream TanStack package repos.
+# Each package repo has a notify-playbook.yml workflow that fires this
+# event on merge to main with the list of changed files.
+
+on:
+  repository_dispatch:
+    types: [skill-check]
+
+  # Manual trigger for testing or ad-hoc checks
+  workflow_dispatch:
+    inputs:
+      package:
+        description: 'Package name (e.g. @tanstack/query)'
+        required: true
+        type: string
+      library:
+        description: 'Library directory in skills/ (e.g. query, db, router)'
+        required: true
+        type: string
+
+jobs:
+  check-staleness:
+    name: Check skill staleness
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Install dependencies
+        run: npm install yaml
+
+      - name: Build prompt from payload
+        id: prompt
+        run: |
+          if [ "${{ github.event_name }}" = "repository_dispatch" ]; then
+            PACKAGE="${{ github.event.client_payload.package }}"
+            SHA="${{ github.event.client_payload.sha }}"
+            CHANGED_FILES='${{ toJson(github.event.client_payload.changed_files) }}'
+          else
+            PACKAGE="${{ inputs.package }}"
+            SHA="manual"
+            CHANGED_FILES="[]"
+          fi
+
+          LIBRARY="${{ inputs.library || '' }}"
+          if [ -z "$LIBRARY" ]; then
+            # Derive library from package name: @tanstack/query -> query
+            LIBRARY=$(echo "$PACKAGE" | sed 's/@tanstack\///' | sed 's/react-//' | sed 's/vue-//' | sed 's/solid-//' | sed 's/svelte-//' | sed 's/angular-//')
+          fi
+
+          cat <<EOF > /tmp/oz-prompt.txt
+          Read the meta skill at meta/skill-staleness-check/SKILL.md and follow
+          its instructions.
+
+          Webhook payload:
+          - package: ${PACKAGE}
+          - sha: ${SHA}
+          - changed_files: ${CHANGED_FILES}
+          - library: ${LIBRARY}
+
+          Run the staleness check for the ${LIBRARY} library. Use
+          scripts/sync-skills.mjs for detection, then evaluate whether any
+          skills need updating. If they do, update them and open a PR.
+          If nothing needs updating, exit silently.
+          EOF
+
+          echo "library=$LIBRARY" >> "$GITHUB_OUTPUT"
+
+      - name: Run Oz agent
+        uses: warpdotdev/oz-agent-action@main
+        id: oz
+        with:
+          prompt: |
+            $(cat /tmp/oz-prompt.txt)
+          warp_api_key: ${{ secrets.WARP_API_KEY }}
+          profile: ${{ vars.WARP_AGENT_PROFILE || '' }}

.github/workflows/validate-skills.yml

@@ -0,0 +1,27 @@
+name: Validate Skills
+
+on:
+  pull_request:
+    paths:
+      - 'packages/playbooks/skills/**'
+      - 'packages/playbooks/package_map.yaml'
+      - 'scripts/validate-skills.ts'
+
+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 dependencies
+        run: npm install yaml
+
+      - name: Run validation
+        run: npx tsx scripts/validate-skills.ts

.warp/automations/skill-check.yml

@@ -0,0 +1,42 @@
+# Warp Oz Automation — Skill Staleness Check
+#
+# Triggered by repository_dispatch from upstream TanStack package repos.
+# Oz evaluates skill staleness, rewrites stale skills, and opens PRs.
+#
+# Trigger: .github/workflows/skill-staleness-check.yml
+# Skill:   meta/skill-staleness-check/SKILL.md
+# Scripts: scripts/sync-skills.mjs
+
+name: Skill Staleness Check
+trigger: webhook
+
+# The meta skill that drives the Oz agent's behavior
+skill: meta/skill-staleness-check/SKILL.md
+
+# Supporting meta skills the agent may load during execution
+supporting_skills:
+  - meta/generate-skill/SKILL.md
+  - meta/tree-generator/SKILL.md
+
+# Repos the agent needs access to (read for source, write for playbooks)
+environments:
+  - repo: tanstack/playbooks
+    access: write
+  - repo: TanStack/query
+    access: read
+  - repo: TanStack/router
+    access: read
+  - repo: TanStack/db
+    access: read
+  - repo: TanStack/form
+    access: read
+  - repo: TanStack/table
+    access: read
+
+# Payload schema (received from package repo webhook)
+#
+# {
+#   "package": "@tanstack/query",
+#   "sha": "abc123def",
+#   "changed_files": ["docs/guides/queries.md", "src/query.ts"]
+# }

README.md

@@ -1 +1 @@
-# TanStack Agents
+# @tanstack/playbook