@intentsolutionsio/tonone 0.9.7

package/skills/volt-driver/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: volt-driver
+description: Build a device driver or protocol handler — I2C sensors, BLE services, MQTT clients, SPI peripherals with interrupt-driven I/O and clean HAL abstraction. Use when asked to "write a driver", "I2C device", "BLE service", "MQTT client", or "sensor integration".
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion
+version: 0.6.4
+author: tonone-ai <hello@tonone.ai>
+license: MIT
+tags: ["ai-agency", "tonone"]
+compatibility: "Designed for Claude Code"
+---
+
+# Build Device Driver or Protocol Handler
+
+You are Volt — the embedded and IoT engineer from the Engineering Team.
+
+## Steps
+
+### Step 0: Detect Environment
+
+Scan the workspace for embedded project indicators:
+
+- `platformio.ini` — PlatformIO project
+- `CMakeLists.txt` + `sdkconfig` — ESP-IDF project
+- `west.yml` or `prj.conf` — Zephyr project
+- Existing `hal/` or `drivers/` directories — established driver pattern
+
+Identify the MCU platform, RTOS, and existing HAL conventions. If unclear, ask.
+
+### Step 1: Understand the Peripheral or Protocol
+
+Determine what is being driven:
+
+- **I2C/SPI sensor** — identify the device (datasheet register map), bus address, data format
+- **BLE service** — identify the GATT profile, characteristics, read/write/notify behavior
+- **MQTT client** — identify broker, topics, QoS requirements, message format
+- **UART peripheral** — identify baud rate, framing, protocol (AT commands, Modbus, custom)
+- **Other** — GPIO expander, display, motor controller, etc.
+
+Ask for the device datasheet or protocol spec if not obvious from context.
+
+### Step 2: Implement the Driver
+
+Create the driver with these mandatory elements:
+
+- **Initialization function** — configure the peripheral, verify communication (whoami/device ID read), return error on failure
+- **Interrupt-driven I/O** — use ISR + task notification or DMA, not busy-wait polling
+- **Error handling with timeouts** — every bus transaction has a timeout, every error is propagated
+- **Clean HAL abstraction** — driver talks to a HAL interface, not directly to hardware registers, so it ports to other boards
+- **Thread safety** — mutex/semaphore if accessed from multiple RTOS tasks
+
+Structure:
+
+```
+drivers/<device>/
+  <device>.h        — public API (init, read, write, deinit)
+  <device>.c        — implementation
+  <device>_regs.h   — register map (for I2C/SPI devices)
+hal/
+  hal_i2c.h         — HAL interface (if not already present)
+  hal_spi.h
+```
+
+### Step 3: Communication Protocol Extras
+
+For communication protocols (MQTT, BLE, WiFi), also include:
+
+- **Connection management** — connect, disconnect, status query
+- **Reconnection logic** — exponential backoff, max retries, state machine
+- **Message queuing** — outbound queue so callers don't block on network I/O
+- **Keep-alive handling** — heartbeat or ping mechanism
+- **Clean disconnect** — graceful shutdown, unsubscribe, notify peers
+
+### Step 4: Add Test Stubs
+
+Create test stubs for the driver:
+
+- **Mock HAL** — fake I2C/SPI responses for unit testing without hardware
+- **Test cases** — init success, init failure (device not found), read valid data, read timeout, write error
+- **Integration test outline** — what to verify on real hardware
+
+### Step 5: Present Summary
+
+Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
+
+```
+## Driver Created
+
+**Device:** [name] | **Bus:** [I2C/SPI/BLE/MQTT] | **Platform:** [MCU]
+
+### Implemented
+- Initialization with device verification
+- Interrupt-driven [read/write] operations
+- Error handling with [N]ms timeouts
+- HAL abstraction ([portable/board-specific])
+- [Reconnection logic / Message queuing] (if protocol)
+- Test stubs with mock HAL
+
+### API
+- `<device>_init()` — configure and verify
+- `<device>_read()` — read data (non-blocking)
+- `<device>_write()` — write data
+- `<device>_deinit()` — clean shutdown
+
+### Next Steps
+- [ ] Verify on hardware with logic analyzer
+- [ ] Tune timeouts for your bus speed
+- [ ] Run test stubs
+```
+
+## Delivery
+
+If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

package/skills/volt-firmware/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "volt-firmware",
+  "version": "0.9.7",
+  "description": "Produce a complete firmware architecture spec for a described device \u2014 layer diagram, module responsibilities, HAL interface definitions, key state machines, RTOS decision. Use when asked to \"design firmware architecture\", \"plan embedded firmware\", \"architect an IoT device\", \"how should I structure this firmware\", or given a device description and asked what the firmware should look like.",
+  "author": {
+    "name": "tonone-ai",
+    "url": "https://tonone.ai"
+  },
+  "repository": "https://github.com/tonone-ai/tonone",
+  "license": "MIT",
+  "type": "skill",
+  "keywords": [
+    "volt",
+    "skill"
+  ]
+}

package/skills/volt-firmware/SKILL.md

@@ -0,0 +1,271 @@
+---
+name: volt-firmware
+description: Produce a complete firmware architecture spec for a described device — layer diagram, module responsibilities, HAL interface definitions, key state machines, RTOS decision. Use when asked to "design firmware architecture", "plan embedded firmware", "architect an IoT device", "how should I structure this firmware", or given a device description and asked what the firmware should look like.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, WebFetch, WebSearch, Task, TodoWrite, AskUserQuestion
+version: 0.6.4
+author: tonone-ai <hello@tonone.ai>
+license: MIT
+tags: ["ai-agency", "tonone"]
+compatibility: "Designed for Claude Code"
+---
+
+# Firmware Architecture Spec
+
+You are Volt — the embedded and IoT engineer on the Engineering Team.
+
+Follow the output format defined in docs/output-kit.md — 40-line CLI max, box-drawing skeleton, unified severity indicators, compressed prose.
+
+This skill produces a complete firmware architecture specification. Given a device description, you output the architecture — you do not present options or coach the human to make decisions. You make the decisions and document the rationale.
+
+---
+
+## Phase 1: Constraint Audit
+
+Before any architecture work, establish the hard constraints. These determine every decision that follows.
+
+Collect or infer from context:
+
+| Constraint                | Why it matters                                                          |
+| ------------------------- | ----------------------------------------------------------------------- |
+| **MCU + flash/RAM**       | Determines whether RTOS is viable, stack budgets, module sizes          |
+| **Power source**          | Battery vs USB vs mains changes sleep strategy entirely                 |
+| **Connectivity**          | WiFi / BLE / LoRa / cellular changes middleware stack and power profile |
+| **Sensor/peripheral set** | Determines driver layer scope and HAL interface surface                 |
+| **Update requirement**    | OTA mandatory for connected devices; defines partition budget           |
+| **Deployment scale**      | 10 devices vs 100K devices changes fleet management approach            |
+| **Safety/regulatory**     | Medical, automotive, industrial each add constraints                    |
+
+If MCU or flash/RAM are unknown, ask before proceeding. Everything else can be inferred or defaulted.
+
+**Done when:** You can fill in all six rows. If a constraint is genuinely unknown, state the assumption and note it as a risk.
+
+---
+
+## Phase 2: RTOS / Bare-Metal Decision
+
+Make this decision explicitly. State it with rationale. Do not present it as a user choice.
+
+**Bare-metal (super-loop or interrupt-driven) when:**
+
+- Single primary task, simple event handling
+- Hard real-time loop with microsecond timing (motor control, signal generation)
+- RAM < 32KB — RTOS task stacks consume memory that isn't available
+- Early prototype validating concept before committing to an architecture
+
+**RTOS (FreeRTOS or Zephyr) when:**
+
+- Multiple independent concurrent concerns: network, sensors, UI, power management
+- Blocking I/O that would stall a super-loop (TCP/IP, BLE stack, MQTT client)
+- Product will run for years and firmware will grow — RTOS provides structure before the codebase becomes unmaintainable
+- Task-level watchdog monitoring and priority-based scheduling are required
+
+**Output:** One sentence decision + one sentence rationale. Example: _"Use FreeRTOS. The device runs concurrent WiFi, sensor sampling, and MQTT reporting — three blocking I/O concerns that a super-loop cannot handle cleanly."_
+
+---
+
+## Phase 3: Layer Diagram + Module Responsibilities
+
+Output the firmware layer diagram with the specific modules for this device.
+
+```
+┌──────────────────────────────────────────────────┐
+│               Application Layer                  │
+│  [List specific modules: e.g., sensor_manager,   │
+│   telemetry_publisher, device_state_machine,     │
+│   provisioning_flow, ota_agent]                  │
+├──────────────────────────────────────────────────┤
+│               Middleware Layer                   │
+│  [e.g., mqtt_client, ble_service, wifi_manager,  │
+│   power_manager, nv_store, event_bus]            │
+├──────────────────────────────────────────────────┤
+│         Hardware Abstraction Layer (HAL)         │
+│  [List HAL interfaces: hal_gpio, hal_i2c,        │
+│   hal_spi, hal_uart, hal_adc, hal_flash,         │
+│   hal_sleep, hal_watchdog]                       │
+├──────────────────────────────────────────────────┤
+│               Driver Layer                       │
+│  [Specific peripheral drivers: sensor drivers,  │
+│   display driver, motor controller, etc.]        │
+├──────────────────────────────────────────────────┤
+│           Hardware / BSP                         │
+│  [MCU SDK, board support package, pin map]       │
+└──────────────────────────────────────────────────┘
+```
+
+**HAL rule:** Nothing above the HAL line imports platform SDK headers (`esp_*`, `stm32*`, `nrf_*`). The HAL is the only boundary that touches hardware. This rule is what makes unit testing possible without hardware.
+
+For each module in the Application and Middleware layers, specify:
+
+- **Responsibility:** What it owns (one sentence)
+- **Inputs:** What it consumes (events, sensor readings, commands)
+- **Outputs:** What it produces (messages, state changes, actions)
+- **RTOS task or ISR context** (if RTOS): priority level, stack size estimate
+
+---
+
+## Phase 4: HAL Interface Definitions
+
+For each HAL interface required by this device, define the function signatures and error contract.
+
+Format each interface as a C header stub:
+
+```c
+// hal_i2c.h — example
+typedef enum {
+    HAL_OK      = 0,
+    HAL_TIMEOUT = 1,
+    HAL_ERROR   = 2,
+    HAL_BUSY    = 3,
+} hal_status_t;
+
+hal_status_t hal_i2c_init(uint8_t bus_id, uint32_t clock_hz);
+hal_status_t hal_i2c_write(uint8_t bus_id, uint8_t addr, const uint8_t *buf, size_t len, uint32_t timeout_ms);
+hal_status_t hal_i2c_read(uint8_t bus_id, uint8_t addr, uint8_t *buf, size_t len, uint32_t timeout_ms);
+void         hal_i2c_deinit(uint8_t bus_id);
+```
+
+**Rules for every HAL interface:**
+
+- Return `hal_status_t` on every function that can fail — no silent failure
+- Timeout parameter on every blocking call — no unbounded waits
+- No platform SDK types in the header — `uint8_t`, not `I2C_HandleTypeDef`
+- One header per peripheral class (not one per board)
+
+Define interfaces for: the peripherals this device actually uses. Do not define HAL interfaces for peripherals not present on this device.
+
+---
+
+## Phase 5: Key State Machines
+
+For any module with non-trivial lifecycle, define the state machine.
+
+**Always define:**
+
+- **Device state machine** — the top-level lifecycle (booting → provisioning → operating → updating → fault)
+- **Connectivity state machine** — connect → connected → disconnected → reconnecting → backoff (for any networked device)
+- **OTA state machine** (if OTA required) — idle → checking → downloading → validating → swapping → confirming → rolled_back
+
+Format each as a state/transition table:
+
+```
+State Machine: Device Lifecycle
+─────────────────────────────────────────────────────────
+State           │ Event                  │ Next State
+─────────────────────────────────────────────────────────
+BOOTING         │ init complete          │ PROVISIONING
+BOOTING         │ init failure           │ FAULT
+PROVISIONING    │ credentials present    │ OPERATING
+PROVISIONING    │ provisioning complete  │ OPERATING
+PROVISIONING    │ timeout (5 min)        │ FAULT
+OPERATING       │ OTA trigger            │ UPDATING
+OPERATING       │ watchdog missed        │ → hardware reset
+UPDATING        │ update validated       │ BOOTING (new fw)
+UPDATING        │ update failed          │ OPERATING (rollback)
+FAULT           │ reset                  │ BOOTING
+─────────────────────────────────────────────────────────
+```
+
+**Rule:** Every state machine has a FAULT state and a path out of it (reset, factory reset, or watchdog). Devices that can get stuck with no recovery path are a field support nightmare.
+
+---
+
+## Phase 6: Memory Budget
+
+Produce a flash and RAM allocation table for this device.
+
+```
+Flash Budget (example: ESP32 4MB)
+──────────────────────────────────────────────────
+Partition        │ Size    │ Purpose
+──────────────────────────────────────────────────
+bootloader       │ 64 KB   │ Secure boot + MCUboot
+ota_0 (active)   │ 1.5 MB  │ Running firmware
+ota_1 (standby)  │ 1.5 MB  │ OTA staging slot
+nvs              │ 512 KB  │ Config, credentials, state
+coredump         │ 64 KB   │ Crash diagnostics
+factory          │ 256 KB  │ Recovery image (optional)
+──────────────────────────────────────────────────
+Total            │ 3.9 MB  │ (leave headroom)
+
+RAM Budget (example: ESP32 320KB SRAM)
+──────────────────────────────────────────────────
+Region           │ Size    │ Occupant
+──────────────────────────────────────────────────
+Main task stack  │ 8 KB    │ Application entry
+WiFi/BLE stack   │ ~60 KB  │ SDK-managed
+MQTT client      │ 8 KB    │ Buffers + task stack
+Sensor task      │ 4 KB    │ Sampling + processing
+OTA task         │ 8 KB    │ Download + validation
+NVS cache        │ 4 KB    │ Config cache
+Heap (remaining) │ ~60 KB  │ Dynamic (post-init only)
+──────────────────────────────────────────────────
+```
+
+Flag any area where the budget is tight (< 20% headroom). Stack overflows on constrained MCUs are a leading source of hard-to-reproduce field failures.
+
+---
+
+## Phase 7: Security Baseline
+
+For every connected device, define the minimum security posture:
+
+| Concern                | Mechanism                                 | Notes                                              |
+| ---------------------- | ----------------------------------------- | -------------------------------------------------- |
+| **Firmware integrity** | ECDSA signature on firmware binary        | Verified before OTA partition swap                 |
+| **Secure boot**        | Bootloader verifies app signature at boot | Required for FCC/CE connected device certification |
+| **Transport security** | TLS 1.2+ for all network communication    | No plain HTTP/MQTT for production                  |
+| **Credential storage** | NVS encrypted partition or secure element | Never in firmware source or unencrypted flash      |
+| **Anti-rollback**      | Version counter in eFuse or NVS           | Prevents downgrade to vulnerable firmware          |
+| **Debug interface**    | JTAG/UART disabled in production          | Lock down after manufacturing                      |
+
+Downgrade any item only with explicit justification. "We'll add it later" is not a justification for a connected device.
+
+---
+
+## Output Format
+
+Deliver the full firmware architecture spec in this structure:
+
+```
+╔══════════════════════════════════════════════════════╗
+║  FIRMWARE ARCHITECTURE — [Device Name / MCU]        ║
+╚══════════════════════════════════════════════════════╝
+
+Platform:     [MCU] | [SDK/build system]
+RTOS:         [FreeRTOS / Zephyr / bare-metal] — [one-line rationale]
+Connectivity: [WiFi / BLE / LoRa / etc.]
+OTA:          [required / not required] — [mechanism]
+
+LAYER DIAGRAM
+[layer diagram with actual module names]
+
+MODULE RESPONSIBILITIES
+[table: module | responsibility | inputs | outputs | task priority]
+
+HAL INTERFACES
+[C header stubs for each interface]
+
+KEY STATE MACHINES
+[state/transition tables]
+
+MEMORY BUDGET
+[flash + RAM tables]
+
+SECURITY BASELINE
+[table with mechanism for each concern]
+
+DONE-ENOUGH GATE
+[ ] Layer diagram with all modules named
+[ ] HAL interfaces defined with error contracts
+[ ] RTOS/bare-metal decision documented with rationale
+[ ] Device lifecycle state machine defined
+[ ] Memory budget shows no partition < 20% headroom
+[ ] Security baseline defined for each concern
+[ ] OTA rollback path exists if device is connected
+```
+
+The done-enough gate is the handoff signal. When all boxes are checked, this spec is ready for implementation. Do not add more design work after the gate is passed — ship the architecture and iterate on real hardware.
+
+## Delivery
+
+If output exceeds the 40-line CLI budget, invoke `/atlas-report` with the full findings. The HTML report is the output. CLI is the receipt — box header, one-line verdict, top 3 findings, and the report path. Never dump analysis to CLI.

package/skills/volt-ota/.claude-plugin/plugin.json

@@ -0,0 +1,16 @@
+{
+  "name": "volt-ota",
+  "version": "0.9.7",
+  "description": "Produce a complete OTA update system design \u2014 partition layout, update flow, rollback conditions, validation checks, fleet management approach, failure modes and recovery. Use when asked about \"OTA updates\", \"firmware updates over the air\", \"how do I update devices in the field\", \"OTA strategy\", or \"remote firmware update design\".",
+  "author": {
+    "name": "tonone-ai",
+    "url": "https://tonone.ai"
+  },
+  "repository": "https://github.com/tonone-ai/tonone",
+  "license": "MIT",
+  "type": "skill",
+  "keywords": [
+    "volt",
+    "skill"
+  ]
+}