📐 specify-framework

Specify (GitHub Spec Kit) is an advanced Spec-Driven Development (SDD) toolkit designed by GitHub. It standardizes and automates SDD loops for developers collaborating with AI coding assistants (such as gemini-cli, claude-code, and GitHub Copilot), ensuring codebase safety, structural consistency, and feature alignment.

For the corresponding hands-on module, see spec-driven-dev.md.

---

📊 Tool Datasheet

Metric	Details
Tool Name	Specify (GitHub Spec Kit)
Category	Spec-Driven Development (SDD) & Orchestration Framework
Purpose	To enforce a strict, testable "spec-first" cycle, generating clear implementation plans, dependency-ordered task checklists, and automated agent memory updates.
License	Open Source
Integrations	gemini-cli, claude-code, GitHub Copilot, Cursor, Roo Code, Amazon Q
Template Formats	Linux POSIX Shell (.sh), Windows PowerShell (.ps1)

🛠️ Core Capabilities

1. Iterative AI Slash Commands: Controls the development cycle through standardized slash command hooks registered directly inside AI agent configurations.
2. Targeted Feature Branching: Auto-generates clean, isolated Git feature branches matching your spec names.
3. Strict Specification Checklists: Validates requirements, edge cases, and technology-agnostic success criteria before allowing coding to start.
4. Automatic Agent Memory Updates: Dynamic injection of technical context and rules into agent configuration directories (.claude/, .gemini/, etc.).
5. TDD Task Checklists: Compiles dependency-ordered tasks.md files where tasks follow strict checkbox formats (- [ ] T001 [StoryID] Description).

---

🎛️ Command Reference

Specify hooks into your AI client session using these standardized slash commands:

Command	Purpose	Primary Execution Flow
/speckit.constitution	Establish codebase principles	Reads core programming rules and templates to initialize project-wide coding standards.
/speckit.specify	Create feature specification	Takes a natural language description, generates a feature branch, and drafts a markdown specification.
/speckit.clarify	Resolve ambiguous scope	Prompts the user with structured multiple-choice questions to resolve outstanding spec details.
/speckit.plan	Compile technical design	Generates research decisions, API contracts (e.g. OpenAPI), database schemas, and updates agent context.
/speckit.checklist	Validate readiness	Audits design documents to check completeness, testability, and technology isolation.
/speckit.tasks	Generate task checklist	Outputs a dependency-ordered, checkbox-based tasks.md file grouped by priority user stories.
/speckit.analyze	Cross-artifact validation	Runs consistency checks between requirements, designs, and tasks.
/speckit.implement	Execute code changes	Walks through tasks.md sequentially, updates files, runs test suites, and checks off tasks.

---

🧭 Step-by-Step Tutorial & Setup

This tutorial guides you through installing the Specify CLI tool, initializing a project, and running through a feature implementation cycle using the gemini-cli.

1. Prerequisites Check

Verify that the Specify CLI is installed and check for available local development tools:

specify check

2. Initialize a New Project

Initialize a fresh Specify template in your workspace for the gemini-cli and bash scripts:

cd ~/AI_BOOTCAMP/labs
specify init my-spec-project --ai gemini --script sh

This generates the following directory layout:

• 📂 .specify/ - Spec templates, configuration files, and utility bash scripts.
• 📂 .gemini/commands/ - Registered command configurations mapped to the /speckit.* commands.
• 📂 specs/ - Working directory for feature specification sheets.
• 📂 tests/ - Project testing suite.

---

💡 The SDD Development Cycle

Once initialized, navigate into your new project folder and launch your AI client (e.g., gemini or claude). Execute the commands inside the active AI agent chat session:

Step 1: Draft the Specification

Type the feature description directly after the command:

/speckit.specify "Implement user JWT authentication with PostgreSQL storage"

• What happens: The agent generates a feature branch named 001-user-jwt-auth, loads the spec-template.md, and drafts the functional requirements, user scenarios, and measurable success criteria.

Step 2: Resolve Ambiguity

If there are any unspecified assumptions (e.g., JWT expiration times, hashing algorithms):

/speckit.clarify

• What happens: The agent asks multiple-choice clarification questions. Once answered, it writes them into the specification sheet and marks them complete.

Step 3: Tech Design Planning

Translate requirements into technical specs:

/speckit.plan

• What happens: The agent creates technical design documents (data-model.md and OpenAPI /contracts/), and updates .gemini/ rules with the new stack information.

Step 4: Generate Actionable Checklist

Compile your execution plan:

/speckit.tasks

• What happens: The agent compiles a dependency-ordered tasks.md file:

- [ ] T001 Initialize database migrations for users table
- [ ] T002 [US1] Create User model logic in src/models/user.py
- [ ] T003 [US1] Create token utility in src/utils/jwt.py

Step 5: Implement Feature

Initiate code generation:

/speckit.implement

• What happens: The agent reads tasks.md, creates/edits the target files, runs the test suite, and checks off tasks as completed in the markdown file until the feature is fully implemented.