Acceptance Pipeline Catalog

Robert C. Martin Acceptance Pipeline Best Practices

Language-neutral specification for a portable acceptance-test pipeline: Gherkin feature files to JSON IR to generated acceptance tests to mutation testing. Based on Robert C. Martin's Acceptance Pipeline Specification. Contains ~50 rules across 14 categories, prioritized by impact.

When to Apply

Reference these rules when:

• Building a Gherkin parser that outputs JSON IR
• Implementing an acceptance test generator from JSON IR
• Writing an acceptance runtime that expands scenarios and dispatches steps
• Implementing mutation testing for acceptance test example values
• Setting up the full pipeline (parser, generator, runner, mutator) in a new project
• Debugging pipeline failures (parse errors, generation issues, mutation classification)

Pipeline Overview

The pipeline has two modes:

Normal acceptance run:

feature file -> gherkin parser -> JSON IR -> acceptance generator -> generated tests -> test runner

Mutation run:

feature file -> gherkin parser -> base JSON IR -> mutator (one changed IR per mutation)
  -> generator (tests per mutation) -> test runner (evaluate each) -> mutation report

The normal run proves the project satisfies the feature. The mutation run probes whether tests are strong enough to fail when example data changes.

Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules | |----------|----------|--------|--------|-------| | 1 | Parser | CRITICAL | parser- | 9 | | 2 | JSON IR | CRITICAL | ir- | 4 | | 3 | Generator | CRITICAL | gen- | 2 | | 4 | Runtime | HIGH | rt- | 3 | | 5 | Step Handlers | HIGH | handler- | 4 | | 6 | Test Runner | HIGH | runner- | 2 | | 7 | Mutator Core | HIGH | mut- | 4 | | 8 | Value Mutation Rules | HIGH | val- | 10 | | 9 | Result Classification | HIGH | result- | 2 | | 10 | Conformance | HIGH | conform- | 1 | | 11 | Agent Setup | HIGH | setup- | 1 | | 12 | Mutation Execution | MEDIUM | exec- | 4 | | 13 | Reports | MEDIUM | report- | 3 | | 14 | Project Layout | MEDIUM | layout- | 3 |

Quick Reference

1. Parser (CRITICAL)

• [parser-command-interface](references/parser-command-interface.md) - Two positional args, exit codes 0/1/2
• [parser-feature-declaration](references/parser-feature-declaration.md) - Feature: keyword required, trimmed name
• [parser-background](references/parser-background.md) - Optional Background: section with Given/And steps
• [parser-scenarios](references/parser-scenarios.md) - Scenario: and Scenario Outline: both supported
• [parser-steps](references/parser-steps.md) - Given/When/Then/And keywords, keyword stored separately
• [parser-parameters](references/parser-parameters.md) - Angle-bracket placeholders, not expanded by parser
• [parser-examples-tables](references/parser-examples-tables.md) - Pipe-delimited tables, header row first
• [parser-general-rules](references/parser-general-rules.md) - Blank lines, comments, whitespace, ordering
• [parser-unsupported-syntax](references/parser-unsupported-syntax.md) - Tags, rules, localized keywords, doc strings

2. JSON IR (CRITICAL)

• [ir-feature-object](references/ir-feature-object.md) - name, scenarios, optional background
• [ir-scenario-object](references/ir-scenario-object.md) - name, steps, examples arrays
• [ir-step-object](references/ir-step-object.md) - keyword, text, optional parameters
• [ir-example-object](references/ir-example-object.md) - String-keyed, string-valued maps

3. Generator (CRITICAL)

• [gen-command-interface](references/gen-command-interface.md) - Two positional args, exit codes 0/1/2
• [gen-requirements](references/gen-requirements.md) - Embed IR, no Gherkin parsing, deterministic output

4. Runtime (HIGH)

• [rt-responsibilities](references/rt-responsibilities.md) - Load IR, expand, dispatch, report
• [rt-scenario-expansion](references/rt-scenario-expansion.md) - One execution per example row, background prepended
• [rt-execution-naming](references/rt-execution-naming.md) - Scenario name / example index naming convention

5. Step Handlers (HIGH)

• [handler-matching](references/handler-matching.md) - Match by exact text value, not keyword
• [handler-world-state](references/handler-world-state.md) - Fresh world/state per scenario execution
• [handler-value-handling](references/handler-value-handling.md) - Fetch, parse, fail on missing/malformed
• [handler-unsupported](references/handler-unsupported.md) - Unsupported step text must fail the test

6. Test Runner (HIGH)

• [runner-interface](references/runner-interface.md) - Input/output contract for the test runner adapter
• [runner-classification](references/runner-classification.md) - Three-way: failure, success, infrastructure error

7. Mutator Core (HIGH)

• [mut-command-interface](references/mut-command-interface.md) - CLI options, exit codes 0/1/2
• [mut-scope](references/mut-scope.md) - Only example cell values mutated
• [mut-identity](references/mut-identity.md) - Stable deterministic IDs, paths, descriptions
• [mut-deep-copy](references/mut-deep-copy.md) - Original IR never modified in place

8. Value Mutation Rules (HIGH)

• [val-rule-order](references/val-rule-order.md) - 8 rules applied in priority order
• [val-comma-list](references/val-comma-list.md) - Comma-delimited list mutation
• [val-boolean](references/val-boolean.md) - true/false toggle
• [val-null](references/val-null.md) - null/nil/none to dithered string
• [val-integer](references/val-integer.md) - Integer plus pseudo-random delta
• [val-float](references/val-float.md) - Float plus pseudo-random delta
• [val-datetime](references/val-datetime.md) - ISO-8601 date/time shift
• [val-duration](references/val-duration.md) - Duration shift preserving syntax
• [val-string-dither](references/val-string-dither.md) - Character-level string edits
• [val-determinism](references/val-determinism.md) - Pseudo-random, deterministic for fixed input

9. Result Classification (HIGH)

• [result-statuses](references/result-statuses.md) - killed, survived, error
• [result-classification-rules](references/result-classification-rules.md) - Mapping from test outcomes to statuses

10. Conformance (HIGH)

• [conform-checklist](references/conform-checklist.md) - All 21 validation items

11. Agent Setup (HIGH)

• [setup-checklist](references/setup-checklist.md) - 15-step installation guide

12. Mutation Execution (MEDIUM)

• [exec-work-directory](references/exec-work-directory.md) - Per-mutation directory structure
• [exec-workflow](references/exec-workflow.md) - Write IR, generate, run, classify
• [exec-parallelism](references/exec-parallelism.md) - Concurrent workers, isolated directories
• [exec-timeout](references/exec-timeout.md) - Full-run timeout, unfinished = error

13. Reports (MEDIUM)

• [report-text-format](references/report-text-format.md) - Summary line + per-result lines
• [report-json-format](references/report-json-format.md) - JSON object with summary and results array
• [report-field-requirements](references/report-field-requirements.md) - Required fields for summary and results

14. Project Layout (MEDIUM)

• [layout-required-paths](references/layout-required-paths.md) - features/, build/, acceptance/ directories
• [layout-commands](references/layout-commands.md) - gherkin-parser, acceptance-generator, gherkin-mutator
• [layout-scripts](references/layout-scripts.md) - Normal acceptance and mutation scripts

How to Use

Read individual reference files for detailed spec requirements and rationale:

• Start with the category relevant to the component you are building
• Each rule file is self-contained with WHY explanations, spec requirements, and examples
• For a new project setup, read [setup-checklist](references/setup-checklist.md) first
• For validation, use [conform-checklist](references/conform-checklist.md)
• Check [gotchas.md](gotchas.md) for known failure points

Reference Files

| File | Description | |------|-------------| | [metadata.json](metadata.json) | Version and reference information | | [gotchas.md](gotchas.md) | Known failure points (append-only) | | [references/](references/) | All rule files organized by prefix |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: pproenca
• Source: pproenca/dot-skills
• License: MIT

Install and usage instructions live in the source repository linked above.