hanakai-yaku

Master orchestrator for hanakai-yaku, a curated library of 35 atomic skills and 10 personas for Hanami, dry-rb, and ROM Ruby development. Covers actions, slices, repositories, relations, providers, DI, CLI, testing, views, routing, and TDD automation. Enforces Hanami conventions and TDD discipline. hanami, dry-rb, rom, ruby, tdd, slices, repositories, operations, providers, di, actions, views, routing, cli, testing.

Use when implementing a Hanami 2.x feature, Hanami action, Hanami slice, or any Hanami controller logic using test-driven development (TDD / red-green-refactor). Orchestrates test planning, generates request specs or action unit specs, drives the implementation of Hanami action classes and route configurations, and performs a final code review. Use when starting a new Hanami feature from scratch, adding integration tests for an existing Hanami action, or following a red-green-refactor cycle for any Hanami 2.x component.

Orchestrates Hanami project onboarding: loads application context, configures providers, implements dependency injection patterns, and verifies the setup. Use when setting up a new Hanami project, onboarding a developer, configuring services and DI, or wiring up dry-container, dry-system, IoC containers, or Hanami app configuration with providers and dependency injection.

Orchestrates the full Hanami slice lifecycle: creates the slice, tests it in isolation, reviews boundary design, and supports extraction from the app module. Use when building a new Hanami slice, auditing existing slices for bounded context violations, extracting monolithic code into a modular architecture, or enforcing slice generator conventions. Trigger terms: bounded context, Hanami module, modular architecture, slice boundaries, slice extraction, slice generator.

Use when building JSON API endpoints in Hanami 2.x Actions — set `response.format = :json`, use dedicated serializers to encode response bodies, write round-trip serialize→parse tests asserting fields match with `.iso8601` timestamps, include pagination metadata with `{data:, meta:}` shape, return consistent error shapes across endpoints, and rescue `JSON::ParserError` with 400 status. Covers setting content-type headers, serializing Ruby objects to JSON, parsing incoming JSON request bodies, content negotiation, and round-trip parse → serialize → parse verification. Use when you need to render JSON, build a JSON endpoint, create an API controller action, or handle JSON request/response cycles in Hanami 2.x.

Use when creating, generating, or reviewing Hanami 2.x Action classes (route handlers, request handling, hanami controller equivalents). Generates Action classes with proper handle method signatures, configures dependency injection via Deps[], renders views with exposures, validates params, redirects, returns JSON responses, sets HTTP status codes, and implements halt-based error handling. Use when building a hanami action, wiring a new endpoint, handling params, or structuring request/response logic in a Hanami 2.x app.

Use when handling errors and halting requests in Hanami 2.x Actions — fail fast with `halt STATUS, {error:}.to_json` for early returns, rescue `StandardError` (never `Exception`) logging full details internally but returning generic messages to clients, let invalid params halt automatically with 422 before `#handle` runs without manual `params.valid?` checks, and match error response format to action format (no HTML errors in JSON actions). Demonstrates halt status codes (404, 422, 500), rescue patterns, and consistent error shapes. Use when implementing error handling patterns, exception handling, or returning JSON error responses in Hanami actions.

Use when validating request parameters in Hanami 2.x Actions, including defining required/optional params blocks, applying type coercion (integer, bool, date), validating nested and array params, adding constraints, writing custom cross-field rules, and handling validation errors with 422 responses. Covers params block DSL, dry-validation predicates, input validation, action params, parameter types, and coercion of request input at the HTTP boundary.

Use when creating a new Hanami 2.x application — generate with `hanami new [name] --database=postgres`, configure environment detection via HANAMI_ENV (development/test/production), establish database connectivity via DATABASE_URL, install dependencies with `bundle install`, set up the database with `hanami db create && hanami db migrate && hanami db version`, and run the development server with `hanami dev`. Generates the full directory layout, config/app.rb, config/routes.rb, config/settings.rb, db/migrate/, slices/, and a config.ru. Use when starting a Hanami project from scratch, scaffolding a new app, or understanding project structure.

Use when generating Hanami 2.x components via CLI. Covers hanami generate action, view, slice, migration with output paths and naming conventions.

Use when running Hanami 2.x database CLI commands — always confirm HANAMI_ENV and DATABASE_URL before destructive operations, create databases with `hanami db create`, run/revert migrations with `hanami db migrate`/`rollback` validating via `hanami db version`, seed data with `hanami db seed` from `db/seeds.rb`, prepare the full database with `hanami db prepare`, and never edit already-run migrations or use `hanami db drop` without environment confirmation. Covers create, migrate, rollback, seed with preconditions and expected outcomes.

Use when running Hanami 2.x development commands — `hanami dev` with code reloading though config files require server restart, verify server responds via `curl http://localhost:2300` and recover from port conflicts and config syntax errors, `hanami console` requiring DATABASE_URL set with HANAMI_ENV awareness before destructive operations, using the container to explore slices/relations/repos, and `hanami routes`/`hanami middleware` for stack inspection. Covers hanami dev (starting the development server with code reloading), hanami console (REPL with full container loaded for exploring the app, accessing slices, inspecting registered components, querying relations, and testing repository methods), hanami routes (listing all routes), and hanami middleware (inspecting the middleware stack).

Loads the Hanami application context before any code, spec, or review work — discovers slices, providers, settings, routes, ROM setup, test framework, DI conventions, and existing patterns, with a mandatory security gate to redact all passwords/credentials/tokens/API keys before note-taking, and a rule to never propose code without first running load-context. The non-negotiable first step for every Hanami task. Trigger words: load context, before I code, what does this app use, match existing style, load-context, show me the app, discover structure, context.

Use when managing Hanami 2.x application settings, app config, or environment variables (env vars). Covers defining typed settings with dry-configurable, setting defaults, validating enum values, reading .env files, and injecting settings into components via Hanami's container. Use when declaring typed environment variable declarations, accessing configuration in Actions or providers, or migrating from Rails config to Hanami 2.x settings.

Use when reviewing Hanami 2.x code for quality and convention adherence — check Action responsibility at ≤~10 lines delegating business logic, verify DI via `include Deps[]` with no `Hanami.app["key"]` direct access, audit query locations ensuring all DB queries live in Repositories/Relations, inspect Repositories returning Entities not raw hashes, review Views receiving pre-fetched data only, check error handling logging+generic messages without exposing e.message, and assess test coverage for 400/404/422/500 paths. Triggers on phrases like 'review my Hanami code', 'check my action', 'code review', or 'dry-rb patterns'.

Creates a ROM changeset for write operations — creating, updating, or deleting data. Covers changeset types, input transformation, validation, and command composition. Use when implementing write operations for a repository. Trigger words: changeset, ROM changeset, create changeset, update changeset, ROM::Changeset, write operation, data mutation, command.

Use when creating ROM Repositories in Hanami 2.x, including CRUD operations, defining custom queries, configuring associations, setting up aggregate roots, entity mapping, transaction handling, and implementing the Repository as your domain persistence layer. Relevant for database access, rom-rb relations, sequel adapter setup, and wiring repositories into actions via dependency injection.

Use when defining ROM Struct attributes, configuring dry-types coercion for entity fields, implementing value-based equality semantics, or setting up a domain model class in Hanami 2.x. Handles creating entity classes, declaring typed attributes, enforcing immutability, configuring the repository struct namespace, and syncing entity definitions with schema changes. Use when working with ROM entity class definitions, persistence layer value objects, ROM relation mappings, or any Hanami 2.x domain model backed by rom-rb.

Use when defining ROM Relations that map to database tables in Hanami 2.x — inherit from `Hanami::DB::Relation` with `schema :table_name, infer: true` for automatic schema introspection or explicit `schema :table_name do ... end` with typed attributes, add custom query methods as public relation methods returning filtered/reordered relations, define associations via `many_to_one`/`one_to_many` with `as:` aliases and load strategies using `combine` for eager-loading, and keep relations in sync with migrations by verifying via console. Trigger terms: ROM Relations, schema inference, associations, query methods, combine, eager-loading.

Use when creating or modifying database schemas in Hanami 2.x with Sequel. Covers create_table, add_column, drop_column, alter_table, primary_key, indexes, and migration lifecycle commands.

Use when injecting dependencies in Hanami 2.x — always use `include Deps["dir.name"]` to inject (never call `Hanami.app["key"]` directly outside of providers), derive container keys from file paths via `app/{dir}/{name}.rb` → `"{dir}.{name}"`, exclude ROM-managed relations/structs/entities from auto-registration via `no_auto_register_paths`, access the dependency by its last key segment — for example `Deps["repos.user_repo"]` → use `user_repo`, and override dependencies in tests by passing stubs to `.new(keyword:)`. Covers container keys, auto-registration rules, no_auto_register_paths, and testing with stubs.

Use when registering external dependencies in Hanami 2.x — integrating a gem, wiring up a service, or setting up dependency injection for databases, mailers, caches, and third-party APIs. Creates provider files at `config/providers/[name].rb` using `hanami generate provider [name]`, implements lifecycle hooks with `prepare` for requiring gems and `start` for instantiation and service registration, registers components with a descriptive key using `register("name.client", instance)`, always loads configuration through `target[:settings]` never raw `ENV`, rescues and logs errors in `start` to prevent boot crashes, and verifies registration via `Hanami.app["key"]` in console or a lightweight smoke test.

Use when using the dry-monads Result pattern in Hanami 2.x — wrap outcomes in `Success(value)` or `Failure(error_object)`, chain operations with `Do notation` using `include Dry::Monads::Do.for(:call)` and `yield` inside the `call` method for sequential flows, inject the service object via `Deps["key"]` after registering it in a provider, handle results in Actions with pattern matching (`case result; in Success(v); ...; in Failure(e); ...; end`) rather than unsafe `value!` unwrapping, and model expected failures as data not exceptions. Covers bind/fmap chaining, and use in service objects registered in the DI container.

Encapsulate a business workflow in a `Dry::Operation` with explicit steps returning `Success(value)` or `Failure(error)` — inject dependencies via `include Deps[...]`, place the class in `slices/[slice]/operations/`, compose operations by injecting them as dependencies (never call one operation from inside another's private methods), pass test doubles through the constructor to verify step ordering, and delegate from actions that map results to HTTP responses. Composes validation, persistence, and side effects into explicit steps using the step/Do notation. Use when the user asks to create a business operation, service object, or workflow using dry-operation, dry-transaction, or Hanami operations. Trigger words: operation, dry-operation, dry-transaction, business logic, workflow, service, Dry::Operation, step, compose operations.

Define type-safe validation contracts with `Dry::Validation::Contract` — declare expected fields and types in `schema do` blocks with `required(:field).filled(:string)` and `optional(:field)`, write custom predicates in `rule(:field) do` blocks returning `key.failure("message")` on invalid input, call the contract as the first step in an operation wrapping the result in `Success(result.to_h)` or `Failure(result.errors.to_h)`, and write tests asserting `.be_success` for valid input and `.be_failure` with specific `result.errors[:field]` assertions for invalid input, using TDD red-green-refactor. Use when validating request params, operation input, or any structured data. Trigger words: validation, contract, dry-validation, params, schema, Dry::Validation::Contract, validate input, type-safe, custom predicate.

Use when integrating background jobs, async jobs, or background processing in Hanami 2.x — including Sidekiq integration, GoodJob worker setup, or any job queue configuration. Sets up background job providers, injects job-adapter dependencies into Hanami actions, creates job-triggering actions, and generates corresponding RSpec tests.

Use when adding a column, field, or new attribute to an existing table in Hanami 2.x, or when performing a database schema change such as altering a table. Chains write-migration, define-relation, define-entity, create-repository, and write-request-spec.

Use when building a REST API, scaffolding API endpoints, or creating a JSON API resource in a Hanami 2.x application. Creates a new Hanami slice, generates controller actions, defines RESTful routes, writes request specs, and performs a code review. Handles JSON serialization, parameter validation, and error responses for API endpoints.

Use when implementing a full CRUD resource in Hanami 2.x, including when asked to scaffold, generate a resource, create a REST endpoint, or build a new API resource. Chains entity, relation, repository, action, view, write-request-spec, and review-code to build the complete data-to-HTTP pipeline.

Use when creating a new Slice in Hanami 2.x — including when a user wants to add a slice, scaffold a slice, create a new Hanami module, or set up a bounded context. Chains create-slice, define-routes, configure-slice, inject-dependencies, and write-request-spec to generate the slice, configure routes, set up dependencies, and write smoke tests.

Use when implementing authentication in Hanami 2.x, including login, logout, signup, session management, password hashing, and protecting endpoints. Sets up login/logout flows, configures session-based or token-based auth, adds password hashing with bcrypt, and returns correct 401/403 responses for auth failures. Use when a user asks about auth, login, signup, JWT, sessions, passwords, or securing Hanami actions.

Use when implementing validation with dry-validation contracts, schemas, or form/input/params validation in Hanami 2.x. Injects dependencies, validates request params using dry-validation contracts, handles monadic Success/Failure result patterns, and writes action specs. Chains inject-dependencies, validate-params, handle-result-pattern, and write-action-spec.

Configure Hanami providers at `config/providers/[name].rb` using `Hanami.app.register_provider(:name) do [...] end` — define settings in `config/settings.rb` if the service needs configuration, implement lifecycle with `prepare` for requiring gems and `start` for instantiation using `target["settings"]` to access config (never hardcode credentials or use raw ENV), register with a descriptive key via `register("key", instance)`, and verify the provider boots without errors. Covers provider structure, settings integration, and boot lifecycle. Use when setting up a new provider, adding a service, or configuring ROM connections. Trigger words: provider, configure, ROM setup, external service, database connection, dry-system, boot, register component.

Inject dependencies through Hanami's `auto_inject` using `Deps["provider_key"]` — never call `Hanami.app["key"]` outside of providers, dependencies must be pre-registered by a provider using a descriptive dot-namespaced snake_case key, inject via constructor (no custom `initialize`), pass `instance_double` test stubs through `.new(keyword:)` in specs, validate resolution to catch `Dry::Container::Error` on unregistered keys, and access dependencies by their last key segment — for example `Deps["repos.user_repo"]` → call `user_repo`. Use when adding DI to actions, operations, or repositories. Trigger words: dependency injection, DI, auto_inject, Deps, inject, dry-system, constructor injection, test with DI.

Use when conducting a security audit, security review, vulnerability assessment, vulnerability check, or secure coding review on Hanami 2.x applications — validate params via the Params DSL in every Action, verify CSRF protection is enabled in config/app.rb, audit authentication checks via explicit `before :authenticate!`, check authorization with role/permission checks, never log passwords/tokens/secrets, use ROM query interface to prevent SQL injection (no string interpolation in `where("...")`), never use `raw` on user input in templates, store secrets in settings not hardcoded, and return generic error messages for auth failures. Validates parameter handling, CSRF, auth integration, XSS, session configuration, and hardening posture.

Use when defining routes in Hanami 2.x. Covers get, post, patch, delete, resources, resource, scope, and named route helpers in config/routes.rb.

Creates and configures Hanami 2.x Slices by registering providers, setting up container dependencies, customizing auto-registration paths, and managing slice-level settings. Use when configuring slice setup, modular app structure, Hanami component registration, dependency injection, provider registration, container imports/exports, or autoloading for a Hanami 2.x Slice.

Use when creating Hanami Slices — generate a slice with `hanami generate slice [name]`, register it in `config/app.rb` via `slice :name, at: "/path"`, define slice routes in `slices/[name]/config/routes.rb`, configure inter-slice dependencies with `import`/`export` (avoid circular deps: if A imports from B, B must not import from A), and keep slices self-contained for distinct bounded contexts like API, admin, or billing, the main web application. Covers slice directory generation, route configuration, cross-slice dependency management, and slice-level container access.

Extract code from Hanami app module into a dedicated slice — DO NOT change behavior, every test must pass after the move, identify bounded context, use `create-slice`, `git mv` preserving history, update namespaces App::X→X plus `Deps[...]` and route defs, run full test suite before and after, load supporting files only when needed (progressive disclosure). Covers identifying extraction boundaries, moving files while preserving history, updating imports and dependencies, and verifying the extraction. Trigger words: extract slice, extract to slice, move to slice, create slice from existing, refactor to slice, modularize.

Reviews Hanami slice boundaries for violations — cross-slice coupling, shared internals, import leaks, provider leaks where a provider registers something that should be slice-scoped, and boundary design — producing findings with severity and concrete recommendations, every finding citing the specific file and line as evidence. Use when auditing slice architecture or preparing for extraction. Trigger words: review slice, slice boundaries, slice coupling, cross-slice, boundary review, slice audit, architecture review, bounded context.