intent review

intent review shows which library skills and planning records need review after source changes. Completed reviews are remembered until their source or guidance changes again.

For the full maintainer pipeline, use intent maintainer review with --base, --json, or --record. It uses the same source-review implementation and report format described here. intent maintainer check combines review with registration, skill validation, distribution, and generated-file checks. The standalone command remains available for review-only checks and generated workflow reminders.

@tanstack/intent@latest review [dir] [--base <ref>] [--json] [--check] [--record <report.json>] [--github-review] [--package-label <label>]

For the normal coding-agent workflow, run maintainer setup once. The installed guidance instructs the agent to review guidance and maintain the planning documents before handoff.

Quick start#

1. Run intent review from your library repository to see pending work.
2. Ask your agent to review those items using the current source change. It updates the skills and planning record, then runs the relevant checks.
3. Keep the resulting .intent/review-state.json with the source, skills, and planning documents in your change.
4. Run intent review --check to confirm that no unreviewed items remain.

A justified no-op is a completed review. Missing evidence remains pending.

Options#

Comparison and output#

Recording and reminders#

--record cannot be combined with --base, --json, or --check. --github-review cannot be combined with --record, --json, or --check.

Behavior#

What appears in a review#

An unmapped file does not automatically require a new skill. A planning review can be needed even when nobody edited the planning documents.

Comparison scope#

Git and an initial commit are required. The default command is read-only.

Items without a recorded review use their introducing commit even when repository review state exists, unless you pass --base. Planning records use the commit that introduced their skill_tree.yaml.

The comparison includes committed changes since the base and staged, unstaged, and untracked files visible to Git. Renames appear as removals and additions. It reviews final working-tree content; a partially staged index is not separately certified.

Recorded hashes detect later edits even when a review happened before a commit. The state retains hashes rather than earlier source text. Default review fails closed when its stored baseline is no longer available; it does not infer a replacement from rewritten history.

Recover an unavailable baseline#

A squash merge, shallow clone, or history rewrite can remove the commit stored as the review baseline. Choose an available commit that covers the changes you intend to review, then create an explicit-base report:

@tanstack/intent@latest review --base <available-commit> --json > .intent/review.json

Review and resolve every item in that report, then record it:

When the previous stored baseline is unavailable, recording this fully resolved explicit-base report adopts the report's base as the new durable baseline. An empty report can also adopt the new base because it records that the selected comparison has no pending items. A partial report, an omitted or unresolved outcome, unresolved source or planning evidence, or a changed fingerprint cannot replace the missing baseline. When the stored baseline is still available, recording an explicit-base report does not replace it.

Source mappings#

Discovery covers first-party skills/**/SKILL.md files in the repository and its packages, custom roots containing _artifacts/, exact paths declared in the skill tree, and previously reviewed skill paths. An unrelated SKILL.md elsewhere does not automatically become a library skill. Review excludes node_modules, even without a Git ignore rule.

Brace expansion and extglobs are unsupported. Ignored files, submodules, external source repositories, and symbolic links require manual review. Missing or unsupported mappings remain unresolved.

Ignored paths#

Files that Intent writes or that carry no library guidance do not appear as unmapped changes. The default list covers the agent instruction files (AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md), .claude-plugin/**, .cursor-plugin/**, .github/workflows/check-skills.yml, .intent/**, **/package.json, and the lockfiles (pnpm-lock.yaml, package-lock.json, npm-shrinkwrap.json, yarn.lock, bun.lock).

The list only stops these paths from surfacing as unmapped changes. A skill that lists one of them in sources still tracks it.

Add repository-specific patterns under review.ignore in skill_tree.yaml:

review:
  ignore:
    - "docs/**"
    - "examples/**/package.json"

Entries use the same Git glob syntax as source mappings. An entry that is not a non-empty string fails review with the path of the tree file.

Required planning documents#

The maintainer workflow keeps a cumulative record across batches:

Review finds existing planning locations from these filenames, including custom directories. Without one, installed maintainer guidance requires _artifacts/ at a monorepo root or skills/_artifacts/ for a standalone library. Previously recorded locations remain required if their files are deleted.

All three files must be present, nonempty, readable, and visible to Git. Each YAML document must contain an object with a skills array. Missing or invalid records remain unresolved.

The planning snapshot includes the documents and the discovered skill/source evidence. Changes reopen planning review without reopening an otherwise unchanged individual skill. The check establishes file presence, YAML shape, and reviewed content hashes; the agent and maintainer still assess whether the written record is accurate and complete.

Record a completed review#

Interactive review#

For a human terminal, run the interactive command from the library repository:

Inspect each item's current guidance and changed files, choose an outcome, and supply the reason and actual evidence. The changes view compares tracked files with the displayed Git base and includes untracked content. Use --base <available-commit> for a specific comparison. Edit and test guidance before starting; changes during review invalidate the affected outcomes.

Choose Leave pending when more work is needed. Items with unresolved source mappings or planning problems cannot be completed. The final preview lists the proposed outcomes and evidence. Confirmation records through the same fingerprint checks as --record; cancellation records nothing. Evidence text is stored, not executed or independently verified.

Interactive review requires a terminal outside CI and cannot be combined with --json or --record. A zero exit status means the interaction completed, not that all review items were resolved. Use intent maintainer check --base <available-commit> as the read-only CI gate. JSON reports and the manual procedure below remain available to agents and scripts.

Record all pending items#

After inspecting all pending items and running the relevant checks, record one conclusion in one command:

@tanstack/intent@latest maintainer review --unchanged "Checked retries and cancellation against the updated implementation; the guidance remains accurate."
@tanstack/intent@latest maintainer review --updated "Updated the affected examples and planning records, then checked them against the source."

Choose one command. --unchanged records no-change; --updated records updated. The reason is required and applies to every pending item. Intent records each item's current changed paths and head revision as evidence and applies the same fingerprint and unresolved-problem checks as JSON recording. The command fails when nothing is pending or any item cannot be recorded. It does not assess the guidance or run the checks for you.

These flags belong to maintainer review, accept --base, and cannot be combined with each other, --json, --record, or --interactive. Use a JSON report when items need different conclusions or more detailed evidence.

JSON review#

The installed maintainer procedure handles these steps. For manual use:

1. Review the pending items, edit guidance and planning records as needed, and run the relevant checks.
2. Regenerate the report after those edits. Save it outside source paths, such as under .intent/, which the maintainer commands create:

@tanstack/intent@latest review --json > .intent/review.json

3. Add an outcome, reason, and evidence to each item you completed. Preserve the report's identities, baseline, and fingerprints. The report's recording block lists the accepted values.
4. Record the report and check remaining work:

Outcomes#

For example, add these fields to an existing report item; this is not a complete report:

{
  "outcome": "no-change",
  "reason": "Only the internal cache changed; the documented retry bound and errors remain the same.",
  "evidence": ["src/request.ts", "test/request.test.ts: passed"]
}

For a planning item, the reason and evidence must cover all three documents. Preserve prior tasks, decisions, and future work when extending them with a new batch.

--record rejects a report that annotates none of its items. The error names the required fields and points to intent maintainer review --interactive; a report with zero items still records its baseline.

Saved state#

--record writes .intent/review-state.json containing the baseline, source/guidance hashes, reviewed revision, outcomes, reasons, and evidence, creating the directory when it is missing. It does not commit, publish, or change skill versions. .intent/ is reserved for Intent's working files and is excluded from unmapped-change items: review state and working reports, .intent/skill-distribution.json written by maintainer sync, and the temporary .intent/maintainer.lock and .intent/review-state.json.lock that serialize writes.

Identical recorded content suppresses repeat reminders. Later edits reopen review. The saved state does not replace the planning documents, execute evidence strings, or verify the truth of a recorded conclusion.

Default and JSON output#

Text output shows the pending count and up to 20 items, with changed paths, unresolved problems, and the next step. Use --json for the full report.

Automated checks#

The optional version 4 setup workflow connects review to PRs and releases:

This catches skipped review recording and missing planning documents. It does not run an authoring model in CI. Your coding agent handles the reminder using the same maintainer procedure.

Status and errors#

Related#

• Maintainer quick start
• intent install
• intent validate
• intent stale