rails-hyperdrive-layered-rails

A rails-hyperdrive companion gem shipping Vladimir Dementyev's Layered Rails skill — the coding-agent distillation of Layered Design for Ruby on Rails Applications.

The architecture core installs into any Rails app. Each per-gem reference manual installs only when that gem is in the app's bundle.

group :development do
  gem "rails-hyperdrive"
  gem "rails-hyperdrive-layered-rails"
end

bin/rails hyperdrive:init

What gets installed

One skill at .claude/skills/layered-rails/: a router SKILL.md plus workflows, pattern/anti-pattern/topic references, and refactoring examples.

Nine reference manuals under references/gems/ are gated on the app's bundle:

Reference	Installs when the app bundles
action-policy.md	action_policy
view-component.md	view_component
anyway-config.md	anyway_config
active-delivery.md	active_delivery
alba.md	alba
workflow.md	workflow or workflow-activerecord
rubanok.md	rubanok
active-agent.md	activeagent
active-job-performs.md	active_job-performs

A Rails app bundling none of them gets the architecture guidance with no dead weight and no dangling links; an app bundling alba and action_policy gets those two manuals and a Gem References table naming exactly those two.

Guidance that recommends adopting a gem stays unconditional — a reader should still learn that Active Delivery exists. Only the reference manuals, which are useless without the gem, are gated.

How the conditioning works

Two rails-hyperdrive mechanisms, both declared in SKILL.md's frontmatter and resolved at install time against the app's Gemfile.lock:

Per-file gating — a conditional: map keyed by supporting-file path:

conditional:
  references/gems/alba.md:
    gem: "alba"
  references/gems/workflow.md:
    gem: "workflow, workflow-activerecord"

The listed file installs only when at least one named gem is bundled. The files themselves are byte-identical to upstream.

Templating — the router ships as SKILL.md.erb and is rendered with gem?, any_gem?, and gem_version helpers. Its Gem References table lists only bundled gems, so gating a manual never leaves a link pointing at a file that was not installed. When no target gem is bundled the section disappears entirely. Rendered output installs as plain SKILL.md.

Upstream sync

Everything except SKILL.md.erb is vendored verbatim from palkan/skills; UPSTREAM records the ref.

bin/vendor-upstream [ref]   # default: v2.0.1

The script re-derives both adaptations from upstream's own content — the conditional: map and the ERB table are generated from the Gem References table it parses out of upstream's SKILL.md. Upstream edits therefore carry over wholesale. A gem reference the script cannot map to target gems aborts the vendor rather than passing through unconditioned.

License

MIT. Skill content © Vladimir Dementyev — see LICENSE and UPSTREAM.