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.