An open source toolkit for hardware teams implementing Spec-Driven Development for hardware products and prototypes - spanning mechanical, electrical, and embedded systems.
- π€ What is Spec-Driven Hardware Development?
- β‘ Get Started
- π½οΈ Video Overview
- π€ Supported AI Agents
- π§ Specify CLI Reference
- π Core Philosophy
- π Development Phases
- π― Experimental Goals
- π§ Prerequisites
- π Learn More
- π Detailed Process
- π Troubleshooting
- π₯ Maintainers
- π¬ Support
- π Acknowledgements
- π License
Spec-Driven Development flips the script on traditional hardware development. For decades, CAD files and schematics have been king β specifications were just scaffolding we built and discarded once the "real work" of design began. Spec-Driven Hardware Development changes this: specifications become executable, directly generating working hardware designs, embedded code, and manufacturing documentation rather than just guiding them.
Hardware development is inherently complex, involving multiple disciplines:
- Mechanical Design: Enclosures, mounting systems, thermal management
- Electrical Engineering: Schematics, PCB layout, power distribution
- Embedded Systems: Firmware, drivers, communication protocols
- Manufacturing: Assembly procedures, testing protocols, quality control
Traditional approaches treat specs as throw-away documentation. Spec-Driven Hardware Development makes specifications the living source of truth that drives design decisions, validates implementations, and ensures all subsystems work together.
Choose your preferred installation method:
Install once and use everywhere:
uv tool install specify-cli --from git+https://github.com/LeFrenchPOC/hardware-spec-kit.gitThen use the tool directly:
specify init <PROJECT_NAME>
specify checkTo upgrade specify run:
uv tool install specify-cli --force --from git+https://github.com/LeFrenchPOC/hardware-spec-kit.gitRun directly without installing:
uvx --from git+https://github.com/LeFrenchPOC/hardware-spec-kit.git specify init <PROJECT_NAME>Use the /constitution command to create your project's governing principles and development guidelines that will guide all subsequent hardware development across mechanical, electrical, and embedded domains.
Use the /specify command to document:
- Product requirements and user scenarios
- Mechanical constraints and form factor requirements
- Electrical specifications and power budgets
- Embedded system functionality and interfaces
- Manufacturing and testing requirements
Use the /plan command to create a detailed implementation plan covering:
- CAD tool selection and mechanical design approach
- PCB design tools and electrical architecture
- Firmware development environment and embedded architecture
- Component selection and sourcing strategy
- Testing and validation procedures
Use the /tasks command to generate an actionable task breakdown organized by engineering discipline and hardware subsystem.
Use the /implement command to guide implementation across all hardware domains while maintaining traceability to specifications.
Coming soon: Video walkthrough of Hardware Spec Kit for hardware product development
Note: This is a fork of github/spec-kit adapted specifically for hardware development workflows.
| Agent | Support | Notes |
|---|---|---|
| Claude Code | β | |
| GitHub Copilot | β | |
| Gemini CLI | β | |
| Cursor | β | |
| Qwen Code | β | |
| opencode | β | |
| Windsurf | β | |
| Kilo Code | β | |
| Auggie CLI | β | |
| CodeBuddy CLI | β | |
| Roo Code | β | |
| Codex CLI | β | |
| Amazon Q Developer CLI | Amazon Q Developer CLI does not support custom arguments for slash commands. | |
| Amp | β |
| Command | Description |
|---|---|
init |
Initialize a new Hardware Specify project from the latest template |
check |
Check for installed tools (git, AI agents, CAD tools) |
| Argument/Option | Type | Description |
|---|---|---|
<project-name> |
Argument | Name for your new hardware project directory (optional if using --here, or use . for current directory) |
--ai |
Option | AI assistant to use: claude, gemini, copilot, cursor-agent, qwen, opencode, codex, windsurf, kilocode, auggie, roo, codebuddy, amp, or q |
--script |
Option | Script variant to use: sh (bash/zsh) or ps (PowerShell) |
--ignore-agent-tools |
Flag | Skip checks for AI agent tools like Claude Code |
--no-git |
Flag | Skip git repository initialization |
--force |
Flag | Merge template files into non-empty directory without confirmation |
--here |
Flag | Initialize in the current directory (equivalent to .) |
--debug |
Flag | Enable debug output for troubleshooting |
--github-token |
Option | GitHub personal access token for API requests (helps with rate limiting) |
# Basic hardware project initialization
specify init my-hardware-project
# Initialize with specific AI assistant
specify init my-hardware-project --ai claude
# Initialize with Cursor support
specify init my-hardware-project --ai cursor-agent
# Initialize with PowerShell scripts (Windows/cross-platform)
specify init my-hardware-project --ai copilot --script ps
# Initialize in current directory
specify init . --ai copilot
# or use the --here flag
specify init --here --ai copilot
# Force merge into current (non-empty) directory without confirmation
specify init . --force --ai copilot
# or
specify init --here --force --ai copilot
# Skip git initialization
specify init my-hardware-project --ai gemini --no-git
# Enable debug output for troubleshooting
specify init my-hardware-project --ai claude --debug
# Use GitHub token for API requests (helpful for corporate environments)
specify init my-hardware-project --ai claude --github-token ghp_your_token_here
# Check system requirements
specify checkAfter running specify init, your AI coding agent will have access to these slash commands for structured hardware development:
/constitution- Define project principles, design constraints, and quality standards specific to hardware development/specify- Create comprehensive hardware product specifications covering mechanical, electrical, and embedded requirements/plan- Generate detailed implementation plans with tool selection, design approach, and validation procedures/tasks- Break down work into actionable tasks organized by discipline and subsystem/implement- Execute implementation following the structured task breakdown
/clarify- Validate and refine specifications before planning/analyze- Perform deep analysis of specifications and designs/checklist- Generate requirement validation checklists for hardware verification
Hardware Spec Kit adapts software engineering best practices to the unique challenges of hardware development:
- Specifications First: Define complete mechanical, electrical, and embedded requirements before any CAD work
- Multi-Discipline Integration: Ensure mechanical, electrical, and embedded systems are designed as integrated wholes
- Design for Test: Build testability into hardware from the start - mechanical fit checks, electrical validation, firmware testing
- Iterative Refinement: Start with high-level architecture, progressively refine through detailed design
- Documentation as Code: Keep specifications, schematics, and firmware docs in sync with actual designs
- Manufacturing-Aware: Consider assembly, testing, and manufacturing constraints throughout the design process
| Phase | Focus | Key Activities |
|---|---|---|
| 0-to-1 Development ("Greenfield") | Generate from scratch |
|
| Creative Exploration | Parallel implementations |
|
| Iterative Enhancement ("Brownfield") | Product evolution |
|
Hardware Spec Kit aims to:
- Reduce design iterations: Get it right the first time through comprehensive specifications
- Improve cross-discipline communication: Bridge mechanical, electrical, and embedded teams
- Accelerate prototyping: Clear specs lead to faster, more focused prototyping
- Minimize late-stage changes: Catch design issues during spec review, not after PCB fab
- Enable parallel development: Well-defined interfaces allow teams to work independently
- Maintain design traceability: Link every component and line of code back to requirements
- Linux/macOS/Windows
- Supported AI coding agent
- uv for package management
- Python 3.11+
- Git
- Optional CAD Tools: Fusion360, KiCAD, or your preferred mechanical/electrical design tools
If you encounter issues with an agent, please open an issue so we can refine the integration.
- Complete Spec-Driven Development Methodology - Deep dive into the full process adapted for hardware
- Detailed Walkthrough - Step-by-step hardware implementation guide
Click to expand the detailed step-by-step walkthrough for hardware projects
You can use the Specify CLI to bootstrap your hardware project, which will bring in the required artifacts in your environment. Run:
specify init <project_name>Or initialize in the current directory:
specify init .
# or use the --here flag
specify init --here
# Skip confirmation when the directory already has files
specify init . --force
# or
specify init --here --force
You will be prompted to select the AI agent you are using. You can also proactively specify it directly in the terminal:
specify init <project_name> --ai claude
specify init <project_name> --ai gemini
specify init <project_name> --ai copilot
# Or in current directory:
specify init . --ai claude
specify init . --ai codex
# or use --here flag
specify init --here --ai claude
specify init --here --ai copilotThe CLI will check if you have your selected AI agent installed. If you do not, or you prefer to get the templates without checking for the right tools, use --ignore-agent-tools with your command:
specify init <project_name> --ai claude --ignore-agent-toolsThe first step is to establish the guiding principles for your hardware project. This is done using the /constitution command with your AI agent.
The constitution defines:
- Design principles and constraints specific to your hardware
- Quality standards for mechanical, electrical, and embedded work
- Testing requirements and validation procedures
- Tool choices and workflows (CAD, PCB design, firmware development)
- Manufacturing and assembly considerations
Example prompt for a hardware project:
We're building an IoT environmental sensor device. Key requirements:
- Mechanical: IP67 rated enclosure, wall-mountable, 100x80x40mm max
- Electrical: Battery powered (2x AA), <50ΞΌA sleep current, I2C sensors
- Embedded: ESP32-C3, MicroPython firmware, MQTT over WiFi
- Manufacturing: Injection molded enclosure, PCBA by external CM
- Testing: Environmental chamber testing, EMC compliance required
Use the /specify command to create detailed functional specifications. For hardware, you'll want to specify:
Create specs for an environmental monitoring device with:
- Temperature range: -40Β°C to +85Β°C, Β±0.5Β°C accuracy
- Humidity: 0-100% RH, Β±3% accuracy
- Pressure: 300-1100 hPa
- Battery life: 2 years on 2x AA batteries with 5-minute reporting interval
- Connectivity: WiFi 2.4GHz, MQTT to cloud platform
- Enclosure: IP67, UV-resistant plastic, wall-mountable
- User interface: RGB LED status indicator, magnetic reed switch for config mode
The output will be a structured specification document covering:
- Functional requirements (what the device must do)
- Performance requirements (accuracy, battery life, response time)
- Physical requirements (dimensions, weight, environmental ratings)
- Interface requirements (sensors, connectivity, user interaction)
- Compliance requirements (EMC, safety, environmental)
Before generating the implementation plan, use /clarify to validate and refine your specifications:
/clarify
This ensures:
- No ambiguous requirements
- All interfaces clearly defined
- Conflicting requirements identified and resolved
- Missing specifications highlighted
Now specify your technical approach. For hardware, this includes tool selection and design strategy:
We'll implement this using:
- Mechanical: Fusion360 for enclosure design, 3D print prototypes, injection molding for production
- Electrical: KiCAD for schematic and PCB, 4-layer board, Espressif devkit for prototyping
- Embedded: ESP-IDF with Arduino framework, OTA firmware updates, low-power state machine
- Sensors: Sensirion SHT40 (temp/humidity), Bosch BMP388 (pressure), I2C bus
- Testing: Environmental chamber validation, current profiling, RF testing
The output will include:
- Component selection and bill of materials
- Mechanical design approach and CAD file structure
- Electrical architecture and PCB stackup
- Firmware architecture and module breakdown
- Testing and validation procedures
- Manufacturing and assembly plan
Your directory tree will include:
.
βββ memory
β βββ constitution.md
βββ scripts
β βββ bash/
β β βββ check-prerequisites.sh
β β βββ common.sh
β β βββ create-new-feature.sh
β β βββ update-agent-context.sh
β βββ powershell/
β βββ check-prerequisites.ps1
β βββ common.ps1
β βββ create-new-feature.ps1
β βββ update-agent-context.ps1
βββ specs
β βββ 001-iot-sensor
β βββ spec.md
β βββ plan.md
β βββ data-model.md # Component interfaces and data structures
β βββ contracts/ # API specs, I2C command sets
β βββ research.md # Technology decisions and trade-offs
βββ templates
βββ plan-template.md
βββ spec-template.md
βββ tasks-template.md
Review the generated plan to ensure:
- Correct components selected (check availability, lifecycle status)
- Realistic power budget and battery life calculations
- Feasible mechanical design (moldability, assembly)
- Appropriate firmware complexity for timeline
- Complete testing coverage
You can ask your AI agent to refine specific sections or validate technical decisions.
Use /tasks to create an actionable task list organized by engineering discipline:
/tasks
This will generate a structured task breakdown:
- Phase 1: Design & Specification - Detailed requirements, interface definitions
- Phase 2: Mechanical Design - Enclosure CAD, 3D printed prototypes
- Phase 3: Electrical Design - Schematic capture, PCB layout, power analysis
- Phase 4: Firmware Development - Driver development, application logic, power management
- Phase 5: Integration - Hardware/firmware integration, system testing
- Phase 6: Validation - Environmental testing, compliance testing, field trials
Once ready, use the /implement command to execute your hardware development:
/implement
The AI agent will guide you through:
- Creating CAD models and generating manufacturing files
- Designing schematics and PCB layouts
- Writing and testing firmware modules
- Documenting assembly procedures
- Defining test protocols and validation criteria
[!IMPORTANT] Hardware implementation requires appropriate tools installed (Fusion360, KiCAD, ESP-IDF, etc.) and access to prototyping resources (3D printer, PCB fab, components).
Monitor your progress, validate designs at each milestone, and iterate based on test results. Your AI agent can help debug issues, suggest design improvements, and maintain documentation throughout the process.
Issue: "No template found for AI assistant"
Make sure you have a valid GitHub release with hardware template assets. See RELEASE_FIX_GUIDE.md for details.
Issue: AI commands not showing up
Verify that the command files exist in the correct location for your AI agent:
- Claude:
.claude/commands/ - Copilot:
.github/prompts/ - Gemini:
.gemini/commands/
Issue: Script execution fails
Ensure you have the required tools installed and permissions set correctly:
# Make scripts executable
chmod +x .specify/scripts/bash/*.sh
# For PowerShell users on Linux/macOS
pwsh .specify/scripts/powershell/script-name.ps1- Check existing Issues
- Review CONTRIBUTING.md for development setup
- Open a new issue with details about your environment and the problem
This hardware fork is maintained by:
- @FrenchPOC - Hardware adaptation and maintenance
Original Spec Kit by:
- @github - Original Spec Kit framework
Need help? Have questions about hardware-specific workflows?
- π Open an issue
- π¬ Discussions
- π Documentation
- οΏ½οΏ½ Upstream Spec Kit
This project is a fork of github/spec-kit, adapted specifically for hardware development workflows. We're grateful to the original maintainers and contributors for creating the foundation that makes this hardware-focused toolkit possible.
Special thanks to:
- The Spec Kit team at GitHub for the original framework
- All contributors to the upstream spec-kit project
- The hardware development community for feedback and testing
This project is licensed under the MIT License - see the LICENSE file for details.
Built with β€οΈ for hardware teams everywhere
Bringing software engineering best practices to mechanical, electrical, and embedded development