From 152d701a030ee859569750b938577370131ce24b Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Thu, 2 Oct 2025 12:15:06 +0530 Subject: [PATCH 1/7] Add alignment check scripts and improve workflow guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .gitignore | 3 +- scripts/bash/alignment-check-all-features.sh | 121 +++++++++++++++++ .../alignment-check-all-features.ps1 | 124 ++++++++++++++++++ templates/alignment-analysis-template.md | 87 ++++++++++++ templates/commands/align.md | 48 +++++++ templates/commands/specify.md | 2 +- 6 files changed, 383 insertions(+), 2 deletions(-) create mode 100755 scripts/bash/alignment-check-all-features.sh create mode 100644 scripts/powershell/alignment-check-all-features.ps1 create mode 100644 templates/alignment-analysis-template.md create mode 100644 templates/commands/align.md diff --git a/.gitignore b/.gitignore index 42a1fbbfa..505e9be7e 100644 --- a/.gitignore +++ b/.gitignore @@ -42,4 +42,5 @@ env/ # Spec Kit-specific files .genreleases/ *.zip -sdd-*/ \ No newline at end of file +sdd-*/ +settings.local.json diff --git a/scripts/bash/alignment-check-all-features.sh b/scripts/bash/alignment-check-all-features.sh new file mode 100755 index 000000000..6c54c5eab --- /dev/null +++ b/scripts/bash/alignment-check-all-features.sh @@ -0,0 +1,121 @@ +#!/usr/bin/env bash +# Analyze current feature alignment with all existing features using systems thinking +set -e + +JSON_MODE=false +ARGS=() +for arg in "$@"; do + case "$arg" in + --json) JSON_MODE=true ;; + --help|-h) echo "Usage: $0 [--json] [analysis_focus]"; exit 0 ;; + *) ARGS+=("$arg") ;; + esac +done + +ANALYSIS_FOCUS="${ARGS[*]}" +if [ -z "$ANALYSIS_FOCUS" ]; then + ANALYSIS_FOCUS="Comprehensive Analysis" +fi + +# Resolve repository root. Prefer git information when available, but fall back +# to the script location so the workflow still functions in repositories that +# were initialised with --no-git. +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +FALLBACK_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)" +if git rev-parse --show-toplevel >/dev/null 2>&1; then + REPO_ROOT=$(git rev-parse --show-toplevel) + HAS_GIT=true +else + REPO_ROOT="$FALLBACK_ROOT" + HAS_GIT=false +fi + +cd "$REPO_ROOT" + +# Get current branch name and find current spec +if [ "$HAS_GIT" = true ]; then + CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) +else + # If no git, try to determine current feature from specs directory + # This is a fallback - in practice, alignment analysis should run on active feature branch + CURRENT_BRANCH=$(ls -t specs/ | head -n 1 2>/dev/null || echo "") +fi + +if [ -z "$CURRENT_BRANCH" ] || [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then + echo "Error: Alignment analysis must be run from a feature branch (created by /specify)" >&2 + exit 1 +fi + +CURRENT_SPEC="$REPO_ROOT/specs/$CURRENT_BRANCH/spec.md" +if [ ! -f "$CURRENT_SPEC" ]; then + echo "Error: Current specification not found at $CURRENT_SPEC" >&2 + exit 1 +fi + +# Find all existing specifications +ALL_SPECS=() +SPECS_DIR="$REPO_ROOT/specs" +if [ -d "$SPECS_DIR" ]; then + for dir in "$SPECS_DIR"/*; do + [ -d "$dir" ] || continue + spec_file="$dir/spec.md" + if [ -f "$spec_file" ] && [ "$spec_file" != "$CURRENT_SPEC" ]; then + ALL_SPECS+=("$spec_file") + fi + done +fi + +# Create analysis file in current feature directory +FEATURE_DIR="$(dirname "$CURRENT_SPEC")" +ANALYSIS_FILE="$FEATURE_DIR/alignment-analysis.md" + +# Create analysis file from template +TEMPLATE="$REPO_ROOT/templates/alignment-analysis-template.md" +if [ -f "$TEMPLATE" ]; then + cp "$TEMPLATE" "$ANALYSIS_FILE" +else + touch "$ANALYSIS_FILE" +fi + +# Add clarification line to current spec.md for /clarify to pick up +CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]" + +# Find the Requirements section and add the clarification line +if [ -f "$CURRENT_SPEC" ]; then + # Check if the clarification line already exists to avoid duplicates + if ! grep -q "alignment-analysis.md" "$CURRENT_SPEC"; then + # Find the line with "### Functional Requirements" and add our clarification after it + if grep -q "### Functional Requirements" "$CURRENT_SPEC"; then + # Use sed to add the line after "### Functional Requirements" + sed -i.bak "/### Functional Requirements/a\\ +$CLARIFICATION_LINE" "$CURRENT_SPEC" && rm "$CURRENT_SPEC.bak" + else + # If no Functional Requirements section, add to end of file + echo "" >> "$CURRENT_SPEC" + echo "$CLARIFICATION_LINE" >> "$CURRENT_SPEC" + fi + fi +fi + +# Build JSON output with all specs array +if $JSON_MODE; then + printf '{"CURRENT_SPEC":"%s","ALL_SPECS":[' "$CURRENT_SPEC" + + # Add all specs as JSON array + first=true + for spec in "${ALL_SPECS[@]}"; do + if [ "$first" = true ]; then + first=false + else + printf ',' + fi + printf '"%s"' "$spec" + done + + printf '],"ANALYSIS_FILE":"%s","ANALYSIS_FOCUS":"%s"}\n' "$ANALYSIS_FILE" "$ANALYSIS_FOCUS" +else + echo "CURRENT_SPEC: $CURRENT_SPEC" + echo "ALL_SPECS: ${ALL_SPECS[*]}" + echo "ANALYSIS_FILE: $ANALYSIS_FILE" + echo "ANALYSIS_FOCUS: $ANALYSIS_FOCUS" +fi \ No newline at end of file diff --git a/scripts/powershell/alignment-check-all-features.ps1 b/scripts/powershell/alignment-check-all-features.ps1 new file mode 100644 index 000000000..19bf91b1f --- /dev/null +++ b/scripts/powershell/alignment-check-all-features.ps1 @@ -0,0 +1,124 @@ +# Analyze current feature alignment with all existing features using systems thinking +param( + [string]$Json = "", + [string[]]$Args = @() +) + +$JsonMode = $Json -eq "{ARGS}" -or $Args -contains "--json" +$AnalysisFocus = ($Args | Where-Object { $_ -ne "--json" }) -join " " +if ([string]::IsNullOrWhiteSpace($AnalysisFocus)) { + $AnalysisFocus = "Comprehensive Analysis" +} + +# Get repository root +$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Definition +$FallbackRoot = Resolve-Path (Join-Path $ScriptDir "../..") + +try { + $RepoRoot = git rev-parse --show-toplevel 2>$null + $HasGit = $true +} catch { + $RepoRoot = $FallbackRoot + $HasGit = $false +} + +Set-Location $RepoRoot + +# Get current branch name and find current spec +if ($HasGit) { + try { + $CurrentBranch = git rev-parse --abbrev-ref HEAD 2>$null + } catch { + $CurrentBranch = "" + } +} else { + # If no git, try to determine current feature from specs directory + $SpecsDirs = Get-ChildItem -Path "specs" -Directory -ErrorAction SilentlyContinue | Sort-Object LastWriteTime -Descending + $CurrentBranch = if ($SpecsDirs) { $SpecsDirs[0].Name } else { "" } +} + +if ([string]::IsNullOrWhiteSpace($CurrentBranch) -or $CurrentBranch -eq "main" -or $CurrentBranch -eq "master") { + Write-Error "Error: Alignment analysis must be run from a feature branch (created by /specify)" + exit 1 +} + +$CurrentSpec = Join-Path $RepoRoot "specs" $CurrentBranch "spec.md" +if (-not (Test-Path $CurrentSpec)) { + Write-Error "Error: Current specification not found at $CurrentSpec" + exit 1 +} + +# Find all existing specifications +$AllSpecs = @() +$SpecsDir = Join-Path $RepoRoot "specs" +if (Test-Path $SpecsDir) { + $SpecDirs = Get-ChildItem -Path $SpecsDir -Directory + foreach ($dir in $SpecDirs) { + $SpecFile = Join-Path $dir.FullName "spec.md" + if ((Test-Path $SpecFile) -and ($SpecFile -ne $CurrentSpec)) { + $AllSpecs += $SpecFile + } + } +} + +# Create analysis file in current feature directory +$FeatureDir = Split-Path -Parent $CurrentSpec +$AnalysisFile = Join-Path $FeatureDir "alignment-analysis.md" + +# Create analysis file from template +$Template = Join-Path $RepoRoot "templates" "alignment-analysis-template.md" +if (Test-Path $Template) { + Copy-Item $Template $AnalysisFile +} else { + New-Item -ItemType File -Path $AnalysisFile -Force | Out-Null +} + +# Add clarification line to current spec.md for /clarify to pick up +$ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]" + +# Find the Requirements section and add the clarification line +if (Test-Path $CurrentSpec) { + $SpecContent = Get-Content $CurrentSpec -Raw + + # Check if the clarification line already exists to avoid duplicates + if (-not $SpecContent.Contains("alignment-analysis.md")) { + $Lines = Get-Content $CurrentSpec + $NewLines = @() + $Added = $false + + foreach ($Line in $Lines) { + $NewLines += $Line + # Add clarification line after "### Functional Requirements" + if ($Line -match "^### Functional Requirements" -and -not $Added) { + $NewLines += $ClarificationLine + $Added = $true + } + } + + # If no Functional Requirements section found, add to end + if (-not $Added) { + $NewLines += "" + $NewLines += $ClarificationLine + } + + # Write back to file + $NewLines | Set-Content $CurrentSpec + } +} + +# Build output +if ($JsonMode) { + $AllSpecsJson = $AllSpecs | ForEach-Object { "`"$_`"" } | Join-String -Separator "," + $Output = @{ + CURRENT_SPEC = $CurrentSpec + ALL_SPECS = $AllSpecs + ANALYSIS_FILE = $AnalysisFile + ANALYSIS_FOCUS = $AnalysisFocus + } + $Output | ConvertTo-Json -Compress +} else { + Write-Output "CURRENT_SPEC: $CurrentSpec" + Write-Output "ALL_SPECS: $($AllSpecs -join ' ')" + Write-Output "ANALYSIS_FILE: $AnalysisFile" + Write-Output "ANALYSIS_FOCUS: $AnalysisFocus" +} \ No newline at end of file diff --git a/templates/alignment-analysis-template.md b/templates/alignment-analysis-template.md new file mode 100644 index 000000000..e7956ebdd --- /dev/null +++ b/templates/alignment-analysis-template.md @@ -0,0 +1,87 @@ +# Alignment Check: [FEATURE NAME] + +**Feature**: `[###-feature-name]` +**Date**: [DATE] +**Analyzed Against**: [Number] existing features + +--- + +## Impact Summary + +**Cross-Feature Interactions**: [Yes/No - if Yes, list which features] +**Conflict Risk**: [None/Low/Medium/High] +**Action Required**: [Yes/No] + +--- + +## Questions to Resolve + +*[Only include this section if there are actual questions. Remove if none.]* + +1. [NEEDS CLARIFICATION: Specific question about interaction between this feature and Feature X] +2. [NEEDS CLARIFICATION: Specific question about shared resource or timing] +3. [NEEDS CLARIFICATION: Specific question about boundary or responsibility] + +--- + +## Issues Found + +*[Only include this section if there are actual issues. Remove if none.]* + +### ⚠️ With Feature [###-feature-name] + +**Issue**: [One-line description of the problem] +**Impact**: [What breaks or goes wrong] +**Fix**: [Specific action to take] + +### ⚠️ With Feature [###-feature-name] + +**Issue**: [One-line description] +**Impact**: [What breaks or goes wrong] +**Fix**: [Specific action to take] + +--- + +## Recommendations + +*[Only include this section if there are actual recommendations. Remove if none.]* + +- [ ] **Do**: [Specific action] because [one-line reason] +- [ ] **Consider**: [Specific action] to prevent [specific problem] +- [ ] **Avoid**: [Specific thing] because [one-line reason] + +--- + +## Feature Dependencies + +*[Only include if there are dependencies. Remove if none.]* + +**This feature depends on**: +- [Feature name]: [What it depends on] + +**Features that will depend on this**: +- [Feature name]: [What they'll need] + +--- + +## Potential Side Effects + +*[Only include if there are notable side effects. Remove if none.]* + +- **[Type of side effect]**: [Brief description] → [What to watch for] + +--- + +## Quick Checklist + +- [ ] All clarification questions answered +- [ ] High/Medium risk issues addressed in spec +- [ ] Recommendations reviewed and incorporated as needed +- [ ] Dependencies documented in spec +- [ ] Clarification line removed from spec.md when complete + +--- + +**Status**: ⏳ Awaiting clarification / ✅ Ready for planning + +*Remove sections that don't apply. Keep it short and actionable.* \ No newline at end of file diff --git a/templates/commands/align.md b/templates/commands/align.md new file mode 100644 index 000000000..45d034ae9 --- /dev/null +++ b/templates/commands/align.md @@ -0,0 +1,48 @@ +--- +description: Analyze how the current feature aligns with existing features using systems thinking to identify conflicts, dependencies, and emergent behaviors. +scripts: + sh: scripts/bash/alignment-check-all-features.sh --json "{ARGS}" + ps: scripts/powershell/alignment-check-all-features.ps1 -Json "{ARGS}" +--- + +The text the user typed after `/align` in the triggering message **is** optional analysis focus. If empty, perform comprehensive alignment analysis. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. + +Given the current feature specification and optional analysis focus, do this: + +1. Run the script `{SCRIPT}` from repo root and parse its JSON output for CURRENT_SPEC, ALL_SPECS, and ANALYSIS_FILE. All file paths must be absolute. + **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. + +2. Load `templates/alignment-analysis-template.md` to understand the alignment analysis framework structure. + +3. Read the current feature specification from CURRENT_SPEC to understand: + - Feature purpose and user scenarios + - Functional requirements + - Key entities and relationships + +4. Analyze ALL_SPECS (array of paths to existing specifications) to identify ONLY actual issues: + - **Real conflicts**: Does this feature conflict with existing features? (shared resources, timing issues, contradictory behavior) + - **Dependencies**: Does this feature depend on or modify behavior from existing features? + - **Side effects**: Will this feature cause unexpected problems in other features? + - **Questions**: What needs clarification about cross-feature interactions? + +5. Be concise and action-oriented: + - **Skip empty sections**: If there are no issues in a category, remove that section entirely + - **One-line summaries**: Issues, impacts, and fixes should each be one line + - **Questions not essays**: Raise specific questions, don't explain systems theory + - **Actionable only**: Only include information that requires a decision or action + - **Target length**: 50-100 lines total, not 500+ lines + +6. Write the alignment analysis to ANALYSIS_FILE using the template structure, including ONLY: + - Impact summary (interactions, risk level, action needed) + - Specific questions that need answers (if any) + - Actual issues found with other features (if any) + - Concrete recommendations (if any) + - Remove any sections that don't apply + +7. Add a single clarification line to the current spec.md file in the Requirements section: + - Add: `- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]` + - This ensures `/clarify` will pick up alignment issues naturally + +8. Report completion with analysis file path, key alignment insights discovered, and any clarification needs identified. + +Note: This command should be run after `/specify` but before `/plan` to ensure systems thinking informs the technical implementation planning phase. \ No newline at end of file diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 652c86a27..0c4ca31fd 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -19,6 +19,6 @@ Given that feature description, do this: **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. 2. Load `templates/spec-template.md` to understand required sections. 3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings. -4. Report completion with branch name, spec file path, and readiness for the next phase. +4. Report completion with branch name, spec file path, and suggest next steps: run `/clarify` to resolve ambiguities, `/align` to check cross-feature conflicts (optional), or `/plan` to proceed with implementation planning. Note: The script creates and checks out the new branch and initializes the spec file before writing. From 0939b57eaaf68daa2159895a70293c96c2da06e5 Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Thu, 2 Oct 2025 12:15:06 +0530 Subject: [PATCH 2/7] Add /align command to documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 1 + 1 file changed, 1 insertion(+) diff --git a/README.md b/README.md index b4e91c377..457ba3164 100644 --- a/README.md +++ b/README.md @@ -211,6 +211,7 @@ After running `specify init`, your AI coding agent will have access to these sla | `/constitution` | Create or update project governing principles and development guidelines | | `/specify` | Define what you want to build (requirements and user stories) | | `/clarify` | Clarify underspecified areas (must be run before `/plan` unless explicitly skipped; formerly `/quizme`) | +| `/align` | Cross-feature alignment analysis using systems thinking (optional, run after `/specify`) | | `/plan` | Create technical implementation plans with your chosen tech stack | | `/tasks` | Generate actionable task lists for implementation | | `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) | From 23149f71d9ec2dcdf14e89af2ea29684512aabd1 Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Fri, 3 Oct 2025 12:19:44 +0530 Subject: [PATCH 3/7] Rename /align command to /cross-feature for clarity MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Renamed the /align command to /cross-feature to better express that this command performs cross-feature alignment analysis using systems thinking. The new name makes it immediately clear that the analysis examines interactions between multiple features. Changes: - Renamed templates/commands/align.md → cross-feature.md - Renamed templates/alignment-analysis-template.md → cross-feature-analysis-template.md - Renamed scripts/bash/alignment-check-all-features.sh → cross-feature-check-all-features.sh - Renamed scripts/powershell/alignment-check-all-features.ps1 → cross-feature-check-all-features.ps1 - Updated all internal references to use new naming: - Output filename: alignment-analysis.md → cross-feature-analysis.md - Template paths in scripts - Command references in documentation - Clarification line text in scripts - Updated README.md command table - Updated templates/commands/specify.md to suggest /cross-feature 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- README.md | 2 +- ...features.sh => cross-feature-check-all-features.sh} | 8 ++++---- ...atures.ps1 => cross-feature-check-all-features.ps1} | 8 ++++---- templates/commands/{align.md => cross-feature.md} | 10 +++++----- templates/commands/specify.md | 2 +- ...-template.md => cross-feature-analysis-template.md} | 0 6 files changed, 15 insertions(+), 15 deletions(-) rename scripts/bash/{alignment-check-all-features.sh => cross-feature-check-all-features.sh} (92%) rename scripts/powershell/{alignment-check-all-features.ps1 => cross-feature-check-all-features.ps1} (91%) rename templates/commands/{align.md => cross-feature.md} (80%) rename templates/{alignment-analysis-template.md => cross-feature-analysis-template.md} (100%) diff --git a/README.md b/README.md index 457ba3164..ca390c979 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ After running `specify init`, your AI coding agent will have access to these sla | `/constitution` | Create or update project governing principles and development guidelines | | `/specify` | Define what you want to build (requirements and user stories) | | `/clarify` | Clarify underspecified areas (must be run before `/plan` unless explicitly skipped; formerly `/quizme`) | -| `/align` | Cross-feature alignment analysis using systems thinking (optional, run after `/specify`) | +| `/cross-feature` | Cross-feature alignment analysis using systems thinking (optional, run after `/specify`) | | `/plan` | Create technical implementation plans with your chosen tech stack | | `/tasks` | Generate actionable task lists for implementation | | `/analyze` | Cross-artifact consistency & coverage analysis (run after /tasks, before /implement) | diff --git a/scripts/bash/alignment-check-all-features.sh b/scripts/bash/cross-feature-check-all-features.sh similarity index 92% rename from scripts/bash/alignment-check-all-features.sh rename to scripts/bash/cross-feature-check-all-features.sh index 6c54c5eab..3bcf3959f 100755 --- a/scripts/bash/alignment-check-all-features.sh +++ b/scripts/bash/cross-feature-check-all-features.sh @@ -67,10 +67,10 @@ fi # Create analysis file in current feature directory FEATURE_DIR="$(dirname "$CURRENT_SPEC")" -ANALYSIS_FILE="$FEATURE_DIR/alignment-analysis.md" +ANALYSIS_FILE="$FEATURE_DIR/cross-feature-analysis.md" # Create analysis file from template -TEMPLATE="$REPO_ROOT/templates/alignment-analysis-template.md" +TEMPLATE="$REPO_ROOT/templates/cross-feature-analysis-template.md" if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$ANALYSIS_FILE" else @@ -78,12 +78,12 @@ else fi # Add clarification line to current spec.md for /clarify to pick up -CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]" +CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" # Find the Requirements section and add the clarification line if [ -f "$CURRENT_SPEC" ]; then # Check if the clarification line already exists to avoid duplicates - if ! grep -q "alignment-analysis.md" "$CURRENT_SPEC"; then + if ! grep -q "cross-feature-analysis.md" "$CURRENT_SPEC"; then # Find the line with "### Functional Requirements" and add our clarification after it if grep -q "### Functional Requirements" "$CURRENT_SPEC"; then # Use sed to add the line after "### Functional Requirements" diff --git a/scripts/powershell/alignment-check-all-features.ps1 b/scripts/powershell/cross-feature-check-all-features.ps1 similarity index 91% rename from scripts/powershell/alignment-check-all-features.ps1 rename to scripts/powershell/cross-feature-check-all-features.ps1 index 19bf91b1f..713d4b6a9 100644 --- a/scripts/powershell/alignment-check-all-features.ps1 +++ b/scripts/powershell/cross-feature-check-all-features.ps1 @@ -63,10 +63,10 @@ if (Test-Path $SpecsDir) { # Create analysis file in current feature directory $FeatureDir = Split-Path -Parent $CurrentSpec -$AnalysisFile = Join-Path $FeatureDir "alignment-analysis.md" +$AnalysisFile = Join-Path $FeatureDir "cross-feature-analysis.md" # Create analysis file from template -$Template = Join-Path $RepoRoot "templates" "alignment-analysis-template.md" +$Template = Join-Path $RepoRoot "templates" "cross-feature-analysis-template.md" if (Test-Path $Template) { Copy-Item $Template $AnalysisFile } else { @@ -74,14 +74,14 @@ if (Test-Path $Template) { } # Add clarification line to current spec.md for /clarify to pick up -$ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]" +$ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" # Find the Requirements section and add the clarification line if (Test-Path $CurrentSpec) { $SpecContent = Get-Content $CurrentSpec -Raw # Check if the clarification line already exists to avoid duplicates - if (-not $SpecContent.Contains("alignment-analysis.md")) { + if (-not $SpecContent.Contains("cross-feature-analysis.md")) { $Lines = Get-Content $CurrentSpec $NewLines = @() $Added = $false diff --git a/templates/commands/align.md b/templates/commands/cross-feature.md similarity index 80% rename from templates/commands/align.md rename to templates/commands/cross-feature.md index 45d034ae9..3776b6d15 100644 --- a/templates/commands/align.md +++ b/templates/commands/cross-feature.md @@ -1,18 +1,18 @@ --- description: Analyze how the current feature aligns with existing features using systems thinking to identify conflicts, dependencies, and emergent behaviors. scripts: - sh: scripts/bash/alignment-check-all-features.sh --json "{ARGS}" - ps: scripts/powershell/alignment-check-all-features.ps1 -Json "{ARGS}" + sh: scripts/bash/cross-feature-check-all-features.sh --json "{ARGS}" + ps: scripts/powershell/cross-feature-check-all-features.ps1 -Json "{ARGS}" --- -The text the user typed after `/align` in the triggering message **is** optional analysis focus. If empty, perform comprehensive alignment analysis. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. +The text the user typed after `/cross-feature` in the triggering message **is** optional analysis focus. If empty, perform comprehensive alignment analysis. Assume you always have it available in this conversation even if `{ARGS}` appears literally below. Given the current feature specification and optional analysis focus, do this: 1. Run the script `{SCRIPT}` from repo root and parse its JSON output for CURRENT_SPEC, ALL_SPECS, and ANALYSIS_FILE. All file paths must be absolute. **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. -2. Load `templates/alignment-analysis-template.md` to understand the alignment analysis framework structure. +2. Load `templates/cross-feature-analysis-template.md` to understand the alignment analysis framework structure. 3. Read the current feature specification from CURRENT_SPEC to understand: - Feature purpose and user scenarios @@ -40,7 +40,7 @@ Given the current feature specification and optional analysis focus, do this: - Remove any sections that don't apply 7. Add a single clarification line to the current spec.md file in the Requirements section: - - Add: `- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in alignment-analysis.md - potential conflicts identified that may require spec adjustments]` + - Add: `- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]` - This ensures `/clarify` will pick up alignment issues naturally 8. Report completion with analysis file path, key alignment insights discovered, and any clarification needs identified. diff --git a/templates/commands/specify.md b/templates/commands/specify.md index 0c4ca31fd..61e815cb9 100644 --- a/templates/commands/specify.md +++ b/templates/commands/specify.md @@ -19,6 +19,6 @@ Given that feature description, do this: **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for. 2. Load `templates/spec-template.md` to understand required sections. 3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings. -4. Report completion with branch name, spec file path, and suggest next steps: run `/clarify` to resolve ambiguities, `/align` to check cross-feature conflicts (optional), or `/plan` to proceed with implementation planning. +4. Report completion with branch name, spec file path, and suggest next steps: run `/clarify` to resolve ambiguities, `/cross-feature` to check cross-feature conflicts (optional), or `/plan` to proceed with implementation planning. Note: The script creates and checks out the new branch and initializes the spec file before writing. diff --git a/templates/alignment-analysis-template.md b/templates/cross-feature-analysis-template.md similarity index 100% rename from templates/alignment-analysis-template.md rename to templates/cross-feature-analysis-template.md From 05db10d721a99181682f6eb8f132c0a8991b4c4e Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Fri, 3 Oct 2025 16:35:26 +0530 Subject: [PATCH 4/7] Address Copilot review feedback: improve portability and reduce duplication MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fix bash script sed portability for macOS/BSD vs GNU/Linux platforms - Extract clarification message to template to eliminate duplication - Update both bash and PowerShell scripts to read clarification from template - Add fallback to hardcoded message if template extraction fails 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../bash/cross-feature-check-all-features.sh | 31 ++++++++++++++++--- .../cross-feature-check-all-features.ps1 | 18 +++++++++-- templates/commands/cross-feature.md | 1 + 3 files changed, 44 insertions(+), 6 deletions(-) diff --git a/scripts/bash/cross-feature-check-all-features.sh b/scripts/bash/cross-feature-check-all-features.sh index 3bcf3959f..7c2d1f2f4 100755 --- a/scripts/bash/cross-feature-check-all-features.sh +++ b/scripts/bash/cross-feature-check-all-features.sh @@ -2,6 +2,13 @@ # Analyze current feature alignment with all existing features using systems thinking set -e +# Detect platform for sed compatibility +if [[ "$OSTYPE" == "darwin"* ]] || [[ "$(uname -s)" == "Darwin" ]]; then + SED_INPLACE="sed -i ''" +else + SED_INPLACE="sed -i" +fi + JSON_MODE=false ARGS=() for arg in "$@"; do @@ -77,8 +84,17 @@ else touch "$ANALYSIS_FILE" fi -# Add clarification line to current spec.md for /clarify to pick up -CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" +# Extract clarification line from template to avoid duplication +COMMAND_TEMPLATE="$REPO_ROOT/templates/commands/cross-feature.md" +if [ -f "$COMMAND_TEMPLATE" ]; then + # Extract the clarification message from the template (it's in backticks on line with "Add:") + CLARIFICATION_LINE=$(grep -A 1 "Add:" "$COMMAND_TEMPLATE" | grep "NEEDS CLARIFICATION" | sed 's/.*`\(.*\)`.*/\1/') +fi + +# Fallback if extraction fails +if [ -z "$CLARIFICATION_LINE" ]; then + CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" +fi # Find the Requirements section and add the clarification line if [ -f "$CURRENT_SPEC" ]; then @@ -87,8 +103,15 @@ if [ -f "$CURRENT_SPEC" ]; then # Find the line with "### Functional Requirements" and add our clarification after it if grep -q "### Functional Requirements" "$CURRENT_SPEC"; then # Use sed to add the line after "### Functional Requirements" - sed -i.bak "/### Functional Requirements/a\\ -$CLARIFICATION_LINE" "$CURRENT_SPEC" && rm "$CURRENT_SPEC.bak" + # Platform-specific sed syntax + if [[ "$OSTYPE" == "darwin"* ]] || [[ "$(uname -s)" == "Darwin" ]]; then + sed -i '' "/### Functional Requirements/a\\ +$CLARIFICATION_LINE +" "$CURRENT_SPEC" + else + sed -i "/### Functional Requirements/a\\ +$CLARIFICATION_LINE" "$CURRENT_SPEC" + fi else # If no Functional Requirements section, add to end of file echo "" >> "$CURRENT_SPEC" diff --git a/scripts/powershell/cross-feature-check-all-features.ps1 b/scripts/powershell/cross-feature-check-all-features.ps1 index 713d4b6a9..344852904 100644 --- a/scripts/powershell/cross-feature-check-all-features.ps1 +++ b/scripts/powershell/cross-feature-check-all-features.ps1 @@ -73,8 +73,22 @@ if (Test-Path $Template) { New-Item -ItemType File -Path $AnalysisFile -Force | Out-Null } -# Add clarification line to current spec.md for /clarify to pick up -$ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" +# Extract clarification line from template to avoid duplication +$CommandTemplate = Join-Path $RepoRoot "templates" "commands" "cross-feature.md" +$ClarificationLine = "" + +if (Test-Path $CommandTemplate) { + # Extract the clarification message from the template (it's in backticks on line with "Add:") + $TemplateContent = Get-Content $CommandTemplate -Raw + if ($TemplateContent -match 'Add: `([^`]+)`') { + $ClarificationLine = $matches[1] + } +} + +# Fallback if extraction fails +if ([string]::IsNullOrWhiteSpace($ClarificationLine)) { + $ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" +} # Find the Requirements section and add the clarification line if (Test-Path $CurrentSpec) { diff --git a/templates/commands/cross-feature.md b/templates/commands/cross-feature.md index 3776b6d15..9809ca77c 100644 --- a/templates/commands/cross-feature.md +++ b/templates/commands/cross-feature.md @@ -42,6 +42,7 @@ Given the current feature specification and optional analysis focus, do this: 7. Add a single clarification line to the current spec.md file in the Requirements section: - Add: `- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]` - This ensures `/clarify` will pick up alignment issues naturally + - **Note:** Scripts should extract this clarification text programmatically from this template to avoid duplication 8. Report completion with analysis file path, key alignment insights discovered, and any clarification needs identified. From 5b03f3c1dd2dc3458c9b966936a301024ac4e343 Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Fri, 3 Oct 2025 17:41:55 +0530 Subject: [PATCH 5/7] Add /cross-feature to Enhancement Commands in init output MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Added /cross-feature command to the Enhancement Commands panel shown after `specify init` - Positioned after /clarify and before /analyze in the workflow - Includes timing guidance: "run after /specify, before /plan" - Described as "Systems thinking alignment analysis to identify cross-feature conflicts" - Improves discoverability of the cross-feature command for new users 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- src/specify_cli/__init__.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/specify_cli/__init__.py b/src/specify_cli/__init__.py index 8268bf094..7308877c7 100644 --- a/src/specify_cli/__init__.py +++ b/src/specify_cli/__init__.py @@ -1088,7 +1088,8 @@ def init( enhancement_lines = [ "Optional commands that you can use for your specs [bright_black](improve quality & confidence)[/bright_black]", "", - f"○ [cyan]/clarify[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run before [cyan]/plan[/] if used)", + f"○ [cyan]/clarify[/] [bright_black](optional)[/bright_black] - Ask structured questions to de-risk ambiguous areas before planning (run after [cyan]/specify[/], before [cyan]/plan[/])", + f"○ [cyan]/cross-feature[/] [bright_black](optional)[/bright_black] - Systems thinking alignment analysis to identify cross-feature conflicts (run after [cyan]/specify[/], before [cyan]/plan[/])", f"○ [cyan]/analyze[/] [bright_black](optional)[/bright_black] - Cross-artifact consistency & alignment report (after [cyan]/tasks[/], before [cyan]/implement[/])" ] enhancements_panel = Panel("\n".join(enhancement_lines), title="Enhancement Commands", border_style="cyan", padding=(1,2)) From a9bad54edd949eccd97c5a7405a794f3415120ad Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Fri, 3 Oct 2025 21:50:34 +0530 Subject: [PATCH 6/7] Revert .gitignore changes unrelated to cross-feature command MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove settings.local.json from .gitignore as it's not related to the /cross-feature command feature. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .gitignore | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/.gitignore b/.gitignore index 505e9be7e..42a1fbbfa 100644 --- a/.gitignore +++ b/.gitignore @@ -42,5 +42,4 @@ env/ # Spec Kit-specific files .genreleases/ *.zip -sdd-*/ -settings.local.json +sdd-*/ \ No newline at end of file From 7e2363b811bbee88b95a12a6bd62c6c660d05a5c Mon Sep 17 00:00:00 2001 From: Hari Krishnan Date: Fri, 3 Oct 2025 22:07:01 +0530 Subject: [PATCH 7/7] Fix remaining Copilot review feedback: regex patterns and sed portability MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update regex patterns to handle both quotes and backticks in template extraction - Improve sed portability by detecting GNU vs BSD sed at runtime - Add documentation comments noting template as source of truth for clarification message - Fix sed append syntax for both macOS (BSD) and Linux (GNU) 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../bash/cross-feature-check-all-features.sh | 28 ++++++++----------- .../cross-feature-check-all-features.ps1 | 6 ++-- 2 files changed, 16 insertions(+), 18 deletions(-) diff --git a/scripts/bash/cross-feature-check-all-features.sh b/scripts/bash/cross-feature-check-all-features.sh index 7c2d1f2f4..f8dd9dbe0 100755 --- a/scripts/bash/cross-feature-check-all-features.sh +++ b/scripts/bash/cross-feature-check-all-features.sh @@ -2,12 +2,7 @@ # Analyze current feature alignment with all existing features using systems thinking set -e -# Detect platform for sed compatibility -if [[ "$OSTYPE" == "darwin"* ]] || [[ "$(uname -s)" == "Darwin" ]]; then - SED_INPLACE="sed -i ''" -else - SED_INPLACE="sed -i" -fi +# Platform detection is done inline where sed is used for better portability JSON_MODE=false ARGS=() @@ -87,11 +82,13 @@ fi # Extract clarification line from template to avoid duplication COMMAND_TEMPLATE="$REPO_ROOT/templates/commands/cross-feature.md" if [ -f "$COMMAND_TEMPLATE" ]; then - # Extract the clarification message from the template (it's in backticks on line with "Add:") - CLARIFICATION_LINE=$(grep -A 1 "Add:" "$COMMAND_TEMPLATE" | grep "NEEDS CLARIFICATION" | sed 's/.*`\(.*\)`.*/\1/') + # Extract the clarification message from the template (handles both quotes and backticks) + CLARIFICATION_LINE=$(grep -A 1 "Add:" "$COMMAND_TEMPLATE" | grep "NEEDS CLARIFICATION" | sed 's/.*["'\''`]\(.*NEEDS CLARIFICATION.*\)["'\''`].*/\1/') fi # Fallback if extraction fails +# NOTE: This fallback must match the clarification line in templates/commands/cross-feature.md +# The template is the source of truth - update there first if changing this message if [ -z "$CLARIFICATION_LINE" ]; then CLARIFICATION_LINE="- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" fi @@ -102,15 +99,14 @@ if [ -f "$CURRENT_SPEC" ]; then if ! grep -q "cross-feature-analysis.md" "$CURRENT_SPEC"; then # Find the line with "### Functional Requirements" and add our clarification after it if grep -q "### Functional Requirements" "$CURRENT_SPEC"; then - # Use sed to add the line after "### Functional Requirements" - # Platform-specific sed syntax - if [[ "$OSTYPE" == "darwin"* ]] || [[ "$(uname -s)" == "Darwin" ]]; then - sed -i '' "/### Functional Requirements/a\\ -$CLARIFICATION_LINE -" "$CURRENT_SPEC" + # Use portable sed in-place editing for macOS and GNU/Linux + if sed --version >/dev/null 2>&1; then + # GNU sed + sed -i "/### Functional Requirements/a\\$CLARIFICATION_LINE" "$CURRENT_SPEC" else - sed -i "/### Functional Requirements/a\\ -$CLARIFICATION_LINE" "$CURRENT_SPEC" + # BSD/macOS sed + sed -i.bak "/### Functional Requirements/a\\ +$CLARIFICATION_LINE" "$CURRENT_SPEC" && rm -f "$CURRENT_SPEC.bak" fi else # If no Functional Requirements section, add to end of file diff --git a/scripts/powershell/cross-feature-check-all-features.ps1 b/scripts/powershell/cross-feature-check-all-features.ps1 index 344852904..49d5da289 100644 --- a/scripts/powershell/cross-feature-check-all-features.ps1 +++ b/scripts/powershell/cross-feature-check-all-features.ps1 @@ -78,14 +78,16 @@ $CommandTemplate = Join-Path $RepoRoot "templates" "commands" "cross-feature.md" $ClarificationLine = "" if (Test-Path $CommandTemplate) { - # Extract the clarification message from the template (it's in backticks on line with "Add:") + # Extract the clarification message from the template (handles both quotes and backticks) $TemplateContent = Get-Content $CommandTemplate -Raw - if ($TemplateContent -match 'Add: `([^`]+)`') { + if ($TemplateContent -match 'Add: ["''`]([^"''`]+)["''`]') { $ClarificationLine = $matches[1] } } # Fallback if extraction fails +# NOTE: This fallback must match the clarification line in templates/commands/cross-feature.md +# The template is the source of truth - update there first if changing this message if ([string]::IsNullOrWhiteSpace($ClarificationLine)) { $ClarificationLine = "- [NEEDS CLARIFICATION: Review cross-feature alignment analysis in cross-feature-analysis.md - potential conflicts identified that may require spec adjustments]" }