x_aeon_agents

x_aeon_agents is a Ruby gem and CLI that arms AI assistants with ready-to-use skills to automate everyday development workflows for X-Aeon projects.

x_aeon_agents is a 💎 Ruby gem that gives AI assistants a ready-to-use skill set so they can automate everyday development workflows for X-Aeon projects. 🤖

📬 Pull Request reviews — automatically read, address and reply to GitHub review comments
📝 Commit messages — generate meaningful descriptions for your staged changes
📚 README generation — build documentation sections straight from your codebase
🔍 Git diff interpretation — summarize what changed and why
🚀 Issue implementation — turn GitHub issues into working code
🛠️ Task bootstrapping — create git worktrees and feature branches in seconds
🔧 Skill templating — generate reusable agent workflows from ERB templates

Use it as a ⚡ CLI in your terminal or as a 📦 library inside your Ruby projects.

Quick start
Requirements
Features
Public API
Documentation
- Library public API
How it works
Development
Contributing
License
Ways skills are written
General principles
Generating skills from ERB templates

Quick start

Prerequisites

Ruby >= 3.1
An OpenRouter API key (OPENROUTER_API_KEY) so the built-in agents can call an LLM
A GitHub token (GITHUB_TOKEN) for features that talk to GitHub (Pull Requests, issues, comments)
Optionally a Cline API key (CLINE_API_KEY) when driving the Cline agent

Install

Install the gem from RubyGems:

gem install x_aeon_agents

Or add it to your project's Gemfile and install with Bundler:

gem 'x_aeon_agents'

bundle install

Configure

Export the required credentials as environment variables (the CLI reads them automatically):

export OPENROUTER_API_KEY="sk-or-..."
export GITHUB_TOKEN="ghp_..."

Use the CLI

The xaa command is installed alongside the gem. Run it from inside any Git repository.

Commit your staged changes with an AI-generated message:

xaa commit

Address GitHub Pull Request review comments (auto-detected from the current branch):

xaa review-comments

Push your branch and open a Pull Request:

xaa create-pr

Generate or update the project README from the codebase:

xaa generate-readme

Ask a quick one-off question to the agent:

xaa prompt "What is the capital of France?"

Bootstrap a new task in a git worktree:

xaa start-task --branch feature/my-task

Use as a library

Require the gem and configure it in your Ruby code:

require 'x_aeon_agents'

XAeonAgents::Config.configure(
  openrouter_api_key: ENV['OPENROUTER_API_KEY'],
  github_token: ENV['GITHUB_TOKEN']
)

# Trigger agents programmatically
XAeonAgents::Agents::CommitterAgent.new.run

Requirements

Ruby >= 3.1 — the xaa CLI and library are Ruby-based (RubyGems/Bundler needed to install the gem)
Git command-line client in PATH — the agents operate on repositories, branches, worktrees and commits
GitHub CLI (gh) installed and authenticated — used by the Pull Request and comment skills to query and reply via gh api
GITHUB_TOKEN environment variable — a GitHub personal access token used by Octokit for API access
OPENROUTER_API_KEY environment variable — an OpenRouter API key that powers the AI agents through RubyLLM
CLINE_API_KEY environment variable (optional) — only required when driving the Cline agent integration

Features

x_aeon_agents provides a xaa command-line interface and a reusable Ruby library that package a suite of AI agents to automate everyday development workflows.

📬 Pull Request review handling — auto-detect the PR for the current branch, read agent-addressed comments, fix the code and reply to each thread
📝 AI commit messages — analyze staged changes and generate a meaningful message, with flexible staging strategies (all, if_empty, none)
🚀 Automated Pull Request creation — push the branch to GitHub and open a PR against a configurable base ref with an AI-written description
📚 README generation — build a full README from the codebase with toggleable sections (about, quick start, requirements, features, public API, documentation, how-it-works, development, contributing, license)
🐛 GitHub issue implementation — turn an issue (and its comments) into working code, committing changes and opening a PR automatically
🛠️ Arbitrary requirement implementation — pass free-form requirements to a Developer agent that edits the codebase, optionally committing and opening a PR
🔍 Git diff interpretation — summarize the working tree changes and the intent behind them relative to any base ref
💬 One-shot prompts — send a single prompt to the AI agent and print the response
🔧 Skill templating — generate skill files from ERB templates, evaluating templates and copying assets to the output directory
📥 Skill installation — install skills and their recursively-resolved dependencies from a manifest for a chosen agent
🌿 Task bootstrapping — create a feature branch, set up a git worktree, push it upstream and open it in the editor
📦 Reusable Ruby library — require the gem and trigger agents programmatically (e.g. Agents::CommitterAgent.new.run)
🧩 Agent framework & provider integration — composable agents built on ai-agents/composable_agents, a Cline/OpenRouter provider, central Config, helpers and GenHelpers
💾 Session persistence & debugging — global --session-id for conversation persistence and a --debug flag for verbose logging

Public API

x_aeon_agents exposes a command-line executable and a set of Ruby library entry points. Only the components below are part of the public API (methods tagged in the Public API YARD group).

Executable: `xaa`

The bin/xaa script is the entry point of the CLI. It boots the gem and dispatches ARGV to XAeonAgents::Cli.

Usecase — commit staged changes with an AI-generated message:

xaa commit

More details: GitHub — bin/xaa

`XAeonAgents::Config`

Singleton holding all configuration of X-Aeon Agents (secrets, data directory, CLI defaults, debug flag). All methods below are part of the public API.

Usecase — configure credentials and options at once:

require 'x_aeon_agents'

XAeonAgents::Config.configure(
  openrouter_api_key: ENV['OPENROUTER_API_KEY'],
  github_token: ENV['GITHUB_TOKEN'],
  debug: false
)

More details: RubyDoc — XAeonAgents::Config

Public methods:

configure(**kwargs) — set any configuration property. doc
cline_api_key / cline_api_key= — Cline API key (also openrouter_api_key, github_token). doc
data_dir / data_dir= — X-Aeon Agents data directory. doc
default_cline_cli_args / default_cline_cli_args= — default Cline CLI arguments. doc
debug / debug= — debug mode. doc
agent_options — the available AgentOptions instance. doc

`XAeonAgents::AgentOptions`

Provides agent options (model, strategy, etc.) keyed by agent category. These options can be passed to an agent's constructor.

Usecase — read the options for a given category:

opts = XAeonAgents::Config.agent_options['free_simple']
# => { model: 'openrouter/free', strategy: ComposableAgents::PromptRenderingStrategy::Markdown }

More details: RubyDoc — XAeonAgents::AgentOptions

Public methods:

[](agent_category) — get the options for a category (lazily evaluated). doc
[]=(agent_category, agent_options) — set the options for a category. doc

`XAeonAgents::GenHelpers`

DSL mixed into ERB skill templates, used to generate skill files (metadata, goals, rules, todo lists).

Usecase — declare a skill's frontmatter inside an ERB template:

<%= skill(description: 'Implement a GitHub issue', dependencies: ['analyzing-github-issue']) %>

More details: RubyDoc — XAeonAgents::GenHelpers

Public methods:

skill(description:, dependencies:, plan:, metadata:) — define skill metadata / YAML frontmatter. doc
goal(goal_desc = nil) — define or get the skill goal. doc
goal_sentence — the skill goal as a sentence. doc
announce — prompt announcing the agent is working on the skill. doc
tmp_path — default temporary folder for agents. doc
rule(title, description:, type:, bad:, good:, rationale:) — generate a documented rule block. doc
ordered_todo_list(&erb_block) — generate a numbered todo list section. doc
when_to_use(&erb_block) — generate the "When to use it" section. doc
name — the skill name being generated. doc
self.config(skill_name) — read a skill's .skill_config.yml. doc

It also exposes XAeonAgents::GenHelpers::ErbEvaluator, a small public helper class that evaluates ERB skill templates with this DSL (ErbEvaluator#new(erb_file) and ErbEvaluator#result). doc

Documentation

GitHub repository — main project page with source code, issues and CI: github.com/Muriel-Salvan/x_aeon_agents
Project README — overview, CLI usage and skill-authoring guidelines: github.com/Muriel-Salvan/x_aeon_agents/blob/main/README.md
RubyDoc.info — full API reference generated from the source (YARD): rubydoc.info/gems/x_aeon_agents
RubyGems — published gem page and release history: rubygems.org/gems/x_aeon_agents

Library public API

The documented public methods (browseable on RubyDoc.info):

XAeonAgents module:
- agent_name — doc
- agent_signature — doc
- VERSION — doc
XAeonAgents::GenHelpers — DSL helpers for generating skill content from ERB templates:
- skill — doc
- goal — doc
- goal_sentence — doc
- announce — doc
- tmp_path — doc
- rule — doc
- ordered_todo_list — doc
- when_to_use — doc
- name — doc
- config (class method) — doc
XAeonAgents::GenHelpers::ErbEvaluator — helper class to evaluate ERB skill templates:
- new — doc
- result — doc

How it works

x_aeon_agents is a 💎 Ruby gem organized around three layers: a CLI, a set of orchestrating agents, and a shared configuration / helper core.

Entry point 🚪

The xaa executable (bin/xaa) boots Zeitwerk auto-loading and calls XAeonAgents::Cli.start(ARGV). The CLI (lib/x_aeon_agents/cli.rb) is a Thor application: each sub-command maps 1:1 to an agent and forwards global options (--session-id, --debug).

Agents as composable workflows 🧩

Every capability (commit, create-pr, review-comments, implement-issue, generate-readme…) is implemented by an Agents::*Agent class. They inherit from composable_agents base classes:

ComposableAgents::Agent — pure orchestrators that run shell commands and coordinate children.
ComposableAgents::AiAgents::Agent / ComposableAgents::Cline::Agent — LLM-driven agents that execute prompts.

Each agent is enriched by the AgentDefaults mixin (lib/x_aeon_agents/agent_defaults.rb), which:

injects new_agent(...), step(...) and step_agent(...) to build multi-step pipelines;
auto-configures the underlying frameworks (setup_composable_agents, setup_ai_agents, setup_cline);
manages a per-session directory under Config.data_dir/sessions/<id>;
prepends ArtifactContract + Resumable mixins for input/output validation and pause/resume.

Orchestration 🔗

A top-level agent decomposes its task into steps that delegate to child agents, passing state through a shared @artifacts hash referenced via artifact_ref. For example, DeveloperAgent chains PlannerAgent ➜ CoderAgent ➜ TesterAgent ➜ (optional) CommitterAgent / DocumenterAgent ➜ (optional) PullRequestCreatorAgent.

flowchart TD
  CLI[XAeonAgents::Cli / xaa] -->|instantiates + run| A[Top-level Agent]
  A -->|step_agent| P[PlannerAgent]
  A -->|step_agent| C[CoderAgent]
  A -->|step_agent| T[TesterAgent]
  A -->|step_agent| K[CommitterAgent]
  C -.->|artifacts hash| T
  T -.->|artifacts hash| K
  subgraph LLM[AI backends]
    C --> Prov[Cline / OpenRouter provider]
    T --> Prov
  end
  K --> Git[(Git + GitHub via Octokit)]

Configuration & providers 🔐

XAeonAgents::Config is a singleton holding secrets (cline_api_key, openrouter_api_key, github_token), the data directory, debug flag and per-category AgentOptions (model + strategy, e.g. free_simple, free_complex). LLM access flows through Providers::Cline (lib/x_aeon_agents/providers/cline.rb), an OpenAI-compatible RubyLLM provider targeting the Cline API.

Skills & ERB templating 📚

Reusable agent instructions live as Markdown skills under skills/. Some are generated from ERB templates in skills.src/ via the generate-skills command, evaluated by XAeonAgents::GenHelpers (lib/x_aeon_agents/gen_helpers.rb) — a DSL that emits YAML front-matter, goals, rules and checklists.

Helpers 🛠️

XAeonAgents::Helpers (lib/x_aeon_agents/helpers.rb) centralizes Git, GitHub (Octokit), real-time command execution, diff extraction and interactive content review used across all agents.

Development

This section explains how to set up a local environment to develop x_aeon_agents, run its test suite, lint the code and build the gem.

Prerequisites

Ruby >= 3.1 (the CI runs on Ruby 3.4) and a matching Bundler.
Git command-line client.
(Maintainer only) Node.js and npm, required for skillkit and semantic-release used during packaging and release.

Clone and install dependencies

git clone https://github.com/Muriel-Salvan/x_aeon_agents.git
cd x_aeon_agents
bundle install

bundle install installs the runtime dependencies declared in x_aeon_agents.gemspec plus the development dependencies from the Gemfile (rspec, rubocop, rubocop-rspec, rubocop-yard, simplecov, simplecov-cobertura, sem_ver_components).

[!NOTE] Gemfile.lock is intentionally git-ignored: this is a library, not an application.

Project layout

lib/                    # Library source, auto-loaded with Zeitwerk (entry: lib/x_aeon_agents.rb)
  x_aeon_agents/
    cli.rb              # The `xaa` Thor CLI definition
    config.rb           # Global configuration
    agents/             # AI agents (commit, PR, README generation, …)
    providers/          # LLM provider integrations
    gen_helpers.rb      # ERB skill template helpers
    version.rb          # Gem version (bumped automatically on release)
bin/
  xaa                   # CLI executable
skills.src/             # ERB skill templates (source of truth)
skills/                 # Generated skills (produced from skills.src)
spec/                   # RSpec test suite
  spec_helper.rb        # Global RSpec / SimpleCov configuration
  scenarios/            # End-to-end scenario specs
  x_aeon_agents_test/   # Test helpers (loaded via Zeitwerk)
.github/workflows/      # CI (continuous_integration.yml)

Running the test suite

Tests use RSpec 3 with SimpleCov coverage (minimum 97%).

# Run the whole suite, exactly like the CI does
bundle exec rspec --format documentation

# Run a single file or directory
bundle exec rspec spec/scenarios/code_quality_spec.rb

# Enable verbose test logging
TEST_DEBUG=1 bundle exec rspec

The coverage report is written to coverage/ (Cobertura format for Codecov). Each example runs with a cleaned, temporary .x_aeon_agents_test/ data directory (git-ignored), and the application configuration is populated with dummy API keys by spec_helper.rb.

Linting

Code style is enforced with RuboCop (rubocop, rubocop-rspec, rubocop-yard), configured through .rubocop.yml.

# Check style
bundle exec rubocop

# Check and auto-correct
bundle exec rubocop -A

Building skills from templates

Some skills are authored as ERB templates under skills.src/. Generate the final skills/ files with:

bundle exec ruby bin/xaa generate-skills

This finds every .erb file in skills.src/, evaluates it with the XAeonAgents::GenHelpers DSL and writes the resulting files (minus the .erb extension). Always regenerate skills before committing so the committed skills/ directory stays in sync with its sources.

Common development tasks

Run the CLI locally without installing the gem:

bundle exec ruby bin/xaa --help
bundle exec ruby bin/xaa <command> [options]

Build the gem package locally:

gem build x_aeon_agents.gemspec

This produces a x_aeon_agents-<version>.gem file. Note that x_aeon_agents.gemspec only packages lib/**/* and top-level *.md/*.txt files; the skills/ directory is committed to the repository separately (regenerate it first) and is not bundled inside the gem.

Generate the API documentation with YARD (output in doc/, git-ignored):

bundle exec yard

Packaging and release

Releases are automated through the package job of GitHub Actions using semantic-release and semantic-release-rubygem:

Skills are regenerated (bundle exec ruby bin/xaa generate-skills) and staged.
semantic-release computes the next version from conventional commits, updates lib/x_aeon_agents/version.rb and CHANGELOG.md, and creates a Git tag plus a GitHub release.
The gem is built and pushed to RubyGems.

Contributors do not need to run these release steps locally — just make sure tests pass with bundle exec rspec and skills are regenerated with bundle exec ruby bin/xaa generate-skills before sharing your changes.

Contributing

Contributions to x_aeon_agents are welcome! This 💎 Ruby gem lives on GitHub and is released automatically via semantic-release, so a clean, linear history and passing CI keep the project healthy. 🌱

🐛 Reporting issues

Open a new issue on the issue tracker and describe the expected vs actual behavior, your Ruby version, and clear steps to reproduce.
For a bug in a specific skill, mention the skill name (e.g. addressing-pull-request-comments) and the command you ran.

🍴 Forking & branching

📌 Fork the repo and add upstream as a remote named github: git remote add github https://github.com/Muriel-Salvan/x_aeon_agents.git.
Create a feature branch from main; the project favors git worktrees, so you can run xaa start-task --branch feature/my-change.
Keep your branch current by rebasing on github/main (git fetch --all && git rebase github/main) — never merge.

🧪 Running the tests

To run the suite locally, install the test dependencies with bundle install (the Gemfile pulls in RSpec 3, RuboCop, SimpleCov and its Cobertura formatter), then launch the full suite exactly like CI via bundle exec rspec --format documentation, or scope it to a single file such as bundle exec rspec spec/scenarios/code_quality_spec.rb; each example runs against a temporary, auto-cleaned .x_aeon_agents_test/ directory with dummy API keys injected by spec/spec_helper.rb, and SimpleCov enforces a minimum 97% coverage before the run is considered green.

🔀 Opening a Pull Request

Push your branch to your fork and open a PR against main on the upstream repo.
Describe what changed and why, and link the related issue when relevant.
Rebase on the latest github/main and push with git push github --force-with-lease if you rebased.

🤖 CI & coverage

Every push triggers the continuous integration workflow, which runs on Ruby 3.4, installs skillkit, executes the tests and uploads coverage to Codecov.
The package job regenerates skills (bundle exec ruby bin/xaa generate-skills) and runs npx semantic-release — you don't need to run these locally, but your changes must not break them.

🧹 Code style

Lint with bundle exec rubocop (config in .rubocop.yml, using rubocop, rubocop-rspec and rubocop-yard); auto-fix with bundle exec rubocop -A.
If you edit a skill written as an ERB template under skills.src/, always regenerate the committed skills/ files with bundle exec ruby bin/xaa generate-skills before committing.

✅ Before you submit

🟢 All RSpec examples pass and coverage stays ≥ 97%.
🪄 rubocop reports no offenses.
📝 Generated skills are in sync (skills/ matches skills.src/).
📜 Keep the BSD-3-Clause license and stay kind & respectful in all interactions. 💛

License

This project is licensed under the BSD License (modified). See the LICENSE file for the full text and terms.

Ways skills are written

Follow guidelines from the following sources:
- agentskills.io
- Claude code best practices
Help agents follow those skills and their steps by using the following guidelines:
- About skill name and YAML frontmatter:
  - Always name skills using <verb>[-<object>-[<context>]].
  - Use gerund in the skill name.
  - Use third person in the skill description.
  - Always add a Use when ... part of the skill description.
- About skill content:
  - Use Markdown for the skill's content.
  - Use imperative verbs (ex: Read the README file to know about the CLI usage).
  - Separate ordered steps in the skill's content using Markdown's headers (ex: ## 5. Perform data analysis), and give details of this step using bullet points.
  - Don't mix several commands in 1 step. Split steps if several commands are involved.
  - Use {variable_name} to identify placeholders.
  - Be clear and consistent about commands: always use backticks to identify a command, and use a prefix for the command type. Here are the prefixes in use:
    - cli: : Used for command-line tools. Ex: Use `cli: ls -la` to list all the files.
    - agent: : Used for agent commands. Ex: Use `agent: ask_followup_question` to ask the USER about the intent.
    - skill: : Used for skills. Ex: Use `skill: creating-pull-request` to create the PR for {branch}.
  - Don't use capital wordings as it adds emotional noise and is different from non-capitalized tokens used during LLMs training.
  - Use some wording in a consistent way. Those words are inspired by https://github.com/rohitg00/skillkit/blob/39b94534ec1c3698c0dec3a005744dafa99e63e9/packages/core/src/quality/index.ts
    - User represents the developer asking the agent to perform a task.
    - Always is used to emphasize that a specific step is mandatory (ex.: Always use `cli: gh` to gather issue information).
    - Never is used to emphasize that a specific step should never be done (ex.: Never use `cli: gh` to create a PR).
    - If ... then ... else are used to clearly identify some branching decisions.
    - Plan and Act modes refer to precisely the 2 ways of executing skills by the agents.
- About skill semantics:
  - A skill is better followed when it consists only in a sequence of easily identified steps (like a workflow). Don't use vague guidelines in a skill.
  - When another skill is performing a sub-task of your skill, reference it explicitely, like Use `skill: skill_name` to perform this action instead of Perform this action. Don't rely on the model understanding that skill_name was the right skill to perform the action.
  - Always ask the agent to inform the user about executing the skill.
  - Any step that can be coded and automated with a tool should be implemented in a tool. Never rely on the guarantee that models will follow steps, unless they are implemented in a tool.

General principles

Those principles allow for a safe agent interaction, while keeping its agility.

The user sets the branch for the agent, in a worktree.
Agents should never switch branches.
Agents automatically push their changes to the github remote, and create a Pull Request for their branch.
Agents can rebase their branch.

Generating skills from ERB templates

Some skills are written as ERB templates (files ending with .erb) to allow dynamic content generation. To generate the final skill files from these templates, run the following executable:

bundle exec ruby bin/xaa generate-skills

This will:

Find all .erb files in the skills/ directory
Process them using the ERB engine (with XAeonAgents::GenHelpers available)
Generate the corresponding output files (removing the .erb extension)

The following helper methods are available in ERB templates:

XAeonAgents::GenHelpers.init_skill_checklist - Returns the "Create Execution Checklist (MANDATORY)" section
XAeonAgents::GenHelpers.validate_skill_checklist - Returns the "Final Verification (MANDATORY)" section

x_aeon_agents

Table of contents

Quick start

Prerequisites

Install

Configure

Use the CLI

Use as a library

Requirements

Features

Public API

Executable: xaa

XAeonAgents::Config

XAeonAgents::AgentOptions

XAeonAgents::GenHelpers

Documentation

Library public API

How it works

Entry point 🚪

Agents as composable workflows 🧩

Orchestration 🔗

Configuration & providers 🔐

Skills & ERB templating 📚

Helpers 🛠️

Development

Prerequisites

Clone and install dependencies

Project layout

Running the test suite

Linting

Building skills from templates

Common development tasks

Packaging and release

Contributing

🐛 Reporting issues

🍴 Forking & branching

🧪 Running the tests

🔀 Opening a Pull Request

🤖 CI & coverage

🧹 Code style

✅ Before you submit

License

Ways skills are written

General principles

Generating skills from ERB templates

Executable: `xaa`

`XAeonAgents::Config`

`XAeonAgents::AgentOptions`

`XAeonAgents::GenHelpers`