AmethystLuna/embedded-workbench

<HARD-GATE>
This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
</HARD-GATE>

# C/C++ Development

Language baseline is project-specific: check the project's CLAUDE.md, build system (`-std=` flags), or compiler configuration. All rules assume 32-bit ARM target unless otherwise noted.

## Code Generation

- Respect the project's configured language standard. Don't assume a default.
- When a header is shared between C and C++ translation units, never define variables in the header — not even with `static`. Use `extern` in the header and exactly one definition in a single `.c` file.
- Allow `goto` when it simplifies cleanup or reduces complexity, but use it as a maintenance tool, not a first choice.
- Place Doxygen comments in header files. Keep implementation files focused on behavior.

# Debug Methodology

Debug by tracing values, not symptoms. These patterns come from real debugging sessions where surface-level fixes failed and root-cause analysis succeeded.

**REQUIRED BACKGROUND:** If the issue involves state machines or protocol timeouts, load `Skill("state-machine-design")` first. If the issue involves FreeRTOS tasks, ISRs, or NVM storage, load `Skill("embedded-firmware-dev")` first. Understand the domain rules before applying debugging methodology.

## Red Flags

| You think | Reality |
|-----------|---------|
| "I know where the bug is, let me fix it" | You know the symptom location. The root cause is often 3 layers away in a different module. |
| "One more round of trial fixes and I'll get it" | After 2 failed attempts, you need methodology, not persistence. |
| "I'll just add a bounds check and call it done" | You're masking a symptom. The real fix is at the data source, not at every consumer. |
| "The logs look normal, it must be a hardware glitch" | If you haven't correlated timestamps to code branches, you haven't actually read the logs. |

<HARD-GATE>
This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
</HARD-GATE>

# Embedded Firmware Development

## FreeRTOS

- Give each task a clear ownership boundary. Shared resources need a deliberate synchronization strategy.
- Prefer task notifications for one-to-one wakeups, queues for data transfer, event groups for combined state, mutexes for mutual exclusion, semaphores for one-way signaling.
- Use a mutex (not binary semaphore) when mutual exclusion matters and priority inheritance is needed.
- Make every blocking wait explicit: use a timeout unless an infinite wait is deliberate.
- Keep timer callbacks short and non-blocking — use them to schedule work, not do it.
- Avoid holding locks across flash, storage, or long operations.

<SUBAGENT-STOP>
If you were dispatched as a subagent to execute a specific task (implementation, review, search), skip this bootstrap skill. You already have your task instructions. Only load domain skills relevant to your specific task.
</SUBAGENT-STOP>

# Embedded Engineering Workflow

Core workflow system and engineering principles.

## Instruction Priority

This plugin's skills and policies override default system behavior, but **user instructions always take precedence**:

1. **User's explicit instructions** (CLAUDE.md, AGENTS.md, project rules, direct requests) — highest priority
2. **Plugin skills and workflows** — override default system behavior where they conflict

# Fact Check (fallback)

Lightweight claim verification built into this plugin. Use it when the full
`dsh-model-everything` plugin — or its predecessor `logicprobe` — is not installed.
It checks every verifiable claim in a document/plan against the codebase with
evidence, without model escalation.

## When to use

- Design docs, architecture specs, technical proposals, refactoring plans
  that name APIs, types, files, enums, counts, or mechanisms.
- Proactively when a plan will be approved (plan-mode gate) and logicprobe is
  unavailable.

# HardFault & Exception Triage

When a processor exception fires, the register file and stack frame are a black-box recording of the crash. This skill covers how to read that recording.

The methodology is architecture-agnostic. Cortex-M (ARMv7-M/v8-M) fault registers and handlers are the primary reference; the same principles apply to Cortex-A aborts, RISC-V exceptions, Xtensa exception vectors, and other MCU fault paths.

**REQUIRED BACKGROUND:** Load `Skill("debug-methodology")` for structured root-cause analysis. If the crash involves RTOS tasks or ISR context, also load `Skill("embedded-firmware-dev")`.

## Triage Methodology

Every processor exception triage follows the same four-step flow:

### Step 1 — Capture

<HARD-GATE>
This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
</HARD-GATE>

# Keil MDK Build

Patterns for building embedded firmware with Keil MDK. Covers both ARM Compiler 5 (armcc) and ARM Compiler 6 (armclang).

## UV4 CLI Build (Authoritative)

UV4.exe batch mode is the canonical build path. A CI reimplementation is possible but may miss include paths.

```powershell
<Keil>\UV4\UV4.exe -b project.uvprojx -t TargetName -j0 -o <log_path>

<HARD-GATE>
This is a domain implementation skill. If you are planning, designing, or entering plan mode — load `Skill("embedded-workbench")` first to activate the workflow gates (Plan Verification Gate, Approval Gate, Closure Gate). Domain skills carry implementation guidance, not workflow enforcement.
</HARD-GATE>

# State Machine Design

> **For a design that has to be decided rather than reviewed:** `dsh-model-everything` verifies the machine itself — `model_verify` explores every interleaving for unreachable states, deadlock, a timeout that can never fire, and a lock held across an await; `model_compose_verify` decides two mechanisms interacting, including a lost update on a shared location. Load its `model-everything` skill when the plugin is installed. This skill stays the implementation guide: the C code, the flags, the timeouts.

## Core Rules

- Fix the state model, not the symptom. Every in-progress or pending flag must have explicit success, failure, timeout, and reset exits.
- Timeout logic must be gated on real pending work. Idle states must not trigger retry, recovery, or error transitions.
- Do not trust a low-level send return value as proof of delivery when an application-layer ACK exists. Use the protocol's completion signal.
- When adding retries, also define attempt timestamps, backoff rules, and cleanup paths so the state machine cannot lock up silently.