Spec-Kit Technical Integration

Purpose

This skill is the single source of truth for all spec-kit technical integration:

• Automatic initialization and setup
• Installation validation
• Project structure management
• CLI command wrappers
• Layout and file path enforcement

This is a low-level technical skill. Workflow skills (brainstorm, implement, etc.) call this skill for setup, then proceed with their specific workflows.

Automatic Initialization Protocol

IMPORTANT: This runs automatically when called by any workflow skill.

Every SDD workflow skill calls this skill first via {Skill: spec-kit}. When called, execute this initialization sequence once per session.

Session Tracking

# Check if already initialized this session
# Use an environment variable or similar mechanism
# If "sdd_init_done" flag is set, skip to step 4

Step 1: Check spec-kit CLI Installation

which speckit

If NOT found:

❌ ERROR: spec-kit is required but not installed

spec-kit provides the templates, scripts, and tooling for SDD workflows.

Installation:
1. Visit: https://github.com/github/spec-kit
2. Follow installation instructions
3. Ensure 'speckit' is in your PATH
4. Verify: run 'which speckit'

After installation, restart this workflow.

STOP workflow. Do not proceed without spec-kit.

If found:

# Get version for logging
speckit --version

Proceed to step 2.

Step 2: Check Project Initialization

# Check if .specify/ directory exists
[ -d .specify ] && echo "initialized" || echo "not-initialized"

If NOT initialized:

Display message:

spec-kit is installed ✓

This project needs initialization...
Running: speckit init

Execute initialization:

speckit init

Check for errors:

• Permission denied → suggest running with proper permissions
• Command failed → display error and suggest manual init
• Success → proceed to step 3

If already initialized: Skip to step 3.

Step 3: Check for New Commands (Restart Detection)

After speckit init runs, check if local commands were installed:

# Check if spec-kit installed Claude Code commands
if [ -d .claude/commands ]; then
  ls .claude/commands/ | grep -q speckit
  if [ $? -eq 0 ]; then
    echo "commands-installed"
  fi
fi

If commands were installed:

Display restart prompt:

✅ Project initialized successfully!

⚠️  RESTART REQUIRED ⚠️

spec-kit has installed local slash commands in:
  .claude/commands/speckit.*

To load these new commands, please:
1. Save your work
2. Close this conversation
3. Restart Claude Code application
4. Return to this project
5. Continue your workflow

After restart, you'll have access to:
- /sdd:* commands (from this plugin)
- /speckit.* commands (from local spec-kit installation)

[Workflow paused - resume after restart]

STOP workflow. User must restart before continuing.

If no new commands installed: Proceed to step 4.

Step 4: Verify Installation

Quick sanity check:

# Verify key files exist
[ -f .specify/templates/spec-template.md ] && \
[ -f .specify/scripts/bash/common.sh ] && \
echo "verified" || echo "corrupt"

If verification fails:

❌ ERROR: .specify/ exists but appears incomplete

This may be due to a failed initialization.

Please run: speckit init --force

Then restart this workflow.

STOP workflow.

If verification succeeds:

• Set session flag: "sdd_init_done"
• Return success to calling skill
• Calling skill continues with its workflow

Layout Validation

Use these helpers to validate spec-kit file structure:

Check Constitution

# Constitution location (per spec-kit convention)
CONSTITUTION=".specify/memory/constitution.md"

if [ -f "$CONSTITUTION" ]; then
  echo "constitution-exists"
else
  echo "no-constitution"
fi

Get Feature Spec Path

# Validate feature spec path follows spec-kit layout
# Expected: specs/NNNN-feature-name/spec.md
# Or: specs/features/feature-name.md

validate_spec_path() {
  local spec_path=$1

  # Check if follows spec-kit conventions
  if [[ $spec_path =~ ^specs/[0-9]+-[a-z-]+/spec\.md$ ]] || \
     [[ $spec_path =~ ^specs/features/[a-z-]+\.md$ ]]; then
    echo "valid"
  else
    echo "invalid: spec must be in specs/ directory with proper naming"
  fi
}

Get Plan Path

# Plan location (per spec-kit convention)
# Expected: specs/NNNN-feature-name/docs/plan.md

get_plan_path() {
  local feature_dir=$1  # e.g., "specs/0001-user-auth"
  echo "$feature_dir/docs/plan.md"
}

Ensure Directory Structure

# Create spec-kit compliant feature structure
ensure_feature_structure() {
  local feature_dir=$1  # e.g., "specs/0001-user-auth"

  mkdir -p "$feature_dir/docs"
  mkdir -p "$feature_dir/checklists"
  mkdir -p "$feature_dir/contracts"

  echo "created: $feature_dir structure"
}

Spec-Kit CLI Commands

Wrapper helpers for common spec-kit commands:

Initialize Project

# Already covered in automatic initialization
speckit init

Create Specification

# Interactive spec creation
speckit specify [feature-description]

# Uses template from .specify/templates/spec-template.md

Validate Specification

# Validate spec format and structure
speckit validate <spec-file>

# Example:
speckit validate specs/0001-user-auth/spec.md

Generate Plan

# Generate implementation plan from spec
speckit plan <spec-file>

# Example:
speckit plan specs/0001-user-auth/spec.md

Create Constitution

# Interactive constitution creation
speckit constitution

# Creates .specify/memory/constitution.md

Error Handling

spec-kit CLI Errors

Command not found after installation:

• Check PATH configuration
• Suggest shell restart
• Provide which speckit output

Init fails:

• Check write permissions
• Check disk space
• Suggest manual troubleshooting

Validation fails:

• Display validation errors
• Suggest fixes based on error type
• Reference spec template

File System Errors

Permission denied:

Cannot write to project directory.

Please ensure you have write permissions:
  chmod +w .

Path not found:

Expected file not found: <path>

This suggests incomplete initialization.
Run: speckit init --force

Integration Points

Called by these workflow skills:

• sdd:brainstorm (at start)
• sdd:implement (at start)
• sdd:evolve (at start)
• sdd:constitution (at start)
• sdd:review-spec (at start)
• All workflow skills that need spec-kit

Calls:

• spec-kit CLI (external command)
• File system operations
• No other skills (this is a leaf skill)

Session Management

First call in session:

• Run full initialization protocol
• Check installation, project, commands
• Prompt restart if needed
• Set session flag

Subsequent calls in session:

• Check session flag
• Skip initialization if already done
• Optionally re-verify critical paths
• Return success immediately

Session reset:

• New conversation = new session
• Re-run initialization protocol
• Ensures project state is current

Remember

This skill is infrastructure, not workflow.

• Don't make decisions about WHAT to build
• Don't route to other workflow skills
• Just ensure spec-kit is ready to use
• Validate paths and structure
• Handle technical errors

Workflow skills handle:

• What to create (specs, plans, code)
• When to use which tool
• Process discipline and quality gates

This skill handles:

• Is spec-kit installed?
• Is project initialized?
• Do files exist in correct locations?
• Are commands available?

The goal: Zero-config, automatic, invisible setup.