feat: Add SPECIFY_SPECS_DIR for centralized specs directory and worktree support

[alanmeadows]

Summary

This PR adds support for a centralized specs directory via the SPECIFY_SPECS_DIR environment variable, enabling powerful workflows for git worktrees, multi-feature development, and team collaboration.

Motivation

This addresses the use case discussed in #1547 (worktree support) with a simpler, more flexible approach. Rather than embedding worktree management into git-spec, this PR decouples git-spec from specific git workflows by letting users control where specs are stored.

Key Features

1. External Specs Directory

Set SPECIFY_SPECS_DIR to store specs outside the repository:

export SPECIFY_SPECS_DIR="/path/to/myrepo.specs"
export SPECIFY_FEATURE="my-feature"

2. Shared Project Context

A _shared/ subdirectory within the specs directory provides project-wide context that all commands automatically incorporate:

myrepo.specs/
    _shared/                    # Project-wide standards
        architecture.md
        api-conventions.md
        coding-standards.md
    001-feature-a/
        spec.md
        plan.md
    002-feature-b/
        spec.md

3. Worktree Compatibility

Works seamlessly with git worktrees - all worktrees can share the same specs directory:

# In any worktree:
export SPECIFY_SPECS_DIR="${HOME}/clones/myrepo.specs"
# All git-spec commands use the centralized specs

Benefits

• Cross-feature visibility: See all feature specs when working on any feature
• Spec survival: Specs persist when worktrees are deleted
• Spec-first development: Create specs before branches exist
• Shared standards: Project-wide guidance incorporated into all commands
• 100% backward compatible: No changes when env var is not set

Changes

Component	Files	Changes
Bash scripts	common.sh, create-new-feature.sh, check-prerequisites.sh	Add get_specs_dir(), update references, add SPECS_DIR to JSON
PowerShell scripts	common.ps1, create-new-feature.ps1, check-prerequisites.ps1	Add Get-SpecsDir, update references, add SPECS_DIR to JSON
Command templates	7 files	Add _shared/ loading to context step

Total: ~50 lines across 13 files

Testing

Tested scenarios:

• Default behavior (no env vars): Works exactly as before
• With SPECIFY_SPECS_DIR set: Correctly uses external directory
• JSON output includes SPECS_DIR for command templates
• Feature auto-numbering works with external specs directory

Relationship to #1547

This is an alternative approach to #1547's embedded worktree support. Instead of git-spec managing worktrees, this lets users manage git however they want while git-spec focuses on spec management. The key insight from #1547's discussion was correct: "rip out branch management and let the user do it how they want."

[Copilot]

Pull request overview

This PR adds support for centralized specs directories via the SPECIFY_SPECS_DIR environment variable and introduces a _shared/ subdirectory convention for project-wide standards. The changes enable powerful workflows for git worktrees, multi-feature development, and team collaboration.

Changes:

• Add get_specs_dir() / Get-SpecsDir functions to bash and PowerShell common libraries to support external specs directories via SPECIFY_SPECS_DIR
• Update all scripts to use the new specs directory functions instead of hardcoded paths
• Add SPECS_DIR to JSON outputs in check-prerequisites scripts for downstream consumption
• Update 7 command templates to conditionally load project-wide context from SPECS_DIR/_shared/ directory

Reviewed changes

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
scripts/bash/common.sh	Add get_specs_dir() function to support SPECIFY_SPECS_DIR environment variable
scripts/bash/create-new-feature.sh	Use SPECIFY_SPECS_DIR environment variable for specs directory location
scripts/bash/check-prerequisites.sh	Include SPECS_DIR in JSON output for both paths-only and normal modes
scripts/powershell/common.ps1	Add Get-SpecsDir function to support SPECIFY_SPECS_DIR environment variable
scripts/powershell/create-new-feature.ps1	Use SPECIFY_SPECS_DIR environment variable for specs directory location
scripts/powershell/check-prerequisites.ps1	Include SPECS_DIR in JSON output for both paths-only and normal modes
templates/commands/specify.md	Add step to load shared context from SPECS_DIR/_shared/ directory
templates/commands/plan.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory
templates/commands/tasks.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory
templates/commands/implement.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory
templates/commands/clarify.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory
templates/commands/checklist.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory
templates/commands/analyze.md	Add instruction to load shared context from SPECS_DIR/_shared/ directory

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[alanmeadows]

All review feedback has been addressed in the latest commit:

Path Validation (common.sh, common.ps1):

• Added validation requiring absolute paths (must start with / on Unix, uses IsPathRooted on Windows)
• Blocks path traversal (rejects paths containing '..')
• Returns clear error messages if validation fails

JSON Escaping (common.sh):

• Added json_escape() helper function that escapes backslashes, quotes, newlines, carriage returns, and tabs
• Applied to all printf JSON outputs in check-prerequisites.sh and create-new-feature.sh

SPECS_DIR in JSON Output (create-new-feature.sh, create-new-feature.ps1):

• Added SPECS_DIR to JSON output alongside BRANCH_NAME, SPEC_FILE, FEATURE_NUM

Template Wording (specify.md):

• Clarified wording about where SPECS_DIR is provided

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The if (-not $specsDir) branch is currently unreachable because Get-SpecsDir always returns a non-empty string. This makes the new "Invalid SPECIFY_SPECS_DIR configuration" error message misleading. Either add validation/$null return behavior to Get-SpecsDir, or remove this conditional and rely on New-Item/Resolve-Path failures for error handling.

Suggested change

	if (-not $specsDir) {
	Write-Host "`n[specify] ERROR: Invalid SPECIFY_SPECS_DIR configuration. Aborting." -ForegroundColor Red
	exit 1
	}

[Copilot]

The example path uses specs/_shared/, but with SPECIFY_SPECS_DIR the shared directory is conceptually SPECS_DIR/_shared/ (which may not be under specs/). Consider updating the example to avoid implying it must live in specs/.

[Copilot]

SPECIFY_SPECS_DIR is user-controlled and can now influence values emitted by get_feature_paths (which are later consumed via eval $(get_feature_paths) in multiple scripts). Because get_feature_paths wraps values in single quotes, a SPECIFY_SPECS_DIR containing a ' can break out of quoting and lead to command injection. Consider switching away from eval-based exports, or ensure values are safely shell-escaped (e.g., escape single quotes) before being embedded in the get_feature_paths output.

[Copilot]

get_specs_dir is used as though it can fail (SPECS_DIR="$(get_specs_dir ...)" || exit 1), but the function always exits 0 and just echoes a path. Either remove the || exit 1 patterns, or add validation so get_specs_dir returns non-zero for invalid configurations (e.g., empty repo_root, path exists but is not a directory, or directory cannot be created when required).

[Copilot]

Get-SpecsDir always returns a (possibly relative-resolved) string, so callers' if (-not $specsDir) { exit 1 } checks can never trigger. Either implement real validation here (and return $null for invalid values like an existing non-directory path), or remove the dead checks and adjust the error messaging accordingly.

Suggested change

	if ($env:SPECIFY_SPECS_DIR) {
	$specsDir = $env:SPECIFY_SPECS_DIR
	# Resolve relative paths against repo root
	if (-not [System.IO.Path]::IsPathRooted($specsDir)) {
	$specsDir = Join-Path $RepoRoot $specsDir
	}
	return $specsDir
	}
	return Join-Path $RepoRoot "specs"
	$specsDir = $null
	if ($env:SPECIFY_SPECS_DIR) {
	$specsDir = $env:SPECIFY_SPECS_DIR
	# Resolve relative paths against repo root
	if (-not [System.IO.Path]::IsPathRooted($specsDir)) {
	$specsDir = Join-Path $RepoRoot $specsDir
	}
	} else {
	$specsDir = Join-Path $RepoRoot "specs"
	}
	# Validate that, if the path exists, it is a directory
	if (Test-Path $specsDir) {
	if (-not (Test-Path $specsDir -PathType Container)) {
	Write-Error "Invalid specs directory path '$specsDir': path exists but is not a directory."
	return $null
	}
	}
	return $specsDir

[Copilot]

Pull request overview

Copilot reviewed 14 out of 14 changed files in this pull request and generated 7 comments.

Comments suppressed due to low confidence (1)

scripts/powershell/create-new-feature.ps1:29

• The -Help output is out of sync with the new -NoBranch parameter: the Usage line doesn’t mention -NoBranch, and the examples don’t show how to use it. Update the help text (and fix the extra indentation before Write-Host " -NoBranch...") so users can discover the flag.

    Write-Host "Usage: ./create-new-feature.ps1 [-Json] [-ShortName <name>] [-Number N] <feature description>"
    Write-Host ""
    Write-Host "Options:"
    Write-Host "  -Json               Output in JSON format"
    Write-Host "  -ShortName <name>   Provide a custom short name (2-4 words) for the branch"
    Write-Host "  -Number N           Specify branch number manually (overrides auto-detection)"
     Write-Host "  -NoBranch           Skip branch creation (auto-enabled when SPECIFY_SPECS_DIR is set)"
    Write-Host "  -Help               Show this help message"
    Write-Host ""
    Write-Host "Examples:"
    Write-Host "  ./create-new-feature.ps1 'Add user authentication system' -ShortName 'user-auth'"
    Write-Host "  ./create-new-feature.ps1 'Implement OAuth2 integration for API'"
    exit 0

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Step 1 only instructs parsing FEATURE_DIR/AVAILABLE_DOCS, but step 4 now depends on SPECS_DIR to load shared standards from _shared/. Consider explicitly adding SPECS_DIR to the parsed JSON fields (or explaining how to derive it from FEATURE_DIR) so shared-context loading is reliable.

[Copilot]

The if (-not $specsDir) guard is currently unreachable because Get-SpecsDir (in common.ps1) always returns a non-empty string (either SPECIFY_SPECS_DIR resolved or the default Join-Path $RepoRoot 'specs'). Either remove this check, or add real validation to Get-SpecsDir (e.g., return $null when the path is invalid/uncreatable) so the error message can actually trigger.

Suggested change

	if (-not $specsDir) {
	Write-Host "`n[specify] ERROR: Invalid SPECIFY_SPECS_DIR configuration. Aborting." -ForegroundColor Red
	exit 1
	}

[Copilot]

This outline says to parse only FEATURE_DIR and AVAILABLE_DOCS from the script output, but the next bullet relies on SPECS_DIR to locate _shared/. Since check-prerequisites now emits SPECS_DIR, explicitly include it in the “parse” step (or change the shared-context instruction to derive it from FEATURE_DIR) so the workflow is internally consistent.

[Copilot]

This adds a shared-context section keyed off SPECS_DIR/_shared, but earlier instructions only say to parse FEATURE_DIR and AVAILABLE_DOCS. Since the script output now includes SPECS_DIR, explicitly include it in the parsed fields (or describe deriving it from FEATURE_DIR) so the shared standards can actually be located.

[Copilot]

This template assumes SPECS_DIR from {SCRIPT} points at the specs root so SPECS_DIR/_shared can be read. But the plan setup scripts (scripts/bash/setup-plan.sh and scripts/powershell/setup-plan.ps1) currently emit SPECS_DIR as the feature directory ($FEATURE_DIR), so this would look for _shared inside the feature folder and never find the shared context. Either update the setup-plan scripts to include the real specs root (and ideally a separate FEATURE_DIR field), or adjust the instruction here to derive the shared dir from the feature dir (e.g., use the parent directory of FEATURE_DIR/SPECS_DIR).

[Copilot]

Step 3 requires SPECS_DIR (to load SPECS_DIR/_shared), but step 1’s “Parse minimal JSON payload fields” list omits SPECS_DIR. Since the script now outputs it, include SPECS_DIR in the fields to parse/capture so the shared-context step is actionable.

[Copilot]

The setup step here only mentions parsing FEATURE_DIR and AVAILABLE_DOCS, but this new bullet requires SPECS_DIR for _shared/. To avoid the agent missing the field, update the setup/parsing instructions to capture SPECS_DIR from the script JSON (or derive it from FEATURE_DIR).