Spec-Kit-Plus Initialization
Problem
The /sp.autonomous command assumes directories already exist. When run on a fresh project, it fails to create the required .specify/ and .claude/ directory structures, causing the workflow to fail or behave unexpectedly.
Context / Trigger Conditions
Use this skill when:
-
Running /sp.autonomous on a new project with no existing structure
-
Error: "directory not found" or "no such file or directory"
-
Workflow state is inconsistent or corrupted
-
.specify/ or .claude/ directories don't exist
-
Starting any project that will use the autonomous workflow
Solution
CRITICAL RULES (NEVER VIOLATE)
╔═══════════════════════════════════════════════════════════════════════════╗ ║ FORBIDDEN ACTIONS - NEVER DO THESE ║ ╠═══════════════════════════════════════════════════════════════════════════╣ ║ ✗ NEVER create: skill-lab/, workspace/, temp/, output/ ║ ║ ✗ NEVER create: .claude/ inside another directory ║ ║ ✗ NEVER overwrite existing .claude/skills/ contents ║ ║ ✗ NEVER ignore existing directories - USE them ║ ║ ✗ NEVER regenerate skills that already exist ║ ╚═══════════════════════════════════════════════════════════════════════════╝
Step 1: Check What ALREADY EXISTS
Check BEFORE doing anything
CLAUDE_EXISTS="false" SPECIFY_EXISTS="false" SKILL_COUNT=0
if [ -d ".claude" ]; then CLAUDE_EXISTS="true" SKILL_COUNT=$(find .claude/skills -name "SKILL.md" 2>/dev/null | wc -l) echo "✓ .claude/ exists with $SKILL_COUNT skills - WILL USE IT" fi
if [ -d ".specify" ]; then SPECIFY_EXISTS="true" echo "✓ .specify/ exists - WILL USE IT" fi
Step 2: Create ONLY Missing Directories
Only create .specify if it doesn't exist
if [ "$SPECIFY_EXISTS" = "false" ]; then mkdir -p .specify/templates mkdir -p .specify/validations mkdir -p .specify/features fi
Only create .claude if it doesn't exist
if [ "$CLAUDE_EXISTS" = "false" ]; then mkdir -p .claude/skills mkdir -p .claude/agents mkdir -p .claude/commands mkdir -p .claude/rules mkdir -p .claude/logs mkdir -p .claude/build-reports fi
Step 3: Initialize Workflow State
cat > .specify/workflow-state.json << 'EOF' { "phase": 0, "status": "initialized", "project_type": "unknown", "timestamp": "2025-01-21T00:00:00Z", "features": [], "completed_phases": [] } EOF
Step 4: Copy Template (If Available)
TEMPLATE_DIR="/path/to/template/repo"
Copy all configurations
cp -r "$TEMPLATE_DIR/.claude/skills/"* .claude/skills/ 2>/dev/null || true cp -r "$TEMPLATE_DIR/.claude/agents/"* .claude/agents/ 2>/dev/null || true cp -r "$TEMPLATE_DIR/.claude/rules/"* .claude/rules/ 2>/dev/null || true cp -r "$TEMPLATE_DIR/.claude/commands/"* .claude/commands/ 2>/dev/null || true cp "$TEMPLATE_DIR/CLAUDE.md" ./ 2>/dev/null || true cp "$TEMPLATE_DIR/.mcp.json" ./ 2>/dev/null || true
Verification
After initialization, verify:
Check directories exist
ls -la .specify/ ls -la .claude/
Check workflow state
cat .specify/workflow-state.json
Check skill count
find .claude/skills -name "SKILL.md" | wc -l
Expected output:
-
.specify/ contains: templates/, validations/, features/, workflow-state.json
-
.claude/ contains: skills/, agents/, commands/, rules/, logs/
-
Skill count should be > 0 if template was copied
Commands
Command Purpose
/q-init
Initialize project structure
/q-reset
Reset workflow state
/q-status
Check current state
/sp.autonomous
Full autonomous build
Notes
-
Always run /q-init BEFORE /sp.autonomous on fresh projects
-
The sp.autonomous command now includes Phase 0.0 that auto-initializes
-
If copying from template, ensure paths are correct for your system
-
MCP servers in .mcp.json may need path adjustments
Root Cause
The original /sp.autonomous command had Phase 0 (PRE-CHECK) that only checked if directories existed but didn't create them. This was fixed by adding Phase 0.0 (INITIALIZATION) that creates directories if they don't exist.
Prevention
Always include initialization logic at the start of autonomous workflows:
-
Check if structure exists
-
Create if missing
-
Then proceed with detection/resume logic