Build documentation and agents file

.github/workflows/main.yml

@@ -1,27 +1,23 @@
-name: Ruby
+name: CI
 
 on:
   push:
-    branches:
-      - main
-
+    branches: [master]
   pull_request:
 
 jobs:
-  build:
+  test:
     runs-on: ubuntu-latest
     name: Ruby ${{ matrix.ruby }}
     strategy:
       matrix:
-        ruby:
-          - '3.1.1'
+        ruby: ["3.3", "3.4", "4.0"]
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Ruby
-      uses: ruby/setup-ruby@v1
-      with:
-        ruby-version: ${{ matrix.ruby }}
-        bundler-cache: true
-    - name: Run the default task
-      run: bundle exec rake
+      - uses: actions/checkout@v4
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+          bundler-cache: true
+      - run: bundle exec rspec
+      - run: bundle exec standardrb

.mise.toml

@@ -0,0 +1,2 @@
+[tools]
+ruby = "3.4.7"

.standard.yml

@@ -0,0 +1,3 @@
+ignore:
+  - "spec/**/*":
+    - Lint/ConstantDefinitionInBlock

AGENTS.md

@@ -0,0 +1,39 @@
+# AGENTS
+
+This file provides project-specific guidance for AI agents working in this repository.
+
+## Project Summary
+Storyteller is a small Ruby gem that provides a DSL for executing user stories through a staged lifecycle using `ActiveSupport::Callbacks` and `SmartInit`.
+
+## Repository Map
+- `lib/storyteller.rb`: Core DSL and lifecycle logic (`Storyteller::Story`).
+- `lib/storyteller/logger.rb`: Custom logger (silent mode warnings).
+- `lib/storyteller/version.rb`: Version constant.
+- `spec/storyteller_spec.rb`: Main RSpec coverage.
+- `bin/setup`: Dependency installation.
+- `bin/console`: Interactive console.
+- `docs/`: Public documentation (site content).
+
+## Commands
+- Setup: `bin/setup`
+- Tests: `bundle exec rake spec`
+- Lint: `bundle exec rubocop`
+- Default (tests + lint): `bundle exec rake`
+
+## Development Conventions
+- Keep the lifecycle order intact: init → preparation → validation → run → verification → after_run.
+- A story must define at least one `step`; validation should fail otherwise.
+- Respect `silent_story: true` by skipping `after_run` callbacks and logging a warning.
+- Prefer adding or updating tests in `spec/storyteller_spec.rb` when changing behavior.
+- Update `CHANGELOG.md` for user-visible behavior changes.
+
+## When Editing
+- Prefer minimal, focused changes that preserve the DSL surface.
+- Avoid breaking compatibility with existing callback names (`requisite`, `validate`, `verify`, `done_criteria`).
+
+## Release Notes
+- Version lives in `lib/storyteller/version.rb`.
+- Releases are handled by `bundle exec rake release`.
+
+## If Unsure
+- Read `README.md` and `docs/DEVELOPERS.md` before making structural changes.

Gemfile

@@ -1,16 +1,16 @@
 # frozen_string_literal: true
 
-source 'https://rubygems.org'
+source "https://rubygems.org"
 
 # Specify your gem's dependencies in storyteller.gemspec
 gemspec
 
-gem 'rake', '~> 13.0'
+gem "rake", "~> 13.0"
 
 group :development, :test do
-  gem 'bump'
-  gem 'rubocop-rake'
-  gem 'rubocop-rspec'
-  gem 'rspec', '~> 3.2'
-  gem 'rubocop', '~> 1.21'
+  gem "benchmark"
+  gem "bump"
+  gem "racc"
+  gem "rspec", "~> 3.2"
+  gem "standard", ">= 1.35.1"
 end

Gemfile.lock

@@ -3,78 +3,119 @@ PATH
   specs:
     storyteller (0.4.4)
       activesupport
+      ostruct
       smart_init
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (7.0.4.3)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
+    activesupport (8.1.3)
+      base64
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
       i18n (>= 1.6, < 2)
+      json
+      logger (>= 1.4.2)
       minitest (>= 5.1)
-      tzinfo (~> 2.0)
-    ast (2.4.2)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    ast (2.4.3)
+    base64 (0.3.0)
+    benchmark (0.5.0)
+    bigdecimal (4.1.0)
     bump (0.10.0)
-    concurrent-ruby (1.2.2)
-    diff-lcs (1.5.0)
-    i18n (1.12.0)
+    concurrent-ruby (1.3.6)
+    connection_pool (3.0.2)
+    diff-lcs (1.6.2)
+    drb (2.2.3)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    json (2.6.2)
-    minitest (5.18.0)
-    parallel (1.22.1)
-    parser (3.1.2.0)
+    json (2.19.3)
+    language_server-protocol (3.17.0.5)
+    lint_roller (1.1.0)
+    logger (1.7.0)
+    minitest (6.0.2)
+      drb (~> 2.0)
+      prism (~> 1.5)
+    ostruct (0.6.3)
+    parallel (1.27.0)
+    parser (3.3.11.1)
       ast (~> 2.4.1)
+      racc
+    prism (1.9.0)
+    racc (1.8.1)
     rainbow (3.1.1)
-    rake (13.0.6)
-    regexp_parser (2.5.0)
-    rexml (3.2.5)
-    rspec (3.11.0)
-      rspec-core (~> 3.11.0)
-      rspec-expectations (~> 3.11.0)
-      rspec-mocks (~> 3.11.0)
-    rspec-core (3.11.0)
-      rspec-support (~> 3.11.0)
-    rspec-expectations (3.11.0)
+    rake (13.3.1)
+    regexp_parser (2.11.3)
+    rspec (3.13.2)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.6)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.5)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-mocks (3.11.1)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.8)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.11.0)
-    rspec-support (3.11.0)
-    rubocop (1.32.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.7)
+    rubocop (1.84.2)
       json (~> 2.3)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.1.0)
       parallel (~> 1.10)
-      parser (>= 3.1.0.0)
+      parser (>= 3.3.0.2)
       rainbow (>= 2.2.2, < 4.0)
-      regexp_parser (>= 1.8, < 3.0)
-      rexml (>= 3.2.5, < 4.0)
-      rubocop-ast (>= 1.19.1, < 2.0)
+      regexp_parser (>= 2.9.3, < 3.0)
+      rubocop-ast (>= 1.49.0, < 2.0)
       ruby-progressbar (~> 1.7)
-      unicode-display_width (>= 1.4.0, < 3.0)
-    rubocop-ast (1.19.1)
-      parser (>= 3.1.1.0)
-    rubocop-rake (0.6.0)
-      rubocop (~> 1.0)
-    rubocop-rspec (2.12.1)
-      rubocop (~> 1.31)
-    ruby-progressbar (1.11.0)
-    smart_init (5.0.2)
+      unicode-display_width (>= 2.4.0, < 4.0)
+    rubocop-ast (1.49.1)
+      parser (>= 3.3.7.2)
+      prism (~> 1.7)
+    rubocop-performance (1.26.1)
+      lint_roller (~> 1.1)
+      rubocop (>= 1.75.0, < 2.0)
+      rubocop-ast (>= 1.47.1, < 2.0)
+    ruby-progressbar (1.13.0)
+    securerandom (0.4.1)
+    smart_init (5.1.0)
+    standard (1.54.0)
+      language_server-protocol (~> 3.17.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.84.0)
+      standard-custom (~> 1.0.0)
+      standard-performance (~> 1.8)
+    standard-custom (1.0.2)
+      lint_roller (~> 1.0)
+      rubocop (~> 1.50)
+    standard-performance (1.9.0)
+      lint_roller (~> 1.1)
+      rubocop-performance (~> 1.26.0)
     tzinfo (2.0.6)
       concurrent-ruby (~> 1.0)
-    unicode-display_width (2.2.0)
+    unicode-display_width (3.2.0)
+      unicode-emoji (~> 4.1)
+    unicode-emoji (4.2.0)
+    uri (1.1.1)
 
 PLATFORMS
   arm64-darwin-21
+  arm64-darwin-24
   x86_64-linux
 
 DEPENDENCIES
+  benchmark
   bump
+  racc
   rake (~> 13.0)
   rspec (~> 3.2)
-  rubocop (~> 1.21)
-  rubocop-rake
-  rubocop-rspec
+  standard (>= 1.35.1)
   storyteller!
 
 BUNDLED WITH
-   2.3.17
+  4.0.6

README.md

@@ -182,6 +182,8 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 You can learn more about the making process by visiting [AvispaTech's development blog on the subject](https://blog.avispa.tech/2022/08/01/storyteller-1.html).
 
+See `docs/DEVELOPERS.md` for a focused developer guide.
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/avispatech/storyteller. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/storyteller/blob/main/CODE_OF_CONDUCT.md).

bin/ci

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -e
+
+RUBIES=("3.3.11" "3.4.7" "4.0.1")
+PASS=()
+FAIL=()
+
+for version in "${RUBIES[@]}"; do
+  echo ""
+  echo "========================================"
+  echo "Ruby $version"
+  echo "========================================"
+
+  if mise exec ruby@$version -- bundle install --quiet 2>&1 && \
+     mise exec ruby@$version -- bundle exec rspec && \
+     mise exec ruby@$version -- bundle exec standardrb; then
+    PASS+=("$version")
+  else
+    FAIL+=("$version")
+  fi
+done
+
+echo ""
+echo "========================================"
+echo "Results"
+echo "========================================"
+for v in "${PASS[@]}"; do echo "  PASS  Ruby $v"; done
+for v in "${FAIL[@]}"; do echo "  FAIL  Ruby $v"; done
+
+[ ${#FAIL[@]} -eq 0 ]