| name | prototype |
| description | Build a throwaway prototype under .scratch/ to answer a design question. Use when the user wants to sanity-check automation/state logic, explore a dashboard or notification shape, or says prototype or /prototype. |
| disable-model-invocation | true |
Prototype — Home Assistant Homelab
A prototype is throwaway work that answers a question. The question decides
the shape. Put it under .scratch/ — never use
packages/ as a throwaway playground.
Git is operator-owned
(operator-owned-git.md): do not commit
scratch contents. Promote validated decisions into tracked paths later.
Pick a branch
Identify which question is being answered — from the user's prompt, nearby
config, or by asking:
| Question | Shape |
|---|
| "Does this logic / state model feel right?" | Tiny script, state diagram, or YAML sketch that walks hard cases (triggers, conditions, modes) |
| "What should this look like?" | Dashboard card mock, notification copy variants, or lovelace YAML drafts — multiple options side by side |
| "Where should this live?" | Package placement sketch + entity naming table (still scratch; not a live package) |
If the question is ambiguous and the operator isn't reachable, default to the
logic branch for automations/packages and the look branch for UI/dashboard
asks — state the assumption at the top of the prototype.
Rules
- Throwaway and marked as such. Create under
.scratch/<slug>/ with a
short README stating the question and that it is disposable.
- Never throwaway under
packages/. Scratch is not loaded by Home
Assistant. Promoting into packages/, esphome/, utilities/, or docs/
is a separate, explicit step after the question is answered.
- One command to run when there is runnable code (
python path,
bash path, etc.). Prefer zero-deps scripts.
- No persistence by default. In-memory or a clearly named scratch file
(
PROTOTYPE — wipe me). Do not write .storage/ or .shopping_list.json.
- Skip the polish. No tests beyond what makes it runnable, no abstractions.
- Surface the state. After each action or variant switch, print/show the
full relevant state so the operator can see what changed.
- Capture the answer, not the junk. When done, record the verdict (what
was learned) in chat. If promoting, move only the validated decision into
the right tracked path via
implement-change
/ HA domain skills — leave the scratch tree disposable.
Workflow
- [ ] 1. Name the question and pick logic vs look vs placement
- [ ] 2. Create .scratch/<slug>/ with a one-paragraph README
- [ ] 3. Build the smallest artifact that answers the question
- [ ] 4. Run / walk cases with the operator
- [ ] 5. Write the verdict; recommend promote path or drop
Promote vs drop
| Outcome | Action |
|---|
| Decision validated | Hand off to implement-change / package-organize / automation path with acceptance bullets |
| Still fuzzy | alignment or another prototype slug |
| Dead end | Leave under .scratch/; do not commit; optional delete |
Do not
- Commit, push, or open PRs for prototypes
- Edit live
packages/ "just to try something"
- Treat scratch YAML as source of truth for Home Assistant
- Invent
docs/research/ or issue files for the prototype writeup
