Hooks Commands

Overview

The Hooks commands enable workflow automation by executing custom scripts at specific lifecycle events. These commands allow you to integrate quality gates, automated testing, notifications, and custom validation into your ACDD workflow, ensuring that work units meet your standards before progressing through each state.

Use hooks commands when you need to:

• Execute custom scripts at command lifecycle events (pre/post execution)
• Add quality gates with blocking pre-hooks that prevent progression on failure
• Automate testing with post-hooks that run after implementation
• Send notifications when work units change state or reach milestones
• Add work unit-scoped virtual hooks for ephemeral, temporary checks
• Validate hook configurations to ensure scripts are properly set up
• List and manage both global hooks and work unit-specific virtual hooks

Hooks support both global hooks (configured in spec/fspec-hooks.json for project-wide enforcement) and virtual hooks (stored per work unit for temporary, context-specific automation). This flexibility allows you to enforce team standards globally while also enabling per-work-unit customization.

Commands Reference

LIFECYCLE HOOKS

HOOK MANAGEMENT

List Hooks

Lists all configured lifecycle hooks in your project, showing which events they're attached to and what hooks are configured for each event. This command is useful for understanding your current automation setup and debugging hook execution.

Usage:

fspec list-hooks

Description: List all configured hooks

Examples:

fspec list-hooks

Validate Hooks

Validates your hook configuration and verifies that all hook scripts exist at their specified paths. This command is essential before relying on hooks for workflow automation, as it catches configuration errors and missing scripts.

Usage:

fspec validate-hooks

Description: Validate hook configuration and script paths

Examples:

fspec validate-hooks

Add Hook

Adds a lifecycle hook to your project configuration. Hooks execute custom scripts at specific command events using the pre-/post- pattern. Use --blocking to make the hook prevent command execution on failure, and --timeout to set maximum execution time.

Usage:

fspec add-hook <event> <name>

Options:

• --command <path> Path to hook script
• --blocking Make hook blocking
• --timeout <seconds> Timeout in seconds

Examples:

fspec add-hook pre-implementing lint --command spec/hooks/lint.sh --blocking
fspec add-hook post-implementing test --command spec/hooks/test.sh

Remove Hook

Removes a lifecycle hook from your project configuration. Useful when you no longer need specific automation or want to temporarily disable a hook.

Usage:

fspec remove-hook <event> <name>

Examples:

fspec remove-hook pre-implementing lint
fspec remove-hook post-implementing test

Add Virtual Hook

Adds a work unit-scoped virtual hook for dynamic validation. Virtual hooks are ephemeral, context-specific quality checks that run BEFORE global hooks and are stored per work unit. Perfect for one-off checks like linting, type checking, or security scans that apply only to a specific story/bug/task.

Use --git-context to automatically generate a script that processes only changed files (staged/unstaged), making quality checks faster and more relevant.

Usage:

fspec add-virtual-hook <id> <event> <command>

Options:

• --blocking Make hook blocking
• --git-context Run on changed files only

Examples:

fspec add-virtual-hook AUTH-001 pre-implementing "npm run lint" --blocking

List Virtual Hooks

Lists all virtual hooks configured for a specific work unit, showing hooks grouped by event with their configuration (blocking, git context, command). Useful for reviewing quality checks before workflow transitions or debugging hook execution.

Usage:

fspec list-virtual-hooks <id>

Examples:

fspec list-virtual-hooks AUTH-001

Remove Virtual Hook

Removes a specific virtual hook from a work unit. This removes the hook configuration from spec/work-units.json and cleans up any generated script files in spec/hooks/.virtual/. Useful for removing broken hooks or hooks that are no longer needed.

Usage:

fspec remove-virtual-hook <id> <name>

Examples:

fspec remove-virtual-hook AUTH-001 lint

Clear Virtual Hooks

Clears all virtual hooks from a work unit. This is typically used when a work unit reaches "done" status and you want to clean up ephemeral quality checks. Clears the entire virtualHooks array and removes all generated script files.

Usage:

fspec clear-virtual-hooks <id>

Examples:

fspec clear-virtual-hooks AUTH-001

HOOK CONFIGURATION

COMMON USE CASES

Add Hook

Adds a lifecycle hook to your project configuration. Hooks execute custom scripts at specific command events using the pre-/post- pattern. Use --blocking to make the hook prevent command execution on failure, and --timeout to set maximum execution time.

Usage:

fspec add-hook pre-implementing validate --command spec/hooks/lint.sh --blocking

Add Hook

Adds a lifecycle hook to your project configuration. Hooks execute custom scripts at specific command events using the pre-/post- pattern. Use --blocking to make the hook prevent command execution on failure, and --timeout to set maximum execution time.

Usage:

fspec add-hook post-implementing test --command spec/hooks/test.sh

Add Hook

Adds a lifecycle hook to your project configuration. Hooks execute custom scripts at specific command events using the pre-/post- pattern. Use --blocking to make the hook prevent command execution on failure, and --timeout to set maximum execution time.

Usage:

fspec add-hook post-validating notify --command spec/hooks/notify.sh

DOCUMENTATION

Examples: