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.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 44809b88-e4ee-4211-832b-2d4dd755b2cd

📥 Commits

Reviewing files that changed from the base of the PR and between a33d163 and 7dba7a1.

📒 Files selected for processing (2)

• internal/adr/0002-skills-in-package-over-mcp.md
• internal/planning/CONTEXT.md

---

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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main documentation change: ADR 0002 choosing Skills-in-package over MCP for agent-native DX.
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.

✨ Finishing Touches

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