CLAUDE.md · diff
git:20260207.6deb0ee to git:20260306.5a7b09c
16 added, 59 removed. Audit A to A.
# CLAUDE.md
- This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
- ## Project Overview
-
- This is a **Claude Code Plugin Marketplace** (`maquina-app/rails-claude-code`) containing three plugins for Ruby on Rails development. All plugins follow 37signals patterns and the One Person Framework philosophy.
-
- **This is a documentation-only project** — no build system, test suite, linter, or CI pipeline. All content is Markdown, JSON, and YAML. Validation happens through manual testing via Claude Code.
-
- ## Plugins
-
- | Plugin | Version | Purpose |
- |--------|---------|---------|
- | `rails-simplifier` | 1.0.0 | Refines Rails code following 37signals patterns (rich models, concerns, CRUD resources) |
- | `rails-upgrade-assistant` | 1.0.0 | Plans and executes Rails upgrades from 7.0 → 8.1.1 with detection scripts and reports |
- | `maquina-ui-standards` | 0.3.1.1 | Builds UIs using maquina_components (ERB partials + Tailwind CSS 4, inspired by shadcn/ui) |
- | `recuerd0` | 1.0.0 | Manages workspaces and memories via the Recuerd0 CLI for preserving knowledge from AI conversations |
-
- ## Architecture
+ Documentation-only plugin marketplace — no build system, test suite, linter, or CI. All content is Markdown, JSON, and YAML.
- ### Marketplace Structure
+ ## Plugin structure
```
- .claude-plugin/marketplace.json ← Marketplace definition (lists all plugins)
- <plugin-name>/
- ├── .claude-plugin/plugin.json ← Plugin metadata (name, version, description)
- ├── agents/<plugin-name>.md ← Main skill definition (Markdown with YAML frontmatter)
- ├── references/ ← Quick lookup guides
- ├── workflows/ ← Step-by-step procedures
- ├── examples/ ← Real usage scenarios
- └── templates/ ← Output format templates
+ .claude-plugin/marketplace.json ← Lists all plugins
+ <plugin-name>/.claude-plugin/plugin.json ← Plugin metadata
+ <plugin-name>/agents/<plugin-name>.md ← Main skill (Markdown + YAML frontmatter)
```
- Each plugin's **agent file** (`agents/*.md`) is the entry point — it contains the full skill instructions for Claude, with selective references to supporting files. Agent files use YAML frontmatter to define skill name, description, and model preference.
-
- ### Key Design Decisions
-
- - **Modular loading**: Agent files are compact (300–600 lines) and reference detailed docs on demand rather than inlining everything
- - **Workflows explain HOW**, examples show WHAT, references provide quick lookups — each has a distinct role
- - **Detection scripts** (upgrade-assistant only) use YAML pattern definitions + shell script templates for automated codebase scanning
-
- ## Version Management
-
- Versions are tracked in two places that must stay in sync:
- 1. `.claude-plugin/marketplace.json` — the `version` field in each plugin entry
- 2. `<plugin-name>/.claude-plugin/plugin.json` — the plugin's own `version` field
-
- ## Installation (for users of these plugins)
-
- ```bash
- # Add marketplace
- /plugin marketplace add maquina-app/rails-claude-code
-
- # Install plugins
- /plugin install rails-simplifier@maquina
- /plugin install rails-upgrade-assistant@maquina
- /plugin install maquina-ui-standards@maquina
- /plugin install recuerd0@maquina
- ```
+ Supporting files go in `references/`, `workflows/`, `examples/`, `templates/` within each plugin directory.
- Team-wide installation goes in `.claude/settings.json` with `extraKnownMarketplaces` and `enabledPlugins` keys (see README.md for full example).
+ ## Critical rules
- ## Editing Guidelines
+ ### Version sync
+ Versions must match in TWO places — update both or you'll create drift:
+ 1. `.claude-plugin/marketplace.json` → `version` field for the plugin
+ 2. `<plugin-name>/.claude-plugin/plugin.json` → `version` field
- - When modifying agent files (`agents/*.md`), preserve the YAML frontmatter structure
- - When adding breaking changes to version guides, update both the version guide and `reference/breaking-changes-by-version.md`
- - Detection script patterns (`detection-scripts/patterns/*.yml`) follow a consistent YAML schema — match existing pattern structure
- - Component additions to maquina-ui-standards go in `references/component-catalog.md` and should include ERB examples with all variant options
+ ### Editing agent files
+ - Preserve YAML frontmatter structure in `agents/*.md` — breaking it breaks the skill
+ - Breaking changes in version guides → update both the version guide AND `reference/breaking-changes-by-version.md`
+ - Detection script patterns (`detection-scripts/patterns/*.yml`) → match existing YAML schema exactly
+ - Component additions to maquina-ui-standards → add to `references/component-catalog.md` with ERB examples and all variant options