fix: remove first-run friction from the maintainer workflow

[LadyBluenotes]

🎯 Changes

Stacked on #268. Walking maintainer setup → add → sync → check on a fresh library failed for reasons unrelated to the library's guidance. This fixes the traps a first-time maintainer hits.

• Unmapped-change review ignores Intent-owned outputs. AGENTS.md/CLAUDE.md/.cursorrules/copilot instructions, .claude-plugin/**, .cursor-plugin/**, .github/workflows/check-skills.yml, .intent/**, **/package.json, and lockfiles no longer appear as source review items. A skill that maps one of these paths in sources still tracks it. skill_tree.yaml accepts review: { ignore: [<git globs>] } for repository-specific patterns; invalid entries fail with a named path.
• maintainer add infers --package from the current directory. Running it inside a workspace member registers the skill with that member instead of silently creating skills/<name> at the repository root with sources that match nothing. An explicit --package stays repository-relative.
• review --record rejects a report that annotates nothing. Previously it printed Recorded 0 review outcome(s). and exited 0. It now names the required fields (outcome, reason, evidence) and points to maintainer review --interactive. Next-step text in review, maintainer check, and the recording hint agree on one command spelling.
• validate accepts per-skill files entries. maintainer sync writes skills/<name>; validate then warned that "skills" was missing. It now checks that each skill directory is covered and names the uncovered one. The !skills/_artifacts warning applies only when the whole skills directory is published and _artifacts exists.
• Workflow version constant is 5, matching the shipped check-skills.yml, so repositories on version 4 receive the update advisory.
• The package README no longer advertises the removed scaffold command.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

Summary by CodeRabbit

• New Features

  • Improved maintainer workflows with workspace-aware package registration and clearer setup, synchronization, review, and validation guidance.
  • Added configurable review exclusions, including repository-managed files and skill-specific ignore patterns.
  • Enhanced package validation to identify uncovered skill directories and artifact publication issues.
  • Review recording now rejects reports without completed outcomes.

• Documentation

  • Updated maintainer documentation and CLI guidance to reflect the current workflow commands.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: b0a87356-e5b5-4fee-bd19-05cef6548c92

📥 Commits

Reviewing files that changed from the base of the PR and between a17880b and dc4857b.

📒 Files selected for processing (10)

• .changeset/maintainer-first-run.md
• packages/intent/README.md
• packages/intent/src/commands/maintainer.ts
• packages/intent/src/commands/review.ts
• packages/intent/src/commands/support.ts
• packages/intent/src/commands/validate.ts
• packages/intent/src/review/review.ts
• packages/intent/tests/cli.test.ts
• packages/intent/tests/maintainer.test.ts
• packages/intent/tests/review.test.ts

---

📝 Walkthrough

Walkthrough

The PR updates maintainer package inference, review recording validation, review ignore patterns, package skill publication checks, and workflow version guidance. It replaces scaffold documentation, adds tests for these behaviors, and includes a patch changeset.

Changes

Intent workflow updates

Layer / File(s)	Summary
Maintainer authoring and ownership .changeset/maintainer-first-run.md, packages/intent/README.md, packages/intent/src/commands/maintainer.ts, packages/intent/tests/maintainer.test.ts	The maintainer command infers workspace package ownership when --package is omitted. Documentation now describes the maintainer workflow. Tests cover inferred and explicit package paths and review output.
Review filtering and recording packages/intent/src/review/review.ts, packages/intent/src/commands/review.ts, packages/intent/tests/review.test.ts, packages/intent/tests/maintainer.test.ts	Review creation excludes default and skill-tree ignore patterns. Review recording rejects non-empty reports without completed outcomes. Tests cover filtering, pattern validation, and rejected state creation.
Package validation and workflow version packages/intent/src/commands/validate.ts, packages/intent/src/commands/support.ts, packages/intent/tests/cli.test.ts	Package validation checks coverage for each skill directory and retains artifact exclusion checks. The required workflow version increases from 4 to 5. Tests cover covered and uncovered skill directories.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix

Sequence Diagram(s)

sequenceDiagram
  participant MaintainerCLI
  participant ReviewCommand
  participant SkillTree
  participant RepositoryFiles
  participant ReviewState
  MaintainerCLI->>RepositoryFiles: create maintainer and skill files
  ReviewCommand->>SkillTree: read review.ignore patterns
  ReviewCommand->>RepositoryFiles: collect files and diffs
  ReviewCommand->>ReviewCommand: exclude ignored paths
  ReviewCommand->>ReviewState: record annotated review outcomes

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/maintainer-first-run

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codspeed-hq]

Merging this PR will not alter performance

✅ 9 untouched benchmarks

---

_{Comparing fix/maintainer-first-run (dc4857b) with refactor-hook-parser-source (a17880b)}