Scripts

​

Script Overview

• Bash scripts: .specify/scripts/bash/ (Linux, macOS, WSL)
• PowerShell scripts: .specify/scripts/powershell/ (Windows, cross-platform)

​

Core Scripts

​

create-new-feature

• Bash: .specify/scripts/bash/create-new-feature.sh
• PowerShell: .specify/scripts/powershell/create-new-feature.ps1

# Basic usage
./create-new-feature.sh "Add user authentication system"

# With custom short name
./create-new-feature.sh "Add OAuth2 integration" --short-name "oauth"

# Specify branch number manually
./create-new-feature.sh "Implement API" --number 5

# JSON output
./create-new-feature.sh "Build dashboard" --json

1. Determines next available feature number
2. Generates branch name from description
3. Creates Git branch (if Git available)
4. Creates feature directory in specs/
5. Copies spec template to feature directory
6. Sets SPECIFY_FEATURE environment variable

BRANCH_NAME: 001-user-auth
SPEC_FILE: /path/to/specs/001-user-auth/spec.md
FEATURE_NUM: 001
SPECIFY_FEATURE environment variable set to: 001-user-auth

{
  "BRANCH_NAME": "001-user-auth",
  "SPEC_FILE": "/path/to/specs/001-user-auth/spec.md",
  "FEATURE_NUM": "001"
}

​

setup-plan

• Bash: .specify/scripts/bash/setup-plan.sh
• PowerShell: .specify/scripts/powershell/setup-plan.ps1

# Basic usage
./setup-plan.sh

# JSON output
./setup-plan.sh --json

1. Validates current feature branch
2. Ensures feature directory exists
3. Copies plan template to feature directory
4. Returns paths to spec and plan files

FEATURE_SPEC: /path/to/specs/001-user-auth/spec.md
IMPL_PLAN: /path/to/specs/001-user-auth/plan.md
SPECS_DIR: /path/to/specs/001-user-auth
BRANCH: 001-user-auth
HAS_GIT: true

​

check-prerequisites

• Bash: .specify/scripts/bash/check-prerequisites.sh
• PowerShell: .specify/scripts/powershell/check-prerequisites.ps1

# Check for plan prerequisites
./check-prerequisites.sh --json

# Check for implementation prerequisites
./check-prerequisites.sh --json --require-tasks --include-tasks

# Get paths only (no validation)
./check-prerequisites.sh --paths-only

# Text output with status indicators
./check-prerequisites.sh

1. Validates feature branch exists
2. Checks required files (plan.md, tasks.md)
3. Identifies available optional documents
4. Returns feature directory and document list

• --json / -Json: Output in JSON format
• --require-tasks / -RequireTasks: Fail if tasks.md missing
• --include-tasks / -IncludeTasks: Include tasks.md in available docs
• --paths-only / -PathsOnly: Skip validation, return paths only

FEATURE_DIR:/path/to/specs/001-user-auth
AVAILABLE_DOCS:
  ✓ research.md
  ✓ data-model.md
  ✓ contracts/
  ✓ quickstart.md
  ✗ tasks.md

{
  "FEATURE_DIR": "/path/to/specs/001-user-auth",
  "AVAILABLE_DOCS": [
    "research.md",
    "data-model.md",
    "contracts/",
    "quickstart.md"
  ]
}

​

update-agent-context

• Bash: .specify/scripts/bash/update-agent-context.sh
• PowerShell: .specify/scripts/powershell/update-agent-context.ps1

# Update all detected agent files
./update-agent-context.sh

# Update specific agent
./update-agent-context.sh --agent claude

# Force create if missing
./update-agent-context.sh --create

1. Detects agent context files (.claude/CLAUDE.md, .opencode/README.md, etc.)
2. Updates feature information section
3. Adds/updates paths to current spec, plan, tasks
4. Preserves other content in agent files

• Claude Code (.claude/CLAUDE.md)
• Gemini CLI (.gemini/GEMINI.md)
• GitHub Copilot (.github/copilot-instructions.md)
• Cursor (.cursorrules)
• opencode (.opencode/README.md)
• Windsurf (.windsurfrules)
• And more…

​

common

• Bash: .specify/scripts/bash/common.sh
• PowerShell: .specify/scripts/powershell/common.ps1

• get_feature_paths() / Get-FeaturePathsEnv: Get all feature-related paths
• check_feature_branch() / Test-FeatureBranch: Validate feature branch
• find_repo_root() / Find-RepositoryRoot: Locate repository root
• File/directory checking utilities

# Source common functions
source "$SCRIPT_DIR/common.sh"

# Get feature paths
eval $(get_feature_paths)
echo "Feature dir: $FEATURE_DIR"

# Check feature branch
check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT"

# Check if file exists and print status
check_file "$FEATURE_SPEC" "spec.md"

# Source common functions
. "$PSScriptRoot/common.ps1"

# Get feature paths
$paths = Get-FeaturePathsEnv
Write-Output "Feature dir: $($paths.FEATURE_DIR)"

# Check feature branch
Test-FeatureBranch -Branch $paths.CURRENT_BRANCH -HasGit:$paths.HAS_GIT

# Check if file exists
Test-FileExists -Path $paths.FEATURE_SPEC -Description 'spec.md'

​

Script Integration

​

Environment Variables

​

SPECIFY_FEATURE

# Set for current session
export SPECIFY_FEATURE="001-user-auth"

# Use in AI agent
/speckit.plan

​

Feature Detection

1. Git branch (if Git available): Uses current branch name
2. SPECIFY_FEATURE env var: Falls back to environment variable
3. Directory scan: Looks for newest feature in specs/ directory

$ git branch
* 001-user-auth
  main

$ ./check-prerequisites.sh --paths-only
BRANCH: 001-user-auth
FEATURE_DIR: /path/to/specs/001-user-auth

$ export SPECIFY_FEATURE="001-user-auth"
$ ./check-prerequisites.sh --paths-only
BRANCH: 001-user-auth (from SPECIFY_FEATURE)
FEATURE_DIR: /path/to/specs/001-user-auth

$ ls specs/
001-user-auth  002-api-integration

$ ./check-prerequisites.sh --paths-only
BRANCH: 002-api-integration (newest in specs/)
FEATURE_DIR: /path/to/specs/002-api-integration

​

Git vs Non-Git Workflows

​

Git Workflow

# Create feature (creates branch automatically)
./create-new-feature.sh "Add feature"

# Scripts detect current branch
./setup-plan.sh
./check-prerequisites.sh

# Switch features by checking out branches
git checkout 002-other-feature
./check-prerequisites.sh  # Automatically uses 002-other-feature

​

Non-Git Workflow

# Create feature (no branch, uses directory only)
./create-new-feature.sh "Add feature"

# Set SPECIFY_FEATURE when switching features
export SPECIFY_FEATURE="001-add-feature"
./setup-plan.sh
./check-prerequisites.sh

# Switch features by updating env var
export SPECIFY_FEATURE="002-other-feature"
./check-prerequisites.sh

​

Script Error Handling

• Exit code 0: Success
• Exit code 1: Error (with descriptive message to stderr)
• Validation failures: Clear error messages guide next steps

# Error: No feature branch
$ ./check-prerequisites.sh
ERROR: Not on a feature branch (###-name format)
Current branch: main
Run /speckit.specify first to create a feature.

# Error: Missing plan
$ ./check-prerequisites.sh
ERROR: plan.md not found in specs/001-feature
Run /speckit.plan first to create the implementation plan.

# Error: Missing tasks (when required)
$ ./check-prerequisites.sh --require-tasks
ERROR: tasks.md not found in specs/001-feature
Run /speckit.tasks first to create the task list.

​

Platform Compatibility

​

Bash Scripts

• Linux (all distributions)
• macOS
• Windows Subsystem for Linux (WSL)
• Git Bash (limited)

• Bash 4.0+
• Standard Unix utilities (grep, sed, awk)

​

PowerShell Scripts

• Windows PowerShell 5.1+
• PowerShell Core 7.0+ (cross-platform)
• macOS (with PowerShell Core)
• Linux (with PowerShell Core)

• PowerShell 5.1+ or PowerShell Core 7.0+

​

Debugging Scripts

​

Enable Debug Output

# Enable trace mode
bash -x ./create-new-feature.sh "Test feature"

# Or add to script
set -x  # Enable
set +x  # Disable

​

Common Issues

# Make script executable
chmod +x .specify/scripts/bash/*.sh

# Check policy
Get-ExecutionPolicy

# Allow local scripts
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

# Or bypass for single command
powershell -ExecutionPolicy Bypass -File .\script.ps1

# Scripts fall back to non-Git mode
[specify] Warning: Git repository not detected; skipped branch creation

# This is normal for --no-git projects
# Use SPECIFY_FEATURE to specify feature manually
export SPECIFY_FEATURE="001-feature-name"

​

Best Practices

​

Version Control

• All scripts in .specify/scripts/
• Script modifications and customizations
• Common utility functions

• Generated output files
• Temporary debug files
• Platform-specific binaries

​

Script Modifications

1. Copy first: Create a custom version
2. Document changes: Add comments explaining modifications
3. Test both platforms: If modifying both Bash and PowerShell
4. Preserve compatibility: Maintain consistent output format

#!/usr/bin/env bash
# Custom version of create-new-feature.sh
# Modifications:
# - Added company-specific branch prefix
# - Custom feature number format

# Source original common functions
source "$(dirname "$0")/common.sh"

# Your customizations here
COMPANY_PREFIX="PROJ"
BRANCH_NAME="${COMPANY_PREFIX}-${FEATURE_NUM}-${BRANCH_SUFFIX}"

​

Error Messages

• Explain what went wrong
• Suggest next steps
• Reference relevant commands

echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
echo "Run /speckit.specify first to create the feature structure." >&2
exit 1

​

Related Resources

• Scripts Directory
• Bash Scripts
• PowerShell Scripts
• Command Reference