Commands
Configuration & Setup

Setup Commands

Overview

The Setup commands handle project initialization, configuration, and structural management for fspec-based projects. These commands set up the foundation for ACDD workflows, configure integrations with AI coding agents, and manage organizational structures like tags, epics, and prefixes.

Use setup commands when you need to:

  • Initialize fspec in a new project with support for 18+ AI coding agents
  • Switch between different AI agents or remove agent-specific files
  • Configure test commands and quality check scripts for your project
  • Register tags in the centralized registry for consistent usage
  • Update or delete tags across all feature files in bulk
  • Perform retag operations to rename tags project-wide
  • Create and manage epics (high-level business initiatives)
  • Create and manage prefixes (namespaces for work unit IDs like AUTH, API, UI)
  • Add and validate Mermaid architecture diagrams
  • Update project foundation documentation programmatically
  • Manage feature-level and scenario-level tag assignments
  • Validate tag usage and compliance across the entire project

These commands ensure that your project has a solid foundation and organizational structure, making it easy for teams and AI agents to collaborate effectively.

Commands Reference

CONFIGURATION & SETUP

INITIALIZATION

Init

Initializes fspec in a project with AI agent integration supporting 18 different coding agents. This command creates agent-specific slash commands, workflow documentation, and configuration files tailored to your chosen AI assistant.

The command provides an interactive menu to select agents or accepts a direct --agent flag. It's intelligent about version management, auto-updating files when fspec versions change, and detecting existing installations to help you switch between agents smoothly.

Usage:

fspec init [options]

Description: Initialize fspec for AI coding agents

Options:

  • --agent <agent> Specify agent directly (18 agents supported)
  • --yes Skip confirmation prompts

Examples:

fspec init
fspec init --agent=claude
fspec init --agent=cursor

Remove Init Files

Removes fspec initialization files for installed agents by auto-detecting which agent is currently configured and cleaning up its specific files. This command is useful when uninstalling fspec or preparing to switch to a different AI agent.

The command removes agent-specific files like spec/<AGENT>.md and slash command files, plus the spec/fspec-config.json, but preserves your project files like features and work units. It's idempotent and safe to run multiple times.

Usage:

fspec remove-init-files

Description: Remove fspec initialization files for installed agents

Examples:

fspec remove-init-files

Configure Tools

Configures test and quality check commands for platform-agnostic ACDD workflow. fspec doesn't hardcode tool commands—you must configure them for your specific platform (Node.js, Python, Rust, Go, etc.). This configuration is required for the validating phase to work.

Use --test-command to specify your test runner (npm test, pytest, cargo test, go test) and --quality-commands for linting/formatting tools. The configuration persists in spec/fspec-config.json and is used automatically during workflow transitions. Use --reconfigure to update existing configuration with auto-detection.

Usage:

fspec configure-tools

Description: Configure test and quality check commands

Options:

  • --test-command <cmd> Test command to run
  • --quality-commands <cmd...> Quality check commands
  • --reconfigure Reconfigure existing setup

Examples:

fspec configure-tools --test-command "npm test"
fspec configure-tools --test-command "npm test" --quality-commands "npm run lint" "npm run format"
fspec configure-tools --reconfigure

TAG REGISTRY

Update Tag

Updates a registered tag's description or category in spec/tags.json. This command helps maintain your tag registry as your project evolves and tag meanings become more refined or categories need reorganization.

Use --description to change the tag's explanatory text or --category to move it to a different organizational grouping. After updating tags, consider regenerating TAGS.md with generate-tags-md to keep documentation in sync.

Usage:

fspec update-tag <tag>

Options:

  • --description <desc> New description
  • --category <category> New category

Examples:

fspec update-tag @performance --description="New description"

Delete Tag

Deletes a tag from the centralized tag registry (spec/tags.json). The tag must not be in use in any feature files before deletion. Use --dry-run to preview the deletion and --force to skip confirmation prompts.

After deleting tags, run validate-tags to verify that no feature files still reference the deleted tag, ensuring your project maintains tag consistency.

Usage:

fspec delete-tag <tag>

Options:

  • --force Delete even if used
  • --dry-run Preview deletion

Examples:

fspec delete-tag @deprecated --dry-run

List Tags

Lists all registered tags from spec/tags.json, displaying them grouped by category with their descriptions. Use --category to filter tags to a specific grouping like "Phase Tags" or "Component Tags".

This command helps you browse available tags when adding them to features, understand what tags mean, and see how your project organizes its tagging system.

Usage:

fspec list-tags

Options:

  • --category <category> Filter by category

Examples:

fspec list-tags --category="Technical Tags"

Tag Stats

Displays statistics about tag usage across your feature files, showing how many features and scenarios use each registered tag. This helps identify unused or underused tags, understand tagging patterns, and maintain tag hygiene.

The command only counts tags actually used in .feature files, making it useful for finding tags that were registered but never applied.

Usage:

fspec tag-stats

Description: Show tag usage statistics

Examples:

fspec tag-stats

Retag

Replaces one tag with another across all feature files in a single operation. Both the old and new tags must be registered in spec/tags.json before running this command. Use --dry-run to preview which files and scenarios will be affected before committing to the change.

This command is perfect for tag migrations when you want to rename tags, consolidate similar tags, or standardize naming conventions project-wide. It updates both feature-level and scenario-level tags.

Usage:

fspec retag

Options:

  • --from=<tag> Old tag
  • --to=<tag> New tag
  • --dry-run Preview changes

Examples:

fspec retag --from=@old-tag --to=@new-tag --dry-run

EPICS & PREFIXES

Create Epic

Creates a new epic for organizing related work units into high-level business initiatives. Epics help group stories, bugs, and tasks that contribute to a common goal or feature area.

Epic IDs must be in lowercase-with-hyphens format (e.g., user-management) and are stored in spec/work-units.json. When creating work units, you can associate them with an epic using the -e or --epic flag.

Usage:

fspec create-epic <name> <title>

Examples:

fspec create-epic user-management "User Management Features"

List Epics

Lists all epics defined in your project, displaying their IDs and titles. This provides a quick overview of your high-level business initiatives and helps you choose which epic to associate with new work units.

Use this command to browse existing epics before creating new stories, bugs, or tasks that need to be grouped under a business initiative.

Usage:

fspec list-epics

Examples:

fspec list-epics

Show Epic

Displays detailed information about an epic including its title, description, and all associated work units. This command helps you understand the scope of a business initiative and see which stories, bugs, and tasks contribute to it.

The output lists all work units linked to the epic with their IDs and titles, making it easy to track progress on large features.

Usage:

fspec show-epic <name>

Examples:

fspec show-epic user-management

Delete Epic

Deletes an epic from the project. Important: This command does NOT delete work units associated with the epic—it only removes the epic itself and clears epic associations from work units. Use --force to skip the confirmation prompt.

This is useful for cleaning up completed initiatives or removing epics that are no longer relevant to your project organization.

Usage:

fspec delete-epic <name>

Examples:

fspec delete-epic old-epic

Create Prefix

Registers a new work unit prefix for organizing work by component or functional area. Prefixes are short uppercase codes (like AUTH, UI, API) that namespace work unit IDs (e.g., AUTH-001, AUTH-002). You must register a prefix before creating work units with that prefix.

Prefixes help teams organize work into logical domains and make it easier to filter and find related work units in large projects.

Usage:

fspec create-prefix <prefix> <description>

Examples:

fspec create-prefix AUTH "Authentication features"

Update Prefix

Updates the description of a registered work unit prefix. This is useful when the scope or meaning of a prefix evolves over time, or when you want to clarify what types of work belong under a particular namespace.

Use --description to provide the new descriptive text that explains what the prefix represents.

Usage:

fspec update-prefix <prefix> <description>

Examples:

fspec update-prefix AUTH "Updated description"

List Prefixes

Lists all registered work unit prefixes with their descriptions. This command provides an overview of how your project organizes work by component or area, and helps you choose the right prefix when creating new work units.

Use this command to browse existing namespaces before creating stories, bugs, or tasks.

Usage:

fspec list-prefixes

Examples:

fspec list-prefixes

FOUNDATION & DOCUMENTATION

Discover Foundation

Interactive AI-guided workflow that discovers your project foundation field-by-field using system-reminders. This command creates a draft foundation.json.draft with placeholders, then guides AI agents through systematic codebase analysis (ULTRATHINK) to fill each field incrementally.

The command chains from field to field automatically: after each fspec update-foundation command, it scans the draft and emits the next system-reminder. When all [QUESTION:] placeholders are resolved, use --finalize to validate and create the final foundation.json and auto-generate FOUNDATION.md.

Usage:

fspec discover-foundation

Description: Discover project foundation automatically

Options:

  • --output <path> Output path (default: spec/foundation.json)

Examples:

fspec discover-foundation
fspec discover-foundation --output foundation.json

Add Capability

Adds a capability to foundation.json or foundation.json.draft. Capabilities describe WHAT users can do with the system (not HOW it works internally). Used during foundation discovery to incrementally build the solution space.

Focus on user-facing functionality in present tense (e.g., "Users can export data in CSV, JSON, and PDF formats"). Capabilities are part of the solution space and help inform Example Mapping and acceptance criteria creation.

Usage:

fspec add-capability <name> <description>

Description: Add capability to foundation.json

Examples:

fspec add-capability "User Authentication" "Secure access control"
fspec add-capability "Data Visualization" "Interactive charts and graphs"

Add Persona

Adds a user persona to foundation.json or foundation.json.draft. Personas describe WHO uses the system, their characteristics, and their goals. Used during foundation discovery to define the problem space.

Use --goal (repeatable) to specify persona goals. Personas help inform Example Mapping by identifying different user perspectives and needs. Example personas: "Developer", "End User", "Administrator", "AI Agent".

Usage:

fspec add-persona <name> <description> --goal <goal>

Description: Add persona to foundation.json

Options:

  • --goal <goal> Persona goal (can be repeated)

Examples:

fspec add-persona "Developer" "Builds features" --goal "Ship quality code faster"
fspec add-persona "AI Agent" "Uses fspec for specs" --goal "Complete foundation" --goal "Validate features"

Remove Capability

Removes a capability from foundation.json or foundation.json.draft by exact name match (case-sensitive). Used to correct mistakes during foundation discovery or remove obsolete capabilities from an existing foundation.

Removal is permanent with no undo. If the name doesn't match exactly, the error message shows all available capabilities to help you find the correct name.

Usage:

fspec remove-capability <name>

Description: Remove capability from foundation.json

Examples:

fspec remove-capability "User Authentication"
fspec remove-capability "[QUESTION: What can users DO?]"

Remove Persona

Removes a persona from foundation.json or foundation.json.draft by exact name match (case-sensitive). Used to correct mistakes during foundation discovery or remove personas that are no longer relevant to the system.

Removal is permanent with no undo. If the name doesn't match exactly, the error message shows all available personas to help you find the correct name.

Usage:

fspec remove-persona <name>

Description: Remove persona from foundation.json

Examples:

fspec remove-persona "Developer"
fspec remove-persona "[QUESTION: Who uses this?]"

Add Diagram

Adds or updates a Mermaid diagram in foundation.json and regenerates FOUNDATION.md. The diagram code is validated against Mermaid syntax before being added, ensuring only valid diagrams are stored.

Diagrams are organized by section (e.g., "Architecture", "Data Flow") and identified by title. If a diagram with the same title exists, it will be replaced. Supports all Mermaid diagram types: flowchart, sequence, class, state, and more.

Usage:

fspec add-diagram <section> <title> <content>

Description: Add Mermaid diagram with validation

Examples:

fspec add-diagram "Architecture" "System" "graph TD\n  A-->B"

Delete Diagram

Deletes a Mermaid diagram from foundation.json by section and title. After deletion, FOUNDATION.md is automatically regenerated to reflect the change.

Use this command to remove outdated or incorrect diagrams from your project foundation documentation.

Usage:

fspec delete-diagram <section> <title>

Examples:

fspec delete-diagram "Architecture" "System"

Update Foundation

Updates section content in foundation.json or foundation.json.draft depending on context. The command automatically detects which file to update: if a draft exists (during discovery), it updates the draft; otherwise it updates the final foundation and regenerates FOUNDATION.md.

Used during discover-foundation workflow to fill [QUESTION:] placeholders field-by-field, or after discovery to update existing foundation sections. Supported sections include: projectName, projectVision, projectType, problemDefinition, problemImpact, solutionOverview.

Usage:

fspec update-foundation <section> <content>

Examples:

fspec update-foundation "What We Are Building" "A CLI tool..."

Show Foundation

Displays the contents of foundation.json in a readable format. When called without arguments, shows the entire foundation. Use the optional section argument to view a specific section, or --list-sections to see available section names.

The --line-numbers option adds line numbers to the output, useful for debugging or referencing specific lines. This command shows the machine-readable JSON; use generate-foundation-md for human-readable markdown documentation.

Usage:

fspec show-foundation

Options:

  • --section <section> Show specific section
  • --format <format> Output: text, json, or markdown
  • --output <file> Write to file
  • --list-sections List all sections
  • --line-numbers Show line numbers

Examples:

fspec show-foundation --section "What We Are Building"

Generate Foundation Md

Generates spec/FOUNDATION.md from foundation.json, creating human-readable documentation that includes project metadata and renders Mermaid diagrams. This file is automatically generated during foundation updates, but you can regenerate it manually if needed.

FOUNDATION.md is the human-readable version of your foundation, while foundation.json is the machine-readable source of truth.

Usage:

fspec generate-foundation-md

Description: Regenerate FOUNDATION.md from foundation.json

Examples:

fspec generate-foundation-md

Generate Tags Md

Generates spec/TAGS.md from tags.json, creating human-readable documentation of all registered tags grouped by category. This file helps team members understand the tagging system and available tags.

TAGS.md is the human-readable version of your tag registry, while tags.json is the machine-readable source of truth.

Usage:

fspec generate-tags-md

Description: Regenerate TAGS.md from tags.json

Examples:

fspec generate-tags-md

Validate Foundation Schema

Validates foundation.json against its JSON schema using Ajv validator, checking for required fields, correct types, and proper structure. This ensures your foundation file meets all schema requirements.

Run this command after any manual edits to foundation.json to catch structural errors before they cause problems with other commands.

Usage:

fspec validate-foundation-schema

Description: Validate foundation.json against its JSON schema

Examples:

fspec validate-foundation-schema
Discovery (Example Mapping)Lifecycle Hooks