feat: implement global configuration support and update related scripts for XDG compliance

Author: kanfil

.gitignore

@@ -48,6 +48,10 @@ env/
 *.zip
 sdd-*
 
+# User-specific configuration (now stored globally in ~/.config/specify/)
+# Old local config directory is kept for backward compatibility but should not be used
+.specify/config/
+
 # Evaluation artifacts
 eval-results*.json
 *.backup

CHANGELOG.md

@@ -7,6 +7,25 @@ All notable changes to the Specify CLI and templates are documented here.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.23] - 2025-01-28
+
+### Changed
+
+- **Global Configuration Support**: Configuration now stored globally in `~/.config/specify/config.json` (XDG Base Directory compliant)
+  - Linux: `$XDG_CONFIG_HOME/specify/config.json` (defaults to `~/.config/specify/config.json`)
+  - macOS: `~/Library/Application Support/specify/config.json`
+  - Windows: `%APPDATA%\specify\config.json`
+  - All projects share a single global configuration file
+  - Uses `platformdirs` for cross-platform path resolution
+  - Updated Python CLI (`src/specify_cli/__init__.py`) with `get_global_config_path()` function
+  - Updated bash scripts (`scripts/bash/common.sh`) with `get_global_config_path()` helper
+  - Updated PowerShell scripts (`scripts/powershell/common.ps1`) with `Get-GlobalConfigPath` function
+  - Old local `.specify/config/` directories are now ignored (added to `.gitignore`)
+
+### Removed
+
+- **`mode_history` from configuration**: Removed `workflow.mode_history` field from config structure (was unused)
+
 ## [0.0.22] - 2025-11-07
 
 - Support for VS Code/Copilot agents, and moving away from prompts to proper agents with hand-offs.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentic-sdlc-specify-cli"
-version = "0.0.22"
+version = "0.0.23"
 description = "Specify CLI, part of GitHub Spec Kit. A tool to bootstrap your projects for Spec-Driven Development (SDD)."
 requires-python = ">=3.11"
 dependencies = [

roadmap.md

@@ -146,9 +146,9 @@
 
 - ❌ **Gateway Health Checks**: Only basic configuration exists, no health check implementation
 - ❌ **Tool Selection Guidance**: Claims implementation but no actual guidance logic found
-- ❌ **Global Configuration Support**: Implement hierarchical config loading (Local `.specify/config/config.json` overrides Global `~/.config/specify/config.json`).
-- ❌ **CLI Config Refactor**: Update `src/specify_cli/__init__.py` to use `platformdirs` for XDG-compliant global path resolution and deep merging logic.
-- ❌ **Script Config Resolution**: Update `common.sh` and `common.ps1` helper functions to check global paths if local config is missing values.
+- ✅ **Global Configuration Support**: All configuration now stored globally in `~/.config/specify/config.json` (XDG compliant). Single shared configuration across all projects. Linux: `$XDG_CONFIG_HOME/specify/config.json`, macOS: `~/Library/Application Support/specify/config.json`, Windows: `%APPDATA%\specify\config.json`.
+- ✅ **CLI Config Refactor**: Updated `src/specify_cli/__init__.py` to use `platformdirs` for XDG-compliant global path resolution.
+- ✅ **Script Config Resolution**: Updated `common.sh` and `common.ps1` with `get_global_config_path()` / `Get-GlobalConfigPath` helper functions.
 - ✅ **Config Consolidation**: Successfully implemented as single unified configuration file to reduce complexity and improve maintainability
 - ❌ **Atomic Commits Config**: Add `atomic_commits` boolean option to `config.json` (default: `false`). Externalize as global configuration available to all workflow modes (build/spec/ad) with per-mode override capability.
 - ❌ **Execution Logic**: Update `scripts/bash/tasks-meta-utils.sh` and `scripts/powershell/common.ps1` to read `atomic_commits` config and inject constraint into `generate_delegation_prompt()` when enabled.

scripts/bash/check-prerequisites.sh

@@ -149,7 +149,8 @@ PY
 
 # Extract mode configuration
 get_mode_config() {
-    local config_file=".specify/config/config.json"
+    local config_file
+    config_file=$(get_global_config_path)
 
     # Extract current mode and options from consolidated config
     python3 - "$config_file" <<'PY'
@@ -225,11 +226,12 @@ fi
 if [[ ! -f "$IMPL_PLAN" ]]; then
     # Get current mode to determine if plan.md is required
     current_mode="spec"
-    if [[ -f ".specify/config/config.json" ]]; then
+    global_config=$(get_global_config_path)
+    if [[ -f "$global_config" ]]; then
         current_mode=$(python3 -c "
 import json
 try:
-    with open('.specify/config/config.json', 'r') as f:
+    with open('$global_config', 'r') as f:
         data = json.load(f)
     print(data.get('workflow', {}).get('current_mode', 'spec'))
 except:

scripts/bash/common.sh

@@ -4,10 +4,20 @@
 # Shared constants
 TEAM_DIRECTIVES_DIRNAME="team-ai-directives"
 
+# Get the global config path using XDG Base Directory spec
+# Platform-specific locations:
+# - Linux: ~/.config/specify/config.json
+# - macOS: ~/Library/Application Support/specify/config.json (but we use XDG for consistency)
+get_global_config_path() {
+    local config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+    echo "$config_home/specify/config.json"
+}
+
 load_team_directives_config() {
     local repo_root="$1"
 
-    local config_file="$repo_root/.specify/config/config.json"
+    local config_file
+    config_file=$(get_global_config_path)
     if [[ -f "$config_file" ]] && command -v jq >/dev/null 2>&1; then
         local path
         path=$(jq -r '.team_directives.path // empty' "$config_file" 2>/dev/null)

scripts/bash/create-new-feature.sh

@@ -174,6 +174,12 @@ fi
 
 cd "$REPO_ROOT"
 
+# Get the global config path using XDG Base Directory spec
+get_global_config_path() {
+    local config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+    echo "$config_home/specify/config.json"
+}
+
 SPECS_DIR="$REPO_ROOT/specs"
 mkdir -p "$SPECS_DIR"
 
@@ -298,7 +304,7 @@ replace_date_placeholders() {
 }
 
 # Mode-aware template selection
-MODE_FILE="$REPO_ROOT/.specify/config/config.json"
+MODE_FILE=$(get_global_config_path)
 CURRENT_MODE="spec"
 if [ -f "$MODE_FILE" ]; then
     CURRENT_MODE=$(python3 -c "

scripts/bash/implement.sh

@@ -121,8 +121,10 @@ load_implementation_context() {
 
     # Get current workflow mode
     local workflow_mode="spec"  # Default
-    if [[ -f ".specify/config/config.json" ]]; then
-        workflow_mode=$(jq -r '.workflow.current_mode // "spec"' ".specify/config/config.json" 2>/dev/null || echo "spec")
+    local global_config
+    global_config=$(get_global_config_path)
+    if [[ -f "$global_config" ]]; then
+        workflow_mode=$(jq -r '.workflow.current_mode // "spec"' "$global_config" 2>/dev/null || echo "spec")
     fi
 
     # Required files (plan.md is optional in build mode)
@@ -426,8 +428,10 @@ handle_task_failure() {
 
     # Get workflow mode for mode-aware rollback
     local mode="spec"  # Default
-    if [[ -f ".specify/config/config.json" ]]; then
-        mode=$(jq -r '.workflow.current_mode // "spec"' ".specify/config/config.json" 2>/dev/null || echo "spec")
+    local global_config
+    global_config=$(get_global_config_path)
+    if [[ -f "$global_config" ]]; then
+        mode=$(jq -r '.workflow.current_mode // "spec"' "$global_config" 2>/dev/null || echo "spec")
     fi
 
     echo "Task $task_id failed. Options:

scripts/bash/spec-hooks-install.sh

@@ -77,20 +77,23 @@ set -euo pipefail
 SCRIPT_DIR="\$(cd "\$(dirname "\${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="\$(cd "\$SCRIPT_DIR/../.." && pwd)"
 
+# Get the global config path using XDG Base Directory spec
+GLOBAL_CONFIG="\${XDG_CONFIG_HOME:-\$HOME/.config}/specify/config.json"
+
 # Check if spec sync is enabled for this project
-if [[ ! -f "\$PROJECT_ROOT/.specify/config/config.json" ]]; then
+if [[ ! -f "\$GLOBAL_CONFIG" ]]; then
     exit 0
 fi
 
 # Check if spec sync is enabled in config
 if command -v jq >/dev/null 2>&1; then
-    enabled=\$(jq -r '.spec_sync.enabled // false' "\$PROJECT_ROOT/.specify/config/config.json" 2>/dev/null)
+    enabled=\$(jq -r '.spec_sync.enabled // false' "\$GLOBAL_CONFIG" 2>/dev/null)
     if [[ "\$enabled" != "true" ]]; then
         exit 0
     fi
 else
     # Fallback: check if enabled exists in config (simple grep)
-    if ! grep -q '"enabled":\s*true' "\$PROJECT_ROOT/.specify/config/config.json" 2>/dev/null; then
+    if ! grep -q '"enabled":\s*true' "\$GLOBAL_CONFIG" 2>/dev/null; then
         exit 0
     fi
 fi
@@ -107,9 +110,11 @@ EOF
     log_success "Installed $hook_name hook"
 }
 
-# Create spec sync configuration
+# Create spec sync configuration (in global config location)
 function create_config {
-    local config_dir=".specify/config"
+    # Use XDG Base Directory spec for global config
+    local config_home="${XDG_CONFIG_HOME:-$HOME/.config}"
+    local config_dir="$config_home/specify"
     local config_file="$config_dir/config.json"
     mkdir -p "$config_dir"
 
@@ -124,8 +129,7 @@ function create_config {
   },
   "workflow": {
     "current_mode": "spec",
-    "default_mode": "spec",
-    "mode_history": []
+    "default_mode": "spec"
   },
   "options": {
     "tdd_enabled": false,
@@ -169,7 +173,7 @@ EOF
         fi
     fi
 
-    log_success "Created/updated spec sync configuration"
+    log_success "Created/updated spec sync configuration at $config_file"
 }
 
 # Main installation function

scripts/bash/spec-sync-post-commit.sh

@@ -32,8 +32,8 @@ log_error() {
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Check if spec sync is enabled
-CONFIG_FILE="$PROJECT_ROOT/.specify/config/config.json"
+# Check if spec sync is enabled (global config)
+CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
 if [[ ! -f "$CONFIG_FILE" ]]; then
     exit 0
 fi