the signals and their derived score are provisional and subject to change.
validate manually before sharing.
07760372507c846535057eefc24cf3d5160e2f483fec399ce0b62 months ago🤖 Generated with [Claude Code](https://claude.com/claude-code)cf9184958bb42 months ago🤖 Generated with [Claude Code](https://claude.com/claude-code)@AGENTS.md
# ChuMicro Development Ecosystem
> Operating manual for AI coding agents.
> Human contributors use [CONTRIBUTING.md](CONTRIBUTING.md).
Cross-runtime Python libraries for embedded boards.
CircuitPython and MicroPython deploy to hardware. CPython is the host test seam,
never a deployment target. Minimum board class is 256 KB RAM and 2 MB flash, of
which roughly 800 KB is usable
([Decision 0015](plans/decisions/0015-board-architecture-support.md)).
## Ground rules
When two instructions conflict, the higheSee AGENTS.md in the repository root for the full rule set, skills, and workspace conventions.
name: AI Review
# Claude reviews a pull request when a maintainer asks for it by commenting
# `@claude /review` on the PR. The abuse model this design answers (full
# write-up in docs/contributing/maintainers.md):
#
# - Spend is maintainer-gated at the only lever that matters: the run
# starts from a comment, the job filters on who wrote it, and the
# action independently verifies the commenter has write access. A PR
# that has nothing to do with the project sits inert forever; nobody
# ---
name: audit-code
description: Deeply evaluates a source file, class, or library from five angles — correctness traps (inversions, off-by-ones, code that says one thing and does another), hazards (peer-sized allocations, injection, reentrancy, leaked resources), test-coverage gaps, comment/doc drift, and clarity/craft — in a clean room that project memory and stale comments cannot bias, then produces a shareable HTML report of per-method summaries plus numbered, apply-by-number fixes. Use when the us---
name: audit-library
description: Code-quality audit on a single library. Looks for duplication, abstraction honesty, method shape, dead code, speculative public API, top-to-bottom readability. Produces a punch-list, then executes high-confidence cleanups with user sign-off. Use when a library has accumulated implementation debt without a recent design pass.
---
# Library audit
Audit one library (`libraries/<name>/` or `workbench/<name>/`) for cleanup opportunities. Output a prioritized punch-list, th---
name: new-skill
description: Authors a new SKILL.md that passes a cold-reader test on first invocation. Use when the user wants to write a new skill, rewrite an existing one from scratch, capture a repeatable session as a skill, build a slash command, or skillify a workflow. Examples: "write a skill that does X", "skillify this", "make this a slash command", "I want a /foo that does Y", "regenerate /<existing> from scratch".
allowed-tools:
- Read
- Write
- Edit
- Bash(ls *)
- Bash(grep *)
- ---
name: task-checkpoint
description: Sanity check at the end of a unit of work: preflight green, workstream and docs refreshed, plans/next-up.md refreshed, durable lessons lifted, commit pushed. Use after finishing a coherent unit of work (one that could carry a single commit subject). Multiple checkpoints can ride the same session; the yield happens once when the named work is done, not after every unit.
---
# Task Checkpoint
Per [AGENTS.md → Workflow](../../../AGENTS.md#workflow), run this at the en---
name: audit-workspace
description: Code-quality audit at the mono-repo / ecosystem level. Looks for cross-library duplication, library-shape candidates (merge / split / delete / promote), speculative public API, dependency-graph health, and decision-ADR drift. Use when the workspace has accumulated patterns nobody owns.
---
# Workspace audit
Audit the entire mono-repo / ecosystem. Where `/audit-library` looks inside one package and `/audit-integration` looks at boundaries between two or three, this s---
name: audit-integration
description: Code-quality audit across two or more libraries that interact. Looks for duplicated handoff logic, leaky abstractions, dependency-direction issues, parallel implementations that should converge. Use when two libraries' boundary feels awkward, or when a feature spans multiple libraries and the seam is showing.
---
# Cross-library integration audit
Audit the boundary between two or more libraries. Where `/audit-library` looks *inside* one package, this skill looks *---
name: new-decision
description: How to create a new decision record in plans/decisions/. Use this skill when a structural, pattern, or tooling tradeoff needs to be recorded.
---
# New Decision
Decision records capture *why* the workspace has its current shape. Create one when a tradeoff is made that future agents or contributors would otherwise have to rediscover.
## When to create a decision
- A structural change affects how libraries, tests, or tooling work.
- A pattern is established that all lib---
description: Audits an existing skill on disk against Anthropic's documented skill-authoring rules — size and token budgets, progressive disclosure, rule salience, frontmatter routing — and the skill's own stated goal. Use when a skill's flow feels off, contradicts itself, or routes wrong — or before relying on it for important work. Examples: "audit the audit-docs skill", "/audit-skill audit-library", "is the audit-library skill achieving its goal?".
allowed-tools: Read, Write, Edit, Grep, Bash(l---
name: audit-publishable-isolation
description: Cross-repo audit for leaks of mono-repo-internal concepts into shipped artifacts — PyPI packages, READMEs, generated payloads, the workspace-template starter. Finds run.py / scripts/ / plans/ / Decision NNNN refs, upstream repo names, and directory-shape assumptions. Use when leaks feel sprinkled everywhere or before a release-prep pass.
---
# Publishable-isolation audit
Audit publishable artifacts for leaks of mono-repo-internal concepts. The principl---
name: schemdraw-circuit-generator
description: "Generate professional circuit diagrams using schemdraw Python library. Creates vector graphics (SVG/PDF/PNG) from natural language descriptions. Components: resistors, capacitors, inductors, diodes, transistors, opamps, ICs, logic gates, etc. Use when: (1) User requests circuit diagrams or schematics, (2) User wants publication-quality output, (3) User needs SVG/PDF for documentation, (4) Complex circuits with ICs/opamps/digital logic, (5) User mentions sc---
name: guide-generation
description: How to generate or update docs/guide.md for a ChuMicro library. Use this skill when a library needs its user guide written or refreshed.
---
# Guide generation
Use this procedure to generate or update `docs/guide.md` for a ChuMicro library.
## When to use
- After implementing a new library (the scaffold generates placeholder comments — see `workbench/workspace/src/chumicro_workspace/_payloads/library_template/guide.md.template`)
- After adding significant new fe---
name: session-handoff
description: Capture session-transition context to plans/handoffs/ before clearing or switching sessions. User-invoked via /session-handoff — do not auto-trigger.
---
# Session Handoff
Pairs with [`session-resume`](../session-resume/SKILL.md) — write/read symmetry.
Used when you're about to `/clear`, switch to a fresh session, or otherwise leave conversation state behind, and the session produced context that would not survive `git log` + `plans/next-up.md` alone.
A handoff---
name: audit-branch
description: Deeply evaluates a change-set — a branch, revision range, or staged/working-tree diff — before it ships: bugs in the changed code, contract breaks for the code it integrates with, every traced usage checked against the new behavior, alignment with the stated intent (root-cause-vs-symptom on bugfixes, unacknowledged scope drift), coverage for the new behavior, and the craft of the new code — in a clean room project memory cannot bias, producing a shareable HTML decis---
name: new-library
description: Full lifecycle for creating a new ChuMicro library — from scaffolding through release-ready. Use this skill when adding a new library to the workspace.
---
# New Library Lifecycle
This skill covers the full workflow from scaffolding a new library through making it release-ready. The scaffold command creates the skeleton; everything after that is on you.
## Procedure
### 1. Scaffold
```bash
python scripts/run.py new-library <name>
```
This creates `libraries/<name>/---
name: audit-embedded
description: Embedded-systems audit of a single device library — flash footprint, import-time RAM, hot-path allocations, heap fragmentation, runtime quirks on MicroPython and CircuitPython, and docs-vs-code drift. Complements (does not replace) `/audit-library`. Use when a library is bound for boards with 256 KB RAM / 2 MB physical / ~800 KB usable flash and you want a focused pass on whether it pulls its weight there.
---
# Embedded-library audit
Audit one device library (`li---
name: code-review-router
description: Intelligently routes code reviews between Gemini CLI and Codex CLI based on tech stack, complexity, and change characteristics. Use when you want an automated code review of your current changes.
---
# Code Review Router
Routes code reviews to the optimal CLI (Gemini or Codex) based on change characteristics.
## Device-library changes (`libraries/`)
When the diff touches files under `libraries/`, the changed code ships to constrained microcontrollers (256 KB RAM---
name: session-resume
description: Resume work from a session handoff in plans/handoffs/. User-invoked at session start via /session-resume [<slug>] or by plain-language ask ("pick up where we left off", "resume the handoff"). Do not auto-trigger from the presence of a handoff pointer in next-up.md alone — the user may have boot intentions unrelated to the handoff.
---
# Session Resume
Pairs with [`session-handoff`](../session-handoff/SKILL.md) — write/read symmetry. The handoff skill captures sess---
name: surfaces
description: Put a rich HTML surface in front of the human when the terminal is not enough - a decision picker over many items, an A/B compare, prose questionnaires, media hand-off (images, audio, video, files), uploads the human hands back, reports, or live status. Use when AskUserQuestion or a plain prompt would lose the shape of the question.
---
# Surfaces
Rich pages the agent puts in front of the human, all through one hub: decision pickers,
compare-and-edit, prose questionnaires, ---
name: audit-docs
description: Audit a user-facing markdown doc (README, INSTALL, library guides) for cold-reader readability, AI-tic phrases, jargon and implementation-detail leaks, unverified claims, section ordering, and visual / link consistency. Produces a punch-list, executes safe cleanups with sign-off. Use when a README has accumulated drift, after a feature pass, or before a release-prep pass.
---
# Docs audit
Audit one human-curated markdown doc (`README.md`, `libraries/<name>/docs/guide.md---
name: audit-comments
description: Audit code comments and docstrings in a file, library, or tree for whether a cold reader learns what the thing does and why it exists. Unlike the trim-only comment passes inside /audit-library, this skill rewrites a degraded comment from a fresh read of the code rather than subtracting it further. Use when comments have gone illegible after repeated audits, after a feature pass, or before a release-prep pass.
---
# Comment audit
Audit the comments and docstrings of a ---
name: git-commit
description: How to write and execute git commits in this workspace. Use this skill whenever committing code to git.
---
# Git Commit Mechanics
Pass the commit message inline via a **single-quoted heredoc** consumed by `git commit -m "$(cat <<'EOF' … EOF)"`. The single quotes around the `EOF` delimiter disable shell expansion inside the heredoc, so backticks, `$`, parentheses, and newlines pass through literally. This was bench-validated 2026-05-10 against backticks, em-dashes, ar.gitignoreclaude-code.claude/*.gitignoreunspecified.agents/