Docs: ADR 0002 — Skills-in-package over MCP for agent-native DX

[justin808]

Why

The #4605 maintainer decision (2026-07-17) settled how React on Rails ships its agent toolchain for 17.2, but the planning glossary (internal/planning/CONTEXT.md) still described Agent-native development with MCP as a presumed delivery vehicle, and the decision's trade-off (Skills-in-package vs slim MCP vs docs-only, after #3870's full-MCP rejection) met the bar for a decision record: hard to reverse (Skills become shipped package surface), surprising without context, and a real trade-off.

What

• internal/adr/0002-skills-in-package-over-mcp.md: records the decision — Skills-in-package + version-matched bundled docs are 17.2 scope; slim MCP deferred pending Tutorial + scripted eval: an AI agent builds a React on Rails Pro app end-to-end, unaided #4603 eval evidence; RFC + build: a React on Rails MCP server (doctor-as-JSON, generators, component scaffold, doc & error-code search) #3870's ruling stands. Includes considered options and revisit triggers.
• internal/planning/CONTEXT.md: updates the Agent-native development entry, adds an Avoid note, and logs the resolved ambiguity with date and links.

Test plan

• Prettier clean on both files
• Internal-docs-only change (internal/ is not published); no runtime, CI, or published-docs surface

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation
  • Documented the decision to provide version-matched AI agent skills and bundled documentation with React on Rails packages.
  • Clarified that agents can work end-to-end without external setup through packaged guidance, project instructions, and machine-readable errors.
  • Recorded that a slim MCP integration is deferred pending evaluation results.

Merge evidence

• Release mode / phase: development / beta; the standard main-branch gate applies and is satisfied.
• Labels: none — internal documentation only; hosted CI expansion is not required.
• Review coverage at current head 7dba7a11f3ccaea8f25a143b4be289e55dd14b1e: Claude review, CodeRabbit, and Greptile completed with no confirmed blocker; zero unresolved review threads.
• Changelog classification: not_user_visible — internal decision records only.
• Decision points: 0.

Confidence note:

• Validated: pnpm dlx prettier@3.6.2 --check internal/adr/0002-skills-in-package-over-mcp.md internal/planning/CONTEXT.md passed at the exact PR head; script/ci-changes-detector origin/main classified the diff as documentation-only with no additional CI jobs.
• Evidence: current-head required-pr-gate, Markdown format/link checks, Claude review, CodeRabbit, Greptile, and CodeQL are complete; pr-ci-readiness returned READY; no pending viewer review drafts.
• UNKNOWN: none.
• Residual risk: none; this changes internal planning/ADR text only.

QA Evidence

• QA lane: not applicable; internal-docs-only dependency PR.
• Scope checked: both changed internal Markdown files at the exact PR head.
• Tested at: PR Docs: ADR 0002 — Skills-in-package over MCP for agent-native DX #4735 head 7dba7a1.
• Automated checks: exact-head Prettier check plus current-head GitHub Markdown, required-gate, review, and CodeQL results.
• Manual checks: decision/glossary cross-link and changed-path inspection.
• Findings: none.
• QA required: no.
• QA required rationale: internal-only decision documentation with no runtime, package, generated-output, CI, or published-docs behavior.
• QA lane status: not_applicable.
• Release-blocking status: not_applicable.
• Process-gap disposition: not applicable.

Completed-batch audit

Status: Clean — no outstanding findings or follow-ups. Durable receipt.

[coderabbitai]

Walkthrough

Changes

Agent delivery policy

Layer / File(s)	Summary
Skills-in-package decision and planning alignment internal/adr/0002-skills-in-package-over-mcp.md, internal/planning/CONTEXT.md	Adds the 17.2 Skills-in-package decision with version-matched bundled docs, defers slim MCP pending evaluation evidence, and updates agent-native development guidance accordingly.

Estimated code review effort: 1 (Trivial) | ~3 minutes

Possibly related issues

• #4605 — Directly covers the in-package Skills, version-matched bundled docs, and deferred slim MCP proposal documented by this change.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately captures the main documentation change: ADR 0002 choosing Skills-in-package over MCP for agent-native development.

✨ 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 docs/adr-0002-agent-toolchain

---

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.}

[greptile-apps]

Greptile Summary

This PR records the agent-toolchain decision for the 17.2 release. The main changes are:

• Adds ADR 0002 for package-bundled Skills and version-matched documentation.
• Defers a slim MCP until the agent evaluation provides supporting evidence.
• Aligns the planning glossary and ambiguity log with the decision.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed documentation.
• The ADR follows the existing structure and its relative links resolve.
• The planning updates consistently describe the accepted 17.2 direction.

Important Files Changed

Filename	Overview
internal/adr/0002-skills-in-package-over-mcp.md	Adds an accepted ADR with the decision, alternatives, consequences, and revisit conditions.
internal/planning/CONTEXT.md	Updates the agent-native development theme and resolved-ambiguity log to reference ADR 0002.

_{Reviews (1): Last reviewed commit: "Docs: record agent-toolchain v2 decision..." | Re-trigger Greptile}

[claude]

Review

Scope: internal-docs-only change (2 files, +23/-1), no runtime/CI/published-docs surface. Reviewed for correctness, convention adherence, and internal consistency.

Overview

Adds internal/adr/0002-skills-in-package-over-mcp.md, recording the #4605 decision that React on Rails' 17.2 agent toolchain ships as Skills-in-package + version-matched bundled docs, with a slim MCP deferred pending #4603 eval evidence. Updates internal/planning/CONTEXT.md's Agent-native development glossary entry to match and logs the resolved ambiguity.

Code quality / convention

• The new ADR follows the exact structural convention established by 0001-rspack-answers-vite.md (frontmatter with status/date, title, prose rationale, "Considered options", "Consequences" with an explicit revisit trigger). Nice consistency.
• The CONTEXT.md edit is minimal and surgical: updates one glossary entry, adds an _Avoid_ line (matching the pattern used by other entries in the file), and appends one line to "Flagged ambiguities" — all consistent with the file's existing structure.
• Cross-link [ADR 0002](../adr/0002-skills-in-package-over-mcp.md) resolves correctly relative to internal/planning/CONTEXT.md → internal/adr/0002-...md.

Issues / risks

None found. This is a low-risk, well-scoped documentation change:

• No code, tests, or CI-relevant files touched.
• internal/ is explicitly not published, so there's no external-facing risk from the decision language.
• Referenced issue numbers (Agent toolchain v2 (17.2): ship Skills in-package + version-matched bundled docs; slim MCP deferred pending #4603 eval #4605, Tutorial + scripted eval: an AI agent builds a React on Rails Pro app end-to-end, unaided #4603, RFC + build: a React on Rails MCP server (doctor-as-JSON, generators, component scaffold, doc & error-code search) #3870) are used consistently between the ADR body and the CONTEXT.md update.

Suggestions (optional, non-blocking)

• Minor: the ADR's "Considered options" section states the full-MCP rejection (RFC + build: a React on Rails MCP server (doctor-as-JSON, generators, component scaffold, doc & error-code search) #3870) "stands," and the prose intro repeats this — slightly redundant but harmless for a decision record meant to be read standalone.

Overall: clean, well-structured decision record that matches this repo's existing ADR conventions. No blocking concerns.

[justin808]

Completed-batch audit: replay evidence follows.