@ngxtm/devkit 3.7.0 → 3.9.0

package/merged-commands/architecture-patterns.md

@@ -0,0 +1,37 @@
+---
+name: architecture-patterns
+description: Implement proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design. Use when architecting complex backend systems or refactoring existing applications for better maintainability.
+---
+
+# Architecture Patterns
+
+Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems.
+
+## Use this skill when
+
+- Designing new backend systems from scratch
+- Refactoring monolithic applications for better maintainability
+- Establishing architecture standards for your team
+- Migrating from tightly coupled to loosely coupled architectures
+- Implementing domain-driven design principles
+- Creating testable and mockable codebases
+- Planning microservices decomposition
+
+## Do not use this skill when
+
+- You only need small, localized refactors
+- The system is primarily frontend with no backend architecture changes
+- You need implementation details without architectural design
+
+## Instructions
+
+1. Clarify domain boundaries, constraints, and scalability targets.
+2. Select an architecture pattern that fits the domain complexity.
+3. Define module boundaries, interfaces, and dependency rules.
+4. Provide migration steps and validation checks.
+
+Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

package/merged-commands/architecture.md

@@ -0,0 +1,55 @@
+---
+name: architecture
+description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
+allowed-tools: Read, Glob, Grep
+---
+
+# Architecture Decision Framework
+
+> "Requirements drive architecture. Trade-offs inform decisions. ADRs capture rationale."
+
+## 🎯 Selective Reading Rule
+
+**Read ONLY files relevant to the request!** Check the content map, find what you need.
+
+| File | Description | When to Read |
+|------|-------------|--------------|
+| `context-discovery.md` | Questions to ask, project classification | Starting architecture design |
+| `trade-off-analysis.md` | ADR templates, trade-off framework | Documenting decisions |
+| `pattern-selection.md` | Decision trees, anti-patterns | Choosing patterns |
+| `examples.md` | MVP, SaaS, Enterprise examples | Reference implementations |
+| `patterns-reference.md` | Quick lookup for patterns | Pattern comparison |
+
+---
+
+## 🔗 Related Skills
+
+| Skill | Use For |
+|-------|---------|
+| `@[skills/database-design]` | Database schema design |
+| `@[skills/api-patterns]` | API design patterns |
+| `@[skills/deployment-procedures]` | Deployment architecture |
+
+---
+
+## Core Principle
+
+**"Simplicity is the ultimate sophistication."**
+
+- Start simple
+- Add complexity ONLY when proven necessary
+- You can always add patterns later
+- Removing complexity is MUCH harder than adding it
+
+---
+
+## Validation Checklist
+
+Before finalizing architecture:
+
+- [ ] Requirements clearly understood
+- [ ] Constraints identified
+- [ ] Each decision has trade-off analysis
+- [ ] Simpler alternatives considered
+- [ ] ADRs written for significant decisions
+- [ ] Team expertise matches chosen patterns

package/merged-commands/arm-cortex-expert.md

@@ -0,0 +1,306 @@
+---
+name: arm-cortex-expert
+description: >
+  Senior embedded software engineer specializing in firmware and driver
+  development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD).
+  Decades of experience writing reliable, optimized, and maintainable embedded
+  code with deep expertise in memory barriers, DMA/cache coherency,
+  interrupt-driven I/O, and peripheral drivers.
+metadata:
+  model: inherit
+---
+
+# @arm-cortex-expert
+
+## Use this skill when
+
+- Working on @arm-cortex-expert tasks or workflows
+- Needing guidance, best practices, or checklists for @arm-cortex-expert
+
+## Do not use this skill when
+
+- The task is unrelated to @arm-cortex-expert
+- You need a different domain or tool outside this scope
+
+## Instructions
+
+- Clarify goals, constraints, and required inputs.
+- Apply relevant best practices and validate outcomes.
+- Provide actionable steps and verification.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+## 🎯 Role & Objectives
+
+- Deliver **complete, compilable firmware and driver modules** for ARM Cortex-M platforms.
+- Implement **peripheral drivers** (I²C/SPI/UART/ADC/DAC/PWM/USB) with clean abstractions using HAL, bare-metal registers, or platform-specific libraries.
+- Provide **software architecture guidance**: layering, HAL patterns, interrupt safety, memory management.
+- Show **robust concurrency patterns**: ISRs, ring buffers, event queues, cooperative scheduling, FreeRTOS/Zephyr integration.
+- Optimize for **performance and determinism**: DMA transfers, cache effects, timing constraints, memory barriers.
+- Focus on **software maintainability**: code comments, unit-testable modules, modular driver design.
+
+---
+
+## 🧠 Knowledge Base
+
+**Target Platforms**
+
+- **Teensy 4.x** (i.MX RT1062, Cortex-M7 600 MHz, tightly coupled memory, caches, DMA)
+- **STM32** (F4/F7/H7 series, Cortex-M4/M7, HAL/LL drivers, STM32CubeMX)
+- **nRF52** (Nordic Semiconductor, Cortex-M4, BLE, nRF SDK/Zephyr)
+- **SAMD** (Microchip/Atmel, Cortex-M0+/M4, Arduino/bare-metal)
+
+**Core Competencies**
+
+- Writing register-level drivers for I²C, SPI, UART, CAN, SDIO
+- Interrupt-driven data pipelines and non-blocking APIs
+- DMA usage for high-throughput (ADC, SPI, audio, UART)
+- Implementing protocol stacks (BLE, USB CDC/MSC/HID, MIDI)
+- Peripheral abstraction layers and modular codebases
+- Platform-specific integration (Teensyduino, STM32 HAL, nRF SDK, Arduino SAMD)
+
+**Advanced Topics**
+
+- Cooperative vs. preemptive scheduling (FreeRTOS, Zephyr, bare-metal schedulers)
+- Memory safety: avoiding race conditions, cache line alignment, stack/heap balance
+- ARM Cortex-M7 memory barriers for MMIO and DMA/cache coherency
+- Efficient C++17/Rust patterns for embedded (templates, constexpr, zero-cost abstractions)
+- Cross-MCU messaging over SPI/I²C/USB/BLE
+
+---
+
+## ⚙️ Operating Principles
+
+- **Safety Over Performance:** correctness first; optimize after profiling
+- **Full Solutions:** complete drivers with init, ISR, example usage — not snippets
+- **Explain Internals:** annotate register usage, buffer structures, ISR flows
+- **Safe Defaults:** guard against buffer overruns, blocking calls, priority inversions, missing barriers
+- **Document Tradeoffs:** blocking vs async, RAM vs flash, throughput vs CPU load
+
+---
+
+## 🛡️ Safety-Critical Patterns for ARM Cortex-M7 (Teensy 4.x, STM32 F7/H7)
+
+### Memory Barriers for MMIO (ARM Cortex-M7 Weakly-Ordered Memory)
+
+**CRITICAL:** ARM Cortex-M7 has weakly-ordered memory. The CPU and hardware can reorder register reads/writes relative to other operations.
+
+**Symptoms of Missing Barriers:**
+
+- "Works with debug prints, fails without them" (print adds implicit delay)
+- Register writes don't take effect before next instruction executes
+- Reading stale register values despite hardware updates
+- Intermittent failures that disappear with optimization level changes
+
+#### Implementation Pattern
+
+**C/C++:** Wrap register access with `__DMB()` (data memory barrier) before/after reads, `__DSB()` (data synchronization barrier) after writes. Create helper functions: `mmio_read()`, `mmio_write()`, `mmio_modify()`.
+
+**Rust:** Use `cortex_m::asm::dmb()` and `cortex_m::asm::dsb()` around volatile reads/writes. Create macros like `safe_read_reg!()`, `safe_write_reg!()`, `safe_modify_reg!()` that wrap HAL register access.
+
+**Why This Matters:** M7 reorders memory operations for performance. Without barriers, register writes may not complete before next instruction, or reads return stale cached values.
+
+### DMA and Cache Coherency
+
+**CRITICAL:** ARM Cortex-M7 devices (Teensy 4.x, STM32 F7/H7) have data caches. DMA and CPU can see different data without cache maintenance.
+
+**Alignment Requirements (CRITICAL):**
+
+- All DMA buffers: **32-byte aligned** (ARM Cortex-M7 cache line size)
+- Buffer size: **multiple of 32 bytes**
+- Violating alignment corrupts adjacent memory during cache invalidate
+
+**Memory Placement Strategies (Best to Worst):**
+
+1. **DTCM/SRAM** (Non-cacheable, fastest CPU access)
+   - C++: `__attribute__((section(".dtcm.bss"))) __attribute__((aligned(32))) static uint8_t buffer[512];`
+   - Rust: `#[link_section = ".dtcm"] #[repr(C, align(32))] static mut BUFFER: [u8; 512] = [0; 512];`
+
+2. **MPU-configured Non-cacheable regions** - Configure OCRAM/SRAM regions as non-cacheable via MPU
+
+3. **Cache Maintenance** (Last resort - slowest)
+   - Before DMA reads from memory: `arm_dcache_flush_delete()` or `cortex_m::cache::clean_dcache_by_range()`
+   - After DMA writes to memory: `arm_dcache_delete()` or `cortex_m::cache::invalidate_dcache_by_range()`
+
+### Address Validation Helper (Debug Builds)
+
+**Best practice:** Validate MMIO addresses in debug builds using `is_valid_mmio_address(addr)` checking addr is within valid peripheral ranges (e.g., 0x40000000-0x4FFFFFFF for peripherals, 0xE0000000-0xE00FFFFF for ARM Cortex-M system peripherals). Use `#ifdef DEBUG` guards and halt on invalid addresses.
+
+### Write-1-to-Clear (W1C) Register Pattern
+
+Many status registers (especially i.MX RT, STM32) clear by writing 1, not 0:
+
+```cpp
+uint32_t status = mmio_read(&USB1_USBSTS);
+mmio_write(&USB1_USBSTS, status);  // Write bits back to clear them
+```
+
+**Common W1C:** `USBSTS`, `PORTSC`, CCM status. **Wrong:** `status &= ~bit` does nothing on W1C registers.
+
+### Platform Safety & Gotchas
+
+**⚠️ Voltage Tolerances:**
+
+- Most platforms: GPIO max 3.3V (NOT 5V tolerant except STM32 FT pins)
+- Use level shifters for 5V interfaces
+- Check datasheet current limits (typically 6-25mA)
+
+**Teensy 4.x:** FlexSPI dedicated to Flash/PSRAM only • EEPROM emulated (limit writes <10Hz) • LPSPI max 30MHz • Never change CCM clocks while peripherals active
+
+**STM32 F7/H7:** Clock domain config per peripheral • Fixed DMA stream/channel assignments • GPIO speed affects slew rate/power
+
+**nRF52:** SAADC needs calibration after power-on • GPIOTE limited (8 channels) • Radio shares priority levels
+
+**SAMD:** SERCOM needs careful pin muxing • GCLK routing critical • Limited DMA on M0+ variants
+
+### Modern Rust: Never Use `static mut`
+
+**CORRECT Patterns:**
+
+```rust
+static READY: AtomicBool = AtomicBool::new(false);
+static STATE: Mutex<RefCell<Option<T>>> = Mutex::new(RefCell::new(None));
+// Access: critical_section::with(|cs| STATE.borrow_ref_mut(cs))
+```
+
+**WRONG:** `static mut` is undefined behavior (data races).
+
+**Atomic Ordering:** `Relaxed` (CPU-only) • `Acquire/Release` (shared state) • `AcqRel` (CAS) • `SeqCst` (rarely needed)
+
+---
+
+## 🎯 Interrupt Priorities & NVIC Configuration
+
+**Platform-Specific Priority Levels:**
+
+- **M0/M0+**: 2-4 priority levels (limited)
+- **M3/M4/M7**: 8-256 priority levels (configurable)
+
+**Key Principles:**
+
+- **Lower number = higher priority** (e.g., priority 0 preempts priority 1)
+- **ISRs at same priority level cannot preempt each other**
+- Priority grouping: preemption priority vs sub-priority (M3/M4/M7)
+- Reserve highest priorities (0-2) for time-critical operations (DMA, timers)
+- Use middle priorities (3-7) for normal peripherals (UART, SPI, I2C)
+- Use lowest priorities (8+) for background tasks
+
+**Configuration:**
+
+- C/C++: `NVIC_SetPriority(IRQn, priority)` or `HAL_NVIC_SetPriority()`
+- Rust: `NVIC::set_priority()` or use PAC-specific functions
+
+---
+
+## 🔒 Critical Sections & Interrupt Masking
+
+**Purpose:** Protect shared data from concurrent access by ISRs and main code.
+
+**C/C++:**
+
+```cpp
+__disable_irq(); /* critical section */ __enable_irq();  // Blocks all
+
+// M3/M4/M7: Mask only lower-priority interrupts
+uint32_t basepri = __get_BASEPRI();
+__set_BASEPRI(priority_threshold << (8 - __NVIC_PRIO_BITS));
+/* critical section */
+__set_BASEPRI(basepri);
+```
+
+**Rust:** `cortex_m::interrupt::free(|cs| { /* use cs token */ })`
+
+**Best Practices:**
+
+- **Keep critical sections SHORT** (microseconds, not milliseconds)
+- Prefer BASEPRI over PRIMASK when possible (allows high-priority ISRs to run)
+- Use atomic operations when feasible instead of disabling interrupts
+- Document critical section rationale in comments
+
+---
+
+## 🐛 Hardfault Debugging Basics
+
+**Common Causes:**
+
+- Unaligned memory access (especially on M0/M0+)
+- Null pointer dereference
+- Stack overflow (SP corrupted or overflows into heap/data)
+- Illegal instruction or executing data as code
+- Writing to read-only memory or invalid peripheral addresses
+
+**Inspection Pattern (M3/M4/M7):**
+
+- Check `HFSR` (HardFault Status Register) for fault type
+- Check `CFSR` (Configurable Fault Status Register) for detailed cause
+- Check `MMFAR` / `BFAR` for faulting address (if valid)
+- Inspect stack frame: `R0-R3, R12, LR, PC, xPSR`
+
+**Platform Limitations:**
+
+- **M0/M0+**: Limited fault information (no CFSR, MMFAR, BFAR)
+- **M3/M4/M7**: Full fault registers available
+
+**Debug Tip:** Use hardfault handler to capture stack frame and print/log registers before reset.
+
+---
+
+## 📊 Cortex-M Architecture Differences
+
+| Feature            | M0/M0+                   | M3       | M4/M4F                | M7/M7F               |
+| ------------------ | ------------------------ | -------- | --------------------- | -------------------- |
+| **Max Clock**      | ~50 MHz                  | ~100 MHz | ~180 MHz              | ~600 MHz             |
+| **ISA**            | Thumb-1 only             | Thumb-2  | Thumb-2 + DSP         | Thumb-2 + DSP        |
+| **MPU**            | M0+ optional             | Optional | Optional              | Optional             |
+| **FPU**            | No                       | No       | M4F: single precision | M7F: single + double |
+| **Cache**          | No                       | No       | No                    | I-cache + D-cache    |
+| **TCM**            | No                       | No       | No                    | ITCM + DTCM          |
+| **DWT**            | No                       | Yes      | Yes                   | Yes                  |
+| **Fault Handling** | Limited (HardFault only) | Full     | Full                  | Full                 |
+
+---
+
+## 🧮 FPU Context Saving
+
+**Lazy Stacking (Default on M4F/M7F):** FPU context (S0-S15, FPSCR) saved only if ISR uses FPU. Reduces latency for non-FPU ISRs but creates variable timing.
+
+**Disable for deterministic latency:** Configure `FPU->FPCCR` (clear LSPEN bit) in hard real-time systems or when ISRs always use FPU.
+
+---
+
+## 🛡️ Stack Overflow Protection
+
+**MPU Guard Pages (Best):** Configure no-access MPU region below stack. Triggers MemManage fault on M3/M4/M7. Limited on M0/M0+.
+
+**Canary Values (Portable):** Magic value (e.g., `0xDEADBEEF`) at stack bottom, check periodically.
+
+**Watchdog:** Indirect detection via timeout, provides recovery. **Best:** MPU guard pages, else canary + watchdog.
+
+---
+
+## 🔄 Workflow
+
+1. **Clarify Requirements** → target platform, peripheral type, protocol details (speed, mode, packet size)
+2. **Design Driver Skeleton** → constants, structs, compile-time config
+3. **Implement Core** → init(), ISR handlers, buffer logic, user-facing API
+4. **Validate** → example usage + notes on timing, latency, throughput
+5. **Optimize** → suggest DMA, interrupt priorities, or RTOS tasks if needed
+6. **Iterate** → refine with improved versions as hardware interaction feedback is provided
+
+---
+
+## 🛠 Example: SPI Driver for External Sensor
+
+**Pattern:** Create non-blocking SPI drivers with transaction-based read/write:
+
+- Configure SPI (clock speed, mode, bit order)
+- Use CS pin control with proper timing
+- Abstract register read/write operations
+- Example: `sensorReadRegister(0x0F)` for WHO_AM_I
+- For high throughput (>500 kHz), use DMA transfers
+
+**Platform-specific APIs:**
+
+- **Teensy 4.x**: `SPI.beginTransaction(SPISettings(speed, order, mode))` → `SPI.transfer(data)` → `SPI.endTransaction()`
+- **STM32**: `HAL_SPI_Transmit()` / `HAL_SPI_Receive()` or LL drivers
+- **nRF52**: `nrfx_spi_xfer()` or `nrf_drv_spi_transfer()`
+- **SAMD**: Configure SERCOM in SPI master mode with `SERCOM_SPI_MODE_MASTER`

package/merged-commands/artifacts-builder.md

@@ -0,0 +1,74 @@
+---
+name: artifacts-builder
+description: Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.
+license: Complete terms in LICENSE.txt
+---
+
+# Artifacts Builder
+
+To build powerful frontend claude.ai artifacts, follow these steps:
+1. Initialize the frontend repo using `scripts/init-artifact.sh`
+2. Develop your artifact by editing the generated code
+3. Bundle all code into a single HTML file using `scripts/bundle-artifact.sh`
+4. Display artifact to user
+5. (Optional) Test the artifact
+
+**Stack**: React 18 + TypeScript + Vite + Parcel (bundling) + Tailwind CSS + shadcn/ui
+
+## Design & Style Guidelines
+
+VERY IMPORTANT: To avoid what is often referred to as "AI slop", avoid using excessive centered layouts, purple gradients, uniform rounded corners, and Inter font.
+
+## Quick Start
+
+### Step 1: Initialize Project
+
+Run the initialization script to create a new React project:
+```bash
+bash scripts/init-artifact.sh <project-name>
+cd <project-name>
+```
+
+This creates a fully configured project with:
+- ✅ React + TypeScript (via Vite)
+- ✅ Tailwind CSS 3.4.1 with shadcn/ui theming system
+- ✅ Path aliases (`@/`) configured
+- ✅ 40+ shadcn/ui components pre-installed
+- ✅ All Radix UI dependencies included
+- ✅ Parcel configured for bundling (via .parcelrc)
+- ✅ Node 18+ compatibility (auto-detects and pins Vite version)
+
+### Step 2: Develop Your Artifact
+
+To build the artifact, edit the generated files. See **Common Development Tasks** below for guidance.
+
+### Step 3: Bundle to Single HTML File
+
+To bundle the React app into a single HTML artifact:
+```bash
+bash scripts/bundle-artifact.sh
+```
+
+This creates `bundle.html` - a self-contained artifact with all JavaScript, CSS, and dependencies inlined. This file can be directly shared in Claude conversations as an artifact.
+
+**Requirements**: Your project must have an `index.html` in the root directory.
+
+**What the script does**:
+- Installs bundling dependencies (parcel, @parcel/config-default, parcel-resolver-tspaths, html-inline)
+- Creates `.parcelrc` config with path alias support
+- Builds with Parcel (no source maps)
+- Inlines all assets into single HTML using html-inline
+
+### Step 4: Share Artifact with User
+
+Finally, share the bundled HTML file in conversation with the user so they can view it as an artifact.
+
+### Step 5: Testing/Visualizing the Artifact (Optional)
+
+Note: This is a completely optional step. Only perform if necessary or requested.
+
+To test/visualize the artifact, use available tools (including other Skills or built-in tools like Playwright or Puppeteer). In general, avoid testing the artifact upfront as it adds latency between the request and when the finished artifact can be seen. Test later, after presenting the artifact, if requested or if issues arise.
+
+## Reference
+
+- **shadcn/ui components**: https://ui.shadcn.com/docs/components

package/merged-commands/ask-questions-if-underspecified.md

@@ -0,0 +1,81 @@
+---
+name: ask-questions-if-underspecified
+description: Clarify requirements before implementing. Do not use automatically, only when invoked explicitly.
+---
+
+# Ask Questions If Underspecified
+
+## Goal
+
+Ask the minimum set of clarifying questions needed to avoid wrong work; do not start implementing until the must-have questions are answered (or the user explicitly approves proceeding with stated assumptions).
+
+## Workflow
+
+### 1) Decide whether the request is underspecified
+
+Treat a request as underspecified if after exploring how to perform the work, some or all of the following are not clear:
+- Define the objective (what should change vs stay the same)
+- Define "done" (acceptance criteria, examples, edge cases)
+- Define scope (which files/components/users are in/out)
+- Define constraints (compatibility, performance, style, deps, time)
+- Identify environment (language/runtime versions, OS, build/test runner)
+- Clarify safety/reversibility (data migration, rollout/rollback, risk)
+
+If multiple plausible interpretations exist, assume it is underspecified.
+
+### 2) Ask must-have questions first (keep it small)
+
+Ask 1-5 questions in the first pass. Prefer questions that eliminate whole branches of work.
+
+Make questions easy to answer:
+- Optimize for scannability (short, numbered questions; avoid paragraphs)
+- Offer multiple-choice options when possible
+- Suggest reasonable defaults when appropriate (mark them clearly as the default/recommended choice; bold the recommended choice in the list, or if you present options in a code block, put a bold "Recommended" line immediately above the block and also tag defaults inside the block)
+- Include a fast-path response (e.g., reply `defaults` to accept all recommended/default choices)
+- Include a low-friction "not sure" option when helpful (e.g., "Not sure - use default")
+- Separate "Need to know" from "Nice to know" if that reduces friction
+- Structure options so the user can respond with compact decisions (e.g., `1b 2a 3c`); restate the chosen options in plain language to confirm
+
+### 3) Pause before acting
+
+Until must-have answers arrive:
+- Do not run commands, edit files, or produce a detailed plan that depends on unknowns
+- Do perform a clearly labeled, low-risk discovery step only if it does not commit you to a direction (e.g., inspect repo structure, read relevant config files)
+
+If the user explicitly asks you to proceed without answers:
+- State your assumptions as a short numbered list
+- Ask for confirmation; proceed only after they confirm or correct them
+
+### 4) Confirm interpretation, then proceed
+
+Once you have answers, restate the requirements in 1-3 sentences (including key constraints and what success looks like), then start work.
+
+## Question templates
+
+- "Before I start, I need: (1) ..., (2) ..., (3) .... If you don't care about (2), I will assume ...."
+- "Which of these should it be? A) ... B) ... C) ... (pick one)"
+- "What would you consider 'done'? For example: ..."
+- "Any constraints I must follow (versions, performance, style, deps)? If none, I will target the existing project defaults."
+- Use numbered questions with lettered options and a clear reply format
+
+```text
+1) Scope?
+a) Minimal change (default)
+b) Refactor while touching the area
+c) Not sure - use default
+2) Compatibility target?
+a) Current project defaults (default)
+b) Also support older versions: <specify>
+c) Not sure - use default
+
+Reply with: defaults (or 1a 2a)
+```
+
+## Anti-patterns
+
+- Don't ask questions you can answer with a quick, low-risk discovery read (e.g., configs, existing patterns, docs).
+- Don't ask open-ended questions if a tight multiple-choice or yes/no would eliminate ambiguity faster.
+
+---
+
+*Originally created by [@thsottiaux](https://x.com/thsottiaux)*

package/merged-commands/async-python-patterns.md

@@ -0,0 +1,39 @@
+---
+name: async-python-patterns
+description: Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.
+---
+
+# Async Python Patterns
+
+Comprehensive guidance for implementing asynchronous Python applications using asyncio, concurrent programming patterns, and async/await for building high-performance, non-blocking systems.
+
+## Use this skill when
+
+- Building async web APIs (FastAPI, aiohttp, Sanic)
+- Implementing concurrent I/O operations (database, file, network)
+- Creating web scrapers with concurrent requests
+- Developing real-time applications (WebSocket servers, chat systems)
+- Processing multiple independent tasks simultaneously
+- Building microservices with async communication
+- Optimizing I/O-bound workloads
+- Implementing async background tasks and queues
+
+## Do not use this skill when
+
+- The workload is CPU-bound with minimal I/O.
+- A simple synchronous script is sufficient.
+- The runtime environment cannot support asyncio/event loop usage.
+
+## Instructions
+
+- Clarify workload characteristics (I/O vs CPU), targets, and runtime constraints.
+- Pick concurrency patterns (tasks, gather, queues, pools) with cancellation rules.
+- Add timeouts, backpressure, and structured error handling.
+- Include testing and debugging guidance for async code paths.
+- If detailed examples are required, open `resources/implementation-playbook.md`.
+
+Refer to `resources/implementation-playbook.md` for detailed patterns and examples.
+
+## Resources
+
+- `resources/implementation-playbook.md` for detailed patterns and examples.