intent stale

intent stale reports whether shipped skills may need review.

@tanstack/intent@latest stale [dir] [--json] [--github-review] [--package-label <label>]

Options

--json: print JSON array of staleness reports
--github-review: write review-reminder files and GitHub Actions output for the generated setup workflow
--package-label <label>: set the fallback library label in generated reminder items

Behavior

Scope

Checks the current package by default
From a monorepo root, checks workspace packages that ship skills and also reports public workspace packages with no skill or artifact coverage
Applies the package.json#intent.skills allowlist when falling back to installed dependencies; workspace packages are first-party and checked regardless. See Configuration.
When dir is provided, scopes the check to the targeted package or skills directory
Computes one staleness report per package

Coverage

Reads repo-root _artifacts/*domain_map.yaml and _artifacts/*skill_tree.yaml when present
Flags public workspace packages that are not represented by generated skills or artifact coverage
Skips workspace packages with "private": true

Output and workflow state

Prints text output by default or JSON with --json
Text output lists flagged skills and review signals with their reasons; JSON contains only report data
Prints a non-failing workflow update reminder when .github/workflows/check-skills.yml is missing the current intent-workflow-version stamp
If no packages are found, prints No intent-enabled packages found.

Artifact coverage ignores can be recorded in _artifacts/*skill_tree.yaml or _artifacts/*domain_map.yaml:

coverage:
  ignored_packages:
    - '@tanstack/internal-tooling'
    - name: packages/devtools-fixture
      reason: test fixture only

Ignored packages are excluded from missing coverage signals. Private workspace packages are excluded automatically.

JSON report schema

--json outputs an array of reports:

[
  {
    "library": "string",
    "currentVersion": "string | null",
    "skillVersion": "string | null",
    "versionDrift": "major | minor | patch | null",
    "skills": [
      {
        "name": "string",
        "reasons": ["string"],
        "needsReview": true
      }
    ],
    "signals": [
      {
        "type": "missing-package-coverage",
        "library": "string",
        "subject": "string",
        "reasons": ["string"],
        "needsReview": true,
        "packageName": "string",
        "packageRoot": "string"
      }
    ]
  }
]

Report fields:

Field	Meaning
`library`	Package name
`currentVersion`	Local package version when available; otherwise latest from npm, or `null` if unavailable
`skillVersion`	`library_version` from skills, or `null`
`versionDrift`	`major`, `minor`, `patch`, or `null`
`skills`	Per-skill checks
`signals`	Artifact and workspace coverage checks

Skill fields:

name
reasons: one or more staleness reasons
needsReview: boolean (true when reasons exist)

Reason generation:

version drift (<skillVersion> → <currentVersion>)
new source (<path>) when a declared source has no stored sync SHA
artifact parse warnings, unresolved artifact skill paths, source drift, artifact library version drift, and missing workspace package coverage

Text output

Report header format: <library> (<skillVersion> → <currentVersion>) [<versionDrift> drift]
When no skill reasons exist: All skills up-to-date
Otherwise: one warning line per stale skill or review signal (⚠ <name>: <reason1>, <reason2>, ...)
Review signals that produce the same line, such as one raised by both domain_map.yaml and skill_tree.yaml, print once; JSON output keeps each signal with its artifactPath

Generated review files

The existing --github-review workflow mode writes review-items.json and, when there are items, pr-body.md. Its Agent Review instructions route to generate-skill and its conditional review-signals reference. The command itself does not create a remote PR or edit skills; the installed GitHub workflow handles the review reminder.

Version drift and missing stored source SHAs do not prove that guidance is wrong. Review actual source changes before editing. Missing evidence stays unresolved, and an evidence-backed no-op may leave a signal flagged. Failed checks require logs; workflow advisories are separate maintenance items. Neither is a reason to rewrite skills.

`stale` and `review` serve different checks

Command	Evidence	Persistent result
`intent stale`	Installed or registry package versions, stored source sync SHAs, artifacts, workflow version, and workspace package coverage.	Reports conservative signals; it does not record semantic review.
`intent review`	Git changes plus recorded source, skill, and planning-record fingerprints.	Records evidence-backed outcomes in `.intent/review-state.json` and reopens them when tracked content changes.

Common errors

Package scan failure: prints a scanner error
Registry fetch failures do not crash command; currentVersion may be null

Notes

Source staleness checking is conservative: it flags missing source SHAs in sync-state, not remote content differences.