---
name: hermes-86duino-cli
description: Use when the user wants Hermes to compile, clean-build, upload, or troubleshoot 86Duino projects with 86duino-cli on macOS/Linux or 86duino-cli.exe on Windows.
version: 1.1.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [86duino, cli, compile, upload, firmware, embedded]
    related_skills: [systematic-debugging, hermes-agent]
---

# Hermes 86Duino CLI Skill

## Overview

This skill helps Hermes use `86duino-cli` (which may be named `86duino-cli.exe` on Windows) to compile, clean-rebuild, flash/upload 86Duino projects, and to ask the user back automatically when required information is missing.

This skill is governed by the rules provided by the user:
- "Flash" and "upload" refer to the same operation.
- "Clean rebuild", "rebuild", and "clean build" all map to `compile --clean`.
- Prefer to use only the explicitly approved parameters of `86duino-cli` / `86duino-cli.exe`.
- If you need to use an `arduino-cli`-compatible parameter that is not listed in this document, you must inform the user first and obtain consent.
- If a required precondition is missing (for example, project path, board model, CLI location, or available port), ask the user back; do not guess.
- `--verbose` should be added by default so that compile and upload progress is observable.

For additional board mappings, command templates, and port-detection examples, refer to the bundled `references/86duino-cli-reference.md`. That reference document also includes the 86Duino-only boards filtered from this machine's actual `board listall` output (Arduino entries are omitted as requested).

## When to Use

Use this skill in the following situations:
- The user wants to "compile" an 86Duino project
- The user wants to "clean-rebuild" an 86Duino project (equivalent to `--clean`)
- The user wants to "flash" or "upload" an 86Duino project to a board
- The user wants to check 86Duino compile errors and retry after attempting fixes
- The user provides only a natural-language board name and the FQBN must be looked up
- The user uses colloquial phrasing such as "QEC 7-inch board", "QEC M02", or "burn it in"

Do not proceed directly in the following situations:
- The user has not provided the project path and it cannot be reliably inferred from context
- The user wants to use an additional CLI parameter not listed in this document but has not yet consented
- The Desktop does not contain the `86Duino_Coding` folder, so the actual `86duino-cli` / `86duino-cli.exe` executable cannot be located
- An upload is requested but no PL2303 serial port is detected; in this case, first ask whether the user has forgotten to plug in the cable
- The board name cannot be uniquely matched to a single FQBN

## Fixed Assumptions

### CLI location
`86duino-cli` must reside in the `86Duino_Coding` folder on the Desktop; on Windows the executable may be named `86duino-cli.exe`.

- Expected Windows path: `%USERPROFILE%\Desktop\86Duino_Coding\86duino-cli.exe`
- Expected macOS path: `~/Desktop/86Duino_Coding/86duino-cli`

If the `86Duino_Coding` folder does not exist on the Desktop:
- **Only prompt the user to create it; do not create it automatically.**
- Clearly tell the user the expected location and the name of the missing executable.

### Executable name compatibility rules
- If the actual executable found on macOS / Linux is `86duino-cli`, invoke it as `./86duino-cli`
- If the actual executable found on Windows is `86duino-cli.exe`, invoke it as `86duino-cli.exe`
- Do not forcibly rewrite the macOS filename to `.exe`
- Always use the actual filename present on the filesystem before executing

### Terminology
- **Compile** = `compile`
- **Clean rebuild / rebuild / clean build** = `compile --clean`
- **Flash / upload** = `compile --upload`

### Default execution principles
- Include `--verbose` by default
- Do not add other parameters not listed unless the user has requested them
- Prefer to run upload as a background process and observe its output
- On upload failure, stop the workflow immediately and report the raw error

## Required Inputs

Confirm at least the following before execution:

1. **Absolute project path**
2. **Target board name** (may be natural language, e.g., QEC 7-inch board, QEC M02)
3. For flash/upload jobs:
   - A port specified by the user, or
   - A port detected automatically by the system

If the user gives a relative path or colloquial location (e.g., "the sketch_mar24b folder on the desktop"):
- Translate it into a reasonable absolute path first
- Then confirm with the user, or verify in the tool that the path exists

If the user has not supplied complete information, proactively ask.

## Board Name Resolution

### Always run board listall first
```bash
86duino-cli.exe board listall
```

If running on macOS, prefer:
```bash
./86duino-cli board listall
```

Expected output includes something like:
```text
Board Name                       FQBN
86Duino DUO                      86duino:x86:86DuinoEX2
86Duino EduCake                  86duino:x86:EduCake
86Duino ONE                      86duino:x86:86DuinoONE
```

Procedure:
- Match the user's described board name to the most plausible Board Name entry
- Then take the corresponding FQBN
- If a unique match cannot be determined, present the candidates and ask the user to confirm

### Common colloquial board-name hints
The following mapping serves only as a **best-effort initial guess**; the final answer must still come from the actual `board listall` output:
- `QEC 7-inch board` -> commonly maps to `86duino:x86:86DuinoQEC7`
- `QEC M02 board` -> commonly maps to `86duino:x86:86DuinoQECM02`

If the user's description does not match the actual listing:
- Do not guess
- Present candidate Board Names and FQBNs and ask the user to confirm

## Approved CLI Commands

### 1) List boards and obtain FQBN
```bash
86duino-cli.exe board listall
```

If the actual filename on macOS is `86duino-cli`, use:
```bash
./86duino-cli board listall
```

### 2) Compile a project
```bash
86duino-cli.exe compile --fqbn <FQBN> <ABSOLUTE_PROJECT_PATH> --verbose
```

If the actual filename on macOS is `86duino-cli`, use:
```bash
./86duino-cli compile --fqbn <FQBN> <ABSOLUTE_PROJECT_PATH> --verbose
```

### 3) Clean-rebuild a project
```bash
86duino-cli.exe compile --fqbn <FQBN> <ABSOLUTE_PROJECT_PATH> --clean --verbose
```

If the actual filename on macOS is `86duino-cli`, use:
```bash
./86duino-cli compile --fqbn <FQBN> <ABSOLUTE_PROJECT_PATH> --clean --verbose
```

### 4) Compile and upload (flash)
```bash
86duino-cli.exe compile --fqbn <FQBN> --port <PORT> --upload <ABSOLUTE_PROJECT_PATH> --verbose
```

If the actual filename on macOS is `86duino-cli`, use:
```bash
./86duino-cli compile --fqbn <FQBN> --port <PORT> --upload <ABSOLUTE_PROJECT_PATH> --verbose
```

### 5) Other arduino-cli-compatible parameters (only usable after user consent)
- Any parameter not listed above
- Before using it, explain its purpose and obtain user consent

## Port Detection Rules

### If the user has provided a port
- Use it as given; do not auto-detect
- If the given value is in an obviously invalid format, ask again to confirm

### If the user has not provided a port
Enable auto-detection.

#### Windows
Auto-detect devices under "Device Manager > Ports (COM & LPT)" and look for one whose name begins with:
- **`Prolific PL2303GC`**

For example, if you detect:
```text
Prolific PL2303GC USB Serial COM Port (COM6)
```
then pass:
```bash
--port COM6
```

#### macOS (Apple Silicon)
List `/dev/tty.*` and look for:
- A tty device whose name contains or begins with **`PL2303`**

For example, if you detect:
```text
/dev/tty.Bluetooth-Incoming-Port
/dev/tty.debug-console
/dev/tty.PL2303G-USBtoUART1120
```
then pass:
```bash
--port /dev/tty.PL2303G-USBtoUART1120
```

### Behavior when no port is detected
If no device matching the `PL2303` keyword is found:
- **Do not upload directly**
- Ask the user back:
  - `I cannot find a PL2303 serial port on your system. Have you forgotten to plug in the cable?`

If multiple PL2303 devices are found:
- Present the candidates and let the user choose
- Do not guess on your own unless exactly one is an obvious correct candidate

## Standard Workflow

### A. Compile workflow
1. Confirm the actual CLI executable inside `86Duino_Coding` exists (e.g., `86duino-cli` or `86duino-cli.exe`)
2. Confirm the absolute project path
3. Run `board listall` to obtain the corresponding FQBN
4. Execute:
   ```bash
   <CLI_CMD> compile --fqbn <FQBN> <PROJECT_PATH> --verbose
   ```
5. If the compile fails:
   - Read the error message
   - Apply the smallest necessary fix
   - Recompile
6. On success, report success

### B. Clean rebuild workflow
1. Same as the compile workflow, but change the command to:
   ```bash
   <CLI_CMD> compile --fqbn <FQBN> <PROJECT_PATH> --clean --verbose
   ```
2. `--clean` means previously compiled `.o` files will not be reused

### C. Compile + upload workflow
1. First confirm the actual executable exists (e.g., `86duino-cli` or `86duino-cli.exe`)
2. Confirm the project path and board model
3. Obtain the FQBN
4. Obtain the port:
   - If the user provided one -> use it
   - Otherwise -> auto-detect
5. Run upload as a background process and continuously observe the output:
   ```bash
   <CLI_CMD> compile --fqbn <FQBN> --port <PORT> --upload <PROJECT_PATH> --verbose
   ```
6. Because the upload procedure causes the target board to reboot automatically, **it may take up to ~40 seconds**
7. If the flash fails:
   - **Stop the entire workflow immediately**
   - Print the complete error message to the user
8. On success:
   - Report that both compile and flash succeeded

## Interaction Policy

### Proactively ask back when required information is missing
For example:
- Missing project path
- Missing board name
- `86Duino_Coding` not found
- Upload requested but no matching port found
- Multiple candidate boards or ports found

### Path handling principles
- When the user says "a folder on the Desktop", you can translate it into the Desktop's absolute path
- However, if the path does not exist, clearly state that it cannot be verified; do not pretend it exists
- If the project path or filename looks suspicious, confirm before executing

### Do not arbitrarily expand the parameter set
Aside from the following explicitly approved parameters, all others require consent first:
- `--fqbn`
- `--clean`
- `--verbose`
- `--port`
- `--upload`

If you need to use another `arduino-cli.exe`-compatible parameter, first explain:
1. Why it is needed
2. Which parameter will be used
3. Obtain user consent before executing

### Error handling principles
- Compile failure: show the key error, fix it, retry
- Flash failure: stop immediately; do not perform any further step
- If the error cause is environmental (missing CLI, port not found, board not connected), inform the user to address the precondition first

## Response Templates

### Cannot find the 86Duino_Coding folder
```text
I notice that the 86Duino_Coding folder is not on the Desktop. It should contain 86duino-cli (or 86duino-cli.exe on Windows). Please create this folder and place the correct CLI executable inside, then notify me so I can continue.
```

### Missing project path and board name
```text
Please provide the absolute path of the 86Duino project and the target board name so I can look up the corresponding FQBN and start compiling.
```

### Cannot find a PL2303 port
```text
I cannot find a PL2303 serial port on your system. Have you forgotten to plug in the cable?
```

### Need to confirm board model
```text
I found multiple possible matching boards. Please confirm which one you are using so I can pick the correct FQBN.
```

### Need to confirm among multiple port candidates
```text
I found multiple possible PL2303 serial ports. Please tell me which one to use so I can continue the upload.
```

### Need to use an additional parameter not listed
```text
I need to use an additional 86duino-cli / arduino-cli-compatible parameter next: <PARAMETER>, because <REASON>. If you agree, I will proceed.
```

## Examples

### Example 1: Compile
```bash
86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQEC7 C:\Users\RoBoard\Desktop\sketch_mar24b --verbose
```

### Example 2: Compile and upload
```bash
86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQEC7 --port COM6 --upload C:\Users\RoBoard\Downloads\arduino_cli\sketch_mar24b --verbose
```

### Example 3: Clean rebuild
```bash
86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQEC7 C:\Users\RoBoard\Downloads\arduino_cli\sketch_mar24b --clean --verbose
```

## Real Dialogue Patterns

### CASE 1
User:
```text
My 86Duino project is in the sketch_mar24b folder on the desktop. I'm using the QEC 7-inch board. Please compile the program and check for errors; if any errors are found, fix them automatically.
```

Agent behavior:
1. Resolve "the sketch_mar24b folder on the desktop" into an absolute path on the Desktop
2. Obtain the FQBN
3. Execute:
   ```bash
   86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQEC7 C:\Users\RoBoard\Desktop\sketch_mar24b --verbose
   ```
4. If there are compile errors, fix them and recompile
5. Report success

### CASE 2
User:
```text
My 86Duino project is at C:\Users\RoBoard\Downloads\arduino_cli\sketch_mar24b. I'm using the QEC M02 board. Please compile the program and check for errors; if any errors are found, fix them automatically. Finally, flash the correctly compiled program to the board.
```

Agent behavior:
1. Obtain the FQBN
2. Auto-detect the port (e.g., COM3)
3. Execute:
   ```bash
   86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQECM02 --port COM3 --upload C:\Users\RoBoard\Downloads\arduino_cli\sketch_mar24b --verbose
   ```
4. If errors occur, fix them and retry
5. On success, wait for the board to reboot and observe the output

### CASE 3
User:
```text
My 86Duino project is in the sketch_mar24b folder on the desktop. Please force a clean rebuild and check for errors; if any errors are found, fix them automatically.
```

Agent behavior:
1. Obtain the FQBN
2. Execute:
   ```bash
   86duino-cli.exe compile --fqbn 86duino:x86:86DuinoQEC7 C:\Users\RoBoard\Desktop\sketch_mar24b --clean --verbose
   ```
3. On success, report

### CASE 4
User:
```text
Please help me compile and upload an 86Duino project.
```

Agent response:
```text
Please provide the absolute path of the 86Duino project and the target board name. I also need to confirm whether the 86Duino_Coding folder exists on the Desktop and contains the executable 86duino-cli (or 86duino-cli.exe on Windows); only then can I continue with compile and upload.
```

### CASE 5
User:
```text
Please help me compile and upload an 86Duino project. My 86Duino project is in the sketch_mar24b folder on the desktop, and I'm using the QEC 7-inch board.
```

Agent response:
```text
I cannot find a PL2303 serial port on your system. Have you forgotten to plug in the cable?
```

## Common Pitfalls

1. **Treating flash and upload as different workflows.**
   In this skill they are synonymous.

2. **Guessing the FQBN without confirming the board model.**
   If a unique match cannot be determined, ask the user to confirm.

3. **Executing without confirming the absolute project path.**
   The compile command requires the absolute project path.

4. **Auto-creating `86Duino_Coding` when it is missing on the Desktop.**
   This is not allowed; only prompt the user to create it.

5. **Forcing an upload when no PL2303 port is detected.**
   You must first ask whether the cable is plugged in.

6. **Picking arbitrarily when multiple PL2303 ports are found.**
   Unless exactly one is an obvious correct candidate, let the user choose.

7. **Continuing other steps after a flash failure.**
   Stop immediately and provide the error message to the user.

8. **Using a CLI parameter not on the list without consent.**
   Do not use such parameters unless the user has agreed in advance.

9. **Not using `--verbose`, making it hard to tell where things are stuck.**
   Unless the user explicitly asks for simplified output, keep `--verbose` by default.

## Verification Checklist

- [ ] Confirmed that `86Duino_Coding` exists on the Desktop along with the actual CLI filename (e.g., `86duino-cli` or `86duino-cli.exe`)
- [ ] Obtained and verified the absolute project path
- [ ] Confirmed or inferred a unique board model
- [ ] Located the corresponding FQBN via `board listall`
- [ ] For a clean rebuild, added `--clean`
- [ ] For uploads, obtained the user-provided or auto-detected port
- [ ] For uploads, handled the "multiple port candidates" case
- [ ] For uploads, used `--verbose` to observe output
- [ ] On flash failure, stopped immediately and reported the raw error
- [ ] If a non-listed parameter is needed, obtained the user's consent first