Agent Skills: Spec-Kit Technical Integration

Spec-Kit Technical Integration

CRITICAL NAMING - READ THIS FIRST

| What | Correct Name | WRONG Names | |------|--------------|-------------| | CLI command | specify | ~~speckit~~, ~~spec-kit~~ | | Package name | specify-cli | ~~spec-kit~~, ~~speckit~~ | | Slash commands | /speckit.* | (these are correct) |

Installation: uv pip install specify-cli or pip install specify-cli

Purpose

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

• Automatic initialization and setup
• Installation validation
• Project structure management
• Slash command availability
• 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.

CRITICAL: Understanding the Tool Architecture

The specify CLI is a setup tool only. It has three commands:

• specify init - Initialize a project with spec-kit templates and commands
• specify check - Check that required tools are installed
• specify version - Display version information

All spec operations are done via /speckit.* slash commands, which are installed by specify init:

• /speckit.specify - Create specifications
• /speckit.plan - Generate implementation plans
• /speckit.tasks - Generate task lists
• /speckit.clarify - Find underspecified areas
• /speckit.analyze - Cross-artifact consistency check
• /speckit.checklist - Generate quality checklists
• /speckit.implement - Execute implementation
• /speckit.constitution - Create project constitution

NEVER call specify validate, specify plan, etc. - these commands don't exist!

Automatic Initialization

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

{Skill: sdd:init}

If init prompts for restart, pause this workflow and resume after restart.

After initialization succeeds, this skill provides reference material below.

Available Slash Commands

After specify init, these /speckit.* commands are available:

| Command | Purpose | Creates | |---------|---------|---------| | /speckit.specify | Create specification interactively | specs/[NNNN]-[name]/spec.md | | /speckit.plan | Generate implementation plan | specs/[name]/plan.md | | /speckit.tasks | Generate task list | specs/[name]/tasks.md | | /speckit.clarify | Find underspecified areas | (analysis output) | | /speckit.analyze | Cross-artifact consistency | (analysis output) | | /speckit.checklist | Generate quality checklist | checklist file | | /speckit.implement | Execute implementation | code files | | /speckit.constitution | Create project constitution | .specify/memory/constitution.md (also check specs/constitution.md) |

Usage in skills:

When a skill needs to create a spec, plan, or tasks, it should:

1. Check that /speckit.* commands are available
2. Invoke the appropriate slash command
3. If commands not available, fall back to manual creation following templates

Example:

To create a spec, invoke: /speckit.specify

If /speckit.specify is not available (not initialized),
create the spec manually following .specify/templates/spec-template.md

Branch Naming Convention

Spec-kit requires feature branches named NNN-feature-name where NNN is a three-digit numeric prefix matching the spec directory number.

| Pattern | Valid | Example | |---------|-------|---------| | NNN-feature-name | Yes | 002-operator-config | | feature/name | No | Fails branch validation | | spec/NNN-name | No | Fails branch validation | | fix/NNN-name | No | Fails branch validation |

The validation regex is ^[0-9]{3}- (must start with exactly three digits followed by a hyphen).

Why this matters: Spec-kit uses the branch name to locate the corresponding spec directory under specs/. The numeric prefix links branch 002-operator-config to specs/002-operator-config/.

Validation helper:

check_branch_for_speckit() {
  local branch=$(git branch --show-current)
  if [[ "$branch" =~ ^[0-9]{3}- ]]; then
    echo "valid: $branch"
  else
    echo "invalid: $branch (must match NNN-feature-name pattern)"
  fi
}

If the branch name is wrong, create or switch to a properly named branch before running any /speckit.* commands:

# Example: for spec in specs/002-operator-config/
git checkout -b 002-operator-config

Layout Validation

Use these helpers to validate spec-kit file structure:

Check Constitution

The constitution can exist in two locations depending on how it was created:

• .specify/memory/constitution.md (created by /speckit.constitution)
• specs/constitution.md (created manually via sdd:constitution)

Always check both locations:

# Check both possible constitution locations
if [ -f ".specify/memory/constitution.md" ]; then
  CONSTITUTION=".specify/memory/constitution.md"
  echo "constitution-exists: $CONSTITUTION"
elif [ -f "specs/constitution.md" ]; then
  CONSTITUTION="specs/constitution.md"
  echo "constitution-exists: $CONSTITUTION"
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/plan.md

get_plan_path() {
  local feature_dir=$1  # e.g., "specs/0001-user-auth"
  echo "$feature_dir/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 Discovery

When a workflow skill requires a spec file and none is specified, use this discovery protocol.

List Available Specs

# Find all spec.md files in specs/ directory
fd -t f "spec.md" specs/ 2>/dev/null || find specs/ -name "spec.md" -type f 2>/dev/null

# Also check for direct .md files in specs/features/
ls specs/features/*.md 2>/dev/null

Present Options to User

If multiple specs found: Use AskUserQuestion to let user select which spec to use.

If single spec found: Confirm with user before proceeding: "Found specs/0001-auth/spec.md. Use this spec?"

If no specs found: Inform user and suggest creating one:

No specs found in specs/ directory.

To create a spec:
- Use `sdd:brainstorm` to refine ideas into a spec
- Use `/speckit.specify` to create a spec from clear requirements

Path Resolution Priority

When resolving a spec path:

1. Exact path if provided (e.g., specs/0001-auth/spec.md)
2. Match by feature name in numbered directory (e.g., auth -> specs/0001-auth/spec.md)
3. Match by feature name in features directory (e.g., auth -> specs/features/auth.md)

# Resolve feature name to spec path
resolve_spec_path() {
  local feature_name=$1

  # Check numbered directory pattern first
  local numbered=$(fd -t f "spec.md" specs/ 2>/dev/null | grep -i "$feature_name" | head -1)
  if [ -n "$numbered" ]; then
    echo "$numbered"
    return
  fi

  # Check features directory
  local features="specs/features/${feature_name}.md"
  if [ -f "$features" ]; then
    echo "$features"
    return
  fi

  # Not found
  echo ""
}

Error Handling

specify CLI Errors

Command not found:

• Provide installation instructions
• Suggest uv or pip installation

Init fails:

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

Slash Command Errors

Commands not available:

• Check if specify init was run
• Check if restart is needed
• Suggest re-initialization

Command execution fails:

• Display error message
• Suggest checking spec format
• 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: specify init --force

Integration Points

Called by these workflow skills:

• sdd:brainstorm (at start)
• sdd:evolve (at start)
• sdd:constitution (at start)
• sdd:review-spec (at start)
• sdd:review-plan (at start)
• /speckit.implement via superpowers trait overlay (at start)
• All workflow skills that need spec-kit

Calls:

• {Skill: sdd:init} (for initialization)
• specify CLI (for init only, via sdd:init)
• /speckit.* slash commands (for all operations)
• File system operations

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

CLI vs Slash Commands Summary

| Task | Tool | Command | |------|------|---------| | Initialize project | CLI | specify init | | Check tools | CLI | specify check | | Show version | CLI | specify version | | Create spec | Slash | /speckit.specify | | Generate plan | Slash | /speckit.plan | | Generate tasks | Slash | /speckit.tasks | | Find gaps | Slash | /speckit.clarify | | Check consistency | Slash | /speckit.analyze | | Generate checklist | Slash | /speckit.checklist | | Execute implementation | Slash | /speckit.implement | | Create constitution | Slash | /speckit.constitution |

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 specify CLI installed?
• Is project initialized?
• Are /speckit.* commands available?
• Do files exist in correct locations?

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