# Project Health

> Audit project completeness against the monorepo standard checklist (docs, config, registration)

- Skill: `laurigates/project-health` (Agent Skill)
- Install (CLI): `npx skillmds@latest add laurigates/project-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/laurigates/project-health/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: laurigates (https://skillmd.com/u/laurigates)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/laurigates/project-health

---


## Task

Audit project(s) for completeness against the monorepo standard checklist.

- If `$ARGUMENTS` is a project path → audit that single project
- If `$ARGUMENTS` is `all` or empty → audit all projects under `packages/<domain>/`

## Checklist

For each project, check these items. Report pass/warn/fail for each.

### 1. README.md
- **Pass**: File exists and is >10 lines
- **Warn**: File exists but is very short (<10 lines)
- **Fail**: Missing

### 2. CLAUDE.md
- **Pass**: File exists and is >20 lines
- **Warn**: File exists but is very short
- **Fail**: Missing

### 3. WIRING.md (hardware projects only)
- **Pass**: File exists
- **Skip**: Project has no GPIO usage (simulation, docs hub)
- **Fail**: Project uses hardware but has no WIRING.md

To determine if a project uses hardware: check for `gpio_config`, `#define.*GPIO`, `ledc_`, `i2c_`, `spi_`, `uart_` in source files.

### 4. justfile
- **Pass**: File exists and imports `tools/esp32.just`
- **Warn**: File exists but doesn't import shared config
- **Fail**: Missing (for ESP-IDF projects)
- **Skip**: ESPHome or non-ESP-IDF projects

### 5. Root justfile registration
- **Pass**: Project appears as `mod` in root `justfile`
- **Fail**: Not registered

Check by grepping root `justfile` for the project directory name.

### 6. sdkconfig.defaults (ESP-IDF only)
- **Pass**: File exists
- **Fail**: Missing for ESP-IDF project

### 7. version.txt
- **Pass**: File exists
- **Fail**: Missing

### 8. .gitignore coverage
- **Pass**: Project has own `.gitignore` OR root `.gitignore` covers common patterns (build/, sdkconfig)
- **Warn**: No coverage found

### 9. Credentials handling (WiFi/API projects only)
- **Pass**: `credentials.h.example` or `secrets.yaml.example` exists
- **Skip**: Project doesn't use WiFi or API credentials
- **Fail**: Source references credentials but no example file exists

Check by grepping for `#include "credentials.h"`, `#include "secrets.h"`, `wifi_config` in source.

### 10. mDNS configuration (WiFi STA projects only)
- **Pass**: `mdns` in CMakeLists.txt REQUIRES and `CONFIG_MDNS_ENABLED` in sdkconfig.defaults
- **Skip**: Project doesn't use WiFi STA mode
- **Fail**: WiFi STA project without mDNS

Check by grepping for `esp_wifi_set_mode.*WIFI_MODE_STA` or `wifi_init_sta` in source.

## Output Format

### Single Project

```
## Project Health: <project-name>

| Check | Status | Notes |
|-------|--------|-------|
| README.md | PASS | 85 lines |
| CLAUDE.md | FAIL | Missing |
| ... | ... | ... |

Score: 8/10 checks passed

Suggested actions:
- Run `/project-claude-md <path>` to generate CLAUDE.md
- Run `/wiring-doc <path>` to generate WIRING.md
```

### All Projects

```
## Monorepo Health Summary

| Project | README | CLAUDE | WIRING | justfile | registered | sdkconfig | version | gitignore | creds | mDNS | Score |
|---------|--------|--------|--------|----------|------------|-----------|---------|-----------|-------|------|-------|
| robocar-main | PASS | FAIL | ... | ... | ... | ... | ... | ... | ... | ... | 7/10 |
| ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... |

Projects needing attention:
- <project>: missing CLAUDE.md, WIRING.md
```