code_work_spawner/.agents/skills/dart-gherkin-tests/SKILL.md

name	description
dart-gherkin-tests	Use when creating or editing Dart tests in this repo. Enforces the repository's required Gherkin-style doc comments for `group(...)` and `test(...)`, plus inline Given/When/Then comments inside test bodies.

Dart Gherkin Tests

Use this skill for any new or modified file under test/.

Required format

Every group(...) must be preceded by a Gherkin doc block:

/// ```gherkin
/// Feature: AppConfig loading
///
///   As a user of the Code Work Spawner
///   I want the app configuration to correctly merge defaults with project-specific overrides
///   So that I can specify common settings once and customize only what differs for each project
/// ```
group('AppConfig.load', () {

Every test(...) must be preceded by a Gherkin doc block:

  /// ```gherkin
  /// Scenario: Merge defaults with project overrides
  ///   Given AO style config with shared defaults and one project override
  ///   When loading the app config from disk
  ///   Then the project keeps inherited defaults that were not overridden
  ///   And the project-specific prompt replaces the shared prompt
  /// ```
  test('Merge defaults with project overrides', () async {

Inside the test body, use inline phase comments:

    // Given AO style config with shared defaults and one project override.
    ...

    // When loading the app config from disk.
    ...

    // Then the project keeps inherited defaults that were not overridden.
    ...

    // And the project-specific prompt replaces the shared prompt.
    ...

Rules

• Do add Feature: and Scenario: only in doc comments.
• Do keep runtime group(...) names code-oriented.
• Do keep runtime test(...) names as the scenario title only.
• Do use inline // Given, // When, and // Then comments in every test body.
• Do use // And when a scenario has multiple assertions or setup steps.
• Do not put Feature: in the group(...) string.
• Do not put Scenario: in the test(...) string.
• Do not add tests under test/ without the required Gherkin doc-comment blocks.

Checklist

Before finishing test work in this repo:

1. Confirm every group(...) has a Feature doc block directly above it.
2. Confirm every test(...) has a Scenario doc block directly above it.
3. Confirm every test body has Given, When, and Then inline comments.
4. Run dart run tool/validate_gherkin_test_format.dart.