ClawHub

Spec-Kit SDD

Dev Tools

GitHub Spec-Kit integration for Spec-Driven Development (SDD). Use when: (1) initializing a new Spec-Kit project, (2) creating/updating project constitution, (3) writing feature specifications, (4) planning technical implementation, (5) generating task breakdowns, (6) implementing features from specs, (7) clarifying requirements, (8) cross-artifact analysis, (9) managing extensions and presets, (10) reassigning Paperclip issues. Triggers on: speckit, spec-kit, spec driven, constitution, specification, /speckit.*, feature spec, implementation plan.

Install

openclaw skills install speckit

Spec-Kit — Spec-Driven Development (SDD)

GitHub 官方開源工具包 (v0.4.3)，將規格驅動開發引入 AI Agent 工作流程。 Repo: https://github.com/github/spec-kit | License: MIT

What is Spec-Driven Development?

Spec-Kit reverses traditional AI coding: specifications are first-class citizens, code is a derived output. Instead of "vibe coding" where you prompt AI directly, SDD follows a structured pipeline:

Constitution → Specify → Clarify → Plan → Tasks → Implement

Each phase has explicit inputs, outputs, and quality gates.

Prerequisites

CLI Installation

# Install Specify CLI (requires uv)
uv tool install specify-cli --from git+https://github.com/github/spec-kit.git@v0.4.3

# Verify
specify check

System requirements: Python 3.11+, uv, Git, a supported AI agent.

Agent Support

Spec-Kit supports 30+ AI agents. Key ones for our stack:

AgentIntegrationNotes
Claude Code/speckit.* slash commands.claude/commands/speckit.*.md
Gemini CLI.gemini/commands/speckit.*.tomlStandard
opencode/speckit.* slash commandsStandard
Codex CLI--ai-skills flagSkills in .agents/skills/
GitHub Copilot/speckit.* slash commandsVS Code native

Workflow Commands

Core Pipeline

StepCommandOutputWhen
0. Initspecify init <project> --ai <agent>.specify/ + commandsNew project
1. Constitution/speckit.constitution <description>memory/constitution.mdNew project / principles
2. Specify/speckit.specify <feature description>specs/<NNN-feature>/spec.mdStarting a new feature
3. Clarify/speckit.clarifyUpdates spec.md clarificationsBefore planning
4. Plan/speckit.plan <tech stack description>specs/<NNN-feature>/plan.md + researchAfter spec approved
5. Tasks/speckit.tasksspecs/<NNN-feature>/tasks.mdAfter plan validated
6. Implement/speckit.implementCode changesTasks defined

Optional Commands

CommandPurposeWhen
/speckit.analyzeCross-artifact consistency & coverage analysisBefore final review
/speckit.checklistQuality checklists (unit tests for specs)Validate completeness
/speckit.taskstoissuesConvert tasks to GitHub IssuesNeed project board sync

CLI Reference

specify init

# New project
specify init my-project --ai claude

# Existing directory
specify init . --ai claude --force

# With Codex skills
specify init my-project --ai codex --ai-skills

# Skip git init
specify init my-project --ai claude --no-git

# Timestamp-based branch numbering
specify init my-project --ai claude --branch-numbering timestamp

specify check

Verifies: git + all CLI agents configured in AGENT_CONFIG.

Extension & Preset Management

# Extensions
specify extension search                    # Browse available
specify extension add <name>                # Install

# Presets
specify preset search                       # Browse available
specify preset add <name>                   # Install

Project Structure

After specify init:

project-root/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Project principles (Step 1)
│   ├── scripts/
│   │   ├── check-prerequisites.sh
│   │   ├── common.sh
│   │   ├── create-new-feature.sh    # Creates feature branch + spec dir
│   │   ├── setup-plan.sh
│   │   └── update-claude-md.sh
│   ├── templates/
│   │   ├── constitution-template.md
│   │   ├── spec-template.md
│   │   ├── plan-template.md
│   │   └── tasks-template.md
│   ├── extensions/
│   │   ├── catalog.json
│   │   └── <ext-id>/templates/
│   └── presets/
│       └── <preset-id>/templates/
├── specs/
│   └── 001-feature-name/
│       ├── spec.md                   # Feature specification (Step 2)
│       ├── plan.md                   # Technical plan (Step 4)
│       ├── research.md               # Phase 0 research output
│       ├── data-model.md             # Data model design
│       ├── quickstart.md             # Getting started guide
│       ├── contracts/                # API contracts
│       │   ├── api-spec.json
│       │   └── signalr-spec.md
│       └── tasks.md                  # Task breakdown (Step 5)
├── .claude/commands/
│   ├── speckit.constitution.md
│   ├── speckit.specify.md
│   ├── speckit.plan.md
│   ├── speckit.tasks.md
│   └── speckit.implement.md
└── [source code]

Template Details

Constitution (memory/constitution.md)

Defines non-negotiable project principles. All specs must comply.

Structure:

  • Core Principles (I, II, III, ...) — Each with clear description
  • Additional Constraints — Tech stack, compliance, security
  • Development Workflow — Code review, testing gates
  • Governance — Amendment rules, compliance verification

Only CEO/CTO may amend. Version: X.Y.Z | Ratified: YYYY-MM-DD

Spec (spec.md)

Key sections:

  • Feature Branch: NNN-feature-name
  • User Scenarios & Testing — Prioritized user stories (P1, P2, P3), each independently testable
  • Edge Cases — Boundary conditions, error scenarios
  • Requirements — Functional + non-functional
  • Review & Acceptance Checklist — Validation gates

Plan (plan.md)

  • Summary — Primary requirement + technical approach
  • Technical Context — Language, dependencies, storage, testing, platform
  • Constitution Check — Must pass before Phase 0
  • Project Structure — File tree
  • Implementation Details — Phase-by-phase breakdown

Tasks (tasks.md)

Format: [ID] [P?] [Story] Description

  • [P] = can run in parallel
  • [Story] = which user story (US1, US2, ...)
  • Organized by user story for independent implementation

Extensions & Presets

Template Resolution Priority (highest → lowest)

Project-local overrides (.specify/templates/overrides/)
    ↓
Presets (.specify/presets/<preset-id>/templates/)
    ↓
Extensions (.specify/extensions/<ext-id>/templates/)
    ↓
Core (.specify/templates/)

Notable Community Extensions

ExtensionPurposeType
spec-kit-jiraSync specs to Jira Epics/Storiesintegration
spec-kit-verifyValidate code vs spec artifactscode (read-only)
spec-kit-cleanupPost-implementation quality gatecode (read+write)
spec-kit-reviewComprehensive code reviewcode (read-only)
spec-kit-archiveArchive merged featuresdocs (read+write)
spec-kit-syncDetect/resolve spec vs code driftdocs (read+write)
spec-kit-doctorProject health diagnosticsvisibility (read-only)
spec-kit-maqa-extMulti-agent QA coordinatorprocess

Notable Presets

PresetPurpose
pirate-speakFun localization demo
aide-in-placeIn-place technology migrations

Paperclip Integration

Reassign via API (use this, NOT shell scripts)

PAPERCLIP_API="http://localhost:3100/api"

# Reassign by agent ID
curl -s -X PATCH "$PAPERCLIP_API/issues/$ISSUE_ID" \
  -H "Content-Type: application/json" \
  -d "{\"assigneeAgentId\": \"$TARGET_AGENT_ID\"}"

# Comment on issue
curl -s -X POST "$PAPERCLIP_API/issues/$ISSUE_ID/comments" \
  -H "Content-Type: application/json" \
  -d "{\"body\": \"Description of work done\"}"

Issue Lifecycle

Dev → implement → reassign code-reviewer → CTO review → reassign qa → PM confirms → done
Bug: Dev → fix → reassign cto → reassign qa → done

Best Practices

  1. Spec before code — Resist "write code first, document later"
  2. Constitution is law — All PRs must verify compliance
  3. Prioritize user stories — P1 is the MVP, each story independently testable
  4. Keep specs alive — Update specs when implementation drifts, don't pretend
  5. Task granularity — Each task 2-4 hours max, split large ones
  6. Use extensions — Install verify + cleanup for automated quality gates
  7. Validate before implement — Run /speckit.analyze + /speckit.checklist
  8. Clarify before planning — /speckit.clarify reduces rework

Common Pitfalls

  • Skipping constitution → Agent makes inconsistent decisions
  • Overly vague specs → AI hallucinates features or misses edge cases
  • No clarify step → Plan includes wrong assumptions
  • Tasks too large → AI loses context, produces buggy code
  • Not updating specs after changes → Drift between spec and code
  • Ignoring constitution during plan → Architecture violations

Upgrade

uv tool install specify-cli --force --from git+https://github.com/github/spec-kit.git@v0.4.3

References

More in Dev Tools