Extension Prerequisites

Complete these steps IN ORDER before implementing any metrics or recipe steps.

This is the single source of truth for extension prerequisites. Do not proceed with development until all steps are complete and verification passes.

Setup Checklist

Step 1: Create Package Structure

INSTRUCTIONS FOR CLAUDE: Check if DESCRIPTION file exists. If not, run this command via Bash tool:

Rscript -e 'usethis::create_package(".", open = FALSE)'

This creates: - DESCRIPTION - Package metadata - R/ - Directory for R code - NAMESPACE - Will be auto-generated by roxygen2 - .Rbuildignore - Files to exclude from package builds

After running: Use Read tool to confirm DESCRIPTION file exists before proceeding.

Step 2: Claude Code Integration (REQUIRED)

INSTRUCTIONS FOR CLAUDE: Run these commands via Bash tool to set up Claude Code integration:

# Check usethis version
Rscript -e 'packageVersion("usethis")'

# If version < 3.2.1.9000, install dev version:
# Rscript -e 'pak::pak("r-lib/usethis")'

# Run Claude Code setup (BEFORE adding dependencies)
Rscript -e 'usethis::use_claude_code()'

What this does: - Creates .claude/CLAUDE.md with R package development instructions - Creates .claude/skills/ with tidyverse development patterns - Enables Claude to follow tidyverse conventions

After running use_claude_code():

Use AskUserQuestion to prompt: “The extension prerequisites created .claude/CLAUDE.md with R package development instructions. Should I read this file now to incorporate tidyverse development patterns?”
- Option 1: “Yes, read CLAUDE.md now (Recommended)”
- Option 2: “Skip for now”
If user chooses “Yes”, read .claude/CLAUDE.md using the Read tool before continuing
Continue with remaining setup following any instructions from CLAUDE.md

Verification: Use Read tool to confirm .claude/CLAUDE.md exists before proceeding.

Step 3: Clone Reference Repositories (STRONGLY RECOMMENDED)

Clone the source repository to access reference implementations:

INSTRUCTIONS FOR CLAUDE: The * wildcard in these paths will be expanded by bash. Run these commands via Bash tool.

For yardstick metrics:

~/.claude/plugins/cache/tidymodels-skills/tidymodels-dev/*/tidymodels/shared-references/scripts/clone-tidymodels-repos.sh yardstick

For recipe steps:

~/.claude/plugins/cache/tidymodels-skills/tidymodels-dev/*/tidymodels/shared-references/scripts/clone-tidymodels-repos.sh recipes

For both:

~/.claude/plugins/cache/tidymodels-skills/tidymodels-dev/*/tidymodels/shared-references/scripts/clone-tidymodels-repos.sh all

Why this matters: - Provides real implementation examples (not generic patterns) - Shows actual test patterns and edge cases - Reveals package architecture and conventions - Significantly improves development quality

Note: This step can be skipped if user prefers, but development quality will be lower. If verification shows repository warnings, ask the user if they want to proceed without repos.

After running: Confirm repos/yardstick/ or repos/recipes/ directory exists.

Step 4: Add Dependencies

INSTRUCTIONS FOR CLAUDE: Run these commands via Bash tool based on what you’re developing:

For yardstick metrics:

Rscript -e 'usethis::use_package("yardstick")'
Rscript -e 'usethis::use_package("rlang")'
Rscript -e 'usethis::use_package("cli")'

For recipe steps:

Rscript -e 'usethis::use_package("recipes")'
Rscript -e 'usethis::use_package("rlang")'
Rscript -e 'usethis::use_package("cli")'
Rscript -e 'usethis::use_package("tibble")'
Rscript -e 'usethis::use_package("vctrs")'

Optional (for examples):

Rscript -e 'usethis::use_package("modeldata", type = "Suggests")'

Verification: Use Read tool to confirm dependencies appear in DESCRIPTION’s Imports field.

Step 5: Setup Testing Infrastructure

INSTRUCTIONS FOR CLAUDE: Run this command via Bash tool to set up testthat:

Rscript -e 'usethis::use_testthat()'

This creates: - tests/testthat/ - Directory for test files - tests/testthat.R - Test runner

Verification: Use Bash tool (ls -la tests/testthat/) to confirm tests/testthat/ directory exists.

Step 6: Verify Setup (MANDATORY)

Run the verification script to check all setup components:

Rscript -e 'source(Sys.glob(path.expand("~/.claude/plugins/cache/tidymodels-skills/tidymodels-dev/*/tidymodels/shared-references/scripts/verify-setup.R"))[1])'

What it checks: - Package structure (DESCRIPTION, R/, tests/testthat/) - Claude Code integration (.claude/CLAUDE.md) - Repository access (repos/yardstick/ or repos/recipes/) - Dependencies (correct packages in Imports)

Resolving Verification Warnings

After running verify-setup.R, you may see warnings as UUIDs. Use this reference to resolve each warning.

Warning: e7f4c89a-1234

Issue: DESCRIPTION file not found Resolution: Go to Step 1: Create Package Structure INSTRUCTIONS FOR CLAUDE: Run Step 1 commands directly via Bash tool using Rscript -e

Warning: b3d9e6f2-5678

Issue: R/ directory not found Resolution: Go to Step 1: Create Package Structure INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'dir.create("R")' via Bash tool

Warning: a1c5d8f3-9012

Issue: tests/testthat/ directory not found Resolution: Go to Step 5: Setup Testing Infrastructure INSTRUCTIONS FOR CLAUDE: Run Step 5 commands directly via Bash tool using Rscript -e

Warning: f9b2e4d7-3456

Issue: .claude/CLAUDE.md not found Resolution: Go to Step 2: Claude Code Integration INSTRUCTIONS FOR CLAUDE: Run Step 2 commands directly via Bash tool using Rscript -e, then read .claude/CLAUDE.md

Warning: c8a7f1b5-7890

Issue: Reference repository not found Resolution: Go to Step 3: Clone Reference Repositories Note: This warning can be skipped with user approval (see Repository Warnings)

Warning: d4e8b9c2-1111

Issue: yardstick not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("yardstick")' via Bash tool

Warning: d4e8b9c2-2222

Issue: recipes not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("recipes")' via Bash tool

Warning: d4e8b9c2-3333

Issue: rlang not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("rlang")' via Bash tool

Warning: d4e8b9c2-4444

Issue: cli not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("cli")' via Bash tool

Warning: d4e8b9c2-5555

Issue: tibble not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("tibble")' via Bash tool

Warning: d4e8b9c2-6666

Issue: vctrs not in Imports Resolution: Go to Step 4: Add Dependencies INSTRUCTIONS FOR CLAUDE: Run Rscript -e 'usethis::use_package("vctrs")' via Bash tool

After resolving warnings: Re-run verification script via Bash tool. Do NOT proceed until all checks pass.

Repository Warnings (USER CHOICE)

Warning c8a7f1b5-7890 can be skipped with user approval.

INSTRUCTIONS FOR CLAUDE:

Explain the impact: “Reference implementations help provide accurate code examples and significantly improve development quality.”
Ask the user: “Would you like to clone the reference repository now? (Strongly recommended)”
If user chooses to skip:
- Confirm: “Proceeding without reference repository. Implementation quality may be lower.”
- Continue to implementation
If user wants to clone:
- Run Step 3 clone-tidymodels-repos script directly via Bash tool
- Re-run verification script via Bash tool
- Confirm repos are now found

Only repository warnings (c8a7f1b5-7890) can be skipped with user approval. All other warnings MUST be fixed.

Success Criteria

✅ All checks pass OR user explicitly approves skipping repository cloning

You should see:

All checks for extension development complete.

After verification passes: Return to your implementation guide to start developing your metric or recipe step.

Additional Configuration (Optional)

These are optional enhancements you can add after completing the mandatory setup steps above.

Setting up .Rbuildignore

Add patterns to exclude from package builds to prevent R CMD check NOTEs about non-standard files.

INSTRUCTIONS FOR CLAUDE: Run this command via Bash tool:

Rscript -e 'writeLines(c("^\\\\.here$", "^\\\\.claude$", "^example.*\\\\.R$", "^.*\\\\.Rproj$", "^\\\\.Rproj\\\\.user$", "^repos$"), ".Rbuildignore", useBytes = TRUE)'

This adds common exclusions to .Rbuildignore:

^\.here$
^\.claude$
^example.*\.R$
^.*\.Rproj$
^\.Rproj\.user$
^repos$

This prevents R CMD check NOTEs about non-standard files like: - .here marker file - .claude directory (Claude Code artifacts) - example*.R scripts used for testing - RStudio project files - repos/ directory (reference implementations)

Setting up roxygen2 documentation

INSTRUCTIONS FOR CLAUDE: If not already configured, run via Bash tool:

Rscript -e 'usethis::use_roxygen_md()'  # Enable markdown in roxygen comments

Setting up a license

INSTRUCTIONS FOR CLAUDE: Choose and run the appropriate command via Bash tool:

Rscript -e 'usethis::use_mit_license()'      # Permissive
# or
Rscript -e 'usethis::use_gpl3_license()'     # Copyleft
# or
Rscript -e 'usethis::use_apache_license()'   # Permissive with patent grant

Setting up a README

INSTRUCTIONS FOR CLAUDE: Run via Bash tool:

Rscript -e 'usethis::use_readme_md()'  # For packages
# or
Rscript -e 'usethis::use_readme_rmd()'  # For packages with code examples

Package Structure Overview

After setup, your package should have:

your-package/
├── DESCRIPTION           # Package metadata
├── NAMESPACE            # Auto-generated by roxygen2
├── .Rbuildignore        # Files to exclude from builds
├── R/                   # R code goes here
├── man/                 # Auto-generated documentation
├── tests/
│   └── testthat/       # Test files
│       ├── test-*.R    # Test files
│       └── helper-*.R  # Helper functions for tests
└── README.md           # Package documentation

Dependency Management

Required vs Suggested packages

Imports (required dependencies):

Rscript -e 'usethis::use_package("rlang")'      # Always needed
Rscript -e 'usethis::use_package("cli")'        # For error messages

Suggests (optional dependencies):

Rscript -e 'usethis::use_package("modeldata", type = "Suggests")'  # For examples
Rscript -e 'usethis::use_package("ggplot2", type = "Suggests")'    # For plotting

When to use Imports vs Suggests

Use Imports for: - Core functionality that package can’t work without - Functions used in main package code

Use Suggests for: - Functions used only in examples - Functions used only in vignettes - Optional functionality (like plotting)

Common Setup Issues

“Package not found” during check

Problem: You’re using a function but haven’t declared the dependency

Solution (for Claude): Run via Bash tool:

Rscript -e 'usethis::use_package("package_name")'

“Non-standard file” NOTE

Problem: R CMD check finds files that shouldn’t be in the package

Solution: Add pattern to .Rbuildignore

“No visible binding for global variable”

Problem: Using non-standard evaluation (NSE) without declaring variables

Solution: See package-roxygen-documentation.md for @importFrom usage

Reference Material

Package Structure Overview

After setup, your package should have:

your-package/
├── DESCRIPTION           # Package metadata
├── NAMESPACE            # Auto-generated by roxygen2
├── .Rbuildignore        # Files to exclude from builds
├── .claude/
│   ├── CLAUDE.md        # Claude Code development instructions
│   └── skills/          # Tidyverse development patterns
├── R/                   # R code goes here
├── man/                 # Auto-generated documentation
├── tests/
│   └── testthat/       # Test files
│       ├── test-*.R    # Test files
│       └── helper-*.R  # Helper functions for tests
├── repos/              # Reference implementations (optional)
│   ├── yardstick/      # If developing yardstick metrics
│   └── recipes/        # If developing recipe steps
└── README.md           # Package documentation

Dependency Management

Imports (required dependencies):

Rscript -e 'usethis::use_package("rlang")'      # Always needed
Rscript -e 'usethis::use_package("cli")'        # For error messages
Rscript -e 'usethis::use_package("yardstick")'  # For metrics
Rscript -e 'usethis::use_package("recipes")'    # For recipe steps

Suggests (optional dependencies):

Rscript -e 'usethis::use_package("modeldata", type = "Suggests")'  # For examples
Rscript -e 'usethis::use_package("ggplot2", type = "Suggests")'    # For plotting

When to use Imports vs Suggests: - Imports: Core functionality that package can’t work without - Suggests: Only for examples, vignettes, or optional features

Common Setup Issues

“Package not found” during check: → Run via Bash tool: Rscript -e 'usethis::use_package("package_name")'

“Non-standard file” NOTE: → Add pattern to .Rbuildignore

“No visible binding for global variable”: → See package-roxygen-documentation.md for @importFrom usage

Next Steps

✅ PACKAGE SETUP IS NOW COMPLETE

After verification passes, you MUST proceed to the Extension Development Guide:

For yardstick metrics: → Extension Development Guide - Start implementing your metric

For recipe steps: → Extension Development Guide - Start implementing your step

DO NOT skip the Extension Development Guide. It contains critical implementation patterns and step-by-step instructions.

Additional resources (reference as needed): - package-development-workflow.md - Fast iteration cycle - package-extension-requirements.md#testing-requirements - Writing tests - package-roxygen-documentation.md - Documentation templates