[Documentation] Add ruby-ui-stimulus agent skill

Merged
CI
3mo ago
+401-0

What

Adds an on-demand agent skill (ruby-ui-stimulus) that codifies how RubyUI wires Stimulus controllers to Phlex components, plus a short pointer in gem/AGENTS.md.

Inspired by The Hotwire Club skills (MIT). Since RubyUI uses Phlex (not ERB) and is a component gem (not an app), only the template-agnostic core — hwc-stimulus-fundamentals — is relevant; it's been adapted to Phlex and paired with RubyUI's own naming/wiring conventions.

Why

There was no documented Stimulus/Hotwire convention in gem/AGENTS.md or as a skill — the pattern only existed "by example", leaving new controllers inconsistent. A skill loads on demand (only when writing/reviewing a controller), so it doesn't tax every session's context the way inlining it in the always-loaded docs would.

Contents

  • .claude/skills/ruby-ui-stimulus/SKILL.md — core workflow + guardrails (lifecycle symmetry, idempotent connect, declarative values/targets/outlets, ruby-ui-- namespacing)
  • references/phlex-stimulus-conventions.md — naming table, data:/default_attrs wiring (both nested-hash and flattened-key styles), outlets, manifest registration, dependencies.yml
  • references/stimulus-fundamentals.md — controller-quality patterns adapted from hwc-stimulus-fundamentals
  • NOTICE.md — MIT attribution to The Hotwire Club
  • gem/AGENTS.md — pointer to the skill from the JavaScript section

All examples are drawn from real components (popover, clipboard, select, dialog).

Scope notes

  • Out of scope by design: the other 5 Hotwire Club skills (app-level: forms, navigation, media, streaming, UX) and Turbo Frames/Streams guidance (only DataTable uses a Frame today).
  • No component/controller code changed — documentation only.

Testing

  • Skill frontmatter is valid (name + description) and the skill is picked up by Claude Code.
  • Docs-only change; no Ruby/JS touched.

🤖 Generated with Claude Code

Summary by cubic

Adds the on-demand ruby-ui-stimulus agent skill to codify how RubyUI wires Stimulus controllers to Phlex components, plus a short pointer in gem/AGENTS.md. This standardizes controller lifecycle and naming to keep new controllers consistent.

  • New Features
    • Introduces ruby-ui-stimulus skill with core workflow and guardrails (idempotent connect, symmetric disconnect, declarative values/targets/outlets, ruby-ui-- namespacing, feature detection).
    • Adds references: Phlex ↔ Stimulus wiring (naming table, default_attrs nested/flat styles, outlets, rake stimulus:manifest:update, dependency mapping) and Stimulus fundamentals adapted for RubyUI; includes MIT attribution in NOTICE.md.
    • Updates gem/AGENTS.md to link the skill for quick discovery when writing or reviewing controllers.