Design

Create or update the living system spec for a feature or change. Read AGENTS.md if not in context. Taxonomy: .aide/docs/core/DOCUMENT_TAXONOMY.md.

Inputs

Design question or topic. Timebox if relevant.

Review-aware

Before starting: check if <artifact>.findings.md exists for this topic. If it does, read it and incorporate findings before proceeding.

Workflow

1. GitHub state check — Run gh issue list and gh pr list to avoid proposing already-built or conflicting work.

2. Locate the system spec — Find the relevant spec in docs/specs/ (project) or .aide/docs/ (AIDE framework work). If none exists for this system, you will create one named for the system, not the feature.

3. Native options and established practice first — Before shaping options, survey what the platforms, frameworks and libraries already in use provide for this problem, what their documentation recommends as best practice, and how the problem is conventionally solved across the industry. Cite a source for each. The spec records which is used or rejected, and why, in a "Native and established options" section. A custom mechanism is an option only after these have been named and ruled out.

4. Shape options — Produce exactly 1 recommended option and optionally 1 alternative. Include: pros/cons, risks, dependencies, success validation.

5. Draft — Create or update docs/specs/<system>.md with frontmatter (status: draft for new specs). Binding rules go in the spec's Invariants section.

6. ADR threshold check — Also write a slim ADR to docs/decisions/YYYY-MM-DD-<slug>.md only if all three hold: real alternatives existed; the choice constrains future work; a newcomer could accidentally reverse it. The ADR points to the spec. Most features need no ADR.

7. Cross-review — Use /findings to exchange findings before accepting. Do not accept unreviewed specs.

8. Accept — Set spec frontmatter status: accepted (and ADR status if one was written). Hand off to /scope to decompose into GitHub issues (or, when the project elects a docs/plans/ layer, an optional staged plan).

Spec frontmatter

---
title: <system name>
description: <one line>
status: draft | accepted | superseded
created: YYYY-MM-DD
last_updated: YYYY-MM-DD
---

ADR format (when threshold is met)

# Title
**Status:** Accepted (durable decision — current) | Executed (historical record) | Superseded by <file>
## Context
## Decision
## Rationale
## Consequences

Reference

• Taxonomy + creation rule: .aide/docs/core/DOCUMENT_TAXONOMY.md
• Design pillars: design/ directory
• Quick reference: docs/DESIGN_QUICK_REFERENCE.md