Skill: Spec Kit (Specification-Driven Development)

Description

Spec Kit is the project's specification-driven development (SDD) workflow. It takes a natural-language feature description through a structured pipeline that produces specs, plans, tasks, and implementation — with review gates, constitution alignment, and automated git hooks at each stage.

When to Use

• Starting a new feature that needs specification before implementation.
• Refining an existing feature spec after user feedback or clarification.
• Analyzing cross-artifact consistency before implementation begins.
• Generating tasks from an approved plan.
• Implementing a fully-specified feature with task tracking.
• Converting tasks to GitHub Issues for project management.

Available Commands

Core Workflow (in order)

Supporting Commands

Git Extension Commands

Full Workflow (End-to-End)

The standard SDD cycle for a new feature:

1. /speckit.specify "Feature description here"
   → Creates specs/<YYYYMMDD-HHMMSS>-feature-name/spec.md
   → Auto-creates feature branch via git hook

2. /speckit.clarify
   → Asks clarification questions, encodes answers into spec.md

3. /speckit.plan
   → Generates plan.md with architecture, phases, data model

4. /speckit.tasks
   → Generates tasks.md with phased, dependency-ordered tasks

5. /speckit.analyze
   → Read-only quality analysis (constitution alignment, coverage gaps)
   → Fix any CRITICAL/HIGH findings before proceeding

6. /speckit.implement
   → Executes tasks with status tracking
   → Auto-commits after each phase

Automated Workflow

The full cycle can also run as a single workflow with review gates:

/speckit.workflow speckit "Describe the feature"

This runs: specify → (review gate) → plan → (review gate) → tasks → implement

File Structure

Spec Kit produces files under specs/<YYYYMMDD-HHMMSS>-feature-name/:

specs/
└── 20260513-160000-feature-name/
    ├── spec.md              # Feature specification (FRs, NFRs, SCs, user stories)
    ├── plan.md              # Implementation plan (architecture, phases)
    ├── tasks.md             # Dependency-ordered task list
    ├── data-model.md        # Entity definitions and schemas
    ├── research.md          # Technical decisions and alternatives
    ├── quickstart.md        # Getting started guide
    ├── checklists/
    │   └── requirements.md  # Quality checklist
    └── contracts/
        ├── deep-links.md    # Deep link contract
        └── *.json           # Schema contracts

Constitution

The project constitution at .specify/memory/constitution.md defines non-negotiable principles. All specs, plans, and tasks are validated against it during /speckit.analyze.

Current constitution (v1.4.2) enforces 7 principles:

1. KMP Core — Business logic in commonMain only
2. Zero Lint Tolerance — spotlessCheck + detekt must pass
3. Compose Multiplatform UI — CMP, not Android-only Compose
4. Privacy First — No PII/location/key exposure
5. Design Standards Compliance — Review against Meshtastic design standards; cross-platform features must reference an upstream spec from meshtastic/design/features/
6. Documentation Freshness — User-facing changes update docs/en/ (in-app browser, Jekyll, Docusaurus) with last_updated frontmatter; links, coverage, the DocBundleLoader registry, and locale layout/nav_order matching docs/en/ with no locale parent are a blocking CI gate (docs-quality.yml) on PRs touching docs/**/*.md, freshness advisory
7. Verify Before Push — Local verification before any git push

Extension Hooks

Git hooks are configured in .specify/extensions.yml and run automatically:

• Before each command: Optional commit hook (commit outstanding changes)
• After each command: Optional commit hook (commit generated artifacts)
• Before specify: Mandatory feature branch creation

Meshtastic-Specific Conventions

Branch Naming

Feature branches created by /speckit.git.feature use timestamp-based numbering: YYYYMMDD-HHMMSS-feature-name (e.g., 20260511-211823-compose-screenshot-testing)

This avoids merge conflicts when multiple specs are developed on parallel branches.

Non-spec branches follow conventional commit-style prefixes: feat/, fix/, chore/, docs/, build/, ci/, refactor/, test/, deps/

Task ID Namespacing

To avoid collision when multiple specs exist, prefix task IDs with a short feature mnemonic (e.g., SST-T001 for screenshot testing, DISC-T001 for discovery). The prefix is defined per-spec in the tasks.md header.

Design Standards Gate

All specs with UI work must include a Phase 0 [UI-GATE] blocking task that reviews the Meshtastic design standards before implementation begins. The /speckit.analyze command flags missing gates as CRITICAL.

Deep Link Convention

All deep links must use the canonical URI scheme: meshtastic://meshtastic/settings/<path>. Compatibility aliases with camelCase or hyphenated variants are acceptable but must not be the primary contract.

Tips

• Run /speckit.analyze before /speckit.implement — it catches constitution violations, coverage gaps, and cross-artifact inconsistencies.
• Use /speckit.clarify when specs feel underspecified — it asks targeted questions and encodes answers directly into the spec.
• The /speckit.checklist command generates feature-specific quality gates beyond the standard code review checklist.
• All commands support passing arguments: /speckit.specify "description".
• Git hooks are optional by default (you'll be prompted). Set auto_execute_hooks: true in .specify/extensions.yml to skip prompts.

Existing Specs

Specs live in specs/, one directory per feature (<YYYYMMDD-HHMMSS>-<slug>; two legacy dirs use NNN-<slug> numbering). List that directory for the live inventory — each spec's spec.md / tasks.md records its own scope and status.

Related Skills

• implement-feature — Feature implementation workflow (post-spec)
• code-review — PR review checklist
• testing-ci — CI validation commands
• new-branch — Branch bootstrap recipes