Initialize Spec-Driven Development Project

You are setting up a Spec-Driven Development (SDD) project. This creates the foundational scaffold that all other spec-kit skills depend on.

Upstream source: github/spec-kit — run /spec-kit:check-updates to check for template updates.

Workflow

Step 1: Detect Project Context

• Check if .speckit/ already exists. If so, inform the user and ask if they want to reinitialize (this will overwrite templates but NOT existing specs).
• Detect the project name from package.json, pyproject.toml, Cargo.toml, go.mod, or the current directory name.
• Ask the user to confirm the project name or provide a different one.

Step 2: Create Directory Structure

Create the following structure:

.speckit/
├── constitution.md
├── spec-template.md
├── plan-template.md
└── tasks-template.md
specs/

Step 3: Generate Constitution Template

Create .speckit/constitution.md with this content:

# [PROJECT_NAME] Constitution
<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->

## Core Principles

### [PRINCIPLE_1_NAME]
<!-- Example: I. Library-First -->
[PRINCIPLE_1_DESCRIPTION]
<!-- Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented -->

### [PRINCIPLE_2_NAME]
<!-- Example: II. CLI Interface -->
[PRINCIPLE_2_DESCRIPTION]
<!-- Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr -->

### [PRINCIPLE_3_NAME]
<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
[PRINCIPLE_3_DESCRIPTION]
<!-- TDD mandatory: Tests written → User approved → Tests fail → Then implement -->

### [PRINCIPLE_4_NAME]
<!-- Example: IV. Integration Testing -->
[PRINCIPLE_4_DESCRIPTION]
<!-- Focus areas requiring integration tests: New library contract tests, Contract changes -->

### [PRINCIPLE_5_NAME]
<!-- Example: V. Simplicity -->
[PRINCIPLE_5_DESCRIPTION]
<!-- Start simple, YAGNI principles; Complexity must be justified -->

## Governance
<!-- Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->

[GOVERNANCE_RULES]

**Version**: 0.0.0 | **Ratified**: [DATE] | **Last Amended**: [DATE]

Replace [PROJECT_NAME] with the detected/confirmed project name. Leave all other [PLACEHOLDER] tokens as-is for the constitution skill to fill in.

Step 4: Generate Spec Template

Create .speckit/spec-template.md with this content:

# Feature Specification: [FEATURE NAME]

**Feature Branch**: `[###-feature-name]`
**Created**: [DATE]
**Status**: Draft
**Input**: User description: "$ARGUMENTS"

## User Scenarios & Testing

<!--
  IMPORTANT: User stories should be PRIORITIZED as user journeys ordered by importance.
  Each user story/journey must be INDEPENDENTLY TESTABLE - meaning if you implement
  just ONE of them, you should still have a viable MVP that delivers value.

  Assign priorities (P1, P2, P3, etc.) where P1 is the most critical.
-->

### User Story 1 - [Brief Title] (Priority: P1)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value and why it has this priority level]

**Independent Test**: [How to verify this story alone, e.g., "Can be fully tested by [specific action]"]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]
2. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 2 - [Brief Title] (Priority: P2)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value]

**Independent Test**: [How to verify this story independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### User Story 3 - [Brief Title] (Priority: P3)

[Describe this user journey in plain language]

**Why this priority**: [Explain the value]

**Independent Test**: [How to verify this story independently]

**Acceptance Scenarios**:

1. **Given** [initial state], **When** [action], **Then** [expected outcome]

---

### Edge Cases

- What happens when [boundary condition]?
- How does system handle [error scenario]?

## Requirements

### Functional Requirements

- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]
- **FR-003**: Users MUST be able to [key interaction]
- **FR-004**: System MUST [data requirement]
- **FR-005**: System MUST [behavior]

*Mark unclear requirements:*
- **FR-006**: System MUST [NEEDS CLARIFICATION: specific question]

### Key Entities *(include if feature involves data)*

- **[Entity 1]**: [What it represents, key attributes without implementation]
- **[Entity 2]**: [What it represents, relationships to other entities]

## Success Criteria

### Measurable Outcomes

- **SC-001**: [Measurable metric, e.g., "Users can complete action in under 2 minutes"]
- **SC-002**: [Measurable metric, e.g., "System handles 1000 concurrent users"]
- **SC-003**: [User satisfaction metric]
- **SC-004**: [Business metric]

## Assumptions

- [Assumption about target users]
- [Assumption about scope boundaries]
- [Assumption about data/environment]
- [Dependency on existing system/service]

Step 5: Generate Plan Template

Create .speckit/plan-template.md with this content:

# Implementation Plan: [FEATURE]

**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link to spec.md]

## Summary

[Extract from feature spec: primary requirement + technical approach]

## Technical Context

**Language/Version**: [e.g., Python 3.11, TypeScript 5.x, or NEEDS CLARIFICATION]
**Primary Dependencies**: [key libraries/frameworks, or NEEDS CLARIFICATION]
**Storage**: [database/file system/API, or N/A]
**Testing**: [framework and strategy, or NEEDS CLARIFICATION]
**Target Platform**: [web/mobile/CLI/library, or NEEDS CLARIFICATION]
**Project Type**: [library/cli/web-service/mobile-app/compiler/desktop-app]
**Performance Goals**: [latency, throughput targets, or NEEDS CLARIFICATION]
**Constraints**: [budget, timeline, compatibility, or NEEDS CLARIFICATION]
**Scale/Scope**: [e.g., 10k users, 1M LOC, 50 screens, or NEEDS CLARIFICATION]

## Constitution Check

*Re-check after design phase.*

[For each principle in the constitution, confirm compliance or document how the plan addresses it]

## Project Structure

### Documentation (this feature)

```text
specs/[###-feature]/
├── spec.md
├── plan.md           (this file)
├── research.md       (Phase 0 research output)
├── data-model.md     (Phase 1 design output)
├── contracts/        (Phase 1 interface definitions)
└── tasks.md          (generated by /spec-kit:tasks)

Source Code (repository root)

src/
├── models/
├── services/
└── [adjust based on project type]

tests/
├── contract/
├── integration/
└── unit/

Structure Decision: [Document the selected structure]

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
[If any]	[Reason]	[Why simpler approach doesn't work]

### Step 6: Generate Tasks Template

Create `.speckit/tasks-template.md` with this content:

```markdown
# Implementation Tasks: [FEATURE]

**Branch**: `[###-feature-name]` | **Date**: [DATE]
**Spec**: [link] | **Plan**: [link]

<!--
  Tasks MUST be organized by user story so each story can be independently
  implemented, tested, and delivered as an MVP increment.
-->

## Phase 1: Setup (Shared Infrastructure)

- [ ] T001 Create project structure per implementation plan
- [ ] T002 Initialize [language] project with [framework] dependencies

---

## Phase 2: Foundational (Blocking Prerequisites)

**⚠️ CRITICAL**: No user story work can begin until this phase is complete

- [ ] T003 Setup database schema and migrations framework
- [ ] T004 [P] Implement authentication/authorization framework

**Checkpoint**: Foundation ready — user story implementation can now begin

---

## Phase 3: User Story 1 - [Title] (Priority: P1) 🎯 MVP

**Goal**: [Brief description of what this story delivers]

**Independent Test**: [How to verify this story works on its own]

- [ ] T005 [P] [US1] Create [Entity] model in src/models/[entity].py
- [ ] T006 [US1] Implement [Service] in src/services/[service].py
- [ ] T007 [US1] Implement [feature] in src/[location]/[file].py

**Checkpoint**: User Story 1 should be fully functional and independently testable

---

## Phase 4: User Story 2 - [Title] (Priority: P2)

- [ ] T008 [P] [US2] Create [Entity] model in src/models/[entity].py
- [ ] T009 [US2] Implement [Service] in src/services/[service].py

---

## Phase N: Polish & Cross-Cutting Concerns

- [ ] TXXX [P] Documentation updates
- [ ] TXXX Code cleanup and refactoring

---

**Legend**: `[P]` = parallelizable | `[US#]` = user story reference | `[T###]` = task ID

Step 7: Create specs/ Directory

Create an empty specs/ directory. If git is being used, create a specs/.gitkeep file.

Step 8: Write Upstream Sync Metadata

Create .speckit/upstream.json with this content (use today's date in ISO format):

{
  "source": "github.com/github/spec-kit",
  "source_sha": "94ba857b78074024f095b08b45802e17d2bff653",
  "last_synced": "[TODAY'S DATE]",
  "plugin_version": "2.0.0"
}

Step 9: Output Summary

Display a summary to the user:

SDD Project Initialized: [PROJECT_NAME]

Created:
  .speckit/constitution.md    - Project principles (template)
  .speckit/spec-template.md   - Feature specification template
  .speckit/plan-template.md   - Implementation plan template
  .speckit/tasks-template.md  - Task breakdown template
  .speckit/upstream.json      - Upstream sync metadata
  specs/                      - Feature specifications directory

Next step: Run /spec-kit:constitution to define your project's core principles.
To check for template updates: Run /spec-kit:check-updates

Important Rules

• Always use today's date in ISO format (YYYY-MM-DD) for any date fields.
• Do NOT fill in placeholder values — leave them for the respective skills to handle.
• The specs/ directory should be at the project root, NOT inside .speckit/.
• If .speckit/ already exists, preserve any non-template files the user may have added.