Skip to content

Commit 0b768e3

Browse files
jschultejschulte
committed
fix: Add GitHub Spec Kit scripts installer for Gear 4 compatibility
PROBLEM: Gear 4 (Gap Analysis) tries to run /speckit.analyze but fails with "Script not found" error. This is because: - Gear 3 creates .specify/scripts/ directory but leaves it empty - /speckit.analyze requires scripts/bash/check-prerequisites.sh - /speckit.implement requires scripts/bash/check-prerequisites.sh - /speckit.plan requires scripts/bash/setup-plan.sh - GitHub Spec Kit commands expect these scripts to exist SOLUTION: Created scripts/install-speckit-scripts.sh that downloads GitHub Spec Kit prerequisite scripts and installs them to .specify/scripts/bash/ SCRIPTS INSTALLED (5): - check-prerequisites.sh - Used by analyze/implement/plan/tasks - setup-plan.sh - Used by plan command - create-new-feature.sh - Used by specify command - update-agent-context.sh - Used by plan command - common.sh - Shared utilities UPDATED SKILLS: 1. Gear 3 (create-specs/SKILL.md): - Added Step 1: Install GitHub Spec Kit Scripts - Downloads scripts before creating specs - Provides fallback download if installer missing - Clear explanation of why scripts are needed 2. Gear 4 (gap-analysis/SKILL.md): - Added script verification check - Offers to download if missing - Provides Step 2a (with scripts) vs Step 2b (manual fallback) - Graceful degradation if scripts unavailable WORKFLOW: Before: Gear 3 → Gear 4 → /speckit.analyze fails ❌ After: Gear 3 → install scripts → Gear 4 → /speckit.analyze works ✅ FALLBACK: If scripts can't be installed, Gear 4 does manual gap analysis: - Iterate through specs - Extract status markers - Count clarifications - Generate basic gap report This ensures Gear 4 never hard-fails - either uses Spec Kit automation or falls back to manual analysis. Fixes: Gear 4 confusion where /speckit.analyze fails with missing scripts
1 parent 8469a4c commit 0b768e3

File tree

3 files changed

+178
-14
lines changed

3 files changed

+178
-14
lines changed

‎scripts/install-speckit-scripts.sh‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
#!/bin/bash
2+
3+
# Install GitHub Spec Kit Scripts
4+
# Copies the prerequisite scripts needed for /speckit.* commands
5+
6+
set -e
7+
8+
# Get target directory (default: current working directory)
9+
TARGET_DIR="${1:-.}"
10+
SCRIPTS_DIR="$TARGET_DIR/.specify/scripts"
11+
12+
echo "📋 GitHub Spec Kit Scripts Installer"
13+
echo ""
14+
echo "Target: $SCRIPTS_DIR"
15+
echo ""
16+
17+
# Create scripts directory structure
18+
mkdir -p "$SCRIPTS_DIR/bash"
19+
mkdir -p "$SCRIPTS_DIR/powershell"
20+
echo "✅ Created scripts directories"
21+
echo ""
22+
23+
# Download scripts from GitHub Spec Kit repo
24+
BASE_URL="https://raw.githubusercontent.com/github/spec-kit/main/scripts"
25+
26+
echo "📥 Downloading prerequisite scripts from GitHub Spec Kit..."
27+
echo ""
28+
29+
# Bash scripts
30+
echo "Bash scripts:"
31+
curl -sSL "$BASE_URL/bash/check-prerequisites.sh" -o "$SCRIPTS_DIR/bash/check-prerequisites.sh"
32+
echo " ✓ check-prerequisites.sh"
33+
34+
curl -sSL "$BASE_URL/bash/setup-plan.sh" -o "$SCRIPTS_DIR/bash/setup-plan.sh"
35+
echo " ✓ setup-plan.sh"
36+
37+
curl -sSL "$BASE_URL/bash/create-new-feature.sh" -o "$SCRIPTS_DIR/bash/create-new-feature.sh"
38+
echo " ✓ create-new-feature.sh"
39+
40+
curl -sSL "$BASE_URL/bash/update-agent-context.sh" -o "$SCRIPTS_DIR/bash/update-agent-context.sh"
41+
echo " ✓ update-agent-context.sh"
42+
43+
curl -sSL "$BASE_URL/bash/common.sh" -o "$SCRIPTS_DIR/bash/common.sh"
44+
echo " ✓ common.sh"
45+
46+
# Make bash scripts executable
47+
chmod +x "$SCRIPTS_DIR/bash"/*.sh
48+
49+
echo ""
50+
echo "PowerShell scripts:"
51+
# PowerShell scripts (if they exist)
52+
curl -sSL "$BASE_URL/powershell/check-prerequisites.ps1" -o "$SCRIPTS_DIR/powershell/check-prerequisites.ps1" 2>/dev/null && echo " ✓ check-prerequisites.ps1" || echo " ⚠️ PowerShell scripts not available"
53+
54+
echo ""
55+
echo "✅ Installation complete!"
56+
echo ""
57+
echo "Installed scripts:"
58+
ls -1 "$SCRIPTS_DIR/bash/" | sed 's/^/ /'
59+
echo ""
60+
echo "These scripts are required by /speckit.* slash commands:"
61+
echo " - /speckit.analyze"
62+
echo " - /speckit.implement"
63+
echo " - /speckit.plan"
64+
echo " - /speckit.tasks"
65+
echo ""
66+
echo "💡 Tip: StackShift's Gear 3 should call this automatically!"
67+
echo ""

‎skills/create-specs/SKILL.md‎

Lines changed: 34 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -146,7 +146,39 @@ fi
146146

147147
**IMPORTANT**: This skill uses automated spec generation tools from F002.
148148

149-
### Step 1: Call the MCP Tool
149+
### Step 1: Install GitHub Spec Kit Scripts
150+
151+
**CRITICAL FIRST STEP:** Install the prerequisite scripts needed by `/speckit.*` commands:
152+
153+
```bash
154+
# Install Spec Kit scripts to enable /speckit.* commands
155+
if [ -f ~/git/stackshift/scripts/install-speckit-scripts.sh ]; then
156+
~/git/stackshift/scripts/install-speckit-scripts.sh .
157+
elif [ -f ~/stackshift/scripts/install-speckit-scripts.sh ]; then
158+
~/stackshift/scripts/install-speckit-scripts.sh .
159+
else
160+
# Download directly if script not available
161+
mkdir -p .specify/scripts/bash
162+
BASE_URL="https://raw.githubusercontent.com/github/spec-kit/main/scripts"
163+
curl -sSL "$BASE_URL/bash/check-prerequisites.sh" -o .specify/scripts/bash/check-prerequisites.sh
164+
curl -sSL "$BASE_URL/bash/setup-plan.sh" -o .specify/scripts/bash/setup-plan.sh
165+
curl -sSL "$BASE_URL/bash/create-new-feature.sh" -o .specify/scripts/bash/create-new-feature.sh
166+
curl -sSL "$BASE_URL/bash/update-agent-context.sh" -o .specify/scripts/bash/update-agent-context.sh
167+
curl -sSL "$BASE_URL/bash/common.sh" -o .specify/scripts/bash/common.sh
168+
chmod +x .specify/scripts/bash/*.sh
169+
echo "✅ Downloaded GitHub Spec Kit scripts"
170+
fi
171+
```
172+
173+
**Why this is needed:**
174+
- `/speckit.analyze` requires `scripts/bash/check-prerequisites.sh`
175+
- `/speckit.implement` requires `scripts/bash/check-prerequisites.sh`
176+
- `/speckit.plan` requires `scripts/bash/setup-plan.sh`
177+
- `/speckit.specify` requires `scripts/bash/create-new-feature.sh`
178+
179+
**Without these scripts, Gear 4 (Gap Analysis) will fail when trying to run `/speckit.analyze`!**
180+
181+
### Step 2: Call the MCP Tool
150182

151183
Run the `stackshift_create_specs` MCP tool to automatically generate ALL specifications:
152184

@@ -177,7 +209,7 @@ const result = await mcp.callTool('stackshift_create_specs', {
177209
- 100% feature coverage
178210
- Implementation plans for incomplete features
179211

180-
### Step 2: Verify Success
212+
### Step 3: Verify Success
181213

182214
After the tool completes, verify:
183215
1. `.specify/memory/constitution.md` exists

‎skills/gap-analysis/SKILL.md‎

Lines changed: 77 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -160,7 +160,53 @@ Ready to proceed to:
160160
**YES analyzing:** Old codebase vs specs
161161
**Using:** /speckit.analyze to find gaps
162162

163-
### Step 1: Run /speckit.analyze
163+
### Step 1: Verify GitHub Spec Kit Scripts Exist
164+
165+
**CRITICAL:** Check if prerequisite scripts are installed:
166+
167+
```bash
168+
# Check for scripts
169+
if [ ! -f .specify/scripts/bash/check-prerequisites.sh ]; then
170+
echo "⚠️ GitHub Spec Kit scripts not found!"
171+
echo ""
172+
echo "The /speckit.analyze command requires prerequisite scripts."
173+
echo "These should have been installed during Gear 3."
174+
echo ""
175+
echo "Fix options:"
176+
echo "1. Run the installer:"
177+
echo " ~/stackshift/scripts/install-speckit-scripts.sh ."
178+
echo ""
179+
echo "2. Download directly from GitHub:"
180+
echo " mkdir -p .specify/scripts/bash"
181+
echo " curl -sSL https://raw.githubusercontent.com/github/spec-kit/main/scripts/bash/check-prerequisites.sh -o .specify/scripts/bash/check-prerequisites.sh"
182+
echo " # ... download other scripts ..."
183+
echo ""
184+
echo "3. Skip /speckit.analyze and do manual gap analysis (see Step 2b below)"
185+
echo ""
186+
187+
# Offer to download now
188+
read -p "Download scripts now? (y/n) " -n 1 -r
189+
echo
190+
if [[ $REPLY =~ ^[Yy]$ ]]; then
191+
~/stackshift/scripts/install-speckit-scripts.sh . || {
192+
echo "❌ Installer not found, downloading directly..."
193+
mkdir -p .specify/scripts/bash
194+
BASE_URL="https://raw.githubusercontent.com/github/spec-kit/main/scripts"
195+
curl -sSL "$BASE_URL/bash/check-prerequisites.sh" -o .specify/scripts/bash/check-prerequisites.sh
196+
curl -sSL "$BASE_URL/bash/setup-plan.sh" -o .specify/scripts/bash/setup-plan.sh
197+
curl -sSL "$BASE_URL/bash/create-new-feature.sh" -o .specify/scripts/bash/create-new-feature.sh
198+
curl -sSL "$BASE_URL/bash/update-agent-context.sh" -o .specify/scripts/bash/update-agent-context.sh
199+
curl -sSL "$BASE_URL/bash/common.sh" -o .specify/scripts/bash/common.sh
200+
chmod +x .specify/scripts/bash/*.sh
201+
echo "✅ Scripts downloaded!"
202+
}
203+
else
204+
echo "Skipping /speckit.analyze - will do manual gap analysis instead"
205+
fi
206+
fi
207+
```
208+
209+
### Step 2a: Run /speckit.analyze (if scripts exist)
164210

165211
GitHub Spec Kit's built-in validation:
166212

@@ -175,24 +221,43 @@ GitHub Spec Kit's built-in validation:
175221
- Conflicting requirements across specs
176222
- Outdated implementation status
177223

224+
**If this command fails with "Script not found"**, the scripts weren't installed. Use Step 2b instead.
225+
226+
### Step 2b: Manual Gap Analysis (fallback if scripts missing)
227+
228+
If `/speckit.analyze` can't run, do manual analysis:
229+
230+
```bash
231+
# For each spec, check implementation status
232+
for spec in .specify/specs/*/spec.md; do
233+
feature=$(dirname "$spec" | xargs basename)
234+
echo "Analyzing: $feature"
235+
236+
# Extract status from spec
237+
status=$(grep "^## Status" "$spec" -A 1 | tail -1)
238+
echo " Status: $status"
239+
240+
# Look for [NEEDS CLARIFICATION] markers
241+
clarifications=$(grep -c "\[NEEDS CLARIFICATION\]" "$spec" 2>/dev/null || echo "0")
242+
echo " Clarifications needed: $clarifications"
243+
244+
echo ""
245+
done
246+
```
247+
248+
This is less thorough than `/speckit.analyze` but will identify the basics.
249+
178250
---
179251

180252
## Process Overview
181253

182-
### Step 1: Run /speckit.analyze
254+
### Step 1: Verify Scripts
183255

184-
GitHub Spec Kit's built-in validation:
256+
Check that GitHub Spec Kit scripts are installed (see above).
185257

186-
```bash
187-
> /speckit.analyze
188-
```
258+
### Step 2: Run Analysis
189259

190-
**What it checks:**
191-
- Specifications marked ✅ COMPLETE but implementation missing
192-
- Implementation exists but not documented in specs
193-
- Inconsistencies between related specifications
194-
- Conflicting requirements across specs
195-
- Outdated implementation status
260+
Try `/speckit.analyze` first. If it fails, fall back to manual analysis.
196261

197262
**Output example:**
198263
```

0 commit comments

Comments
 (0)