Embedded Driver Design

Embedded Driver Design

Overview

Create implementation plan assuming engineer has zero context and questionable taste. Document everything needed: files, code, testing, verification steps.

Context: Run after embedded-brainstorming approval.

Save plans to: docs/embedded/plans/YYYY-MM-DD--plan.md

Do NOT generate code during this phase. This skill ONLY creates the plan. Code generation happens in embedded-implementation.

Process

1. Load Design Spec

read docs/embedded/specs/YYYY-MM-DD--spec.md

2. Load References

Based on task type:

| Task Type | Reference File | |-----------|----------------| | Driver dev | references/chips.md + hardware-interfaces.md | | Protocol | references/protocols.md | | GUI | references/gui-feedback.md | | Debugging | references/debugging.md |

3. Define File Structure

Map files BEFORE defining tasks:

| File | Responsibility | |------|----------------| | include/driver.h | API declarations, constants | | src/driver.c | Implementation | | src/driver_test.c | Unit tests (if applicable) |

4. Create Bite-Sized Tasks

Each step = ONE action (2-5 minutes):

### Task 1: Driver Header

**Files:**
- Create: `include/lcd_st7789.h`

- [ ] **Step 1: Write header file**

```c
#ifndef LCD_ST7789_H
#define LCD_ST7789_H
// ... complete code
#endif

• [ ] Step 2: Build to verify syntax

Run: idf.py build Expected: No errors in header

• [ ] Step 3: Commit

git add include/lcd_st7789.h
git commit -m "feat: add ST7789 header"

Task 2: Driver Implementation

Files:

• Create: src/lcd_st7789.c
• Modify: include/lcd_st7789.h (if needed)

• [ ] Step 1: Write init function

esp_err_t lcd_st7789_init(void) {
    // ... complete implementation
}

• [ ] Step 2: Write DMA-chunked write function

esp_err_t lcd_st7789_write(const uint8_t *data, size_t len) {
    // Chunking for > 4092 bytes
}

• [ ] Step 3: Build

Run: idf.py build Expected: Exit 0

• [ ] Step 4: Commit

### 5. Plan Document Header

Every plan MUST start with:

```markdown
# [Driver Name] Implementation Plan

> **For agentic workers:** REQUIRED: Use embedded-implementation skill to execute this plan task-by-task.

**Goal:** [One sentence]

**Architecture:** [2-3 sentences]

**Constraints:**
- DMA -plan.md

8. Transition to Next Skill

Offer execution choice:

Plan saved to docs/embedded/plans/.md

Two execution options:

1. Subagent-Driven - Fresh subagent per task, two-stage review
2. Inline Execution - Execute in current session

Which approach?

REQUIRED: Invoke embedded-implementation next.

No Placeholders

These are plan failures - never write them:

• "TBD", "TODO", "implement later"
• "Add appropriate error handling"
• "Write tests for the above" (without actual test code)
• "Similar to Task N" (repeat the code)
• Steps without complete code blocks

Task Template

### Task N: [Component Name]

**Files:**
- Create: `exact/path/to/file.c`
- Modify: `exact/path/to/file.c:123-145`

- [ ] **Step 1: [Action]**

[Complete code block]

- [ ] **Step 2: [Verification]**

Run: `[command]`
Expected: `[output]`

- [ ] **Step 3: Commit`

```bash
git add [files]
git commit -m "[message]"

## Red Flags - STOP

- Writing code during design phase
- "TBD" in any task
- Tasks without complete code
- Skipping file structure definition
- User hasn't approved brainstorming spec

## Output

Plan: docs/embedded/plans/YYYY-MM-DD--plan.md Tasks: N tasks defined Status: READY FOR IMPLEMENTATION Next: embedded-implementation

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [lhbsaa](https://github.com/lhbsaa)
- **Source:** [lhbsaa/embedded-dev-skill](https://github.com/lhbsaa/embedded-dev-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.