Add comprehensive documentation to workflow automation scripts

scripts/bash/check-task-prerequisites.sh

@@ -1,4 +1,48 @@
 #!/usr/bin/env bash
+
+# ==============================================================================
+# Check Task Prerequisites Script
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Validates that all required prerequisites are in place before starting
+#   implementation tasks in the Spec-Driven Development workflow. This script
+#   ensures that the current branch is a valid feature branch, that the feature
+#   directory structure exists, and that essential planning documents are present.
+#
+# USAGE:
+#   ./check-task-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json    Output results in JSON format for programmatic consumption
+#   --help    Show usage information and exit
+#   -h        Show usage information and exit
+#
+# PREREQUISITES:
+#   - Must be run from within a git repository
+#   - Must be on a feature branch (format: XXX-feature-name)
+#   - Feature directory must exist in specs/
+#   - plan.md must exist in the feature directory
+#
+# OUTPUT:
+#   In default mode: Displays feature directory path and available documentation files
+#   In JSON mode: Returns structured JSON with FEATURE_DIR and AVAILABLE_DOCS array
+#
+# EXIT CODES:
+#   0 - All prerequisites met successfully
+#   1 - Missing prerequisites or invalid branch/directory structure
+#
+# EXAMPLES:
+#   ./check-task-prerequisites.sh
+#   ./check-task-prerequisites.sh --json
+#
+# RELATED SCRIPTS:
+#   - common.sh: Provides shared functions for path resolution and validation
+#   - create-new-feature.sh: Creates the feature structure that this script validates
+#   - setup-plan.sh: Creates the plan.md file that this script requires
+#
+# ==============================================================================
+
 set -e
 JSON_MODE=false
 for arg in "$@"; do case "$arg" in --json) JSON_MODE=true ;; --help|-h) echo "Usage: $0 [--json]"; exit 0 ;; esac; done

scripts/bash/common.sh

@@ -1,5 +1,49 @@
 #!/usr/bin/env bash
-# (Moved to scripts/bash/) Common functions and variables for all scripts
+
+# ==============================================================================
+# Common Functions Library
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Shared utility functions and path resolution logic used across all
+#   Spec-Driven Development workflow scripts. This library provides consistent
+#   behavior for git operations, feature branch validation, and file system
+#   path management.
+#
+# FUNCTIONS:
+#   get_repo_root()        - Returns the root directory of the git repository
+#   get_current_branch()   - Returns the name of the current git branch
+#   check_feature_branch() - Validates feature branch naming convention
+#   get_feature_dir()      - Constructs feature directory path from repo root and branch
+#   get_feature_paths()    - Generates all standard feature-related file paths
+#   check_file()           - Displays file existence status with checkmark/X
+#   check_dir()            - Displays directory existence status with contents check
+#
+# FEATURE BRANCH NAMING CONVENTION:
+#   Feature branches must follow the pattern: XXX-feature-name
+#   Where XXX is a 3-digit zero-padded number (001, 002, etc.)
+#   Examples: 001-user-authentication, 042-payment-integration
+#
+# STANDARD FEATURE DIRECTORY STRUCTURE:
+#   specs/XXX-feature-name/
+#   ├── spec.md           # Feature specification (required)
+#   ├── plan.md           # Implementation plan (required)
+#   ├── tasks.md          # Task breakdown (optional)
+#   ├── research.md       # Research notes (optional)
+#   ├── data-model.md     # Data model documentation (optional)
+#   ├── quickstart.md     # Quick start guide (optional)
+#   └── contracts/        # API contracts and interfaces (optional)
+#
+# USAGE:
+#   This file should be sourced by other scripts:
+#   source "$SCRIPT_DIR/common.sh"
+#   eval $(get_feature_paths)
+#
+# DEPENDENCIES:
+#   - git (for repository operations)
+#   - bash 4.0+ (for associative arrays and advanced features)
+#
+# ==============================================================================
 
 get_repo_root() { git rev-parse --show-toplevel; }
 get_current_branch() { git rev-parse --abbrev-ref HEAD; }

scripts/bash/create-new-feature.sh

@@ -1,5 +1,63 @@
 #!/usr/bin/env bash
-# (Moved to scripts/bash/) Create a new feature with branch, directory structure, and template
+
+# ==============================================================================
+# Create New Feature Script
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Initializes a new feature in the Spec-Driven Development workflow by:
+#   1. Creating a new feature branch with proper naming convention
+#   2. Setting up the feature directory structure in specs/
+#   3. Copying the specification template to start feature definition
+#   4. Auto-incrementing feature numbers for consistent organization
+#
+# USAGE:
+#   ./create-new-feature.sh [OPTIONS] <feature_description>
+#
+# OPTIONS:
+#   --json    Output results in JSON format for programmatic consumption
+#   --help    Show usage information and exit
+#   -h        Show usage information and exit
+#
+# ARGUMENTS:
+#   feature_description    A descriptive name for the feature (multiple words allowed)
+#                         Will be normalized to lowercase with hyphens
+#
+# FEATURE NUMBERING:
+#   Features are automatically numbered starting from 001, incrementing based on
+#   existing feature directories. The script finds the highest existing number
+#   and adds 1 to ensure sequential, non-conflicting feature numbers.
+#
+# BRANCH NAMING:
+#   Created branches follow the pattern: XXX-first-few-words
+#   - XXX: 3-digit zero-padded feature number
+#   - Only first 3 words of description are used for brevity
+#   - All text converted to lowercase with hyphens as separators
+#   - Special characters are removed or converted to hyphens
+#
+# DIRECTORY STRUCTURE CREATED:
+#   specs/XXX-feature-name/
+#   └── spec.md           # Feature specification (copied from template)
+#
+# OUTPUT:
+#   In default mode: Displays branch name, spec file path, and feature number
+#   In JSON mode: Returns structured JSON with BRANCH_NAME, SPEC_FILE, FEATURE_NUM
+#
+# EXIT CODES:
+#   0 - Feature created successfully
+#   1 - Missing feature description or other error
+#
+# EXAMPLES:
+#   ./create-new-feature.sh "User Authentication System"
+#   ./create-new-feature.sh --json "Payment Processing Integration"
+#   ./create-new-feature.sh "Advanced Search and Filtering Capabilities"
+#
+# RELATED SCRIPTS:
+#   - setup-plan.sh: Next step to create implementation plan
+#   - check-task-prerequisites.sh: Validates the created structure
+#
+# ==============================================================================
+
 set -e
 
 JSON_MODE=false

scripts/bash/get-feature-paths.sh

@@ -1,4 +1,58 @@
 #!/usr/bin/env bash
+
+# ==============================================================================
+# Get Feature Paths Script
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Displays all relevant file and directory paths for the current feature branch
+#   in the Spec-Driven Development workflow. This utility script helps developers
+#   quickly identify where feature-related files are located and provides a
+#   convenient way to inspect the current workspace configuration.
+#
+# USAGE:
+#   ./get-feature-paths.sh
+#
+# PREREQUISITES:
+#   - Must be run from within a git repository
+#   - Must be on a valid feature branch (format: XXX-feature-name)
+#
+# OUTPUT:
+#   Displays the following paths:
+#   - REPO_ROOT: Git repository root directory
+#   - BRANCH: Current git branch name
+#   - FEATURE_DIR: Feature-specific directory in specs/
+#   - FEATURE_SPEC: Path to spec.md file
+#   - IMPL_PLAN: Path to plan.md file
+#   - TASKS: Path to tasks.md file
+#
+# EXIT CODES:
+#   0 - Successfully displayed paths
+#   1 - Not on a valid feature branch or other error
+#
+# EXAMPLES:
+#   ./get-feature-paths.sh
+#
+#   Example output:
+#   REPO_ROOT: /home/user/my-project
+#   BRANCH: 001-user-authentication
+#   FEATURE_DIR: /home/user/my-project/specs/001-user-authentication
+#   FEATURE_SPEC: /home/user/my-project/specs/001-user-authentication/spec.md
+#   IMPL_PLAN: /home/user/my-project/specs/001-user-authentication/plan.md
+#   TASKS: /home/user/my-project/specs/001-user-authentication/tasks.md
+#
+# USE CASES:
+#   - Debugging workflow scripts
+#   - Setting up IDE workspace paths
+#   - Creating custom automation scripts
+#   - Troubleshooting missing files or directories
+#
+# RELATED SCRIPTS:
+#   - common.sh: Provides the path generation functions
+#   - check-task-prerequisites.sh: Uses these paths for validation
+#
+# ==============================================================================
+
 set -e
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 source "$SCRIPT_DIR/common.sh"

scripts/bash/setup-plan.sh

@@ -1,4 +1,60 @@
 #!/usr/bin/env bash
+
+# ==============================================================================
+# Setup Implementation Plan Script
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Creates the implementation plan (plan.md) for the current feature by copying
+#   the plan template into the feature directory. This is the second step in the
+#   Spec-Driven Development workflow, following the feature specification creation.
+#   The plan.md file contains technical implementation details, architecture
+#   decisions, and step-by-step implementation guidance.
+#
+# USAGE:
+#   ./setup-plan.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json    Output results in JSON format for programmatic consumption
+#   --help    Show usage information and exit
+#   -h        Show usage information and exit
+#
+# PREREQUISITES:
+#   - Must be run from within a git repository
+#   - Must be on a valid feature branch (format: XXX-feature-name)
+#   - Feature directory should exist (created by create-new-feature.sh)
+#
+# TEMPLATE LOCATION:
+#   The script looks for the plan template at:
+#   $REPO_ROOT/.specify/templates/plan-template.md
+#   If the template doesn't exist, the script will still create the target
+#   directory structure but won't copy any template content.
+#
+# OUTPUT:
+#   In default mode: Displays paths for feature spec, implementation plan,
+#                   feature directory, and current branch
+#   In JSON mode: Returns structured JSON with the same information
+#
+# EXIT CODES:
+#   0 - Plan setup completed successfully
+#   1 - Not on a valid feature branch or other error
+#
+# WORKFLOW INTEGRATION:
+#   This script is typically called as part of the /plan command in AI coding
+#   assistants, after the initial feature specification has been created but
+#   before implementation begins.
+#
+# EXAMPLES:
+#   ./setup-plan.sh
+#   ./setup-plan.sh --json
+#
+# RELATED SCRIPTS:
+#   - create-new-feature.sh: Previous step that creates the feature structure
+#   - check-task-prerequisites.sh: Validates that plan.md exists before implementation
+#   - common.sh: Provides shared path resolution functions
+#
+# ==============================================================================
+
 set -e
 JSON_MODE=false
 for arg in "$@"; do case "$arg" in --json) JSON_MODE=true ;; --help|-h) echo "Usage: $0 [--json]"; exit 0 ;; esac; done

scripts/bash/update-agent-context.sh

@@ -1,4 +1,74 @@
 #!/usr/bin/env bash
+
+# ==============================================================================
+# Update Agent Context Script
+# ==============================================================================
+#
+# DESCRIPTION:
+#   Updates AI coding assistant context files with information from the current
+#   feature's implementation plan. This script extracts technical details like
+#   programming language, frameworks, database choices, and project structure
+#   from plan.md and updates the appropriate agent configuration files to ensure
+#   the AI assistant has current project context.
+#
+# USAGE:
+#   ./update-agent-context.sh [AGENT_TYPE]
+#
+# ARGUMENTS:
+#   AGENT_TYPE    Specific agent to update (optional)
+#                 Options: claude, gemini, copilot, cursor
+#                 If omitted, updates all existing agent files or creates Claude by default
+#
+# SUPPORTED AGENTS:
+#   - claude: Updates CLAUDE.md (Claude Code)
+#   - gemini: Updates GEMINI.md (Gemini CLI)
+#   - copilot: Updates .github/copilot-instructions.md (GitHub Copilot)
+#   - cursor: Updates .cursor/rules/specify-rules.mdc (Cursor IDE)
+#
+# EXTRACTED INFORMATION:
+#   From plan.md, the script extracts:
+#   - **Language/Version**: Programming language and version
+#   - **Primary Dependencies**: Main frameworks and libraries
+#   - **Storage**: Database and storage solutions
+#   - **Project Type**: Application type (web, mobile, CLI, etc.)
+#
+# AGENT FILE UPDATES:
+#   For existing files:
+#   - Updates "Active Technologies" section with new tech stack
+#   - Updates "Recent Changes" section with latest feature info
+#   - Updates "Last updated" timestamp
+#   - Preserves manual additions between special comment markers
+#
+#   For new files:
+#   - Creates from agent-file-template.md
+#   - Populates with project-specific information
+#   - Sets up appropriate commands based on detected technology
+#   - Configures project structure based on project type
+#
+# PREREQUISITES:
+#   - Must be run from within a git repository
+#   - plan.md must exist in current feature directory
+#   - Python 3 available for text processing
+#
+# EXIT CODES:
+#   0 - Agent context files updated successfully
+#   1 - Missing plan.md file or invalid agent type
+#
+# EXAMPLES:
+#   ./update-agent-context.sh              # Update all agent files
+#   ./update-agent-context.sh claude       # Update only Claude context
+#   ./update-agent-context.sh copilot      # Update only GitHub Copilot context
+#
+# TEMPLATE DEPENDENCIES:
+#   - agent-file-template.md: Base template for creating new agent files
+#   - Must be located at .specify/templates/agent-file-template.md
+#
+# RELATED SCRIPTS:
+#   - setup-plan.sh: Creates the plan.md file that this script reads
+#   - common.sh: Could be used for shared functionality (currently not used)
+#
+# ==============================================================================
+
 set -e
 REPO_ROOT=$(git rev-parse --show-toplevel)
 CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)