# Speckit

> Skill: Spec Kit (Specification-Driven Development)

- Skill: `meshtastic/speckit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add meshtastic/speckit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/meshtastic/speckit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: meshtastic (https://skillmd.com/u/meshtastic)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/meshtastic/speckit

---

# 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)

| Command | Slash Command | Purpose |
|---------|--------------|---------|
| **Specify** | `/speckit.specify` | Create or update `spec.md` from a feature description |
| **Clarify** | `/speckit.clarify` | Ask up to 5 targeted clarification questions, encode answers into spec |
| **Plan** | `/speckit.plan` | Generate `plan.md` with architecture, phases, data models |
| **Tasks** | `/speckit.tasks` | Generate `tasks.md` with dependency-ordered, parallelizable tasks |
| **Analyze** | `/speckit.analyze` | Read-only cross-artifact consistency and quality analysis |
| **Implement** | `/speckit.implement` | Execute tasks from `tasks.md` with status tracking |

### Supporting Commands

| Command | Slash Command | Purpose |
|---------|--------------|---------|
| **Checklist** | `/speckit.checklist` | Generate a custom quality checklist for the feature |
| **Constitution** | `/speckit.constitution` | Create or update project constitution (`.specify/memory/constitution.md`) |
| **Tasks to Issues** | `/speckit.taskstoissues` | Convert `tasks.md` into GitHub Issues |

### Git Extension Commands

| Command | Slash Command | Purpose |
|---------|--------------|---------|
| **Git Initialize** | `/speckit.git.initialize` | Initialize git repo (skips if already initialized) |
| **Git Feature** | `/speckit.git.feature` | Create a feature branch with sequential numbering |
| **Git Commit** | `/speckit.git.commit` | Auto-commit changes after a Spec Kit command |
| **Git Remote** | `/speckit.git.remote` | Detect git remote URL for GitHub integration |
| **Git Validate** | `/speckit.git.validate` | Validate branch follows feature naming conventions |

## Full Workflow (End-to-End)

The standard SDD cycle for a new feature:

```text
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:

```text
/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.3.6) 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, and the DocBundleLoader registry are a blocking CI gate (`docs-quality.yml`) on PRs touching `docs/en/**`, 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