diff --git a/scripts/bash/check-task-prerequisites.sh b/scripts/bash/check-task-prerequisites.sh index e578f864..cb730d3c 100644 --- a/scripts/bash/check-task-prerequisites.sh +++ b/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 diff --git a/scripts/bash/common.sh b/scripts/bash/common.sh index 582d940d..62f990b7 100644 --- a/scripts/bash/common.sh +++ b/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; } diff --git a/scripts/bash/create-new-feature.sh b/scripts/bash/create-new-feature.sh index bc4b4067..50ede245 100644 --- a/scripts/bash/create-new-feature.sh +++ b/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] +# +# 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 diff --git a/scripts/bash/get-feature-paths.sh b/scripts/bash/get-feature-paths.sh index 016727db..aa7f5c6c 100644 --- a/scripts/bash/get-feature-paths.sh +++ b/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" diff --git a/scripts/bash/setup-plan.sh b/scripts/bash/setup-plan.sh index 1da42657..ff709310 100644 --- a/scripts/bash/setup-plan.sh +++ b/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 diff --git a/scripts/bash/update-agent-context.sh b/scripts/bash/update-agent-context.sh index 2ad22cbb..a539789d 100644 --- a/scripts/bash/update-agent-context.sh +++ b/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) diff --git a/scripts/powershell/check-task-prerequisites.ps1 b/scripts/powershell/check-task-prerequisites.ps1 index 3be870f3..5c274975 100644 --- a/scripts/powershell/check-task-prerequisites.ps1 +++ b/scripts/powershell/check-task-prerequisites.ps1 @@ -1,4 +1,49 @@ #!/usr/bin/env pwsh + +# ============================================================================== +# Check Task Prerequisites Script (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash check-task-prerequisites.sh script. +# 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.ps1 [-Json] +# +# PARAMETERS: +# -Json Output results in JSON format for programmatic consumption +# +# 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 +# - PowerShell 5.1+ or PowerShell Core 6+ +# +# 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.ps1 +# .\check-task-prerequisites.ps1 -Json +# +# RELATED SCRIPTS: +# - common.ps1: Provides shared functions for path resolution and validation +# - create-new-feature.ps1: Creates the feature structure that this script validates +# - setup-plan.ps1: Creates the plan.md file that this script requires +# - check-task-prerequisites.sh: Bash equivalent of this script +# +# ============================================================================== + [CmdletBinding()] param([switch]$Json) $ErrorActionPreference = 'Stop' diff --git a/scripts/powershell/common.ps1 b/scripts/powershell/common.ps1 index 3e04a1ec..2e6364d7 100644 --- a/scripts/powershell/common.ps1 +++ b/scripts/powershell/common.ps1 @@ -1,5 +1,55 @@ #!/usr/bin/env pwsh -# Common PowerShell functions analogous to common.sh (moved to powershell/) + +# ============================================================================== +# Common Functions Library (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash common.sh library. Provides shared utility +# functions and path resolution logic used across all Spec-Driven Development +# workflow scripts. This library ensures consistent behavior for git operations, +# feature branch validation, and file system path management in Windows and +# cross-platform PowerShell environments. +# +# FUNCTIONS: +# Get-RepoRoot() - Returns the root directory of the git repository +# Get-CurrentBranch() - Returns the name of the current git branch +# Test-FeatureBranch() - Validates feature branch naming convention +# Get-FeatureDir() - Constructs feature directory path from repo root and branch +# Get-FeaturePathsEnv() - Generates all standard feature-related file paths +# Test-FileExists() - Displays file existence status with checkmark/X +# Test-DirHasFiles() - 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 dot-sourced by other PowerShell scripts: +# . "$PSScriptRoot/common.ps1" +# $paths = Get-FeaturePathsEnv +# +# DEPENDENCIES: +# - git (for repository operations) +# - PowerShell 5.1+ or PowerShell Core 6+ (for cross-platform support) +# +# CROSS-PLATFORM NOTES: +# - Uses Join-Path for proper path handling across Windows/Linux/macOS +# - Compatible with both Windows PowerShell and PowerShell Core +# - Handles both forward and backward slashes appropriately +# +# ============================================================================== function Get-RepoRoot { git rev-parse --show-toplevel diff --git a/scripts/powershell/create-new-feature.ps1 b/scripts/powershell/create-new-feature.ps1 index b99f0889..763fe307 100644 --- a/scripts/powershell/create-new-feature.ps1 +++ b/scripts/powershell/create-new-feature.ps1 @@ -1,5 +1,61 @@ #!/usr/bin/env pwsh -# Create a new feature (moved to powershell/) + +# ============================================================================== +# Create New Feature Script (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash create-new-feature.sh script. +# 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.ps1 [-Json] +# +# PARAMETERS: +# -Json Output results in JSON format for programmatic consumption +# FeatureDescription 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.ps1 "User Authentication System" +# .\create-new-feature.ps1 -Json "Payment Processing Integration" +# .\create-new-feature.ps1 "Advanced Search and Filtering Capabilities" +# +# RELATED SCRIPTS: +# - setup-plan.ps1: Next step to create implementation plan +# - check-task-prerequisites.ps1: Validates the created structure +# - create-new-feature.sh: Bash equivalent of this script +# +# ============================================================================== + [CmdletBinding()] param( [switch]$Json, diff --git a/scripts/powershell/get-feature-paths.ps1 b/scripts/powershell/get-feature-paths.ps1 index fc095857..c80eaba8 100644 --- a/scripts/powershell/get-feature-paths.ps1 +++ b/scripts/powershell/get-feature-paths.ps1 @@ -1,4 +1,61 @@ #!/usr/bin/env pwsh + +# ============================================================================== +# Get Feature Paths Script (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash get-feature-paths.sh script. +# 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.ps1 +# +# PREREQUISITES: +# - Must be run from within a git repository +# - Must be on a valid feature branch (format: XXX-feature-name) +# - PowerShell 5.1+ or PowerShell Core 6+ +# +# 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.ps1 +# +# Example output: +# REPO_ROOT: C:\Users\user\my-project +# BRANCH: 001-user-authentication +# FEATURE_DIR: C:\Users\user\my-project\specs\001-user-authentication +# FEATURE_SPEC: C:\Users\user\my-project\specs\001-user-authentication\spec.md +# IMPL_PLAN: C:\Users\user\my-project\specs\001-user-authentication\plan.md +# TASKS: C:\Users\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.ps1: Provides the path generation functions +# - check-task-prerequisites.ps1: Uses these paths for validation +# - get-feature-paths.sh: Bash equivalent of this script +# +# ============================================================================== + param() $ErrorActionPreference = 'Stop' diff --git a/scripts/powershell/setup-plan.ps1 b/scripts/powershell/setup-plan.ps1 index b0264405..cdd39d67 100644 --- a/scripts/powershell/setup-plan.ps1 +++ b/scripts/powershell/setup-plan.ps1 @@ -1,4 +1,61 @@ #!/usr/bin/env pwsh + +# ============================================================================== +# Setup Implementation Plan Script (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash setup-plan.sh script. +# 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.ps1 [-Json] +# +# PARAMETERS: +# -Json Output results in JSON format for programmatic consumption +# +# 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.ps1) +# - PowerShell 5.1+ or PowerShell Core 6+ +# +# TEMPLATE LOCATION: +# The script looks for the plan template at: +# $REPO_ROOT/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.ps1 +# .\setup-plan.ps1 -Json +# +# RELATED SCRIPTS: +# - create-new-feature.ps1: Previous step that creates the feature structure +# - check-task-prerequisites.ps1: Validates that plan.md exists before implementation +# - common.ps1: Provides shared path resolution functions +# - setup-plan.sh: Bash equivalent of this script +# +# ============================================================================== + [CmdletBinding()] param([switch]$Json) $ErrorActionPreference = 'Stop' diff --git a/scripts/powershell/update-agent-context.ps1 b/scripts/powershell/update-agent-context.ps1 index 4578ed30..443dc38a 100644 --- a/scripts/powershell/update-agent-context.ps1 +++ b/scripts/powershell/update-agent-context.ps1 @@ -1,4 +1,77 @@ #!/usr/bin/env pwsh + +# ============================================================================== +# Update Agent Context Script (PowerShell) +# ============================================================================== +# +# DESCRIPTION: +# PowerShell equivalent of the bash update-agent-context.sh script. +# 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.ps1 [AgentType] +# +# PARAMETERS: +# AgentType 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 +# - **Testing**: Testing frameworks and approaches +# - **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 +# - Uses regex-based text processing for reliable updates +# +# For new files: +# - Creates from agent-file-template.md if available +# - 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 +# - PowerShell 5.1+ or PowerShell Core 6+ +# +# EXIT CODES: +# 0 - Agent context files updated successfully +# 1 - Missing plan.md file or invalid agent type +# +# EXAMPLES: +# .\update-agent-context.ps1 # Update all agent files +# .\update-agent-context.ps1 claude # Update only Claude context +# .\update-agent-context.ps1 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.ps1: Creates the plan.md file that this script reads +# - common.ps1: Could be used for shared functionality (currently not used) +# - update-agent-context.sh: Bash equivalent of this script +# +# ============================================================================== + [CmdletBinding()] param([string]$AgentType) $ErrorActionPreference = 'Stop'