@tanstack/intent 0.0.5 → 0.0.7

package/meta/domain-discovery/SKILL.md

@@ -57,7 +57,26 @@ reading exhaustively yet.
    guidance, read it. This is high-signal for what the maintainer
    considers important
 
-### 1b — Note initial impressions
+### 1b — Read peer dependency constraints
+
+Check `package.json` for `peerDependencies` and `peerDependenciesMeta`.
+For each major peer dependency (React, Vue, Svelte, Next.js, etc.):
+
+1. Note the version range required
+2. Read the peer's docs for integration constraints that affect this
+   library: SSR/hydration rules, component lifecycle boundaries,
+   browser-only APIs, singleton patterns, connection limits
+3. Log framework-specific failure modes — these are the highest-impact
+   failure modes and cannot be discovered from the library's own source
+
+Examples of peer-dependency-driven failure modes:
+
+- SSR: calling browser-only APIs during server render
+- React: breaking hook rules in library wrapper components
+- Connection limits: opening multiple WebSocket connections per tab
+- Singleton patterns: creating multiple client instances in dev mode
+
+### 1c — Note initial impressions
 
 Log (but do not group yet):
 
@@ -191,7 +210,11 @@ Move concept inventory items into groups. Two items belong together when:
 - They share a lifecycle, configuration scope, or architectural tradeoff
 - Getting one wrong tends to produce bugs in the other
 
-Target 4–7 domains. These are conceptual groupings, not the final skills.
+Let library complexity drive the domain count — a focused library may need
+only 2–3 domains, while a large framework may need 7+. Validate by asking:
+"Would a developer working on a single feature need to load skills from
+multiple domains? If so, merge those domains." These are conceptual
+groupings, not the final skills.
 
 Do not create a group for:
 
@@ -202,6 +225,14 @@ Do not create a group for:
 
 Name each domain as work being performed, not what the library provides.
 
+**Validation step:** After grouping, check each domain by asking:
+"Would a developer working on a single feature need to load skills from
+multiple domains?" If yes, merge those domains. Group by developer tasks
+(what they're trying to accomplish), not by architecture (how the library
+is organized internally). For example, prefer "writing data" over
+"producer lifecycle" — the former matches a developer's intent, the latter
+matches the codebase structure.
+
 ### 3b — Map domains × tasks → skills
 
 Merge your conceptual domains with the maintainer's task list from
@@ -268,6 +299,14 @@ For each skill, extract failure modes that pass all three tests:
 
 Target 3 failure modes per skill minimum. Complex skills target 5–6.
 
+**Code patterns.** Every failure mode should include `wrong_pattern` and
+`correct_pattern` fields with short code snippets (3–10 lines each).
+The wrong pattern is what an agent would generate; the correct pattern
+is the fix. These feed directly into SKILL.md Common Mistakes sections
+as wrong/correct code pairs. If the failure mode is purely conceptual
+(e.g. an architectural choice) rather than a code pattern, omit both
+fields and explain in `mechanism` instead.
+
 **Cross-skill failure modes.** Some failure modes belong to multiple
 skills. A developer doing SSR work and a developer doing state management
 both need to know about "stale state during hydration" — they load
@@ -298,7 +337,30 @@ only considers one side.
 Target 2–4 tensions. If you find none, the skills may be too isolated —
 revisit whether you're missing cross-connections.
 
-### 3f — Identify gaps
+### 3f — Map cross-references
+
+Beyond tensions (conflicts) and shared failure modes, identify skills
+that illuminate each other without conflicting. A cross-reference means:
+"an agent loading skill A would produce better code if it knew about
+skill B." These become "See also" pointers in the generated SKILL.md
+files.
+
+For each pair, note:
+
+- Which skill references which (can be bidirectional)
+- Why awareness of the other skill improves output
+
+Examples:
+
+- A quickstart skill references the security checklist ("after setup, audit")
+- A state management skill references an SSR skill ("state hydration
+  requires understanding SSR lifecycle")
+- A data writing skill references a data reading skill ("writes affect
+  how queries invalidate")
+
+Output these in the `cross_references` section of domain_map.yaml.
+
+### 3g — Identify gaps
 
 For each skill, explicitly list what you could NOT determine from docs
 and source alone. These become interview questions in Phase 4.
@@ -312,7 +374,7 @@ Common gaps:
 - "GitHub issues show confusion about X but docs don't address it"
 - "I found two patterns for doing X — unclear which is current/preferred"
 
-### 3g — Discover composition targets
+### 3h — Discover composition targets
 
 Scan `package.json` for peer dependencies, optional dependencies, and
 `peerDependenciesMeta`. Scan example directories and integration tests
@@ -324,7 +386,7 @@ for import patterns. For each frequently co-used library, log:
 
 These become targeted composition questions in Phase 4e.
 
-### 3h — Produce the draft
+### 3i — Produce the draft
 
 Write the full `domain_map.yaml` (format in Output Artifacts below) with
 a `status: draft` field. Flag every gap in the `gaps` section.
@@ -366,7 +428,7 @@ Follow up on any corrections. Then:
 
 ### 4b — Gap-targeted questions (3–8 questions)
 
-For each gap flagged in Phase 3f, ask a specific question. These are not
+For each gap flagged in Phase 3g, ask a specific question. These are not
 generic — they reference what you found:
 
 **Instead of:** "What do developers get wrong?"
@@ -433,7 +495,7 @@ These surface knowledge that doesn't appear in any docs:
 
 ### 4e — Composition questions (if library interacts with others)
 
-Use what you discovered in Phase 3g. For each integration target
+Use what you discovered in Phase 3h. For each integration target
 identified from peer dependencies and example code, ask targeted
 questions:
 
@@ -465,6 +527,11 @@ Update `status: draft` to `status: reviewed`.
 If the maintainer uses a custom skills root, replace `skills/` in the paths
 below with their chosen directory.
 
+**Monorepo layout:** For monorepos, domain map artifacts go at the REPO ROOT
+(e.g. `_artifacts/domain_map.yaml`) since they describe the whole library.
+Skills are generated per-package later by the tree-generator and generate-skill
+steps.
+
 ### 1. skills/\_artifacts/domain_map.yaml
 
 ```yaml
@@ -510,6 +577,10 @@ skills:
     failure_modes:
       - mistake: '[5-10 word phrase]'
         mechanism: '[one sentence]'
+        wrong_pattern: | # the code an agent would incorrectly generate
+          [short code snippet showing the mistake]
+        correct_pattern: | # the code that should be generated instead
+          [short code snippet showing the fix]
         source: '[doc page, source file, issue link, or maintainer interview]'
         priority: '[CRITICAL | HIGH | MEDIUM]'
         status: '[active | fixed-but-legacy-risk | removed]'
@@ -525,6 +596,11 @@ tensions:
     description: '[what conflicts — one sentence]'
     implication: '[what an agent gets wrong when it only considers one side]'
 
+cross_references:
+  - from: '[skill-slug]'
+    to: '[skill-slug]'
+    reason: '[why loading one skill benefits from awareness of the other]'
+
 gaps:
   - skill: '[skill slug]'
     question: '[what still needs input]'
@@ -570,6 +646,12 @@ not promotional.]
 | -------------- | ------------------- | ----------------------- |
 | [short phrase] | [slug-a] ↔ [slug-b] | [what agents get wrong] |
 
+## Cross-References
+
+| From   | To     | Reason                                    |
+| ------ | ------ | ----------------------------------------- |
+| [slug] | [slug] | [why awareness of one improves the other] |
+
 ## Subsystems & Reference Candidates
 
 | Skill  | Subsystems                     | Reference candidates       |
@@ -624,6 +706,7 @@ not promotional.]
 | Subsystems flagged                    | Skills with 3+ adapters/backends list them as subsystems                   |
 | Dense surfaces flagged                | Topics with >10 patterns noted as reference_candidates                     |
 | Lifecycle skills considered           | Suggest journey skills when docs have the material                         |
+| Cross-references mapped               | Skills that illuminate each other get "See also" pointers                  |
 
 ---
 

package/meta/feedback-collection/SKILL.md

@@ -4,12 +4,11 @@ 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 via the intent feedback CLI.
+  and brief human input, then submits directly via gh CLI or provides manual
+  submission instructions.
 metadata:
-  version: '1.0'
+  version: '2.0'
   category: meta-tooling
-  output_artifacts:
-    - intent-feedback.json
 ---
 
 # Skill Feedback Collection
@@ -83,74 +82,86 @@ If the human gives an explicit rating, use that instead.
 
 ---
 
-## Phase 3 — Build the Payload
-
-Construct one JSON payload per skill used. The schema must match exactly:
-
-```json
-{
-  "skill": "<skill name from SKILL.md frontmatter>",
-  "package": "<npm package name that contains the skill>",
-  "skillVersion": "<metadata.version from SKILL.md frontmatter, or library_version>",
-  "task": "<one-sentence summary of what the human asked you to do>",
-  "whatWorked": "<patterns/instructions from the skill that were accurate and helpful>",
-  "whatFailed": "<errors from 1b — what the skill got wrong>",
-  "missing": "<gaps from 1a — what the skill should have covered>",
-  "selfCorrections": "<fixes you applied from 1b + interventions from 1c>",
-  "userRating": "good | mixed | bad",
-  "userComments": "<optional — direct quotes or paraphrased human input from Phase 2>"
-}
-```
+## Phase 3 — Build the Feedback
 
-### Field derivation guide
+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]
+
+## What Worked
+
+[patterns/instructions from the skill that were accurate and helpful]
+
+## What Failed
+
+[from 1b — skill instructions that produced errors]
+
+## Missing
 
-| Field             | Source                                                             |
-| ----------------- | ------------------------------------------------------------------ |
-| `skill`           | Frontmatter `name` field of the SKILL.md you loaded                |
-| `package`         | The npm package the skill lives in (e.g. `@tanstack/query-intent`) |
-| `skillVersion`    | Frontmatter `metadata.version` or `library_version`                |
-| `task`            | Summarize the human's original request in one sentence             |
-| `whatWorked`      | List skill sections/patterns that were correct and useful          |
-| `whatFailed`      | From 1b — skill instructions that produced errors                  |
-| `missing`         | From 1a — gaps where the skill was silent                          |
-| `selfCorrections` | From 1b fixes + 1c human interventions, combined                   |
-| `userRating`      | From Phase 2 sentiment analysis or explicit rating                 |
-| `userComments`    | From Phase 2 answers, keep brief                                   |
-
-### Example
-
-```json
-{
-  "skill": "tanstack-query/core",
-  "package": "@anthropic/tanstack-query-intent",
-  "skillVersion": "1.0",
-  "task": "Add optimistic updates to a mutation with rollback on error",
-  "whatWorked": "Setup pattern was correct. onMutate/onError/onSettled lifecycle was accurate.",
-  "whatFailed": "Cache key format used array syntax that doesn't match v5 — had to switch to queryOptions pattern.",
-  "missing": "No guidance on TypeScript generics for mutation variables. Had to read source.",
-  "selfCorrections": "Fixed cache key format. Human corrected the rollback type to include undefined.",
-  "userRating": "mixed",
-  "userComments": "The optimistic update pattern was helpful but the cache key thing wasted 10 minutes."
-}
+[from 1a — gaps where the skill should have covered]
+
+## Self-Corrections
+
+[from 1b fixes + 1c human interventions, combined]
+
+## User Comments
+
+[optional — direct quotes or paraphrased human input from Phase 2]
 ```
 
-If multiple skills were loaded, produce one payload per skill. Only include
-skills that were actually used during the session — skip any that were loaded
-but never referenced.
+### 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             |
+| What Worked      | List skill sections/patterns that were correct and useful          |
+| What Failed      | From 1b — skill instructions that produced errors                  |
+| Missing          | From 1a — gaps where the skill was silent                          |
+| Self-Corrections | From 1b fixes + 1c human interventions, combined                   |
+| Rating           | From Phase 2 sentiment analysis or explicit rating                 |
+| User Comments    | From Phase 2 answers, keep brief                                   |
 
 ---
 
 ## Phase 4 — Submit
 
-1. Save the payload to `intent-feedback.json` in the project root.
-   If multiple skills, save as a JSON array.
+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.
+
+### 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 "feedback:[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.
 
-2. Submit:
+If submission succeeds, delete the feedback file.
 
-   ```bash
-   npx intent feedback --submit --file intent-feedback.json
-   ```
+### If `gh` CLI is not available
 
-3. If the submission succeeds, delete `intent-feedback.json`.
+Tell the human:
 
-4. If it fails, tell the human and leave the file for manual retry.
+> "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."

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/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
@@ -514,10 +520,18 @@ See also: [lib]-core/[other-domain]/SKILL.md § Common Mistakes
 The cross-reference ensures agents that load one skill are pointed
 toward the related skill where the other side of the tension lives.
 
+Also check the domain map's `cross_references` section for non-tension
+relationships between skills. For each cross-reference, add a "See also"
+line at the end of the relevant skill's body:
+
+```markdown
+See also: [other-skill]/SKILL.md — [reason]
+```
+
 ### Step 6 — Write composition skills (if applicable)
 
 Use the `compositions` entries from `domain_map.yaml` (populated during
-skill-domain-discovery Phase 2h) to identify which composition skills
+skill-domain-discovery Phase 3h) to identify which composition skills
 to produce.
 
 Composition skills cover how two or more libraries work together. These

package/package.json

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