feat:global and project level config file and fix mode documentation

Author: kanfil

docs/quickstart.md

@@ -29,26 +29,26 @@ Specify supports two workflow modes that control development complexity, plus co
 /mode
 
 # Switch to lightweight mode for prototyping
-/mode build
+/speckit.mode build
 
 # Switch to comprehensive mode for production features
-/mode spec
+/speckit.mode spec
 
 # Customize framework opinions
-/mode --no-contracts  # Disable API contracts
-/mode --tdd           # Enable TDD
-/mode --risk-tests    # Enable risk-based testing
-/mode --reset-opinions  # Reset to mode defaults
+/speckit.mode --no-contracts  # Disable API contracts
+/speckit.mode --tdd           # Enable TDD
+/speckit.mode --risk-tests    # Enable risk-based testing
+/speckit.mode --reset-opinions  # Reset to mode defaults
 
 # Learn more about modes and opinions
-/mode --info
+/speckit.mode --info
 ```
 
 **Recommendation:**
 
 - Use **`build` mode** for: Individual development, rapid prototyping, quick wins, senior engineer autonomy
 - Use **`spec` mode** for: Team collaboration, complex systems, comprehensive documentation, rigorous validation
-- Switch between modes as needed: `/mode build` for fast iteration, `/mode spec` for thorough planning
+- Switch between modes as needed: `/speckit.mode build` for fast iteration, `/speckit.mode spec` for thorough planning
 
 1. **Project Initialization (`/init`)**  
    **Action:** From the project root, run the Agentic SDLC Spec Kit `init` command (e.g., `specify init <project> --team-ai-directives https://github.com/your-org/team-ai-directives.git`) to configure local settings and clone the shared `team-ai-directives` modules.  
@@ -304,7 +304,7 @@ Your development needs may change as features evolve:
 ### When to Switch from Build to Spec Mode
 
 ```bash
-/mode spec
+/speckit.mode spec
 ```
 
 **Indicators:**
@@ -317,7 +317,7 @@ Your development needs may change as features evolve:
 ### When to Switch from Spec to Build Mode
 
 ```bash
-/mode build
+/speckit.mode build
 ```
 
 **Indicators:**

roadmap.md

@@ -25,9 +25,9 @@
 
 ### **Workflow Modes Feature** - **COMPLETED**
 
-- ✅ **Mode Switching Command**: `/mode` command to set build/spec workflow modes and framework options (spec mode is default)
+- ✅ **Mode Switching Command**: `/speckit.mode` command to set build/spec workflow modes and framework options (spec mode is default)
 - ✅ **Consolidated Configuration**: Unified `.specify/config/mode.json` with `options` section replacing separate `opinions.json`
-- ✅ **Framework Options**: Configurable TDD, contracts, data models, and risk-based testing via `/mode` command
+- ✅ **Framework Options**: Configurable TDD, contracts, data models, and risk-based testing via `/speckit.mode` command
 - ✅ **Mode State Persistence**: Store current mode, options, and history in single config file
 - ✅ **Mode-Aware Commands**: `/specify`, `/clarify`, `/plan`, `/implement`, `/analyze` commands adapted for mode-aware behavior
 - ✅ **Mode Validation**: Commands validate mode compatibility and provide guidance
@@ -64,7 +64,7 @@
 
 - ✅ **Risk Extraction**: Standardized severity levels (Critical/High/Medium/Low) in `check-prerequisites.sh`
 - ✅ **Automated Test Generation**: `generate-risk-tests.sh` creates targeted test tasks
-- ✅ **Mode Integration**: Risk-based testing configurable via `/mode --risk-tests` command
+- ✅ **Mode Integration**: Risk-based testing configurable via `/speckit.mode --risk-tests` command
 - ✅ **Test Evidence Capture**: `/implement` preserves risk mitigation validation
 
 #### **Dual Execution Loop Infrastructure**
@@ -114,7 +114,7 @@
 
 #### **Configurable Framework Options** *(100% Complete)* - **MEDIUM PRIORITY** - Addresses over-opinionated critique
 
-- ✅ **Opt-in Architecture Patterns**: TDD, contracts, data models, risk-based testing become user-configurable via `/mode` command
+- ✅ **Opt-in Architecture Patterns**: TDD, contracts, data models, risk-based testing become user-configurable via `/speckit.mode` command
 - ✅ **Consolidated Configuration**: Unified `config.json` with `options` section
 - ✅ **Mode-Based Preferences**: Different defaults for build vs spec modes
 - ✅ **Reduced Mandatory Options**: Core workflow preserved, options made optional

scripts/bash/check-prerequisites.sh

@@ -150,7 +150,7 @@ PY
 # Extract mode configuration
 get_mode_config() {
     local config_file
-    config_file=$(get_global_config_path)
+    config_file=$(get_config_path)
 
     # Extract current mode and options from consolidated config
     python3 - "$config_file" <<'PY'
@@ -228,7 +228,7 @@ fi
 if [[ ! -f "$IMPL_PLAN" ]]; then
     # Get current mode to determine if plan.md is required
     current_mode="spec"
-    global_config=$(get_global_config_path)
+    global_config=$(get_config_path)
     if [[ -f "$global_config" ]]; then
         current_mode=$(python3 -c "
 import json

scripts/bash/common.sh

@@ -13,11 +13,33 @@ get_global_config_path() {
     echo "$config_home/specify/config.json"
 }
 
-# Get current workflow mode from global config (build or spec)
+# Get project-level config path (.specify/config.json)
+get_project_config_path() {
+    local repo_root=$(get_repo_root)
+    echo "$repo_root/.specify/config.json"
+}
+
+# Get config path with hierarchical resolution
+# Priority: 1) Project config  2) User config  3) Default to project
+get_config_path() {
+    local project_config=$(get_project_config_path)
+    local user_config=$(get_global_config_path)
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        # Default to project-level config
+        echo "$project_config"
+    fi
+}
+
+# Get current workflow mode from config (build or spec)
 # Defaults to "spec" if config doesn't exist or mode is invalid
 get_current_mode() {
     local config_file
-    config_file=$(get_global_config_path)
+    config_file=$(get_config_path)
 
     # Default to spec mode if no config exists
     if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then
@@ -43,7 +65,7 @@ get_current_mode() {
 get_mode_config() {
     local key="$1"
     local config_file
-    config_file=$(get_global_config_path)
+    config_file=$(get_config_path)
 
     # Default to false if no config exists or jq not available
     if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then
@@ -62,11 +84,11 @@ get_mode_config() {
     echo "$value"
 }
 
-# Get architecture diagram format from global config (mermaid or ascii)
+# Get architecture diagram format from config (mermaid or ascii)
 # Defaults to "mermaid" if config doesn't exist or format is invalid
 get_architecture_diagram_format() {
     local config_file
-    config_file=$(get_global_config_path)
+    config_file=$(get_config_path)
 
     # Default to mermaid if no config exists or jq not available
     if [[ ! -f "$config_file" ]] || ! command -v jq >/dev/null 2>&1; then

scripts/bash/create-new-feature.sh

@@ -180,6 +180,25 @@ get_global_config_path() {
     echo "$config_home/specify/config.json"
 }
 
+# Get project-level config path (.specify/config.json)
+get_project_config_path() {
+    echo "$REPO_ROOT/.specify/config.json"
+}
+
+# Get config path with hierarchical resolution
+get_config_path() {
+    local project_config=$(get_project_config_path)
+    local user_config=$(get_global_config_path)
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        echo "$project_config"
+    fi
+}
+
 SPECS_DIR="$REPO_ROOT/specs"
 mkdir -p "$SPECS_DIR"
 
@@ -304,7 +323,7 @@ replace_date_placeholders() {
 }
 
 # Mode-aware template selection
-MODE_FILE=$(get_global_config_path)
+MODE_FILE=$(get_config_path)
 CURRENT_MODE="spec"
 if [ -f "$MODE_FILE" ]; then
     CURRENT_MODE=$(python3 -c "

scripts/bash/implement.sh

@@ -122,7 +122,7 @@ load_implementation_context() {
     # Get current workflow mode
     local workflow_mode="spec"  # Default
     local global_config
-    global_config=$(get_global_config_path)
+    global_config=$(get_config_path)
     if [[ -f "$global_config" ]]; then
         workflow_mode=$(jq -r '.workflow.current_mode // "spec"' "$global_config" 2>/dev/null || echo "spec")
     fi
@@ -444,7 +444,7 @@ handle_task_failure() {
     # Get workflow mode for mode-aware rollback
     local mode="spec"  # Default
     local global_config
-    global_config=$(get_global_config_path)
+    global_config=$(get_config_path)
     if [[ -f "$global_config" ]]; then
         mode=$(jq -r '.workflow.current_mode // "spec"' "$global_config" 2>/dev/null || echo "spec")
     fi

scripts/bash/spec-hooks-install.sh

@@ -77,8 +77,39 @@ 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"
+# Get config path with hierarchical resolution (project-level preferred)
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        pwd
+    fi
+}
+
+get_project_config_path() {
+    local repo_root=$(get_repo_root)
+    echo "$repo_root/.specify/config.json"
+}
+
+get_global_config_path() {
+    local config_home="\${XDG_CONFIG_HOME:-\$HOME/.config}"
+    echo "$config_home/specify/config.json"
+}
+
+get_config_path() {
+    local project_config=$(get_project_config_path)
+    local user_config=$(get_global_config_path)
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        echo "$project_config"
+    fi
+}
+
+GLOBAL_CONFIG=$(get_config_path)
 
 # Check if spec sync is enabled for this project
 if [[ ! -f "\$GLOBAL_CONFIG" ]]; then

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

@@ -32,8 +32,22 @@ log_error() {
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Check if spec sync is enabled (global config)
-CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+# Get config path with hierarchical resolution
+get_config_path() {
+    local project_config="$PROJECT_ROOT/.specify/config.json"
+    local user_config="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        echo "$project_config"
+    fi
+}
+
+# Check if spec sync is enabled
+CONFIG_FILE=$(get_config_path)
 if [[ ! -f "$CONFIG_FILE" ]]; then
     exit 0
 fi

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

@@ -32,8 +32,22 @@ log_error() {
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Check if spec sync is enabled (global config)
-CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+# Get config path with hierarchical resolution
+get_config_path() {
+    local project_config="$PROJECT_ROOT/.specify/config.json"
+    local user_config="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        echo "$project_config"
+    fi
+}
+
+# Check if spec sync is enabled
+CONFIG_FILE=$(get_config_path)
 if [[ ! -f "$CONFIG_FILE" ]]; then
     exit 0
 fi

scripts/bash/spec-sync-pre-push.sh

@@ -32,8 +32,22 @@ log_error() {
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 
-# Check if spec sync is enabled (global config)
-CONFIG_FILE="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+# Get config path with hierarchical resolution
+get_config_path() {
+    local project_config="$PROJECT_ROOT/.specify/config.json"
+    local user_config="${XDG_CONFIG_HOME:-$HOME/.config}/specify/config.json"
+    
+    if [[ -f "$project_config" ]]; then
+        echo "$project_config"
+    elif [[ -f "$user_config" ]]; then
+        echo "$user_config"
+    else
+        echo "$project_config"
+    fi
+}
+
+# Check if spec sync is enabled
+CONFIG_FILE=$(get_config_path)
 if [[ ! -f "$CONFIG_FILE" ]]; then
     exit 0
 fi