Status: v0.2 — exercised on 7 worked examples (see examples/), MIT-licensed.
Software PMs have established tools — user stories, PRDs, sprint planning. Pure hardware PMs have theirs — datasheets, BOMs, DFM checklists. But when the product is both — firmware-driven hardware with sensors, actuators, maybe an app, maybe cloud — most PMs either use a software PRD template that ignores physics, or a hardware spec that ignores the software.
The boundary between HW and SW is where the expensive mistakes happen, and it's usually the least documented part.
You have a connected product idea and want to stress-test it before committing resources. Here's the fastest path:
# 1. Install Claude Code (https://docs.anthropic.com/en/docs/claude-code)
# 2. Clone this repo and open a terminal in it
git clone https://github.com/yoelf22/electrum.git && cd electrum
# 3. Start Claude Code and run the skill
claude
> /electrum <describe your product in one sentence>The process will walk you through a structured dialogue — mapping the HW/SW boundary, forcing specifics, and surfacing what you're still assuming. It pauses after every output for your review. Budget 60–90 minutes for a full run.
Don't have Claude Code? The templates work without AI. Copy templates/system_description_template.md into your project folder, fill it in by hand, then run through templates/checklist.md. That's 80% of the value.
Want to see what a full run looks like? Read the Bubbler walkthrough — a soup-to-nuts example that turned "automated soap bubble machine" into a force-sensing feedback system with a 90-item gate review.
A repeatable, AI-assisted process for defining hardware products that have software inside them — so the firmware team and the mechanical team aren't surprised by each other at EVT.
It takes a product idea from "I think this could work" through to a structured system description, product illustrations, and a presentation-ready carousel. Eight phases, driven by the /electrum Claude Code skill:
| Phase | Output | Description |
|---|---|---|
| 1. Explore | explore_notes.md |
Map the HW/SW boundary, identify knowledge gaps, surface risks |
| 2. High-Level Design | high_level_design.md |
Single-page system overview: blocks, interfaces, constraints, hardest problems |
| 3. Component Arrangement | component_arrangement.md, arrangement_options.png |
Spatial layout alternatives — where boards, batteries, sensors, and actuators sit relative to each other and the enclosure |
| 4. System Description | system_description.md, schedule_gantt.png |
Full engineering-grade spec with real components, power budgets, firmware architecture |
| 5. Gate Checklist | gate_checklist.md |
Validate completeness across both domains (103 items, PASS/FAIL/N/A) |
| 6. Product Visual | product_visual.png |
Pick an existing diagram from earlier phases (or a user-supplied image) as the carousel visual |
| 7. PPTX Carousel | *_Carousel.pptx |
LinkedIn-format slide deck (4:5 portrait, dark theme, 8 pages) |
| 8. PDF Carousel | *_Carousel.pdf |
Same carousel as multi-page PDF |
Phases 1-5 produce the engineering definition. Phases 6-8 turn it into visual presentation materials.
Three documents carry the product definition. Each one feeds the next:
High-Level Design → System Description → Gate Checklist
(what and why) (how, in detail) (is it complete?)
↑ │
└──── a FAIL sends you back to revise ←───────┘
| Document | What it is | Who writes it | Who reads it | When |
|---|---|---|---|---|
| High-Level Design | A one-to-two-page overview: what the product is, the main blocks and how they connect, the constraints that rule options out, the three hardest problems | The product manager, with one hardware lead and one software lead | Executives, partners, investors, new team members: anyone who needs to understand the product in five minutes | After the idea is explored, before anyone picks parts. Half a day to a day |
| System Description | The full engineering spec: real part numbers, interfaces, power budget, firmware architecture, connectivity, key decisions, and constraints (BOM cost with lead times and minimum order quantities, lead times for manufactured parts, assembly and inspection times, certification) and a Gantt schedule with the critical path | The technical lead or systems engineer, with the electrical, mechanical, firmware and app leads | Engineers design from it; suppliers and contract manufacturers quote from it | Once the High-Level Design is agreed, before schematics or tooling. Several days, then kept current through the first engineering prototype build (EVT) |
| Gate Checklist | 103 items, each marked PASS / FAIL / N/A, that test whether the System Description is complete enough to start detailed design. Items tagged [HW↔SW] target the hardware/software line | Preferably someone who did not write the System Description: a reviewer, the engineering manager, or the hardware and software leads together | The team deciding whether to commit to detailed design | When you believe the System Description is ready. Re-run after each revision until the FAILs left are ones you accept |
The High-Level Design is also a gate. If it doesn't hold together, the details won't either, so don't start the System Description until it does. The System Description builds on it rather than repeating it: its vision, architecture, subsystem, interface, constraint and open-question sections each expand the matching High-Level Design section.
For people who'd rather fill in Word than markdown, the same three documents are available as fill-in forms on the Electrum Word Kit page, linked from tangibles-book.com/tools/electrum. The grey text in each is the Bubbler worked example; it disappears when you type. scripts/build_word_forms.py builds them from templates/ and the Bubbler example.
The workbook (electrum-workbook.docx) is all three forms in one file, in fill-in order. It is not a fourth step, and the other documents don't come from it: the three single files contain the same forms. Use the workbook when one person or team takes the product through all three. Use the single files when different people own each document or you share them at different times.
pip install -r requirements.txtRequired packages: python-pptx, reportlab, playwright, matplotlib, numpy.
pip install playwright
python -m playwright install chromiumInstall Claude Code and open a terminal in this repo. The /electrum skill is automatically available:
claude
> /electrum smart posture-correcting office chair├── scripts/ # Python reference implementations (carousel, diagrams, deck builders)
├── templates/ # Directive markdown files (workflow, checklists, templates)
├── examples/ # Worked examples with full output artifacts
│ ├── bubbler-automated-soap-bubble-maker/ ← start here (has WALKTHROUGH.md)
│ ├── pop-miniature-popcorn-machine/
│ ├── metronome/
│ ├── chair_balancing_act/
│ ├── consumable-electric-toothbrush/
│ ├── shusher/
│ └── smart_sensor_hub/
└── output/ # Raw output from recent runs
| File | What it does |
|---|---|
electrum/templates/hw_sw_product_initiation.md |
8-phase workflow from concept to presentation |
electrum/templates/hw_sw_high_level.md |
Single-page system overview template |
electrum/templates/system_description_template.md |
Full system description template with HW↔SW boundary items |
electrum/templates/checklist.md |
Gate checklist — 103 items, each tagged if it targets the HW/SW boundary |
electrum/templates/skills_map.md |
16 competency areas a PM should understand or staff for |
.claude/skills/electrum/SKILL.md |
Claude Code skill definition (drives the 8-phase workflow) |
| File | What it does |
|---|---|
electrum/scripts/generate_illustration.py |
DALL-E image generation via Playwright browser automation |
electrum/scripts/build_carousel.py |
PPTX + PDF carousel builder (LinkedIn-format, 4:5 portrait) |
electrum/scripts/build_deck.py |
Executive product overview deck builder |
electrum/scripts/build_high_level_deck.py |
High-level design deck builder |
electrum/scripts/visualize.py |
Visualization utilities |
electrum/scripts/block_diagram.py |
Block diagram generator |
scripts/gantt.py |
Gantt chart of the §9 Schedule table, critical path highlighted |
scripts/build_word_forms.py |
Builds the Word fill-in forms from templates/ and the Bubbler example |
| Project | What it is | Phases covered |
|---|---|---|
bubbler-automated-soap-bubble-maker/ |
Force-sensing automated bubble machine with adaptive optimization — full walkthrough | All 8 phases |
pop-miniature-popcorn-machine/ |
Miniature countertop popcorn machine with heating and motor control | Explore, HLD, system description, gate checklist, carousel |
metronome/ |
Wrist-worn haptic metronome bracelet for musicians — silent, precise beat pulses | All phases |
chair_balancing_act/ |
Clip-on tilt sensor that plays an escalating tone when a chair leaves static balance | HLD, system description, gate checklist |
consumable-electric-toothbrush/ |
Disposable electric toothbrush with wear tracking | Full |
shusher/ |
Noise-aware mechanical mute device with sound detection | HLD, system description, gate checklist |
smart_sensor_hub/ |
Wireless indoor environment monitor (CO2, temp, humidity, PM) with BLE mesh | HLD, system description |
The bubbler example includes a step-by-step walkthrough showing what each phase surfaced and what the team would have missed without the process.
- Open a terminal in this repo
- Run
claudeto start Claude Code - Type
/electrum <your product idea> - Walk through all 8 phases interactively — Claude drafts, you review and refine at each step
- Final output: a complete product definition + diagrams + presentation deck
Download the workbook or the three single forms from the Electrum Word Kit and fill them in order: High-Level Design, System Description, Gate Checklist. See The Documents for who owns each one and when.
The core toolkit is markdown templates and checklists — no AI required:
- Understand the process — Read
electrum/templates/hw_sw_product_initiation.mdfor the workflow overview - Assess your gaps — Review
electrum/templates/skills_map.mdfor team competency planning - Create the high-level design — Copy
electrum/templates/hw_sw_high_level.mdinto your project folder and fill it in - Write the system description — Copy
electrum/templates/system_description_template.mdand work through each section - Validate — Run through
electrum/templates/checklist.mdto confirm nothing was missed
For image generation and carousel building, adapt the scripts in electrum/scripts/ to your product.
Hardware product managers and technical leads building products where physical hardware and software must be designed together. The toolkit is most useful when:
- Your product has firmware, and maybe a companion app or cloud backend
- Your team spans EE/ME and software disciplines
- You need documents that both an executive and an engineer can use
- You want presentation-ready materials alongside the engineering spec
- You've been burned before by HW/SW integration surprises at EVT
Electrum is the open-source companion to Tangibles — a book on building connected hardware your competitors can't copy. The book's companion site hosts an overview of Electrum plus a set of free, no-signup tools for connected-hardware teams:
Book: tangibles-book.com · Available on Amazon: https://a.co/d/00nTWJs0
- Electrum overview — what this toolkit is, with worked examples
- IoT Security Scorecard — grade your device against ETSI EN 303 645 / EU CRA
- Security Requirements Generator — a PRD-ready requirements list
- Regulatory Landscape — which frameworks bind your product, by market and archetype
By Yoel Frischoff.