Diogenes

Diogenes walked through Athens with a lantern in broad daylight, looking for an honest man.

Diogenes is a Ruby gem that holds your AI features to the same light. It has two jobs:

1. A five-gate gauntlet decision framework that determines whether something should be an AI feature in production, or whether it's a software problem in disguise. Derived from Ruby's core principles: least surprise, programmer happiness, and human-centered design.
2. An agent configuration build tool that lets you write your AI agent skills, rules, and hooks once in a canonical Ruby DSL, and Diogenes builds the right configuration for every agent you use: Claude Code, Cursor, Copilot, Codex, Gemini, and more.

Why Diogenes?

The current pressure to ship AI features is real. Your PM read something. Your CEO saw a demo. And you're a Ruby developer — you know how to build it, the APIs are cheap, and a proof of concept takes an afternoon.

But Ruby has always had opinions about how software should feel, who it should serve, and what it means to write something you're proud of. Those opinions are exactly the framework we need right now.

Diogenes encodes those opinions into something you can run, test, and commit.

Installation

# Gemfile
gem "diogenes"

bundle install

Or, install globally to use the CLI anywhere:

gem install diogenes

The CLI - Agent Configuration as Code

Initialize a project

diogenes init

Creates a .diogenes/ directory with a canonical source structure:

.diogenes/
├── diogenes.rb          # root config — declare your targets
├── skills/              # things you invoke explicitly (/commands)
├── rules/               # standing instructions for every session
├── hooks/               # event-triggered behaviors
└── artifacts/           # output templates (decision records, ADRs, etc.)

Define skills in the Ruby DSL

# .diogenes/skills/evaluate_feature.rb

Diogenes.skill "evaluate_feature" do
  command     "/evaluate-feature"
  description "Walk a proposed AI feature through the five Diogenes gates"
  prompt      <<~PROMPT
    You are helping a Ruby developer evaluate whether a proposed AI feature
    should be built. Walk them through each of the five Diogenes gates in order,
    asking focused questions and surfacing the failure mode clearly if a gate fails.

    The five gates are:
    1. Is the failure mode acceptable at scale?
    2. Can the average user tell when it's wrong?
    3. Is there a real human in the loop — actually checking?
    4. Do you have the observability to know when it's going wrong?
    5. Is AI actually the right tool, or just the exciting one?

    At the end, generate a structured decision record.
  PROMPT
end

Build for your agents

diogenes build --all                  # build for every configured target
diogenes build --target claude-code   # .claude/commands/ + CLAUDE.md
diogenes build --target cursor        # .cursor/rules/
diogenes build --target copilot       # .github/copilot-instructions.md
diogenes build --target codex         # codex-instructions.md + tools.json
diogenes build --target gemini        # .gemini/instructions.md

Configure your targets in diogenes.rb:

Diogenes.configure do
  targets :claude_code, :cursor, :copilot
end

Evaluate a feature interactively

diogenes evaluate "AI assistant to explain billing history"

Walks through each gate as a conversation:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  DIOGENES — Feature Gate Evaluation
  "AI assistant to explain billing history"
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Gate 1 of 5: Failure Mode
→ Ruby principle: Least surprise — at scale

What happens when this feature is wrong?
A wrong answer here is a billing dispute the user
can't resolve without contacting support.

  Severity: [recoverable / embarrassing / catastrophic]
  > catastrophic

  ✗ GATE FAILED
  Catastrophic failure modes don't pass Gate 1.
  Consider: is there a software solution that makes
  the billing data clearer without AI interpretation?

Continue evaluating remaining gates? (y/N)

At the end, generates a decision record you can commit:

  ✓ Decision record written to docs/decisions/ai_billing_assistant_decision.md

The Runtime Library — Gates in Your Code

Include Diogenes::Gated

class BillingAssistant
  include Diogenes::Gated

  gate :failure_mode,    severity: :catastrophic
  gate :user_verifiable, domain: :financial
  gate :human_in_loop,   capacity: :real
  gate :observability,   monitoring: :required
  gate :right_tool

  def explain(invoice)
    # implementation
  end
end

Development — loud failures

In development, gate configuration is validated at class load time. A failing gate raises immediately so you can't start a server with a misconfigured AI feature:

Diogenes::GateFailed: Gate 1 (failure_mode) failed.
  severity: :catastrophic — catastrophic failures are not acceptable at scale.
  Consider a software alternative: clearer UI, explicit error states,
  or rule-based logic with predictable output.

Production — structured failures

In production, gate failures return a Diogenes::GateResult rather than raising:

result = BillingAssistant.new.explain(invoice)

if result.passed?
  render json: result.value
else
  render json: { error: result.reason }, status: :service_unavailable
end

Testing — gates are testable

# spec/models/billing_assistant_spec.rb
require "diogenes/rspec"

RSpec.describe BillingAssistant do
  it "declares all five gates" do
    expect(described_class).to have_gate(:failure_mode)
    expect(described_class).to have_gate(:user_verifiable)
    expect(described_class).to have_gate(:human_in_loop)
    expect(described_class).to have_gate(:observability)
    expect(described_class).to have_gate(:right_tool)
  end

  it "fails the failure mode gate — catastrophic severity is not acceptable" do
    expect(described_class).to fail_gate(:failure_mode)
  end
end

The Five Gates

Gate	Ruby Principle	The Question
1. Failure Mode	Least surprise — at scale	What happens when it's wrong? Is that acceptable?
2. User Verifiable	Trust — you can't trust what you can't verify	Can your average user tell when it's wrong?
3. Human in the Loop	Human-centered design, genuinely	Is there a human checking — actually checking?
4. Observability	Craftsmanship — you wouldn't ship a sort blind	Do you have the monitoring to know when it drifts?
5. Right Tool	Convention over configuration	Is AI the right answer, or just the exciting one?

Gate Reference

See docs/gates.md for the full schema of gate options and what passes/fails each gate.

Agent Targets

See docs/targets.md for the full list of supported build targets, what files they emit, and how to add a new target.

Contributing

See CONTRIBUTING.md.

Diogenes uses itself. The .diogenes/ directory in this repo contains the canonical source for the skills, rules, and hooks used when developing the gem. Run diogenes build --all after changing them.

Philosophy

Diogenes is not anti-AI. It's pro-Ruby.

Ruby has always prioritized the human — the programmer, the user, the person reading the code at 2am. That priority is the framework. The gates aren't a checklist to defeat; they're the questions you'd ask if you had time to think.

Most AI features should be software features. The ones that survive all five gates are worth building well.

License

MIT