| name | ruby-services |
| description | Use when creating, changing, testing, or reviewing Ruby service objects, especially Assistant::Service subclasses, service inputs, validation, execution, logs, or Minitest coverage. |
Ruby Services
Use this skill when working on Ruby service objects in this repository,
especially Assistant::Service subclasses or framework behavior that affects
service inputs, validation, execution, logs, result hashes, or tests.
Do not use this skill for unrelated Ruby scripts, packaging-only changes, or
opencode configuration tasks unless the work directly concerns Ruby service
guidance.
Core Approach
- Preserve the existing
Assistant::Service public API unless the user asks for
an API change.
- Prefer soft-fail service behavior: report domain and validation failures with
error logs instead of raising, unless an exception is explicitly part of the
API being changed.
- Keep service logic clear and object-oriented: every method should have one
responsibility.
- Only add a private helper when it makes sense in the context of the service's
domain and improves readability.
- Keep helper names aligned with what the service does, not generic process
steps like
handle_data or process_stuff.
- Do not add arguments to service instance methods other than
initialize.
Service behavior should use declared inputs and instance state.
- Return computed data from
execute; put pre-execution domain checks in
validate.
- Use
log_item_warning, log_item_error, log_item_info, or
add_log(level:, source:, detail:, message:) consistently with existing
log patterns.
Inputs
- Declare service inputs with
input :name, type: SomeClass and existing DSL
options such as required:, optional:, default:, allow_nil:, and if:.
- Prefer
default: -> { [] } or default: -> { {} } for mutable defaults.
- Use
allow_nil: true only when explicit nil is a valid service value.
- Do not depend on deprecated
valid_require_*? names in new internal code;
use the canonical valid_required_*? names.
Tests
- Add or update Minitest coverage under
test/**/*_test.rb for behavior
changes.
- Use anonymous
Class.new(Assistant::Service) fixtures for framework-level
service behavior, matching the existing tests.
- Assert the service result hash shape,
status, warnings, errors, logs,
and memoization when relevant.
- For input DSL changes, cover required, optional, default, type, conditional,
and
allow_nil behavior as applicable.
- Use helpers from
test/test_helper.rb for log-item construction or warning
capture instead of duplicating helper setup.
Style
- Ruby target is 3.4.
- Start Ruby files with
# frozen_string_literal: true.
- Prefer concise Ruby that matches nearby code; endless methods are acceptable
where they are already used.
- Respect the repo's hybrid compact nesting convention from
rubocop-style-compact_nesting.
- Keep public API documentation aligned with
docs/v1/01-api-surface.md and
user-facing changes aligned with CHANGELOG.md when appropriate.
- Make the smallest correct change; avoid generic abstractions until there is a
concrete second use.
Verification
Run the focused test first when possible, then the broader checks relevant to
the change:
bundle exec ruby -Itest test/assistant/service_test.rb
bundle exec rake test
bundle exec rubocop
