---
name: architecture
description: "Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design."
risk: safe
source: community
date_added: "2026-02-27"
---

# 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

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: architecture-decision-records
description: "Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions."
risk: critical
source: community
date_added: "2026-02-27"
---

# Architecture Decision Records

Comprehensive patterns for creating, maintaining, and managing Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions.

## Use this skill when

- Making significant architectural decisions
- Documenting technology choices
- Recording design trade-offs
- Onboarding new team members
- Reviewing historical decisions
- Establishing decision-making processes

## Do not use this skill when

- You only need to document small implementation details
- The change is a minor patch or routine maintenance
- There is no architectural decision to capture

## Instructions

1. Capture the decision context, constraints, and drivers.
2. Document considered options with tradeoffs.
3. Record the decision, rationale, and consequences.
4. Link related ADRs and update status over time.

## Core Concepts

### 1. What is an ADR?

An Architecture Decision Record captures:
- **Context**: Why we needed to make a decision
- **Decision**: What we decided
- **Consequences**: What happens as a result

### 2. When to Write an ADR

| Write ADR | Skip ADR |
|-----------|----------|
| New framework adoption | Minor version upgrades |
| Database technology choice | Bug fixes |
| API design patterns | Implementation details |
| Security architecture | Routine maintenance |
| Integration patterns | Configuration changes |

### 3. ADR Lifecycle

```
Proposed → Accepted → Deprecated → Superseded
              ↓
           Rejected
```

## Templates

### Template 1: Standard ADR (MADR Format)

```markdown
# ADR-0001: Use PostgreSQL as Primary Database

## Status

Accepted

## Context

We need to select a primary database for our new e-commerce platform. The system
will handle:
- ~10,000 concurrent users
- Complex product catalog with hierarchical categories
- Transaction processing for orders and payments
- Full-text search for products
- Geospatial queries for store locator

The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
compliance for financial transactions.

## Decision Drivers

* **Must have ACID compliance** for payment processing
* **Must support complex queries** for reporting
* **Should support full-text search** to reduce infrastructure complexity
* **Should have good JSON support** for flexible product attributes
* **Team familiarity** reduces onboarding time

## Considered Options

### Option 1: PostgreSQL
- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
  search, PostGIS for geospatial, team has experience
- **Cons**: Slightly more complex replication setup than MySQL

### Option 2: MySQL
- **Pros**: Very familiar to team, simple replication, large community
- **Cons**: Weaker JSON support, no built-in full-text search (need
  Elasticsearch), no geospatial without extensions

### Option 3: MongoDB
- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: No ACID for multi-document transactions (at decision time),
  team has limited experience, requires schema design discipline

## Decision

We will use **PostgreSQL 15** as our primary database.

## Rationale

PostgreSQL provides the best balance of:
1. **ACID compliance** essential for e-commerce transactions
2. **Built-in capabilities** (full-text search, JSONB, PostGIS) reduce
   infrastructure complexity
3. **Team familiarity** with SQL databases reduces learning curve
4. **Mature ecosystem** with excellent tooling and community support

The slight complexity in replication is outweighed by the reduction in
additional services (no separate Elasticsearch needed).

## Consequences

### Positive
- Single database handles transactions, search, and geospatial queries
- Reduced operational complexity (fewer services to manage)
- Strong consistency guarantees for financial data
- Team can leverage existing SQL expertise

### Negative
- Need to learn PostgreSQL-specific features (JSONB, full-text search syntax)
- Vertical scaling limits may require read replicas sooner
- Some team members need PostgreSQL-specific training

### Risks
- Full-text search may not scale as well as dedicated search engines
- Mitigation: Design for potential Elasticsearch addition if needed

## Implementation Notes

- Use JSONB for flexible product attributes
- Implement connection pooling with PgBouncer
- Set up streaming replication for read replicas
- Use pg_trgm extension for fuzzy search

## Related Decisions

- ADR-0002: Caching Strategy (Redis) - complements database choice
- ADR-0005: Search Architecture - may supersede if Elasticsearch needed

## References

- [PostgreSQL JSON Documentation](https://www.postgresql.org/docs/current/datatype-json.html)
- [PostgreSQL Full Text Search](https://www.postgresql.org/docs/current/textsearch.html)
- Internal: Performance benchmarks in `/docs/benchmarks/database-comparison.md`
```

### Template 2: Lightweight ADR

```markdown
# ADR-0012: Adopt TypeScript for Frontend Development

**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob, @charlie

## Context

Our React codebase has grown to 50+ components with increasing bug reports
related to prop type mismatches and undefined errors. PropTypes provide
runtime-only checking.

## Decision

Adopt TypeScript for all new frontend code. Migrate existing code incrementally.

## Consequences

**Good**: Catch type errors at compile time, better IDE support, self-documenting
code.

**Bad**: Learning curve for team, initial slowdown, build complexity increase.

**Mitigations**: TypeScript training sessions, allow gradual adoption with
`allowJs: true`.
```

### Template 3: Y-Statement Format

```markdown
# ADR-0015: API Gateway Selection

In the context of **building a microservices architecture**,
facing **the need for centralized API management, authentication, and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx solution**,
to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
accepting that **we need to manage Kong infrastructure ourselves**.
```

### Template 4: ADR for Deprecation

```markdown
# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL

## Status

Accepted (Supersedes ADR-0003)

## Context

ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
needs. Since then:
- MongoDB's multi-document transactions remain problematic for our use case
- Our schema has stabilized and rarely changes
- We now have PostgreSQL expertise from other services
- Maintaining two databases increases operational burden

## Decision

Deprecate MongoDB and migrate user profiles to PostgreSQL.

## Migration Plan

1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
4. **Phase 4** (Week 6): Remove MongoDB writes, decommission

## Consequences

### Positive
- Single database technology reduces operational complexity
- ACID transactions for user data
- Team can focus PostgreSQL expertise

### Negative
- Migration effort (~4 weeks)
- Risk of data issues during migration
- Lose some schema flexibility

## Lessons Learned

Document from ADR-0003 experience:
- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimated
- Consider long-term maintenance in technology decisions
```

### Template 5: Request for Comments (RFC) Style

```markdown
# RFC-0025: Adopt Event Sourcing for Order Management

## Summary

Propose adopting event sourcing pattern for the order management domain to
improve auditability, enable temporal queries, and support business analytics.

## Motivation

Current challenges:
1. Audit requirements need complete order history
2. "What was the order state at time X?" queries are impossible
3. Analytics team needs event stream for real-time dashboards
4. Order state reconstruction for customer support is manual

## Detailed Design

### Event Store

```
OrderCreated { orderId, customerId, items[], timestamp }
OrderItemAdded { orderId, item, timestamp }
OrderItemRemoved { orderId, itemId, timestamp }
PaymentReceived { orderId, amount, paymentId, timestamp }
OrderShipped { orderId, trackingNumber, timestamp }
```

### Projections

- **CurrentOrderState**: Materialized view for queries
- **OrderHistory**: Complete timeline for audit
- **DailyOrderMetrics**: Analytics aggregation

### Technology

- Event Store: EventStoreDB (purpose-built, handles projections)
- Alternative considered: Kafka + custom projection service

## Drawbacks

- Learning curve for team
- Increased complexity vs. CRUD
- Need to design events carefully (immutable once stored)
- Storage growth (events never deleted)

## Alternatives

1. **Audit tables**: Simpler but doesn't enable temporal queries
2. **CDC from existing DB**: Complex, doesn't change data model
3. **Hybrid**: Event source only for order state changes

## Unresolved Questions

- [ ] Event schema versioning strategy
- [ ] Retention policy for events
- [ ] Snapshot frequency for performance

## Implementation Plan

1. Prototype with single order type (2 weeks)
2. Team training on event sourcing (1 week)
3. Full implementation and migration (4 weeks)
4. Monitoring and optimization (ongoing)

## References

- [Event Sourcing by Martin Fowler](https://martinfowler.com/eaaDev/EventSourcing.html)
- [EventStoreDB Documentation](https://www.eventstore.com/docs)
```

## ADR Management

### Directory Structure

```
docs/
├── adr/
│   ├── README.md           # Index and guidelines
│   ├── template.md         # Team's ADR template
│   ├── 0001-use-postgresql.md
│   ├── 0002-caching-strategy.md
│   ├── 0003-mongodb-user-profiles.md  # [DEPRECATED]
│   └── 0020-deprecate-mongodb.md      # Supersedes 0003
```

### ADR Index (README.md)

```markdown
# Architecture Decision Records

This directory contains Architecture Decision Records (ADRs) for [Project Name].

## Index

| ADR | Title | Status | Date |
|-----|-------|--------|------|
| 0001 | Use PostgreSQL as Primary Database | Accepted | 2024-01-10 |
| 0002 | Caching Strategy with Redis | Accepted | 2024-01-12 |
| 0003 | MongoDB for User Profiles | Deprecated | 2023-06-15 |
| 0020 | Deprecate MongoDB | Accepted | 2024-01-15 |

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in the template
3. Submit PR for review
4. Update this index after approval

## ADR Status

- **Proposed**: Under discussion
- **Accepted**: Decision made, implementing
- **Deprecated**: No longer relevant
- **Superseded**: Replaced by another ADR
- **Rejected**: Considered but not adopted
```

### Automation (adr-tools)

```bash
# Install adr-tools
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR
adr new "Use PostgreSQL as Primary Database"

# Supersede an ADR
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"

# Generate table of contents
adr generate toc > docs/adr/README.md

# Link related ADRs
adr link 2 "Complements" 1 "Is complemented by"
```

## Review Process

```markdown
## ADR Review Checklist

### Before Submission
- [ ] Context clearly explains the problem
- [ ] All viable options considered
- [ ] Pros/cons balanced and honest
- [ ] Consequences (positive and negative) documented
- [ ] Related ADRs linked

### During Review
- [ ] At least 2 senior engineers reviewed
- [ ] Affected teams consulted
- [ ] Security implications considered
- [ ] Cost implications documented
- [ ] Reversibility assessed

### After Acceptance
- [ ] ADR index updated
- [ ] Team notified
- [ ] Implementation tickets created
- [ ] Related documentation updated
```

## Best Practices

### Do's
- **Write ADRs early** - Before implementation starts
- **Keep them short** - 1-2 pages maximum
- **Be honest about trade-offs** - Include real cons
- **Link related decisions** - Build decision graph
- **Update status** - Deprecate when superseded

### Don'ts
- **Don't change accepted ADRs** - Write new ones to supersede
- **Don't skip context** - Future readers need background
- **Don't hide failures** - Rejected decisions are valuable
- **Don't be vague** - Specific decisions, specific consequences
- **Don't forget implementation** - ADR without action is waste

## Resources

- [Documenting Architecture Decisions (Michael Nygard)](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions)
- [MADR Template](https://adr.github.io/madr/)
- [ADR GitHub Organization](https://adr.github.io/)
- [adr-tools](https://github.com/npryce/adr-tools)

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: architecture-patterns
description: "Master proven backend architecture patterns including Clean Architecture, Hexagonal Architecture, and Domain-Driven Design to build maintainable, testable, and scalable systems."
risk: none
source: community
date_added: "2026-02-27"
---

# 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.
5. For workflows that must survive failures (payments, order fulfillment, multi-step processes), use durable execution at the infrastructure layer — frameworks like DBOS persist workflow state, providing crash recovery without adding architectural complexity.

Refer to `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

## Related Skills

Works well with: `event-sourcing-architect`, `saga-orchestration`, `workflow-automation`, `dbos-*`

## Resources

- `resources/implementation-playbook.md` for detailed patterns, checklists, and templates.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: aria
description: "Designs the data model, API contracts, and structural foundation of the system."
risk: safe
source: community
date_added: "2026-06-11"
role: System Architect
phase: 3 — Architecture
squad: agent-squad
reports-to: agent-squad
depends-on: rex, alex
---

# Aria — The Architect

Aria designs the structural foundation of the system. She works from Rex's requirements and Alex's implementation plan to produce the definitive data model, API contract, file structure, and design pattern decisions. Her output is the blueprint Mason builds from — nothing gets coded without Aria's architecture signed off first.

Aria is opinionated but not dogmatic. She selects patterns because they fit the problem, not because they're fashionable. She names every decision and its rationale so future agents (and humans) understand why the system is shaped the way it is.

---

## When to Use
- Use this skill when the task matches this description: Designs the data model, API contracts, and structural foundation of the system.

## Responsibilities

### 1. Data Modeling
- Design the **entity model**: all tables/collections, fields, types, and relationships.
- Define **primary keys**, foreign keys, indexes, and constraints explicitly.
- Specify **nullable vs. required** fields, default values, and enum types.
- Design for **data integrity at the schema level** — don't rely on application code to enforce what the DB can.
- Note **migration strategy** if the project has an existing schema.
- Flag **N+1 risks**, hot-row contention, and fields that will need full-text or geo indexing.

### 2. API Contract Design
- Define every **endpoint**: method, path, request shape, response shape, status codes.
- Use consistent **naming conventions** (RESTful resource names or GraphQL type names).
- Define **authentication & authorization** per endpoint (public, user-scoped, admin-only).
- Specify **pagination strategy** (cursor vs. offset), **filtering**, and **sorting** params.
- Document **error response envelope**: shape must be consistent across all endpoints.
- For event-driven systems: define **event names**, payloads, and producers/consumers.

### 3. File & Module Structure
- Produce a **directory tree** for the project.
- Assign **responsibilities to each module/file** — one sentence per file describing its job.
- Define **import rules**: which layers can import from which (e.g. UI cannot import from DB layer directly).
- Specify **config and environment variable** names and where they live.
- Flag files that are **security-sensitive** and must not be committed.

### 4. Design Pattern Selection
- Select the **architectural pattern** for the backend (MVC, layered, hexagonal, event-driven, etc.) and justify.
- Select the **state management pattern** for the frontend if applicable (flux, context, signals, etc.).
- Define **error handling strategy**: how errors propagate from DB → service → API → client.
- Define **logging & observability** hooks: what gets logged, at what level, in what format.
- Define **caching strategy** if relevant: what's cached, TTL, invalidation triggers.

### 5. Security Architecture
- Define **authentication mechanism** (JWT, session, OAuth, API key) and token lifecycle.
- Specify **authorization model** (RBAC, ABAC, ownership-based).
- List **input validation boundaries**: where validation happens, what library handles it.
- Flag all **OWASP Top 10** surfaces relevant to this system and how each is mitigated.

---

## Output Format (Structured Report to Main Agent)

```
ARIA BLUEPRINT — v1.0
Project: [name]
Input: Rex Report v[x], Alex Plan v[x]

## Architecture Decision Record (ADR Summary)
- Pattern: [chosen pattern] — Reason: [one sentence]
- DB: [engine] — Reason: [one sentence]
- Auth: [mechanism] — Reason: [one sentence]

## Data Model
Entity: [Name]
  Fields:
    - id: uuid, PK, auto-generated
    - [field]: [type], [nullable/required], [constraints]
  Indexes: [field(s)]
  Relations: [entity] via [FK/join table]

## API Contract
[METHOD] /[path]
  Auth: [none / bearer / admin]
  Request: { field: type, ... }
  Response 200: { field: type, ... }
  Response 4xx: { error: string, code: string }

## File Structure
/src
  /models       — DB entity definitions
  /services     — Business logic, no HTTP knowledge
  /controllers  — HTTP handlers, no business logic
  /routes       — Route registration
  /middleware   — Auth, validation, error handling
  /utils        — Pure helper functions
  /config       — Env var loading and validation

## Security Notes
- [OWASP surface]: [mitigation]

## Notes for Mason (Implementation)
- [specific build ordering or gotcha]

## Notes for Luna (Code Review)
- [what to watch for in this codebase]

## Open Questions
- [question] — blocking: yes/no
```

---

## Handoff Protocol

When handing off to **Mason (Implementation)**:
- Pass the ARIA BLUEPRINT + Alex Plan reference (version number).
- Include "Notes for Mason" explicitly.
- Do NOT write any implementation code — that's Mason's domain.

When handing off to **Luna (Code Review)**:
- Pass the "Notes for Luna" section to prime her review criteria.

When Aria is re-invoked (new feature or schema change):
- Outputs an **ARIA BLUEPRINT AMENDMENT** with a migration note if DB schema changed.
- Does NOT rewrite the full blueprint — appends only changed sections.

---

## Interaction Style

- Precise and structural. Thinks in shapes and contracts.
- Challenges any vagueness in Alex's plan that would produce an ambiguous schema.
- Never over-engineers. If a single table works, she won't design microservices.
- States tradeoffs explicitly when two valid patterns exist — never flips a coin silently.
- Uses concrete field names and real types — never placeholder schemas.

## Limitations
- AI agents may occasionally hallucinate or provide incorrect guidance. Always verify generated code and architectural designs before pushing to production.
- Context window constraints mean large project histories must be compressed by the Orchestrator.


---
name: arm-cortex-expert
description: Senior embedded software engineer specializing in firmware and driver development for ARM Cortex-M microcontrollers (Teensy, STM32, nRF52, SAMD).
risk: critical
source: community
date_added: '2026-02-27'
---

# @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`

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: arrowspace
description: "Spectral vector search using graph Laplacian eigenstructure. Use when cosine/L2 similarity misses latent structure in your embeddings."
category: data
risk: safe
source: community
source_repo: Genefold/arrowspace-skills
source_type: community
date_added: "2026-06-25"
author: Genefold AI
license: Apache-2.0
license_source: "https://github.com/Genefold/arrowspace-skills/blob/main/LICENSE"
tags: [vector-search, spectral-analysis, graph-laplacian, embeddings, lambda-tau]
tools: [claude, cursor, codex, gemini, opencode]
---

# ArrowSpace

Spectral vector search that augments nearest-neighbour search with graph Laplacian features. Computes a Laplacian over the item graph and uses the Rayleigh quotient to produce a λτ (lambda-tau) score per item, enabling search that respects both semantic similarity and structural role.

## When to Use This Skill

- Cosine or L2 similarity misses latent structure in your embeddings
- You want graph-based retrieval with spectral awareness
- You need to characterise the spectral properties of an embedding space
- You are building RAG pipelines where contextual role matters alongside semantic content

## How It Works

### Step 1: Install and import

```bash
pip install arrowspace
```

```python
from arrowspace import ArrowSpaceBuilder
import numpy as np
```

### Step 2: Prepare your data

Pass an (N, d) float64 NumPy array of embedding vectors:

```python
items = np.array([[0.1, 0.2, 0.3],
                  [0.0, 0.5, 0.1],
                  [0.9, 0.1, 0.0]], dtype=np.float64)
```

### Step 3: Configure graph parameters

```python
graph_params = {"eps": 0.2, "k": 6, "topk": 3, "p": 2.0, "sigma": 1.0}
builder = ArrowSpaceBuilder(items, graph_params=graph_params)
aspace = builder.build()
```

### Step 4: Query

```python
lambdas = aspace.lambdas()           # array indexed by insertion order
sorted_res = aspace.lambdas_sorted()  # (score, index) pairs ascending
```

Higher λτ values indicate items that are both semantically close and structurally central.

## Examples

### Example 1: Basic spectral retrieval

```python
items = np.random.randn(100, 64).astype(np.float64)
builder = ArrowSpaceBuilder(items, graph_params={"eps": 0.5, "k": 10, "topk": 5, "p": 2.0, "sigma": None})
aspace = builder.build()
scores = aspace.lambdas()
top_indices = np.argsort(scores)[-5:]
```

### Example 2: Compare spectral vs cosine ranking

```python
from sklearn.metrics.pairwise import cosine_similarity
cos_sim = cosine_similarity(items)
cosine_order = np.argsort(cos_sim[0])[::-1]
spectral_order = np.argsort(aspace.lambdas())[::-1]
```

## Best Practices

- ✅ Normalise embeddings to unit norm before passing to ArrowSpace
- ✅ Start with eps proportional to 1/sqrt(dim) and tune from there
- ✅ Use k between 3 and 25 depending on dataset size (rule: N/50)
- ✅ Set sigma=None to auto-select kernel width from distance distribution
- ❌ Don't use with fewer than 10 items (graph structure is not meaningful)
- ❌ Don't use for real-time streaming data (ArrowSpace is batch-oriented)

## Limitations

- This skill does not replace environment-specific validation, testing, or expert review.
- ArrowSpace is batch-oriented and not designed for real-time indexing of streaming data.

## Common Pitfalls

- **Problem:** eps is too small, producing a disconnected graph
  **Solution:** Increase eps, or set it proportional to 1/sqrt(embedding_dim)

- **Problem:** k is too large, producing a dense graph with washed-out spectral features
  **Solution:** Keep k ≤ 25 for most datasets

## Related Skills

- `vector-database-engineer` — General vector database expertise
- `embedding-strategies` — Embedding model selection and chunking
- `similarity-search-patterns` — Semantic search implementation patterns
- `hybrid-search-implementation` — Combined semantic + keyword search


---
name: article-illustrations
description: "Generate hand-drawn 16:9 article illustrations with the Grav character IP, sparse annotations, and absurd but clear visual metaphors."
category: creative
risk: safe
source: community
source_repo: vipin-si/article-illustrations
source_type: community
license: MIT
license_source: https://github.com/vipin-si/article-illustrations/blob/main/LICENSE
date_added: "2026-06-06"
author: vipin-si
tags: [illustration, article-graphics, visual-metaphors, image-generation, whiteboard-sketch]
tools: [image-generation]
---

# Article Illustrations — Grav Hand-Drawn Style

## Overview

Generate 16:9 landscape hand-drawn illustrations for articles, blog posts, and technical content. Each illustration captures one cognitive anchor point from an article and turns it into a clean, absurd, memorable whiteboard-sketch explanation.

The skill uses a recurring character IP called **Grav**: a small, round, always-floating figure with dot eyes and a thin antenna. Grav participates in the core action of every illustration — never just decoration.

**Repository:** [vipin-si/article-illustrations](https://github.com/vipin-si/article-illustrations)

## When to Use This Skill

- Use when writing articles, blog posts, or documentation that need inline illustrations
- Use when you want to turn abstract concepts into concrete visual metaphors
- Use when you want a consistent visual language across multiple articles
- Use when you need hand-drawn explanation sketches, not PPT infographics

## How It Works

### Step 1: Digest the Article

Read the article and identify cognitive anchor points — core judgments, turning points, input/output loops, before/after contrasts, and common pitfalls. Don't distribute illustrations evenly; prioritize moments that benefit from visual explanation.

### Step 2: Plan a Shot List

For each illustration, define:
- **Placement**: After which section
- **Theme**: What this image is about
- **Core Meaning**: The one idea it conveys
- **Structure Type**: One of 8 composition patterns (Workflow, System Closeup, Before/After, Role States, Conceptual Metaphor, Layered Method, Map Route, Mini Comic)
- **Grav's Action**: What Grav is doing in the scene
- **Annotation Labels**: 3–5 short English labels

### Step 3: Generate Images

Use the `generate_image` tool with the built-in prompt template. Each image follows strict style rules:
- Pure white background, no textures
- Black hand-drawn line art with slight wobble
- Sparse red/orange/blue handwritten annotations
- Grav always floating (never touching surfaces)
- One core idea per image
- 40–60% canvas usage, 35%+ whitespace

### Step 4: QA Check

Verify each image against the QA checklist: correct format, Grav present and active, original metaphor, clean composition, sparse annotations, correct color usage.

## Examples

### Example 1: Plan illustrations for an article

```
Analyze this article and create a shot list of 5 illustrations.
Don't generate images yet — just plan which cognitive anchor points
deserve illustrations and what each image should convey.

<paste article>
```

### Example 2: Generate illustrations directly

```
Generate 4 Grav-style illustrations for this article.
Requirements: 16:9 landscape, pure white background, black hand-drawn
line art, sparse red/orange/blue English annotations.

<paste article>
```

### Example 3: Single concept illustration

```
Generate one 16:9 illustration for this concept:
"Trust isn't declared — it's built one piece of evidence at a time."
Grav must perform the core action. Maximum 5 annotation labels.
```

### Example 4: Iterate on a result

```
This illustration is on the right track, but Grav feels like decoration.
Keep the core meaning but regenerate: make Grav the one actually
driving the structure.
```

## Visual Style

| Element | Rule |
|:--------|:-----|
| Background | Pure white — no cream, texture, gradients, or shadows |
| Line art | Black, hand-drawn, slightly wobbly, not mechanical |
| Whitespace | Main subject 40–60% of canvas, 35%+ empty space |
| Annotations | Handwritten English, 2–5 words each, max 5–8 per image |
| Color: Black | Main line art, characters, structures, objects |
| Color: Red | Key highlights, problems, warnings, results |
| Color: Orange | Main flow, paths, arrows, direction |
| Color: Blue | Supplementary notes, feedback, system state |
| Prohibited | Green, purple, yellow, pink, gradients, drop shadows, 3D, realistic UI |

## Character: Grav

- Small round body (pebble/potato shape)
- Two dot eyes (slightly asymmetric)
- One thin bent antenna with tiny circle tip
- Thin stick legs that dangle without touching surfaces
- Always hovering — visible gap between Grav and any surface
- Expression: calm, focused, deadpan
- Role: active participant in the system, never decoration

## Best Practices

- ✅ Start with a shot list before generating images
- ✅ Invent a new metaphor for every illustration — never reuse compositions
- ✅ Make Grav the action protagonist, not a bystander
- ✅ Keep it absurd but structurally clear
- ✅ Use color sparingly — when in doubt, use black
- ❌ Don't make PPT infographics or formal flowcharts
- ❌ Don't add title bars or decorative frames
- ❌ Don't let Grav touch the ground or stand on surfaces
- ❌ Don't make Grav cute, smiling, or emoji-like

## Limitations

- Requires access to an image-generation tool that can follow composition, line-art, and annotation constraints.
- The recurring Grav character style can drift between generations; verify every output against the QA checklist.
- Text in generated images may be misspelled or distorted, so short labels and post-generation review are required.
- The style is intended for explanatory article illustrations, not photorealistic product imagery or brand-final artwork.

## Common Pitfalls

- **Problem:** Illustration looks like a PPT slide
  **Solution:** Remove 30% of elements, increase whitespace, make it weirder

- **Problem:** Grav is just standing next to the action
  **Solution:** Redesign so Grav IS the mechanism — becomes the funnel, dangles from the lever, is suspended inside the machine

- **Problem:** Same metaphor as a previous illustration
  **Solution:** Replace the physical object entirely — same concept, different analogy

## Additional Resources

- [Full skill with prompt templates and QA checklist](https://github.com/vipin-si/article-illustrations)
- [Example illustrations](https://github.com/vipin-si/article-illustrations#examples)


---
name: asana-automation
description: "Automate Asana tasks via Rube MCP (Composio): tasks, projects, sections, teams, workspaces. Always search tools first for current schemas."
risk: critical
source: community
date_added: "2026-02-27"
---

# Asana Automation via Rube MCP

Automate Asana operations through Composio's Asana toolkit via Rube MCP.

## Prerequisites

- Rube MCP must be connected (RUBE_SEARCH_TOOLS available)
- Active Asana connection via `RUBE_MANAGE_CONNECTIONS` with toolkit `asana`
- Always call `RUBE_SEARCH_TOOLS` first to get current tool schemas

## Setup

**Get Rube MCP**: Add `https://rube.app/mcp` as an MCP server in your client configuration. No API keys needed — just add the endpoint and it works.

1. Verify Rube MCP is available by confirming `RUBE_SEARCH_TOOLS` responds
2. Call `RUBE_MANAGE_CONNECTIONS` with toolkit `asana`
3. If connection is not ACTIVE, follow the returned auth link to complete Asana OAuth
4. Confirm connection status shows ACTIVE before running any workflows

## Core Workflows

### 1. Manage Tasks

**When to use**: User wants to create, search, list, or organize tasks

**Tool sequence**:
1. `ASANA_GET_MULTIPLE_WORKSPACES` - Get workspace ID [Prerequisite]
2. `ASANA_SEARCH_TASKS_IN_WORKSPACE` - Search tasks [Optional]
3. `ASANA_GET_TASKS_FROM_A_PROJECT` - List project tasks [Optional]
4. `ASANA_CREATE_A_TASK` - Create a new task [Optional]
5. `ASANA_GET_A_TASK` - Get task details [Optional]
6. `ASANA_CREATE_SUBTASK` - Create a subtask [Optional]
7. `ASANA_GET_TASK_SUBTASKS` - List subtasks [Optional]

**Key parameters**:
- `workspace`: Workspace GID (required for search/creation)
- `projects`: Array of project GIDs to add task to
- `name`: Task name
- `notes`: Task description
- `assignee`: Assignee (user GID or email)
- `due_on`: Due date (YYYY-MM-DD)

**Pitfalls**:
- Workspace GID is required for most operations; get it first
- Task GIDs are returned as strings, not integers
- Search is workspace-scoped, not project-scoped

### 2. Manage Projects and Sections

**When to use**: User wants to create projects, manage sections, or organize tasks

**Tool sequence**:
1. `ASANA_GET_WORKSPACE_PROJECTS` - List workspace projects [Optional]
2. `ASANA_GET_A_PROJECT` - Get project details [Optional]
3. `ASANA_CREATE_A_PROJECT` - Create a new project [Optional]
4. `ASANA_GET_SECTIONS_IN_PROJECT` - List sections [Optional]
5. `ASANA_CREATE_SECTION_IN_PROJECT` - Create a new section [Optional]
6. `ASANA_ADD_TASK_TO_SECTION` - Move task to section [Optional]
7. `ASANA_GET_TASKS_FROM_A_SECTION` - List tasks in section [Optional]

**Key parameters**:
- `project_gid`: Project GID
- `name`: Project or section name
- `workspace`: Workspace GID for creation
- `task`: Task GID for section assignment
- `section`: Section GID

**Pitfalls**:
- Projects belong to workspaces; workspace GID is needed for creation
- Sections are ordered within a project
- DUPLICATE_PROJECT creates a copy with optional task inclusion

### 3. Manage Teams and Users

**When to use**: User wants to list teams, team members, or workspace users

**Tool sequence**:
1. `ASANA_GET_TEAMS_IN_WORKSPACE` - List workspace teams [Optional]
2. `ASANA_GET_USERS_FOR_TEAM` - List team members [Optional]
3. `ASANA_GET_USERS_FOR_WORKSPACE` - List all workspace users [Optional]
4. `ASANA_GET_CURRENT_USER` - Get authenticated user [Optional]
5. `ASANA_GET_MULTIPLE_USERS` - Get multiple user details [Optional]

**Key parameters**:
- `workspace_gid`: Workspace GID
- `team_gid`: Team GID

**Pitfalls**:
- Users are workspace-scoped
- Team membership requires the team GID

### 4. Parallel Operations

**When to use**: User needs to perform bulk operations efficiently

**Tool sequence**:
1. `ASANA_SUBMIT_PARALLEL_REQUESTS` - Execute multiple API calls in parallel [Required]

**Key parameters**:
- `actions`: Array of action objects with method, path, and data

**Pitfalls**:
- Each action must be a valid Asana API call
- Failed individual requests do not roll back successful ones

## Common Patterns

### ID Resolution

**Workspace name -> GID**:
```
1. Call ASANA_GET_MULTIPLE_WORKSPACES
2. Find workspace by name
3. Extract gid field
```

**Project name -> GID**:
```
1. Call ASANA_GET_WORKSPACE_PROJECTS with workspace GID
2. Find project by name
3. Extract gid field
```

### Pagination

- Asana uses cursor-based pagination with `offset` parameter
- Check for `next_page` in response
- Pass `offset` from `next_page.offset` for next request

## Known Pitfalls

**GID Format**:
- All Asana IDs are strings (GIDs), not integers
- GIDs are globally unique identifiers

**Workspace Scoping**:
- Most operations require a workspace context
- Tasks, projects, and users are workspace-scoped

## Quick Reference

| Task | Tool Slug | Key Params |
|------|-----------|------------|
| List workspaces | ASANA_GET_MULTIPLE_WORKSPACES | (none) |
| Search tasks | ASANA_SEARCH_TASKS_IN_WORKSPACE | workspace, text |
| Create task | ASANA_CREATE_A_TASK | workspace, name, projects |
| Get task | ASANA_GET_A_TASK | task_gid |
| Create subtask | ASANA_CREATE_SUBTASK | parent, name |
| List subtasks | ASANA_GET_TASK_SUBTASKS | task_gid |
| Project tasks | ASANA_GET_TASKS_FROM_A_PROJECT | project_gid |
| List projects | ASANA_GET_WORKSPACE_PROJECTS | workspace |
| Create project | ASANA_CREATE_A_PROJECT | workspace, name |
| Get project | ASANA_GET_A_PROJECT | project_gid |
| Duplicate project | ASANA_DUPLICATE_PROJECT | project_gid |
| List sections | ASANA_GET_SECTIONS_IN_PROJECT | project_gid |
| Create section | ASANA_CREATE_SECTION_IN_PROJECT | project_gid, name |
| Add to section | ASANA_ADD_TASK_TO_SECTION | section, task |
| Section tasks | ASANA_GET_TASKS_FROM_A_SECTION | section_gid |
| List teams | ASANA_GET_TEAMS_IN_WORKSPACE | workspace_gid |
| Team members | ASANA_GET_USERS_FOR_TEAM | team_gid |
| Workspace users | ASANA_GET_USERS_FOR_WORKSPACE | workspace_gid |
| Current user | ASANA_GET_CURRENT_USER | (none) |
| Parallel requests | ASANA_SUBMIT_PARALLEL_REQUESTS | actions |

## When to Use
This skill is applicable to execute the workflow or actions described in the overview.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: ask-copilot
description: "Use GitHub Copilot CLI in non-interactive mode to ask questions, review code, or generate snippets without manual interaction."
category: development
risk: critical
source: self
source_repo: cshara1/antigravity-awesome-skills
source_type: self
date_added: "2026-07-08"
author: cshara1
tags: [copilot, github, cli, review, prompt]
tools: [claude, cursor, gemini]
---

# Ask Copilot

## Overview

This skill allows the agent to interact with GitHub Copilot CLI (`copilot`) in a non-interactive (headless) mode. Use this skill when the user explicitly wants secondary advice, code reviews, explanations, or code generation from GitHub Copilot's models.

Use `source: self` and `source_type: self` when the skill is original to this repository and does not require README external-source credit.

Copilot is an external service. Treat prompts, file paths, snippets, repository content, command output, and generated suggestions as data that may leave the local environment.

## When to Use This Skill

- **User Request Only**: Use this skill **ONLY** when the user explicitly asks to "consult Copilot", "ask Copilot", "review with Copilot", or explicitly requests a second opinion using Copilot.
- **Do NOT Invoke Automatically**: To comply with privacy policies, the agent must not invoke this skill automatically for its own second opinions or checks without explicit user consent.

## How It Works

### Step 1: Request Explicit User Consent

Before executing any command that references local files, repository paths, snippets, command output, secrets-adjacent config, or private project context, you **MUST** obtain explicit user consent to send that material to GitHub Copilot.

Ask for separate approval before allowing Copilot to run tools, execute shell commands, edit files, install packages, or mutate the workspace.

### Step 2: Execute with Minimal Permitted Flags

To prevent TUI lockups, execute the `copilot` command with headless flags. Do not use blanket bypasses such as `--yolo`, `--allow-all-tools`, or `--allow-all-paths` for routine Q&A or review.

- **For Read-Only / General Q&A**: Send only the user-approved, redacted text in the prompt. Do not grant Copilot broad local-path access; it is not needed when the prompt already contains the approved context.
- **For Trusted Mutation Tasks**: Prefer a scoped permission flag if the CLI supports one. Use blanket mutation bypasses only after the user explicitly authorizes Copilot to execute tools and mutate the workspace for the specific task.

### Step 3: Use Session Management (Optional)

To maintain conversation context, use `--name` and `--resume` flags, or pass a `--session-id` on subsequent calls.

## Examples

### Example 1: General Question (Read-Only)

Does not require repository path access or mutation permissions.
```bash
copilot -p "Explain how to implement a debounce function in TypeScript" -s
```

### Example 2: Code Review (Approved File Excerpt)

Always confirm the exact file and excerpt with the user before executing. Keep the path in a
quoted variable; build the prompt from a static instruction plus the approved excerpt. Shell
does not re-evaluate command-substitution output, so metacharacters inside the reviewed file
remain prompt text rather than shell syntax:
```bash
review_file="path/to/file.ts"
test -f "$review_file" || { echo "File not found: $review_file" >&2; exit 1; }
copilot -p "$(printf '%s\n\n' 'Review this approved excerpt for potential memory leaks:'; sed -n '1,220p' -- "$review_file")" -s
```

Never construct a shell command by interpolating user-controlled prompt text, paths, issue
content, or filenames into shell source. Use fixed command structure, quoted variables, and
approved file content only.

### Example 3: Named Session Management

```bash
copilot -p "Remember this session label for follow-up questions." -s --name "my-session-name"
copilot -p "Summarize the prior advice in this session." -s --resume "my-session-name"
```

## Best Practices

- ✅ **Do:** Ask for user consent before uploading any project files to third-party endpoints.
- ✅ **Do:** Send only the approved, redacted excerpt; keep Copilot out of the broader workspace.
- ✅ **Do:** Keep untrusted values in quoted variables or command input, never in shell source.
- ✅ **Do:** Use `-s` (silent) to suppress metadata and statistics, leaving only clean output.
- ❌ **Don't:** Automatically trigger this skill for background second opinions without the user's explicit ask.
- ❌ **Don't:** Send files, logs, environment details, or private repository context to Copilot without explicit approval.
- ❌ **Don't:** use `--allow-all-paths` for a review, or interpolate untrusted text inside `copilot -p "..."`.
- ❌ **Don't:** Run `copilot` without permission-bypass flags in background tasks, as it will hang waiting for interactive input.

## Limitations

- This skill does not replace environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, or safety boundaries are missing.
- Copilot responses may be incomplete, outdated, or wrong; verify any proposed code locally before using it.

## Security & Safety Notes

- The `--yolo` flag bypasses all permission prompts and allows Copilot CLI to run arbitrary shell commands and mutate workspace files. It must be treated as a high-risk option and never used by default.
- Always check that the code/files being sent do not contain sensitive credentials, API keys, or private environment variables.
- Prefer redacted snippets over whole files when only a small context sample is needed.
- `--allow-all-paths` grants Copilot broader local visibility than a narrow review requires; it is not a read-only least-privilege flag.

## Common Pitfalls

- **Problem:** The terminal hangs or the command times out.
  **Solution:** Ensure both `-p` (or `--prompt`) and the narrowest required non-interactive permission flag are present in the command arguments. Without required permission flags, the CLI may prompt for confirmation and hang headless processes.

## Related Skills

- `@cli-assistant` - How to interact with CLI tools in general.


---
name: ask-matt
description: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.
disable-model-invocation: true
category: "productivity"
risk: "safe"
source: "community"
source_repo: "mattpocock/skills"
source_type: "community"
date_added: "2026-06-19"
author: "Matt Pocock"
license: "MIT"
license_source: "https://github.com/mattpocock/skills/blob/main/LICENSE"
tags:
  - productivity
  - workflow
  - coding-agents
tools:
  - claude-code
  - codex-cli
  - cursor
---

# Ask Matt

## When to Use

Use when this workflow matches the user request: Ask which skill or flow fits your situation. A router over the user-invoked skills in this repo.

_Source: [mattpocock/skills](https://github.com/mattpocock/skills) (MIT)._

You don't remember every skill, so ask.

A **flow** is a path through the skills. Most paths run along one **main flow**, and two **on-ramps** merge onto it. Everything else is standalone.

## The main flow: idea → ship

The route most work travels. You have an idea and want it built.

1. **`/grill-with-docs`** — sharpen the idea by interview. Start here when you **have a codebase**: it's stateful, retaining what it learns in `CONTEXT.md` and ADRs. (No codebase? Use `/grill-me` — see Standalone.)
2. **Branch — can you settle every question in conversation?** If a question needs a runnable answer (state, business logic, a UI you have to see), detour through a prototype, bridged by **`/handoff`** in both directions (see Crossing sessions):
   - **`/handoff`** out, then open a fresh session against that file,
   - **`/prototype`** to answer the question with throwaway code,
   - **`/handoff`** back what you learned, and reference it from the original idea thread.
3. **Branch — is this a multi-session build?**
   - **Yes** → **`/to-prd`** (turn the thread into a PRD) → **`/to-issues`** (split the PRD into independently-grabbable issues). Because the issues are independent, **clear context between each one**: start a fresh session per issue and kick off **`/implement`** by passing it the PRD and the single issue to work on.
   - **No** → **`/implement`** right here, in the same context window.

### Context hygiene

Keep steps 1–3 in **one unbroken context window** — don't compact or clear until after `/to-issues` — so the grilling, PRD, and issues all build on the same thinking. Each `/implement` then starts fresh, working from the issue.

The limit on this is the **[smart zone](https://www.aihero.dev/ai-coding-dictionary/smart-zone)**: the window (~120k tokens on state-of-the-art models) within which the model still reasons sharply. If a session approaches it before `/to-issues`, don't push on degraded — `/handoff` and continue in a fresh thread.

## On-ramps

A starting situation that generates work, then merges onto the main flow.

- **Bugs and requests piling up** → **`/triage`**. It moves issues through triage roles and produces agent-ready issues, which **`/implement`** later picks up.

  Triage is only for issues **you didn't create** — bug reports, incoming feature requests, anything that arrives raw. Issues that `/to-issues` produced are already agent-ready, so **don't triage them**.

## Codebase health

Not feature work — upkeep.

- **`/improve-codebase-architecture`** — run whenever you have a spare moment to keep the codebase good for agents to operate in. It surfaces deepening opportunities; picking one _generates an idea_ you can take into the main flow at `/grill-with-docs`.

## Crossing sessions

- **`/handoff`** — when a thread is full or you need to branch off (e.g. into a `/prototype` session), this compacts the conversation into a markdown file. You don't continue in place — you **open a new session and reference that file** to carry the context across. It's the bridge between context windows, in either direction. Use it when you want a **fresh session** but need the **current conversation preserved**.
- **`/compact`** (built-in) — stay in the **same conversation**, letting the earlier turns be summarized. Use it at **intentional breaks between phases**, when you don't mind losing the verbatim history. Don't compact mid-phase — the agent can lose its way. `/handoff` forks; `/compact` continues.

## Standalone

Off the main flow entirely.

- **`/grill-me`** — the same relentless interview as `/grill-with-docs`, but for when you have **no codebase**. Stateless: it saves nothing locally, builds no `CONTEXT.md`. Reach for it to sharpen any plan or design that doesn't live in a repo.
- **`/teach`** — learn a concept over multiple sessions, using the current directory as a stateful workspace.
- **`/writing-great-skills`** — reference for writing and editing skills well.

## Precondition

**`/setup-matt-pocock-skills`** — run before your first engineering flow to configure the issue tracker, triage labels, and doc layout the other skills assume. Custom issue trackers also work.

## Limitations

- Requires the upstream tool, account, API key, or local setup when the workflow names one.
- Does not authorize destructive, production, paid, or external-message actions without explicit user approval.
- Validate generated artifacts or recommendations against the user's real sources before treating them as final.


---
name: ask-questions-if-underspecified
description: Clarify requirements before implementing. Use when serious doubts arise.
risk: safe
source: community
---

# Ask Questions If Underspecified

## When to Use
Use this skill when a request has multiple plausible interpretations or key details (objective, scope, constraints, environment, or safety) are unclear.

## When NOT to Use

Do not use this skill when the request is already clear, or when a quick, low-risk discovery read can answer the missing details.

## 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.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: astro
description: "Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support."
category: frontend
risk: safe
source: community
date_added: "2026-03-18"
author: suhaibjanjua
tags: [astro, ssg, ssr, islands, content, markdown, mdx, performance]
tools: [claude, cursor, gemini]
---

# Astro Web Framework

## Overview

Astro is a web framework designed for content-rich websites — blogs, docs, portfolios, marketing sites, and e-commerce. Its core innovation is the **Islands Architecture**: by default, Astro ships zero JavaScript to the browser. Interactive components are selectively hydrated as isolated "islands." Astro supports React, Vue, Svelte, Solid, and other UI frameworks simultaneously in the same project, letting you pick the right tool per component.

## When to Use This Skill

- Use when building a blog, documentation site, marketing page, or portfolio
- Use when performance and Core Web Vitals are the top priority
- Use when the project is content-heavy with Markdown or MDX files
- Use when you want SSG (static) output with optional SSR for dynamic routes
- Use when the user asks about `.astro` files, `Astro.props`, content collections, or `client:` directives

## How It Works

### Step 1: Project Setup

```bash
npm create astro@latest my-site
cd my-site
npm install
npm run dev
```

Add integrations as needed:

```bash
npx astro add tailwind        # Tailwind CSS
npx astro add react           # React component support
npx astro add mdx             # MDX support
npx astro add sitemap         # Auto sitemap.xml
npx astro add vercel          # Vercel SSR adapter
```

Project structure:

```
src/
  pages/          ← File-based routing (.astro, .md, .mdx)
  layouts/        ← Reusable page shells
  components/     ← UI components (.astro, .tsx, .vue, etc.)
  content/        ← Type-safe content collections (Markdown/MDX)
  styles/         ← Global CSS
public/           ← Static assets (copied as-is)
astro.config.mjs  ← Framework config
```

### Step 2: Astro Component Syntax

`.astro` files have a code fence at the top (server-only) and a template below:

```astro
---
// src/components/Card.astro
// This block runs on the server ONLY — never in the browser
interface Props {
  title: string;
  href: string;
  description: string;
}

const { title, href, description } = Astro.props;
---

<article class="card">
  <h2><a href={href}>{title}</a></h2>
  <p>{description}</p>
</article>

<style>
  /* Scoped to this component automatically */
  .card { border: 1px solid #eee; padding: 1rem; }
</style>
```

### Step 3: File-Based Pages and Routing

```
src/pages/index.astro          → /
src/pages/about.astro          → /about
src/pages/blog/[slug].astro    → /blog/:slug (dynamic)
src/pages/blog/[...path].astro → /blog/* (catch-all)
```

Dynamic route with `getStaticPaths`:

```astro
---
// src/pages/blog/[slug].astro
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();
---

<h1>{post.data.title}</h1>
<Content />
```

### Step 4: Content Collections

Content collections give you type-safe access to Markdown and MDX files:

```typescript
// src/content/config.ts
import { z, defineCollection } from 'astro:content';

const blog = defineCollection({
  type: 'content',
  schema: z.object({
    title: z.string(),
    date: z.coerce.date(),
    tags: z.array(z.string()).default([]),
    draft: z.boolean().default(false),
  }),
});

export const collections = { blog };
```

```astro
---
// src/pages/blog/index.astro
import { getCollection } from 'astro:content';

const posts = (await getCollection('blog'))
  .filter(p => !p.data.draft)
  .sort((a, b) => b.data.date.valueOf() - a.data.date.valueOf());
---

<ul>
  {posts.map(post => (
    <li>
      <a href={`/blog/${post.slug}`}>{post.data.title}</a>
      <time>{post.data.date.toLocaleDateString()}</time>
    </li>
  ))}
</ul>
```

### Step 5: Islands — Selective Hydration

By default, UI framework components render to static HTML with no JS. Use `client:` directives to hydrate:

```astro
---
import Counter from '../components/Counter.tsx';  // React component
import VideoPlayer from '../components/VideoPlayer.svelte';
---

<!-- Static HTML — no JavaScript sent to browser -->
<Counter initialCount={0} />

<!-- Hydrate immediately on page load -->
<Counter initialCount={0} client:load />

<!-- Hydrate when the component scrolls into view -->
<VideoPlayer src="/demo.mp4" client:visible />

<!-- Hydrate only when browser is idle -->
<Analytics client:idle />

<!-- Hydrate only on a specific media query -->
<MobileMenu client:media="(max-width: 768px)" />
```

### Step 6: Layouts

```astro
---
// src/layouts/BaseLayout.astro
interface Props {
  title: string;
  description?: string;
}
const { title, description = 'My Astro Site' } = Astro.props;
---

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>{title}</title>
    <meta name="description" content={description} />
  </head>
  <body>
    <nav>...</nav>
    <main>
      <slot />  <!-- page content renders here -->
    </main>
    <footer>...</footer>
  </body>
</html>
```

```astro
---
// src/pages/about.astro
import BaseLayout from '../layouts/BaseLayout.astro';
---

<BaseLayout title="About Us">
  <h1>About Us</h1>
  <p>Welcome to our company...</p>
</BaseLayout>
```

### Step 7: SSR Mode (On-Demand Rendering)

Enable SSR for dynamic pages by setting an adapter:

```javascript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import vercel from '@astrojs/vercel/serverless';

export default defineConfig({
  output: 'hybrid',  // 'static' | 'server' | 'hybrid'
  adapter: vercel(),
});
```

Opt individual pages into SSR with `export const prerender = false`.

## Examples

### Example 1: Blog with RSS Feed

```typescript
// src/pages/rss.xml.ts
import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');
  return rss({
    title: 'My Blog',
    description: 'Latest posts',
    site: context.site,
    items: posts.map(post => ({
      title: post.data.title,
      pubDate: post.data.date,
      link: `/blog/${post.slug}/`,
    })),
  });
}
```

### Example 2: API Endpoint (SSR)

```typescript
// src/pages/api/subscribe.ts
import type { APIRoute } from 'astro';

export const POST: APIRoute = async ({ request }) => {
  const { email } = await request.json();

  if (!email) {
    return new Response(JSON.stringify({ error: 'Email required' }), {
      status: 400,
      headers: { 'Content-Type': 'application/json' },
    });
  }

  await addToNewsletter(email);
  return new Response(JSON.stringify({ success: true }), { status: 200 });
};
```

### Example 3: React Component as Island

```tsx
// src/components/SearchBox.tsx
import { useState } from 'react';

export default function SearchBox() {
  const [query, setQuery] = useState('');
  const [results, setResults] = useState([]);

  async function search(e: React.FormEvent) {
    e.preventDefault();
    const data = await fetch(`/api/search?q=${query}`).then(r => r.json());
    setResults(data);
  }

  return (
    <form onSubmit={search}>
      <input value={query} onChange={e => setQuery(e.target.value)} />
      <button type="submit">Search</button>
      <ul>{results.map(r => <li key={r.id}>{r.title}</li>)}</ul>
    </form>
  );
}
```

```astro
---
import SearchBox from '../components/SearchBox.tsx';
---
<!-- Hydrated immediately — this island is interactive -->
<SearchBox client:load />
```

## Best Practices

- ✅ Keep most components as static `.astro` files — only hydrate what must be interactive
- ✅ Use content collections for all Markdown/MDX content — you get type safety and auto-validation
- ✅ Prefer `client:visible` over `client:load` for below-the-fold components to reduce initial JS
- ✅ Use `import.meta.env` for environment variables — prefix public vars with `PUBLIC_`
- ✅ Add `<ViewTransitions />` from `astro:transitions` for smooth page navigation without a full SPA
- ❌ Don't use `client:load` on every component — this defeats Astro's performance advantage
- ❌ Don't put secrets in `.astro` frontmatter that gets used in client-facing templates
- ❌ Don't skip `getStaticPaths` for dynamic routes in static mode — builds will fail

## Security & Safety Notes

- Frontmatter code in `.astro` files runs server-side only and is never exposed to the browser.
- Use `import.meta.env.PUBLIC_*` only for non-sensitive values. Private env vars (no `PUBLIC_` prefix) are never sent to the client.
- When using SSR mode, validate all `Astro.request` inputs before database queries or API calls.
- Sanitize any user-supplied content before rendering with `set:html` — it bypasses auto-escaping.

## Common Pitfalls

- **Problem:** JavaScript from a React/Vue component doesn't run in the browser
  **Solution:** Add a `client:` directive (`client:load`, `client:visible`, etc.) — without it, components render as static HTML only.

- **Problem:** `getStaticPaths` data is stale after content updates during dev
  **Solution:** Astro's dev server watches content files — restart if changes to `content/config.ts` are not reflected.

- **Problem:** `Astro.props` type is `any` — no autocomplete
  **Solution:** Define a `Props` interface or type in the frontmatter and Astro will infer it automatically.

- **Problem:** CSS from a `.astro` component bleeds into other components
  **Solution:** Styles in `.astro` `<style>` tags are automatically scoped. Use `:global()` only when intentionally targeting children.

## Related Skills

- `@sveltekit` — When you need a full-stack framework with reactive UI (vs Astro's content focus)
- `@nextjs-app-router-patterns` — When you need a React-first full-stack framework
- `@tailwind-patterns` — Styling Astro sites with Tailwind CSS
- `@progressive-web-app` — Adding PWA capabilities to an Astro site

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: astropy
description: "Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis."
license: BSD-3-Clause license
metadata:
    skill-author: K-Dense Inc.
risk: critical
source: "https://github.com/astropy/astropy"
---

# Astropy

## Overview

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis. Use astropy for coordinate transformations, unit and quantity calculations, FITS file operations, cosmological calculations, precise time handling, tabular data manipulation, and astronomical image processing.

## When to Use This Skill

Use astropy when tasks involve:
- Converting between celestial coordinate systems (ICRS, Galactic, FK5, AltAz, etc.)
- Working with physical units and quantities (converting Jy to mJy, parsecs to km, etc.)
- Reading, writing, or manipulating FITS files (images or tables)
- Cosmological calculations (luminosity distance, lookback time, Hubble parameter)
- Precise time handling with different time scales (UTC, TAI, TT, TDB) and formats (JD, MJD, ISO)
- Table operations (reading catalogs, cross-matching, filtering, joining)
- WCS transformations between pixel and world coordinates
- Astronomical constants and calculations

## Quick Start

```python
import astropy.units as u
from astropy.coordinates import SkyCoord
from astropy.time import Time
from astropy.io import fits
from astropy.table import Table
from astropy.cosmology import Planck18

# Units and quantities
distance = 100 * u.pc
distance_km = distance.to(u.km)

# Coordinates
coord = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')
coord_galactic = coord.galactic

# Time
t = Time('2023-01-15 12:30:00')
jd = t.jd  # Julian Date

# FITS files
data = fits.getdata('image.fits')
header = fits.getheader('image.fits')

# Tables
table = Table.read('catalog.fits')

# Cosmology
d_L = Planck18.luminosity_distance(z=1.0)
```

## Core Capabilities

### 1. Units and Quantities (`astropy.units`)

Handle physical quantities with units, perform unit conversions, and ensure dimensional consistency in calculations.

**Key operations:**
- Create quantities by multiplying values with units
- Convert between units using `.to()` method
- Perform arithmetic with automatic unit handling
- Use equivalencies for domain-specific conversions (spectral, doppler, parallax)
- Work with logarithmic units (magnitudes, decibels)

**See:** `references/units.md` for comprehensive documentation, unit systems, equivalencies, performance optimization, and unit arithmetic.

### 2. Coordinate Systems (`astropy.coordinates`)

Represent celestial positions and transform between different coordinate frames.

**Key operations:**
- Create coordinates with `SkyCoord` in any frame (ICRS, Galactic, FK5, AltAz, etc.)
- Transform between coordinate systems
- Calculate angular separations and position angles
- Match coordinates to catalogs
- Include distance for 3D coordinate operations
- Handle proper motions and radial velocities
- Query named objects from online databases

**See:** `references/coordinates.md` for detailed coordinate frame descriptions, transformations, observer-dependent frames (AltAz), catalog matching, and performance tips.

### 3. Cosmological Calculations (`astropy.cosmology`)

Perform cosmological calculations using standard cosmological models.

**Key operations:**
- Use built-in cosmologies (Planck18, WMAP9, etc.)
- Create custom cosmological models
- Calculate distances (luminosity, comoving, angular diameter)
- Compute ages and lookback times
- Determine Hubble parameter at any redshift
- Calculate density parameters and volumes
- Perform inverse calculations (find z for given distance)

**See:** `references/cosmology.md` for available models, distance calculations, time calculations, density parameters, and neutrino effects.

### 4. FITS File Handling (`astropy.io.fits`)

Read, write, and manipulate FITS (Flexible Image Transport System) files.

**Key operations:**
- Open FITS files with context managers
- Access HDUs (Header Data Units) by index or name
- Read and modify headers (keywords, comments, history)
- Work with image data (NumPy arrays)
- Handle table data (binary and ASCII tables)
- Create new FITS files (single or multi-extension)
- Use memory mapping for large files
- Access remote FITS files (S3, HTTP)

**See:** `references/fits.md` for comprehensive file operations, header manipulation, image and table handling, multi-extension files, and performance considerations.

### 5. Table Operations (`astropy.table`)

Work with tabular data with support for units, metadata, and various file formats.

**Key operations:**
- Create tables from arrays, lists, or dictionaries
- Read/write tables in multiple formats (FITS, CSV, HDF5, VOTable)
- Access and modify columns and rows
- Sort, filter, and index tables
- Perform database-style operations (join, group, aggregate)
- Stack and concatenate tables
- Work with unit-aware columns (QTable)
- Handle missing data with masking

**See:** `references/tables.md` for table creation, I/O operations, data manipulation, sorting, filtering, joins, grouping, and performance tips.

### 6. Time Handling (`astropy.time`)

Precise time representation and conversion between time scales and formats.

**Key operations:**
- Create Time objects in various formats (ISO, JD, MJD, Unix, etc.)
- Convert between time scales (UTC, TAI, TT, TDB, etc.)
- Perform time arithmetic with TimeDelta
- Calculate sidereal time for observers
- Compute light travel time corrections (barycentric, heliocentric)
- Work with time arrays efficiently
- Handle masked (missing) times

**See:** `references/time.md` for time formats, time scales, conversions, arithmetic, observing features, and precision handling.

### 7. World Coordinate System (`astropy.wcs`)

Transform between pixel coordinates in images and world coordinates.

**Key operations:**
- Read WCS from FITS headers
- Convert pixel coordinates to world coordinates (and vice versa)
- Calculate image footprints
- Access WCS parameters (reference pixel, projection, scale)
- Create custom WCS objects

**See:** `references/wcs_and_other_modules.md` for WCS operations and transformations.

## Additional Capabilities

The `references/wcs_and_other_modules.md` file also covers:

### NDData and CCDData
Containers for n-dimensional datasets with metadata, uncertainty, masking, and WCS information.

### Modeling
Framework for creating and fitting mathematical models to astronomical data.

### Visualization
Tools for astronomical image display with appropriate stretching and scaling.

### Constants
Physical and astronomical constants with proper units (speed of light, solar mass, Planck constant, etc.).

### Convolution
Image processing kernels for smoothing and filtering.

### Statistics
Robust statistical functions including sigma clipping and outlier rejection.

## Installation

```bash
# Install astropy
uv pip install astropy

# With optional dependencies for full functionality
uv pip install astropy[all]
```

## Common Workflows

### Converting Coordinates Between Systems

```python
from astropy.coordinates import SkyCoord
import astropy.units as u

# Create coordinate
c = SkyCoord(ra='05h23m34.5s', dec='-69d45m22s', frame='icrs')

# Transform to galactic
c_gal = c.galactic
print(f"l={c_gal.l.deg}, b={c_gal.b.deg}")

# Transform to alt-az (requires time and location)
from astropy.time import Time
from astropy.coordinates import EarthLocation, AltAz

observing_time = Time('2023-06-15 23:00:00')
observing_location = EarthLocation(lat=40*u.deg, lon=-120*u.deg)
aa_frame = AltAz(obstime=observing_time, location=observing_location)
c_altaz = c.transform_to(aa_frame)
print(f"Alt={c_altaz.alt.deg}, Az={c_altaz.az.deg}")
```

### Reading and Analyzing FITS Files

```python
from astropy.io import fits
import numpy as np

# Open FITS file
with fits.open('observation.fits') as hdul:
    # Display structure
    hdul.info()

    # Get image data and header
    data = hdul[1].data
    header = hdul[1].header

    # Access header values
    exptime = header['EXPTIME']
    filter_name = header['FILTER']

    # Analyze data
    mean = np.mean(data)
    median = np.median(data)
    print(f"Mean: {mean}, Median: {median}")
```

### Cosmological Distance Calculations

```python
from astropy.cosmology import Planck18
import astropy.units as u
import numpy as np

# Calculate distances at z=1.5
z = 1.5
d_L = Planck18.luminosity_distance(z)
d_A = Planck18.angular_diameter_distance(z)

print(f"Luminosity distance: {d_L}")
print(f"Angular diameter distance: {d_A}")

# Age of universe at that redshift
age = Planck18.age(z)
print(f"Age at z={z}: {age.to(u.Gyr)}")

# Lookback time
t_lookback = Planck18.lookback_time(z)
print(f"Lookback time: {t_lookback.to(u.Gyr)}")
```

### Cross-Matching Catalogs

```python
from astropy.table import Table
from astropy.coordinates import SkyCoord, match_coordinates_sky
import astropy.units as u

# Read catalogs
cat1 = Table.read('catalog1.fits')
cat2 = Table.read('catalog2.fits')

# Create coordinate objects
coords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)
coords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)

# Find matches
idx, sep, _ = coords1.match_to_catalog_sky(coords2)

# Filter by separation threshold
max_sep = 1 * u.arcsec
matches = sep < max_sep

# Create matched catalogs
cat1_matched = cat1[matches]
cat2_matched = cat2[idx[matches]]
print(f"Found {len(cat1_matched)} matches")
```

## Best Practices

1. **Always use units**: Attach units to quantities to avoid errors and ensure dimensional consistency
2. **Use context managers for FITS files**: Ensures proper file closing
3. **Prefer arrays over loops**: Process multiple coordinates/times as arrays for better performance
4. **Check coordinate frames**: Verify the frame before transformations
5. **Use appropriate cosmology**: Choose the right cosmological model for your analysis
6. **Handle missing data**: Use masked columns for tables with missing values
7. **Specify time scales**: Be explicit about time scales (UTC, TT, TDB) for precise timing
8. **Use QTable for unit-aware tables**: When table columns have units
9. **Check WCS validity**: Verify WCS before using transformations
10. **Cache frequently used values**: Expensive calculations (e.g., cosmological distances) can be cached

## Documentation and Resources

- Official Astropy Documentation: https://docs.astropy.org/en/stable/
- Tutorials: https://learn.astropy.org/
- GitHub: https://github.com/astropy/astropy

## Reference Files

For detailed information on specific modules:
- `references/units.md` - Units, quantities, conversions, and equivalencies
- `references/coordinates.md` - Coordinate systems, transformations, and catalog matching
- `references/cosmology.md` - Cosmological models and calculations
- `references/fits.md` - FITS file operations and manipulation
- `references/tables.md` - Table creation, I/O, and operations
- `references/time.md` - Time formats, scales, and calculations
- `references/wcs_and_other_modules.md` - WCS, NDData, modeling, visualization, constants, and utilities

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.


---
name: async-python-patterns
description: "Comprehensive guidance for implementing asynchronous Python applications using asyncio, concurrent programming patterns, and async/await for building high-performance, non-blocking systems."
risk: safe
source: community
date_added: "2026-02-27"
---

# 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.

## Limitations
- Use this skill only when the task clearly matches the scope described above.
- Do not treat the output as a substitute for environment-specific validation, testing, or expert review.
- Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.