Commands
Configuration & Setup

Configuration & Setup Commands

Configure your fspec project structure, foundation documentation, and tag registry.

Foundation Discovery

Discover Foundation

Automatically discover and document your project's foundation through an interactive AI-guided workflow.

fspec discover-foundation [options]

Options:

  • --output <path> - Output path for final foundation.json (default: spec/foundation.json)
  • --finalize - Finalize foundation.json from edited draft file
  • --draft-path <path> - Path to draft file (default: spec/foundation.json.draft)

When to Use: Use when starting a new project with fspec to bootstrap foundation.json. Creates draft with placeholders, then guides AI field-by-field using system-reminders and chaining to next field after each fspec update-foundation command.

Workflow:

  1. AI runs fspec discover-foundation to create draft with placeholders
  2. Command creates spec/foundation.json.draft with [QUESTION:] and [DETECTED:] placeholders
  3. Command scans draft and emits system-reminder for FIRST unfilled field (Field 1/N)
  4. AI analyzes codebase (ULTRATHINK), asks human for confirmation, runs fspec update-foundation <section> <content>
  5. Command automatically re-scans draft and emits system-reminder for NEXT unfilled field
  6. Repeat steps 4-5 until all [QUESTION:] placeholders resolved
  7. When complete, AI runs fspec discover-foundation --finalize to validate and create foundation.json
  8. Draft file deleted, FOUNDATION.md auto-generated

Examples:

# Create draft and receive guidance for first field
fspec discover-foundation
 
# Fill first field (command chains to next field automatically)
fspec update-foundation projectName "fspec"
 
# Validate complete draft and create final foundation.json
fspec discover-foundation --finalize

Update Foundation

Update a specific section of the foundation documentation.

fspec update-foundation <section> <content>

Examples:

fspec update-foundation projectVision "A CLI tool for AI-driven ACDD workflows"
fspec update-foundation projectName "fspec"

Show Foundation

Display foundation documentation.

fspec show-foundation [options]

Options:

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

Examples:

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

Generate Foundation Markdown

Regenerate FOUNDATION.md from foundation.json.

fspec generate-foundation-md

Capabilities & Personas

Add Capability

Add a capability to the foundation.json.

fspec add-capability <name> <description>

Examples:

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

Remove Capability

Remove a capability from the foundation.json.

fspec remove-capability <name>

Examples:

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

Add Persona

Add a persona to the foundation.json.

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

Options:

  • --goal <goal> - Persona goal (can be repeated for multiple goals)

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 Persona

Remove a persona from the foundation.json.

fspec remove-persona <name>

Examples:

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

Architecture Diagrams

Add Diagram

Add a Mermaid diagram to the foundation with syntax validation.

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

Examples:

fspec add-diagram "Architecture" "System Overview" "graph TD\n  A[Client]-->B[Server]\n  B-->C[Database]"

Update Diagram

Update an existing Mermaid diagram.

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

Delete Diagram

Delete a Mermaid diagram.

fspec delete-diagram <section> <title>

List Diagrams

List all Mermaid diagrams in the foundation.

fspec list-diagrams

Show Diagram

Display a specific Mermaid diagram.

fspec show-diagram <section> <title>

Tag Registry

Register Tag

Register a new tag in the centralized registry.

fspec register-tag <tag> <category> <description>

Examples:

fspec register-tag @performance "Technical Tags" "Performance-critical features"
fspec register-tag @phase1 "Project Phases" "First release features"

Update Tag

Update an existing tag's description or category.

fspec update-tag <tag> [options]

Options:

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

Examples:

fspec update-tag @performance --description "New description"
fspec update-tag @phase1 --category "Release Planning"

Delete Tag

Delete a tag from the registry.

fspec delete-tag <tag> [options]

Options:

  • --force - Delete even if used in feature files
  • --dry-run - Preview deletion without making changes

Examples:

fspec delete-tag @deprecated --dry-run
fspec delete-tag @old-tag --force

List Tags

List all registered tags.

fspec list-tags [options]

Options:

  • --category <category> - Filter by category

Examples:

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

Tag Statistics

Show tag usage statistics across the project.

fspec tag-stats

Retag

Bulk rename tags across all feature files.

fspec retag --from=<old-tag> --to=<new-tag> [options]

Options:

  • --from=<tag> - Old tag to replace
  • --to=<tag> - New tag to use
  • --dry-run - Preview changes without applying them

Examples:

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

Generate Tags Markdown

Regenerate TAGS.md from tags.json.

fspec generate-tags-md

Epics & Prefixes

Create Epic

Create a new epic to group related work units.

fspec create-epic <name> <title>

Examples:

fspec create-epic user-management "User Management Features"
fspec create-epic api-v2 "API Version 2"

List Epics

List all epics in the project.

fspec list-epics

Show Epic

Display details of a specific epic.

fspec show-epic <name>

Delete Epic

Delete an epic.

fspec delete-epic <name>

Create Prefix

Create a new work unit ID prefix.

fspec create-prefix <prefix> <description>

Examples:

fspec create-prefix AUTH "Authentication features"
fspec create-prefix UI "User interface components"

Update Prefix

Update a prefix description.

fspec update-prefix <prefix> <description>

List Prefixes

List all registered prefixes.

fspec list-prefixes

Validation

Validate JSON Schema

Validate JSON schema compliance for all spec files.

fspec validate-json-schema

Common Patterns

CLI Tools

AI analyzes CLI framework usage, command definitions, identifies command-line user persona

Web Applications

AI analyzes routes, UI components, identifies End User and API Consumer personas

Libraries

AI analyzes exports and API, identifies Developer persona

Related Commands

Notes

  • AI-driven workflow: The discover-foundation command guides AI field-by-field with system-reminders
  • Draft-first approach: Commands prioritize foundation.json.draft over foundation.json
  • Auto-chaining: After each update-foundation, the command automatically chains to the next unfilled field
  • Validation: All diagrams are validated for Mermaid syntax before being added
  • Case-sensitive: Persona and capability removal uses exact name matching
  • Tag registry: Single source of truth for all project tags with auto-generated documentation
Discovery (Example Mapping)Lifecycle Hooks