hanakai-yaku

hanakai-yaku turns AI coding assistants into disciplined Hanami collaborators.

A curated library of 35 atomic skills and 10 personas for Hanami, dry-rb, and ROM Ruby development that teach AI tools how to configure providers, implement dependency injection, write TDD tests, create repositories, design slices, and build operations — using Hanami conventions.

Status: Experimental — used to validate skill format portability across Ruby frameworks. Not actively maintained as a product. For production Rails AI tooling, see rails-ai-bridge.

The project is built around one non-negotiable rule:

Write test -> Run test -> Verify it FAILS for the right reason -> Implement -> Verify it PASSES

That TDD gate is encoded directly into the skills and personas.

This repo is one of 6 in a composable AI skill ecosystem:

See the Ecosystem Overview for the full architecture.

This repo depends on ruby-core-skills. See Migration Guide.

Supported agent environments

| Reader | What you get | | Hanami developers | AI-assisted Hanami development: slices, repositories, operations, actions, views. | | dry-rb users | Guidance on operations, validation contracts, DI patterns, and type-safe design. | | ROM users | Repository patterns, relation design, changeset composition, migration safety. | | Team leads | Repeatable workflows for Hanami onboarding, TDD discipline, and slice architecture. |

Install skills via skills.sh:

npx skills add igmarin/hanakai-yaku

Or via GitHub CLI (v2.90.0+):

# Install the dependency first
gh skill install igmarin/ruby-core-skills

# Install all skills interactively
gh skill install igmarin/hanakai-yaku

# Install a specific skill
gh skill install igmarin/hanakai-yaku load-context --scope project

Or use directly as chat commands (@skill-name) in compatible AI tools (OpenCode, Cursor, Claude Code, Gemini CLI, Windsurf).

Skills are invoked via chat commands:

@load-context            # Discover the app's slices, providers, and routes
@configure-providers     # Set up providers and settings
@implement-di            # Configure dependency injection patterns
@hanami-setup            # Full project onboarding workflow

See docs/reference/skill-catalog.md for the complete catalog.

Each skill is a single SKILL.md file with YAML frontmatter and a 6-section body:

1. Frontmatter (YAML)       — name, description, metadata
2. Quick Reference          — scannable table for fast lookup
3. HARD-GATE               — non-negotiable blocking rules
4. Core Process             — step-by-step procedure
5. Output Style             — exact shape of artifacts
6. Integration              — predecessor/successor skills

When contributing skills, personas, or docs:

• Keep generated artifacts in English unless the user explicitly asks for another language.
• Preserve the tests-gate-implementation rule for every code-producing skill.
• Keep public docs consistent with directory.json and CONTEXT.md.