Specs Commands

Overview

The Specs commands help you write and manage Gherkin feature files throughout the ACDD (Acceptance Criteria Driven Development) workflow. These commands provide the foundation for creating well-structured specifications that serve as living documentation and executable acceptance criteria.

Use specs commands when you need to:

• Create new feature files with proper Gherkin structure and templates
• Add, edit, or delete scenarios and steps in your feature files
• Add background stories (user stories) and architecture notes
• Validate Gherkin syntax using the official Cucumber parser
• Format feature files for consistency across your project
• List and show features with filtering by tags
• Perform bulk operations on features and scenarios

These commands integrate seamlessly with fspec's coverage tracking system, ensuring traceability between specifications, tests, and implementation code.

Commands Reference

GHERKIN SPECIFICATIONS

FEATURES

Create Feature

Creates a new Gherkin feature file with a well-structured template including Background section placeholders, example scenarios, and proper formatting. This is typically the first command you run when starting a new feature specification in the ACDD workflow.

The command automatically:

• Converts feature names to kebab-case for filenames (e.g., "User Authentication" → user-authentication.feature)
• Creates the spec/features/ directory if it doesn't exist
• Generates a corresponding .feature.coverage file for tracking test and implementation coverage
• Detects placeholder text like [role], [action], [benefit] and provides CLI commands to replace them properly

Usage:

fspec create-feature <name>      Create new feature file

Examples:

fspec create-feature "User Authentication"

List Features

Lists all Gherkin feature files in your project's spec/features/ directory. You can filter the results by tags to find features in a specific phase, component, or priority level. This command is useful for getting an overview of your specifications or finding specific features that match certain criteria.

Multiple --tag flags use AND logic, meaning the feature must have all specified tags to be included in the results. Output formats include table (default), JSON (for tooling integration), or simple list format.

Usage:

fspec list-features              List all feature files

Options:

• --tag=<tag> Filter by tag

Examples:

fspec list-features --tag=@critical

Show Feature

Displays the complete contents of a Gherkin feature file with syntax highlighting, making it easy to review specifications directly from the command line. This command is useful for quickly inspecting feature files without opening them in an editor, or for piping feature content to other tools.

You can specify output formats (text or JSON) and optionally write the output to a file instead of displaying it in the terminal.

Usage:

fspec show-feature <name>         Show feature details

Options:

• --format <format> Output: text or json
• --output <file> Write to file

Examples:

fspec show-feature user-authentication
fspec show-feature login --format=json

Delete Features By Tag

Bulk deletes feature files that match specified tags using AND logic (all tags must match). This command is essential for cleanup after major refactoring or phase completion, such as removing all deprecated, experimental, or spike features.

IMPORTANT: Always use --dry-run first to preview which files will be deleted before running the actual deletion. This prevents accidental data loss.

Usage:

fspec delete-features-by-tag      Delete features by tag

Options:

• --tag=<tag> Tag to match (required)
• --dry-run Preview without deleting

Examples:

fspec delete-features-by-tag --tag=@deprecated --dry-run

SCENARIOS

Add Scenario

Adds a new scenario to an existing feature file. The scenario is created with placeholder Given/When/Then steps that you can then populate using add-step. Scenarios are appended to the end of the feature file.

This command is typically used after creating a feature file and during the specifying phase of ACDD to add acceptance criteria.

Usage:

fspec add-scenario <feature> <title> Add scenario to feature

Examples:

fspec add-scenario login "Login with valid credentials"

Update Scenario

Renames a scenario within a feature file. The scenario name must match exactly (case-sensitive). This is useful when refining acceptance criteria or clarifying scenario intent during the specifying phase.

Usage:

fspec update-scenario <feature> <old> <new> Update scenario name

Examples:

fspec update-scenario login "Old Name" "New Name"

Delete Scenario

Removes a scenario from a feature file. The scenario name must match exactly (case-sensitive). You can use the --force flag to skip the confirmation prompt.

Usage:

fspec delete-scenario <feature> <title> Delete scenario

Examples:

fspec delete-scenario login "Deprecated scenario"

Get Scenarios

Extracts and displays scenarios from feature files with optional filtering by file or tags. This command is useful for querying scenarios across your specifications, generating reports, or integrating with external tools using JSON output.

Multiple --tag flags use AND logic for filtering.

Usage:

fspec get-scenarios               Query scenarios by tag

Options:

• --tag=<tag> Filter by tag (AND logic)
• --format=<format> Output: text or json

Examples:

fspec get-scenarios --tag=@critical --tag=@critical

Show Acceptance Criteria

Displays all scenarios (acceptance criteria) from a feature file in a readable format. This command provides a clear view of what needs to be implemented and validated for a feature, making it easy to review specifications without opening files in an editor.

Usage:

fspec show-acceptance-criteria    Show acceptance criteria

Options:

• --tag=<tag> Filter by tag
• --format=<format> Output: text, markdown, json
• --output=<file> Write to file

Examples:

fspec show-acceptance-criteria --tag=@critical --format=markdown

Delete Scenarios By Tag

Bulk deletes scenarios that match specified tags. This is useful for cleaning up deprecated or temporary scenarios across multiple feature files. Always use --dry-run first to preview which scenarios will be deleted.

Usage:

fspec delete-scenarios-by-tag     Delete scenarios by tag

Options:

• --tag=<tag> Tag to match
• --dry-run Preview without deleting

STEPS

Add Step

Adds a Gherkin step (Given/When/Then/And/But) to a scenario. Steps are the building blocks of scenarios, defining preconditions, actions, and expected outcomes. This command is used during the specifying phase to flesh out scenario details.

Usage:

fspec add-step <feature> <scenario> <keyword> <text>

Examples:

fspec add-step login "Valid login" given "I am on the login page"

Update Step

Modifies an existing step in a scenario by finding and replacing it. You can change the step text, the keyword (Given/When/Then/And/But), or both. The command validates that the current step text matches exactly before updating, ensuring you're modifying the correct step.

Usage:

fspec update-step <feature> <scenario> <old-text>

Options:

• --text <new-text> New step text
• --keyword <keyword> New keyword (Given/When/Then/And/But)

Examples:

fspec update-step login "Valid" "old step" --text "new step"

Delete Step

Removes a step from a scenario by its index position (0-based). Use --force to skip the confirmation prompt. This is useful when refining scenarios or removing unnecessary preconditions or assertions.

Usage:

fspec delete-step <feature> <scenario> <text>

Examples:

fspec delete-step login "Valid login" "I am on the login page"

CONTENT

Add Background

Adds or updates the Background section in a feature file, which typically contains the user story in the format "As a [role] I want to [action] So that [benefit]". The Background section provides context for all scenarios in the feature and appears after the Feature line but before any scenarios.

Usage:

fspec add-background <feature> <text> Add/update background story

Examples:

fspec add-background login "As a user\nI want to log in"

Add Architecture

Adds technical architecture notes to a feature file using Gherkin doc strings ("""). These notes document implementation details, technical constraints, dependencies, and architectural decisions. Architecture notes appear after the Feature line and help developers understand the technical context.

Usage:

fspec add-architecture <feature> <text> Add architecture notes

Examples:

fspec add-architecture login "Uses JWT tokens"

VALIDATION & FORMATTING

Validate

Validates Gherkin syntax in feature files using the official @cucumber/gherkin parser. This command checks that your feature files have correct syntax before committing and is an essential step in the ACDD workflow before moving from specifying to testing phase.

Run this command to catch syntax errors like incorrect indentation, missing keywords, or malformed steps. Use --verbose for detailed output including line numbers and helpful suggestions.

Usage:

fspec validate                   Validate Gherkin syntax

Options:

• --verbose Show detailed output

Examples:

fspec validate
fspec validate spec/features/login.feature

Format

Formats feature files using fspec's custom AST-based Gherkin formatter (NOT prettier-plugin-gherkin). This ensures consistent formatting across all feature files including proper indentation (2 spaces for scenarios, 4 for steps), spacing, and structure.

The formatter preserves doc strings ("""), data tables (|), and tag formatting. It's safe to run multiple times (idempotent) and should be run before committing feature files.

Usage:

fspec format                     Format feature files

Examples:

fspec format
fspec format spec/features/login.feature

Check

Runs all validation checks in one command: Gherkin syntax validation (validate), tag compliance (validate-tags), and formatting verification (format). This is the recommended command to run before committing or as part of CI/CD pipelines to ensure all specifications meet quality standards.

Exit code 0 means all checks passed, non-zero indicates failures that need to be fixed.

Usage:

fspec check                      Run all validation checks

Options:

• --verbose Show detailed output

Examples:

fspec check --verbose

Validate Tags

Validates that all tags used in feature files are properly registered in spec/tags.json and enforces tag placement rules. This command ensures work unit ID tags (like @AUTH-001) appear only at feature level, not scenario level, maintaining the two-tier linking system where coverage files handle scenario-to-implementation traceability.

Run before committing to catch unregistered tags and placement violations. Part of the check command.

Usage:

fspec validate-tags              Validate tag usage

Examples:

fspec validate-tags

Link Coverage

Links Gherkin scenarios to test files and implementation code, creating full traceability from specification to tests to code. This command is CRITICAL for ACDD workflow and should be used IMMEDIATELY after writing tests or implementation.

Use --test-file and --test-lines to link tests, then use --impl-file and --impl-lines to link implementation. The --skip-validation flag is useful for skeleton tests in reverse ACDD, and --skip-step-validation is for task work units that don't require test coverage.

Usage:

fspec link-coverage <feature> --scenario <name> Link tests/implementation

Options:

• --test-file <path> Test file path (e.g., src/tests/auth.test.ts)
• --test-lines <range> Test line range (e.g., "45-62")
• --impl-file <path> Implementation file path
• --impl-lines <lines> Implementation lines (e.g., "10,11,12,23")
• --skip-validation Skip file validation (reverse ACDD)
• --skip-step-validation Skip step validation (ONLY for task work units)

Examples:

fspec link-coverage user-auth --scenario "Login" --test-file src/__tests__/auth.test.ts --test-lines 45-62

Show Coverage

Displays a coverage report showing which scenarios have test and implementation coverage, and which have gaps. When called without arguments, shows project-wide coverage statistics. When given a feature name, shows detailed coverage for that feature including which files and line numbers are linked.

This command helps identify uncovered scenarios and track progress toward 100% scenario mapping.

Usage:

fspec show-coverage [feature]    Show coverage report (gaps)

Options:

• --format <format> Output: text or json
• --output <file> Write to file

Examples:

fspec show-coverage user-authentication
fspec show-coverage              # Project-wide

Audit Coverage

Verifies that all file paths referenced in coverage mappings actually exist on disk. This command is useful after refactoring when files may have moved or been deleted. Use --fix to automatically remove broken mappings from coverage files.

Usage:

fspec audit-coverage <feature>     Verify file paths exist

Options:

• --fix Remove broken mappings

Examples:

fspec audit-coverage user-authentication --fix

Unlink Coverage

Removes coverage mappings for a scenario, test file, or implementation file. Use --all to remove all mappings for a scenario, or specify --test-file or --impl-file to remove specific mappings. This is useful when tests or implementation files are refactored or deleted.

Usage:

fspec unlink-coverage <feature>    Remove coverage mappings

Options:

• --scenario <name> Scenario to unlink
• --test-file <path> Test file to remove
• --impl-file <path> Implementation to remove
• --all Remove all mappings

Examples:

fspec unlink-coverage user-auth --scenario "Login" --all

Generate Coverage

Generates or updates .feature.coverage files for existing feature files. Creates new coverage files for features that don't have them, or updates existing ones with missing scenarios. This command is essential for setting up coverage tracking on existing projects or when scenarios are added to features.

The command is safe to run anytime—it preserves existing test mappings and only adds missing scenario entries. Use --dry-run to preview what would be created or updated.

Usage:

fspec generate-coverage           Generate .coverage files for existing features

Options:

• --dry-run Preview without creating files

Examples:

fspec generate-coverage
fspec generate-coverage --dry-run

Add Tag To Feature

Adds one or more tags to a feature file at the feature level. Tags help organize and filter features by phase (@critical, @high), component (@cli, @api), or other categories. Use --validate-registry to ensure tags are registered in spec/tags.json before adding them.

Usage:

fspec add-tag-to-feature <file> <tag>

Options:

• --validate-registry Check tag exists in registry

Examples:

fspec add-tag-to-feature spec/features/login.feature @critical

Remove Tag From Feature

Removes one or more tags from a feature file. This is useful when removing work-in-progress tags (@wip) after completion, cleaning up deprecated tags, or correcting tagging mistakes.

Usage:

fspec remove-tag-from-feature <file> <tag>

Examples:

fspec remove-tag-from-feature spec/features/login.feature @wip

List Feature Tags

Lists all tags applied to a specific feature file. Use --show-categories to display each tag's category from the tag registry (spec/tags.json), which helps understand the organizational purpose of each tag.

Usage:

fspec list-feature-tags <file>

Options:

• --show-categories Show tag categories

Add Tag To Scenario

Adds one or more tags to a specific scenario within a feature file. Scenario-level tags are optional and used for fine-grained organization like @smoke, @edge-case, or @regression. The scenario name must match exactly (case-sensitive).

Note: Work unit ID tags (e.g., @AUTH-001) must be at feature level only, not scenario level.

Usage:

fspec add-tag-to-scenario <file> <scenario> <tag>

Examples:

fspec add-tag-to-scenario login.feature "Valid login" @smoke

Remove Tag From Scenario

Removes one or more tags from a specific scenario. This is useful for removing temporary tags like @wip after completing work, or cleaning up incorrect tags from individual scenarios.

Usage:

fspec remove-tag-from-scenario <file> <scenario> <tag>

List Scenario Tags

Lists all tags applied to a specific scenario. Use --show-categories to display each tag's category from the tag registry, helping you understand how the scenario is organized and filtered.

Usage:

fspec list-scenario-tags <file> <scenario>