If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/cucumber/cucumber-ruby shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 2d ago
• 13 active contributors
• MIT licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 53% of recent commits

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live cucumber/cucumber-ruby repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/cucumber/cucumber-ruby.

What it runs against: a local clone of cucumber/cucumber-ruby — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in cucumber/cucumber-ruby | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 32 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of cucumber/cucumber-ruby. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/cucumber/cucumber-ruby.git
#   cd cucumber-ruby
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of cucumber/cucumber-ruby and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "cucumber/cucumber-ruby(\\.git)?\\b" \\
  && ok "origin remote is cucumber/cucumber-ruby" \\
  || miss "origin remote is not cucumber/cucumber-ruby (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "bin/cucumber" \\
  && ok "bin/cucumber" \\
  || miss "missing critical file: bin/cucumber"
test -f "cucumber.gemspec" \\
  && ok "cucumber.gemspec" \\
  || miss "missing critical file: cucumber.gemspec"
test -f "lib/cucumber/cli/main.rb" \\
  && ok "lib/cucumber/cli/main.rb" \\
  || miss "missing critical file: lib/cucumber/cli/main.rb"
test -f "lib/cucumber/runtime.rb" \\
  && ok "lib/cucumber/runtime.rb" \\
  || miss "missing critical file: lib/cucumber/runtime.rb"
test -f "lib/cucumber/formatter/base_formatter.rb" \\
  && ok "lib/cucumber/formatter/base_formatter.rb" \\
  || miss "missing critical file: lib/cucumber/formatter/base_formatter.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 32 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/cucumber/cucumber-ruby"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Cucumber for Ruby is a behavior-driven development (BDD) testing framework that executes plain-English feature specifications (written in Gherkin syntax) against Ruby code. It bridges business requirements and automated tests by allowing non-technical stakeholders to read and write test scenarios in features/*.feature files, which are parsed and executed against Ruby step definitions. This is the official Ruby implementation maintained by the Cucumber organization. Monolithic gem structure: bin/cucumber is the CLI entry point; core parsing and execution logic resides in lib/ (not detailed in file list but standard for Ruby gems). compatibility/features/ contains CCK (Cucumber Compatibility Kit) tests covering scenarios like backgrounds, data tables, doc-strings, and hooks. GitHub Actions define test matrix and release pipeline. Rakefile orchestrates builds; .rubocop.yml enforces style.

Ruby developers and QA engineers building acceptance tests, particularly on Rails projects (via cucumber-rails companion gem). Teams practicing BDD who want executable specifications that serve as living documentation. Anyone needing to validate behavior in a way that's readable to product managers, business analysts, and developers alike.

Highly mature and production-ready. The project is actively maintained with recent commits, comprehensive CI/CD via GitHub Actions (test-ruby.yaml, release workflows), and supports modern Ruby versions (3.2–4.0, TruffleRuby, JRuby). Large OSS project with significant community backing (OpenCollective sponsors), Code Climate monitoring, and coveralls integration. This is the de facto standard BDD framework for Ruby.

Standard open source risks apply.

Active maintenance with recent renovate.json (dependency updates), zizmor-analysis.yaml (security scanning), and release workflows for both GitHub and RubyGems. The project is tracking Ruby 4.0 support and maintaining JRuby compatibility. Typical onboarding cadence for junior developers evidenced by CONTRIBUTING.md and issue templates.

git clone https://github.com/cucumber/cucumber-ruby.git
cd cucumber-ruby
bundle install
bundle exec rake test

Or install the gem: gem install cucumber, then initialize a new project with bundle exec cucumber --init (creates features/ directory structure).

Daily commands: Run existing features: bundle exec cucumber features/ or bundle exec cucumber (default). Run with options: bundle exec cucumber features/feature_file.feature:line_number for specific scenarios. Run RSpec tests: bundle exec rspec. Run all tests: bundle exec rake test (Rakefile likely defines this). Use --help for CLI options.

• bin/cucumber — Entry point executable that initializes and runs the Cucumber CLI—all test execution flows through here.
• cucumber.gemspec — Gem specification defining dependencies, version, and package metadata—critical for understanding project scope and external integrations.
• lib/cucumber/cli/main.rb — Core CLI argument parser and orchestrator that coordinates feature file discovery, parsing, and test execution.
• lib/cucumber/runtime.rb — Central runtime engine that manages step definitions, hooks, and the execution lifecycle of scenarios and features.
• lib/cucumber/formatter/base_formatter.rb — Abstract formatter base class that all output formatters (JSON, HTML, pretty-print) inherit from—defines the reporting pipeline.
• lib/cucumber/step_definition.rb — Represents a single step definition and manages regex matching, parameter capture, and step invocation.
• Rakefile — Build and test automation configuration—defines how the project is compiled, tested, and released.

• CLI Main (bin/cucumber, lib/cucumber/cli/main.rb) (OptionParser, Ruby stdlib) — Parses command-line arguments, builds configuration, instantiates runtime, and orchestrates test execution.
  • Failure mode: Invalid arguments or missing feature files cause early exit with error message; bad config prevents runtime startup.
• Runtime Engine (lib/cucumber/runtime.rb) (Ruby, Gherkin parser) — Central coordinator managing the feature-to-step execution pipeline: loads features, hooks, and steps; invokes matchers and formatters.
  • Failure mode: Step failures halt scenario execution; hook failures trigger

Add a new step definition

1. Create a .rb file in features/step_definitions/ (e.g., features/step_definitions/user_steps.rb) (features/step_definitions/example_steps.rb)
2. Use Given, When, Then helpers from lib/cucumber/dsl.rb to define step patterns with regex and/or parameter types (lib/cucumber/dsl.rb)
3. The runtime automatically discovers and registers steps via lib/cucumber/step_definition.rb at test startup (lib/cucumber/runtime.rb)

Add a new formatter/reporter

1. Create a new class in lib/cucumber/formatter/ that inherits from lib/cucumber/formatter/base_formatter.rb (lib/cucumber/formatter/base_formatter.rb)
2. Implement event handler methods (before_feature, before_scenario, after_step, etc.) to capture test events (lib/cucumber/formatter/pretty.rb)
3. Register the formatter in lib/cucumber/cli/main.rb or via the --format command-line option (lib/cucumber/cli/main.rb)

Add a new command-line option

1. Define the option in lib/cucumber/cli/options.rb using the OptionParser DSL (lib/cucumber/cli/options.rb)
2. Pass the parsed option to lib/cucumber/configuration.rb to store in runtime config (lib/cucumber/configuration.rb)
3. Access the option in lib/cucumber/runtime.rb or formatters via the configuration object (lib/cucumber/runtime.rb)

Add a new hook (Before/After/Around)

1. In a step_definitions or support file, use Before, After, or Around helpers from lib/cucumber/dsl.rb (lib/cucumber/dsl.rb)
2. Hooks are registered and stored in lib/cucumber/hooks.rb; runtime invokes them at scenario boundaries (lib/cucumber/hooks.rb)
3. Access scenario context and world instance via the block parameter passed to hook blocks (lib/cucumber/runtime.rb)

• Gherkin (domain-specific language) — Enables non-technical stakeholders to read and write test cases in plain English (Given-When-Then), improving communication and collaboration.
• Ruby & RSpec — Ruby's DSL capabilities and flexible syntax allow Cucumber to provide elegant step definition and hook APIs; RSpec integration ensures compatibility with Ruby test ecosystems.
• Regex-based step matching — Allows flexible, expressive pattern matching of natural-language steps to code, supporting parameterization and reusable step definitions.
• Pluggable formatter architecture — Enables multiple output formats (JSON, HTML, pretty-print) without coupling to a single reporter, supporting diverse CI/CD and reporting needs.

• Regex-based step matching vs. structured DSL

  • Why: Regex allows maximum flexibility and readability in plain language steps, but can lead to ambiguous or overlapping patterns.
  • Consequence: Developers must carefully design step patterns; Cucumber provides warnings/errors for ambiguity, but disambiguation is manual.

• Ruby-only implementation (not polyglot like Java Cucumber)

  • Why: Deep integration with Ruby idioms, RSpec, and Rails ecosystems; faster iteration for Ruby projects.
  • Consequence: Non-Ruby projects must use different Cucumber implementations (Cucumber.js, Cucumber-JVM); no shared codebase across languages.

• Runtime step discovery (dynamic loading) vs. compile-time generation

  • Why: Supports dynamic step definition files and hot-reloading in development; simpler API.
  • Consequence: Slightly higher runtime overhead and potential late discovery of missing steps; requires careful file organization.

• Does not provide a web UI or IDE—it is a command-line test runner
• Does not enforce test data management or database setup—that is delegated to hooks and step implementations
• Does not parallelize test execution at the core level—requires external orchestration or plugins
• Does not handle authentication or security policy—test scenarios are user-provided and unconstrained
• Does not provide cross-language compatibility—Ruby-only implementation

Gherkin syntax sensitivity: feature files must follow exact Gherkin dialect (Feature:, Scenario:, Given/When/Then). Step matching: step definitions use regex patterns that must be precise or they won't match Gherkin steps—off-by-one regex errors are hard to debug. World/context: the World object persists between steps within a scenario but resets between scenarios; shared state bugs are common. JRuby limitations: documented in docs/jruby-limitations.md—some Ruby standard lib features unavailable. Ruby version constraints: project targets 3.2+, so older Ruby syntax or gems won't work. Dependency hell: as a testing framework, it may conflict with other gems in complex Gemfiles; run bundle update carefully. Relative path loading: feature file references to step definitions or support files can break if working directory differs; use absolute paths or careful relative loading.

• Gherkin Syntax & Parsing — Gherkin is the domain-specific language (DSL) for writing executable specifications in Cucumber; understanding its grammar (Feature, Scenario, Given/When/Then, Examples tables, Backgrounds) is fundamental to writing and debugging tests
• Behavior-Driven Development (BDD) — BDD is the methodology Cucumber enforces—tests are written in plain language to bridge communication gaps between developers and non-technical stakeholders; it's the 'why' behind this framework
• Step Definition Regex Matching — Steps in Gherkin are matched to Ruby step definitions via regular expressions; mastering regex capture groups and lookahead/lookbehind is essential for writing robust, reusable step definitions
• World Object & Hooks Lifecycle — The World is a Ruby object that holds test state between steps in a scenario; Before/After hooks control setup/teardown; understanding this lifecycle prevents shared-state bugs and resource leaks
• Scenario Outlines & Example Tables — Scenario Outlines with Examples tables allow parameterized tests; this feature reduces boilerplate for testing multiple inputs and is visible throughout compatibility/features/examples-tables* scenarios
• Test Isolation & Tagging — Cucumber supports @tags on scenarios to enable selective execution, categorization, and test isolation; critical for CI/CD pipelines and for running subsets of tests locally
• Cucumber Compatibility Kit (CCK) — The compatibility/features/ directory contains CCK tests that ensure Ruby Cucumber behaves identically to other language implementations; understanding CCK helps you identify cross-platform bugs and contribute to feature parity

• cucumber/cucumber-jvm — Java implementation of Cucumber; if you need to understand how BDD frameworks work across ecosystems, this is the reference
• cucumber/cucumber-js — JavaScript/Node.js implementation; shows how Cucumber's core concepts (Gherkin parsing, step matching) translate to other runtimes
• cucumber/gherkin-ruby — Ruby gem that parses Gherkin syntax into AST; cucumber-ruby depends on this for parsing feature files
• rails/rails — The most common environment for cucumber-ruby; Rails users typically use cucumber-rails companion gem to integrate with this framework
• cucumber/cucumber-rails — Companion gem that bridges Cucumber and Ruby on Rails; essential for Rails projects using this framework

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive test coverage for compatibility/cck_spec.rb

The compatibility directory contains extensive CCK (Cucumber Compatibility Kit) test scenarios across 20+ feature sets (hooks, data-tables, attachments, examples-tables, etc.) but cck_spec.rb appears to be the main test harness. Adding detailed unit tests for the CCK test runner itself, test result validation, and cross-feature compatibility assertions would improve maintainability and catch regressions early. This is critical for a tool that defines the standard for Cucumber implementations.

• [ ] Create spec/compatibility/cck_spec_test.rb with tests for cck_spec.rb parsing and execution
• [ ] Add tests validating each compatibility feature folder (ambiguous, backgrounds, data-tables, hooks, etc.) executes correctly
• [ ] Add regression tests ensuring CCK results match expected outputs for known scenarios
• [ ] Document the CCK test structure in CONTRIBUTING.md

Refactor and add tests for bin/cucumber CLI argument parsing

The bin/cucumber executable is the primary entry point but likely lacks comprehensive unit tests for argument handling, option validation, and edge cases. Given the critical nature of CLI tools and the presence of multiple workflows testing different scenarios, creating a dedicated spec file with focused CLI tests would catch bugs, improve developer experience for contributors, and document expected behavior.

• [ ] Create spec/cli/argument_parser_spec.rb with tests for common CLI flags and options
• [ ] Add tests for invalid argument combinations and error messaging
• [ ] Test integration with .cucumberproignore file parsing
• [ ] Add tests for profile loading and configuration precedence

Add comprehensive tests for GitHub workflow configurations and renovate.json validation

The repo has multiple GitHub workflows (test-ruby.yaml, release-ruby.yaml, codeql-ruby.yaml, zizmor-analysis.yaml) and a renovate.json config, but there's no validation that these workflows reference valid Ruby versions, have proper syntax, or that renovate rules won't cause dependency conflicts. Adding a CI step to validate workflow YAML syntax and renovate configuration consistency would prevent configuration drift and CI failures.

• [ ] Add GitHub Action or Rake task to validate all .github/workflows/*.yaml files for proper YAML syntax and required fields
• [ ] Add validation for renovate.json against Renovate's schema
• [ ] Verify all referenced Ruby versions in workflows match VERSION file and are actively supported
• [ ] Document workflow expectations in .github/CONTRIBUTING.md or RELEASING.md

• Add missing step definitions for currently untested feature scenarios in compatibility/features/ (e.g., edge cases in global-hooks-* scenarios) to increase CCK coverage across Ruby dialect
• Document or add examples for the World object lifecycle and best practices in a features/support/WORLD.md or equivalent guide (evidence: CONTRIBUTING.md exists but no World docs visible)
• Extend the compatibility test suite to cover Ruby 4.0-specific features or TruffleRuby edge cases by adding scenarios to compatibility/features/ matching patterns seen in examples-tables-attachment or data-tables

The codebase appears to be a well-structured open-source Ruby project with standard security practices (GitHub Actions workflows, static analysis tools like RuboCop, Renovate for dependency management). No critical security vulnerabilities were identified in the provided file structure. However, the security analysis is limited by the absence of actual dependency lists and workflow/configuration file contents. The project should conduct regular dependency audits using 'bundle audit' and ensure GitHub Actions workflows follow security best practices. No evidence of hardcoded secrets, SQL injection patterns, or XSS vulnerabilities was found in the file structure alone.

• Low · Missing dependency information for vulnerability analysis — Gemfile / *.gemspec (not provided). The dependency/package file content was not provided in the security context. This prevents a thorough analysis of known vulnerabilities in dependencies (Gemfile, gemspec, etc.). Fix: Provide the Gemfile and gemspec files for dependency vulnerability scanning. Run 'bundle audit' or 'bundler-audit' to check for known CVEs in dependencies.
• Low · GitHub Actions workflow review needed — .github/workflows/. Multiple GitHub Actions workflows are present (.github/workflows/) but their content was not provided for analysis. Workflows can contain security issues such as insecure secret handling, privilege escalation, or injection vulnerabilities. Fix: Review all workflow files for: (1) Use of 'secrets' with proper scoping, (2) Avoid using 'pull_request_target' without caution, (3) Pin action versions, (4) Restrict permissions with 'permissions' blocks, (5) Validate user inputs in scripts.
• Low · Renovate configuration present — .github/renovate.json. A Renovate configuration file is present (.github/renovate.json) for dependency management. While beneficial, the configuration content should be reviewed to ensure secure update policies. Fix: Verify that: (1) Auto-merge is not enabled for untested dependencies, (2) Major version updates require approval, (3) Security patches are prioritized.
• Low · Test framework feature files not reviewed — compatibility/features/. The codebase contains extensive test fixtures in the 'compatibility' directory with step definitions. These are typically safe but should be reviewed for test data leakage or exposure of sensitive information. Fix: Ensure no real credentials, API keys, or sensitive data are hardcoded in test fixtures. Use environment variables or fixtures with placeholder data.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.