R包生态编排插件

RForge Plugin

R package ecosystem orchestrator for Claude Code — 44 commands, R-aware hooks, validation skills.

Self-contained R package analysis for Claude Code. As of v1.3.0 the plugin is fully self-sufficient — pure-Python lib/ modules handle discovery, dependencies, status, and init. No MCP server required.

Codex personal plugin

The native rforge-openai adapter 0.1.1 provides two skills: $rforge-check for package validation and $rforge-docs-check for static README/vignette API audits. Both reuse the Rforge engines and have been verified in fresh sessions on isolated medfit copies. The adapter is integrated on dev (PR #92); it is not a published adapter release or a port of the Claude command catalog and hooks.

Start with the Codex installation and checks guide. Claude marketplace and Homebrew installation below do not install these Codex skills.

What's new in v2.22.1

• 🔢 --run-examples compares short integers exactly. A documented whole number of up to six digits must match the real output ([1] 100 against [1] 101 is now a mismatch). Decimals, scientific notation and longer integers keep their tolerance. See the Docs audit guide.

What's new in v2.22.0

• 🌐 /rforge:docs:check --site URL [--ref REF] audits a deployed pkgdown site over HTTP and --run-examples [--examples-budget-seconds 300] replays README examples in a guarded R process. Both are opt-in; the default stays offline. Incomplete stages exit 2 with either enabled threshold, and --site reports pkgdown development-mode sites and .qmd articles as incomplete rather than clean. Accepted on ubuntu-24.04 and macos-14 (662 required checks each). See the Docs audit guide.

What's new in v2.21.0

• 🔎 /rforge:docs:check is a real docs audit — lib/docaudit.py checks the calls and signatures in your README and vignettes against the package exports: signature-named-arg (error), signature-names / signature-arity (warn), scannability (info), --since coverage. --eco, --detailed, --fail-on none|warn|error, docs.allowlist. Reports end INCOMPLETE / NOT AUDITED instead of no findings when it could not finish. Opt-in A2 stages add --site URL [--ref REF] and --run-examples [--examples-budget-seconds 300]; the default stays offline. README execution is partial coverage and runs package code. Completed A2 discrepancies are warnings; incomplete stages exit 2 with either enabled threshold. See the Docs audit guide.
• 🐛 /rforge:finish keeps .STATUS version annotations and still adds version: when missing (#84).
• 📚 New Ecosystem analysis guide, a "Fix a docs:check finding" tutorial, corrected command cards, one Quick Start.

What's new in v2.20.1

• 🐛 .STATUS parsing fixes — lib.status (behind /rforge:status and /rforge:health) now reads the key: value frontmatter dialect every mediationverse package uses (#75) and takes phase only from a phase: key, not from old history lines in the prose (#82).
• 🐛 /rforge:restore NEWS count — entries grouped under ## subsections are counted again (#78).
• 📚 MediationVerse doctrine in the CRAN-submission, dev-cycle and S7-review Command Guides (#76).

What's new in v2.20.0

• 🔖 /rforge:restore + /rforge:finish (PR #71) — R-package session-boundary commands: recap a single package's state (DESCRIPTION/NEWS.md/git/.STATUS) and sync .STATUS from what actually happened, dry-run by default with a redundant-edit guard and a version-drift check against DESCRIPTION.
• 🛡️ Backed by a new lib/rstatus.py reader/differ, with an apply_updates() helper closing a data-loss trap (a bare RStatus(...) construction silently defaulted every untouched field to None) found in a 4-agent adversarial review before merge.

What's new in v2.19.0

• 🔍 r:urlcheck evidence-based 403 triage (#67) — replaces the hardcoded doi.org heuristic with root-then-URL probing, classifying dead/real_403 (gate) vs bot_blocked/transient (advisory).
• 🐛 r:rhub dispatch bugfix (#66) — rhub::rhub_check()'s first param is gh_url, not a local path; fixed via setwd().
• 🧹 r:tidy command + r:lint --tidy (#65) — tidyverse-conventions audit: lint preset, DESCRIPTION normalization, roxygen completeness, NEWS.md header currency.

Full release history: CHANGELOG.md.

Quick Start

# Quick analysis (< 30 seconds)
/rforge:analyze "Update RMediation bootstrap algorithm"

# Ultra-fast (< 10 seconds)
/rforge:quick

# CRAN submission gate (per-package)
/rforge:r:cran-prep

# Ecosystem rollup (2-5 minutes)
/rforge:thorough "Prepare for CRAN release"

Features

✨ Auto-delegation - Recognizes task patterns, selects appropriate tools ⚡ Parallel execution - Invokes multiple lib/ modules simultaneously 📊 Live progress - Real-time updates as tools complete 🎯 Smart synthesis - Combines results into actionable summary 🧠 ADHD-friendly - Fast feedback, clear structure, visual progress 🐍 Pure-Python lib/ - lib/discovery.py, lib/deps.py, lib/status.py, lib/init.py, lib/cranlint.py (pure Python, no R); lib/rcmd.py runs R engines for the r:* dev-cycle + CRAN commands. No MCP server, no Node.js. See docs/lib-modules.md.

How It Works

User Request
    ↓
Pattern Recognition (CODE_CHANGE, BUG_FIX, etc.)
    ↓
Tool Selection (impact, tests, docs, health)
    ↓
Parallel `lib/` invocations (python3 -m lib.* in subprocess)
    ↓
Results Synthesis (impact + quality + maintenance + next steps)
    ↓
Actionable Summary

Skills

/rforge:analyze

Balanced analysis with recommendations (< 30 seconds)

/rforge:analyze "Update code"

/rforge:quick

Ultra-fast status check (< 10 seconds)

/rforge:quick

/rforge:thorough

Comprehensive analysis with R CMD check (2-5 minutes)

/rforge:thorough "Prepare for CRAN"

Requirements

1. Python 3.10+ (the lib/ modules run via python3 -m lib.<tool>)
2. R Environment
   • R >= 4.0.0
   • devtools package (optional, for /rforge:thorough)
   • testthat package (optional)
   • covr package (optional, for coverage analysis)
3. Claude Code CLI or Claude Desktop
   • Plugin works in both environments

Migrating from v1.2.x? If you have an mcpServers.rforge entry in ~/.claude/settings.json, you can remove it — v1.3.0 no longer needs the MCP server. See docs/migration/rforge-mcp-deprecation.md.

Installation

Option 1: Claude Code Marketplace (Recommended)

From inside Claude Code:

/plugin marketplace add Data-Wise/rforge
/plugin install rforge

The marketplace install reads .claude-plugin/marketplace.json from the repository, fetches the plugin into ~/.claude/plugins/rforge, and wires it up automatically. Works on macOS, Linux, and Windows. Update later with /plugin update rforge.

Option 2: Homebrew (macOS)

# Add the Data-Wise tap
brew tap data-wise/tap

# Install rforge plugin
brew install rforge

The Homebrew formula automatically:

• Installs the plugin to ~/.claude/plugins/rforge
• Makes it available in Claude Code CLI and Claude Desktop

Option 3: Manual Installation (Local Development)

For Claude Code CLI and Claude Desktop:

# Clone the repository
git clone https://github.com/Data-Wise/rforge.git
cd rforge

# Install in development mode (symlink - changes reflected immediately)
ln -s $(pwd) ~/.claude/plugins/rforge

# Or install in production mode (copy - stable)
cp -r . ~/.claude/plugins/rforge

Installation locations:

• Plugin directory: ~/.claude/plugins/rforge
• Commands: ~/.claude/plugins/rforge/commands/
• Agent: ~/.claude/plugins/rforge/agents/orchestrator.md
• Lib: ~/.claude/plugins/rforge/lib/

Verify Installation

Step 1: Check plugin

# Check plugin directory exists
ls -la ~/.claude/plugins/rforge

# Verify plugin.json
cat ~/.claude/plugins/rforge/.claude-plugin/plugin.json

Step 2: Check Python

python3 --version    # Expect 3.10+

Step 3: Test end-to-end

# Navigate to an R package
cd ~/projects/r-packages/active/RMediation

# Start Claude Code
claude

# Test a command
/rforge:status

Expected output:

📊 RMediation - Single Package
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Version: 2.4.0
Tests: 187 passing
Health: 87/100 (B+)

Using in Claude Code CLI

After installation, commands are immediately available:

# Navigate to any R package
cd ~/my-r-package

# Start Claude Code
claude

# Use rforge commands
/rforge:analyze "Update bootstrap algorithm"
/rforge:status
/rforge:quick

Using in Claude Desktop App

RForge automatically loads when you open Claude Desktop. Commands work the same way:

1. Open Claude Desktop app
2. Navigate conversation to an R package directory (or specify path)
3. Use slash commands: /rforge:analyze, /rforge:status, etc.

Migration

• From v1.2.x: the mcpServers.rforge entry in ~/.claude/settings.json is no longer needed in v1.3.0. Remove it manually (we don't auto-edit user settings). See docs/migration/rforge-mcp-deprecation.md for the full migration table.

Migration from rforge-orchestrator (historical, pre-v1.3.0)

Only relevant if you skipped v1.2.x and are coming from a much older rforge-orchestrator setup. v1.3.0 doesn't use any MCP server, so the end state is just: remove these entries entirely.

If your ~/.claude/settings.json has either an rforge-orchestrator or rforge-mcp entry under mcpServers, delete it:

// Delete BOTH of these patterns if present:
{
  "mcpServers": {
    "rforge-orchestrator": { ... },
    "rforge-mcp": { ... }
  }
}

In v1.3.0+ the plugin runs entirely in-process via lib/ modules — there's no MCP server to configure. The plugin loads via /plugin install rforge; no settings.json entries are required.

For the full transition narrative, see docs/migration/rforge-mcp-deprecation.md.

Pattern Recognition

The orchestrator automatically detects what you're doing:

Example Outputs

Quick Analysis

⚡ Quick analysis running...
✅ Done! (8.2 seconds)

📊 QUICK SUMMARY:
✅ Impact: 2 packages (MEDIUM)
✅ Tests: 187/187 passing
⚠️ Docs: NEWS.md needs update
✅ Health: 87/100 (B+)

Full Analysis

🎯 IMPACT: MEDIUM
  • 2 packages affected (mediate, sensitivity)
  • Estimated cascade: 4 hours

✅ QUALITY: EXCELLENT
  • Tests: 187/187 passing (94% coverage)
  • CRAN: Clean

📝 MAINTENANCE: 2 items
  • NEWS.md needs entry
  • Vignette example outdated

📋 NEXT STEPS:
  1. Implement changes (3 hours)
  2. Auto-fix documentation
  3. Run cascade for dependents

Architecture

┌─────────────────────────────────────┐
│      Claude Code Session            │
│                                     │
│  ┌───────────────────────────────┐ │
│  │  RForge Orchestrator Plugin   │ │
│  │                               │ │
│  │  • Pattern Recognition        │ │
│  │  • Tool Selection             │ │
│  │  • Parallel Execution         │ │
│  │  • Progress Display           │ │
│  │  • Results Synthesis          │ │
│  └───────┬───────────────────────┘ │
│          │                          │
└──────────┼──────────────────────────┘
           │ Parallel python3 -m lib.* calls
           ↓
    ┌──────┴──────┬──────┬──────┐
    ↓             ↓      ↓      ↓
[discovery]  [deps] [status] [init]
    ↓             ↓      ↓      ↓
  (8s)          (5s)   (3s)   (7s)
    │             │      │      │
    └─────────────┴──────┴──────┘
                  │
                  ↓
         Results synthesized
         by orchestrator

Performance

Time savings: Parallel execution = 4x faster than sequential!

ADHD-Friendly Design

1. Fast feedback - Results in seconds, not minutes
2. Clear structure - Consistent output format
3. Visual progress - See what's happening
4. Actionable - Always provides next steps
5. Interruptible - Can cancel/resume anytime
6. Incremental - Results stream as they complete

Troubleshooting

"python3: command not found"

# Verify Python 3.10+ is on PATH
python3 --version

# macOS: install via Homebrew
brew install python@3.12

"Package not detected"

# Run from package directory
cd /path/to/package

# Or specify path explicitly
/rforge:analyze --package /path/to/package

"Analysis too slow"

• Use /rforge:quick for fast status
• Use /rforge:analyze for balanced speed/depth
• Only use /rforge:thorough when needed

Configuration

Plugin settings in plugin.json:

{
  "settings": {
    "default_mode": "quick",           // quick, analyze, or thorough
    "parallel_execution": true,         // Run tools in parallel
    "show_progress": true,              // Show progress bars
    "auto_synthesize": true             // Auto-generate summary
  }
}

Development

Plugin structure:

~/.claude/plugins/rforge/
├── .claude-plugin/
│   ├── plugin.json          # Plugin manifest (v2.21.0)
│   ├── marketplace.json     # Marketplace install metadata
│   ├── config.json          # User-tunable options (CRAN mirror, etc.)
│   ├── hooks/
│   │   └── pretooluse.py    # R-aware Write/Edit guard (4 rules)
│   └── skills/
│       └── validation/
│           └── description-sync.md  # DESCRIPTION ↔ NEWS.md drift check
├── commands/                # 44 slash commands (/rforge:*)
├── agents/
│   └── orchestrator.md      # Pattern recognition + delegation
├── lib/                     # Pure-Python analysis modules
│   ├── discovery.py         # Package detection + ecosystem layout
│   ├── deps.py              # Dependency graph + impact
│   ├── status.py            # DESCRIPTION + .STATUS health snapshot
│   ├── init.py              # ~/.rforge/context.json initializer
│   ├── rcmd.py              # R dev-cycle + quality + CRAN-submission engines (v2.7.0)
│   ├── cranlint.py          # CRAN-incoming linter — DESCRIPTION + build-hygiene (v2.3.0)
│   └── formatters.py        # Output formatting helpers
└── docs/                    # User-facing docs

Contributing

Ideas for improvement:

• [ ] Add caching for repeated analyses
• [ ] Track user preferences for tool selection
• [ ] Add more pattern types
• [ ] Improve time estimates
• [ ] Add result export (markdown, JSON)

License

MIT

Links

• v1.3.0 absorbed the prior rforge-mcp prototype (local-only, never published to GitHub or npm). See docs/migration/rforge-mcp-deprecation.md for the migration narrative.
• Claude Code: https://claude.com/code
• Documentation: See docs/ folder

Version: 2.22.1 Status: Active development Compatibility: Claude Code 0.1.0+