Status: v0.3 — 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. The same
/electrum skill runs in three places. The phases, the questions and the output files are identical;
what differs is what you install and where the files live.
| Route | For | Needs | What you give up |
|---|---|---|---|
| 1. Skill in Claude chat | Trying it out, no installs | A claude.ai plan with code execution on | Files are downloads; you re-upload them to resume. A full run may need two conversations |
| 2. Claude Cowork | Real work without a terminal | A paid plan and the Claude Desktop app | Nothing in the workflow; outputs persist in a folder you pick |
| 3. Claude Code | Teams, git, long runs, extending the scripts | Claude Code, Python 3.11, this repo | Nothing |
Routes 1 and 2 use the same ZIP, so start with 1 and move to 2 when it earns a working folder.
Route 3 picks up where either left off: copy your phase files into output/<slug>/ in a clone and
the skill resumes from the first missing phase.
- Download
electrum-skill.zip(about 100 KB: the skill, templates, reference documents and scripts; no examples). - In claude.ai or the Claude Desktop app, open Settings, then Customize, then Skills. Click Add and choose Upload skill. Pick the ZIP.
- Under Settings, Capabilities, make sure Code execution and file creation is on. The skill needs it to draw diagrams and build the carousel.
- Start a new chat and type
/electrum <describe your product in one sentence>.
Download each file as it is produced. To continue in a new conversation, upload the files you have
and run /electrum again; it resumes from the first missing phase.
- Upload the same ZIP the same way (Cowork reads your uploaded skills).
- Open Cowork in the Claude Desktop app, pick a working folder for the product, and type
/electrum <describe your product in one sentence>.
Phase files land in electrum-output/<slug>/ inside that folder and stay there between sessions.
# 1. Install Claude Code (https://docs.anthropic.com/en/docs/claude-code) and Python 3.11+
# 2. Clone this repo and open a terminal in it
git clone https://github.com/yoelf22/electrum.git
cd electrum
pip install -r requirements.txt
# 3. Start Claude Code and run the skill
claude
> /electrum <describe your product in one sentence>On Windows, install Python from python.org with Add python.exe to PATH ticked, and use python
and pip where this README says python3 and pip3. Git for Windows is recommended but optional:
the green Code button on GitHub also offers Download ZIP.
Whichever route you take, the process walks 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 want AI in the loop? The templates work without it. 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.
Routes 1 and 2 run the scripts in Claude's sandbox and need nothing installed. For Claude Code:
pip install -r requirements.txtRequired packages: python-pptx, reportlab, matplotlib, numpy. playwright and python-docx
are only for the optional scripts below.
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├── .claude/skills/ # The /electrum skill (one SKILL.md for all three routes)
├── .github/workflows/skill-zip.yml # Builds electrum-skill.zip on each release tag
├── 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 |
|---|---|
templates/hw_sw_product_initiation.md |
8-phase workflow from concept to presentation |
templates/hw_sw_high_level.md |
Single-page system overview template |
templates/system_description_template.md |
Full system description template with HW↔SW boundary items |
templates/checklist.md |
Gate checklist — 103 items, each tagged if it targets the HW/SW boundary |
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 |
|---|---|
scripts/generate_illustration.py |
DALL-E image generation via Playwright browser automation |
scripts/build_carousel.py |
PPTX + PDF carousel builder (LinkedIn-format, 4:5 portrait) |
scripts/build_deck.py |
Executive product overview deck builder |
scripts/build_high_level_deck.py |
High-level design deck builder |
scripts/visualize.py |
Visualization utilities |
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.
Pick a route from Choose Your Route, then:
- 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
Moving up a route. The output files are the same everywhere. Chat downloads go into a Cowork
working folder, or into output/<slug>/ in a Claude Code clone, and /electrum resumes from the
first missing phase. Nothing is redone.
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
templates/hw_sw_product_initiation.mdfor the workflow overview - Assess your gaps — Review
templates/skills_map.mdfor team competency planning - Create the high-level design — Copy
templates/hw_sw_high_level.mdinto your project folder and fill it in - Write the system description — Copy
templates/system_description_template.mdand work through each section - Validate — Run through
templates/checklist.mdto confirm nothing was missed
For image generation and carousel building, adapt the scripts in 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.