AGENTS.md · facebook/astryx

Sections

1. Instruction surface
2. Start here
3. Authority
4. Judgment boundary
5. Validation
6. Custom Commands
7. AI Context
8. Documentation Standard
9. Quick Reference
10. JSDoc Conventions

First lines (shown under the repo's MIT license)

# Astryx repository guidance

Astryx is a public design-system repository. Never commit internal links,
identifiers, service names, private operational instructions, or other
Meta-only context.

## Instruction surface

This `AGENTS.md` is the canonical, tool-agnostic instruction surface for the
repository. Add or change shared agent guidance here rather than duplicating it
in tool-specific instruction files. Put genuinely path-specific guidance in a
nested `AGENTS.md`.

## Start here

- Product builders: use `astryx docs`, component `{Name}.doc.mjs` files, and
  `packages/cli/assets/docs/`.
- Contributors: read `CONTRIBUTING.md` and the relevant guidance linked from
  `docs/README.md`.
- Pull requests: choose one primary intent and use its template under
  `.github/PULL_REQUEST_TEMPLATE/`; read `docs/contributing/pull-requests.md`
  before opening or reviewing a mixed change.
- Component work: derive the review's semantic triggers, load matching `current`
  global baseline claims with `node scripts/review-global-baselines.mjs
--authority-commit <base-sha> --review-head <head-sha> --triggers
<comma-separated-triggers>`, then read
  the component's `{Name}.spec.md` when one exists and any `module:*` records it
  lists. Load global records before narrower owners, but resolve the direct
  component or family owner first when it governs the exact delta. A global
  route exposes only the listed claim; it never makes the whole record govern
  the component or change. Preserve each matched record, claim, trigger, and
  match reason in the review receipt.
- Any path: `pnpm specs:for <path>` lists the current records linked to it,
  the specs that decided them, and the global claims its component's triggers
  route. It reads the working tree, so on a pull-request branch it shows that
  branch's proposed records; it is a lookup, not review authority. It adds to
  the component-review steps above; it does not replace them.
- Component-local visual intent: reuse or amend the optional `Design decisions`
  table in the current component/module spec only when durable local intent must
  survive future redesigns. Keep exact tuning in code/evidence and shared rules
  in `docs/design/`. DESIGNOWNER authors may include that local intent with the
  pixels and evidence in one atomic appearance-only PR. External contributors
  follow the normal contribution flow and are never asked to author specs;
  maintainers own missing authority.
- Cross-component work: read the relevant contract under `docs/families/`,
  applicable design spec under `docs/design/`, and current architecture under
  `docs/architecture/`.
- Consequential shared-system changes: use a record under `docs/specs/`.
- Writing or reviewing any knowledge record: run the rubric in
  `docs/contributing/spec-writing.md` over the record and put its results in
  the pull request description under `## Writing rubric results`. A record
  describes the system in the present tense; proposals, history, pull
  requests, and research stay out of it. When reviewing, read the record
  against the reported results; a record pull request without them is
  incomplete, so ask for them before reviewing the content.
- Integration contribution work: read `docs/specs/AST-039/spec.md`. Every new
  discoverable item owns a strongly typed, same-stem `.doc.mjs`; root manifests
  locate directories and never catalog their items. No catalog file (like
  `themes/manifest.json`) and no per-item map in the manifest, ever.

## Authority

Knowledge records declare `authority`:

- `draft`: not authoritative; may still need evidence or owner review;
- `current`: explicitly approved and authoritative;
- `archived`: context only, with a reason such as `superseded`, `withdrawn`,
  or `historical` and a replacement link when one exists.

Only `current` records govern implementation and review. Never infer approval
from merged code, silence, an old review, or an existing wiki page.

## Judgment boundary

Resolve checkable behavior from code, tests, and browser evidence. Ask a human
only when a stable public API, theme contract, ownership boundary, compatibility
policy, or genuinely subjective visual direction remains undecided. Ask one
question at a time.

Before drafting, reviewing, or implementing a proposed outcome, search current
records and open pull requests using the proposed canonical owner/id, affected
paths and exported symbols, and the behavior's semantic terms. Extend or project
the existing canonical owner by default. Create a new record only for a distinct
fact boundary, and state why the existing owner cannot contain it. Do not create
new policy for work that is already complete, owned, or superseded.

## Validation

Run `pnpm check:knowledge` after editing knowledge records or templates. A
material template-shape change requires a schema-version bump and migration of
active records; changing template guidance alone does not rewrite accepted
history.

## Custom Commands

### `/vibe-test [count]` - Run vibeability tests

Tests how well AGENTS.md helps LLMs generate correct Astryx component code.

**Usage:**

```
/vibe-test 5                    # Run 5 stratified sample tests (one-shot)
/vibe-test                      # Run all 21 tests (one-shot)
/vibe-test 5 --degradation      # Run 5 tests with degradation curve (10-turn)
```

**How to execute:**

1. Run `pnpm -F @astryxdesign/vibe-tests interactive --sample <count>` to set up iteration
2. Spawn parallel subagents (one per test prompt) to:
   - Read the task file from `results/<iteration>/tasks/{promptId}.json`
   - Generate code for the prompt using Astryx components (AGENTS.md auto-injected)
   - Self-evaluate for success/escape hatches
   - Write `.tsx` result to `results/<iteration>/results/{promptId}.tsx`
   - Write `.json` metadata to `results/<iteration>/results/{promptId}.json`
3. Trigger `gh workflow run vibe-screenshots.yml` to build previews and capture screenshots
4. Run `pnpm -F @astryxdesign/vibe-tests aggregate --iteration <id>` to see results

**Degradation mode (--degradation):**
Tests context retention across 10-turn conversations with filler, distractor, and recovery turns.
Probes at turns 0, 6, 8, 10 to measure quality degradation. Results show a line graph of each test's progression.

**Result format:**

```json
{
  "id": "<iter>-<promptId>",
  "timestamp": "...",
  "model": "claude-code-interactive",
  "persona": "naive",
  "promptCategory": "...",
  "trajectoryDepth": 0,
  "prompt": "...",
  "response": "<code>",
  "evaluation": {"success": true, "componentsUsed": [...], "escapeHatches": [...]}
}
```

Runners may also write an optional `<promptId>.provenance.json` sidecar beside the result metadata. The versioned, executor-neutral contract and fallback behavior are documented in `internal/vibe-tests/docs/execution-provenance.md`.

## AI Context

For architectural context, decisions, and research, see the **[GitHub Wiki](https://github.com/facebook/astryx/wiki)**:

- **Decisions** — API Conventions, Why StyleX, StyleX Distribution
- **Architecture** — System Architecture, Component Authoring Guide
- **Research** — AI + Design Systems, AI Model Trajectory, Swizzle Ergonomics
- **Future** — Animation System, RSC Utilities, Distribution Strategy

For component-specific documentation, see the `{Name}.doc.mjs` file in each component directory under `packages/core/src/` (e.g. `Button/Button.doc.mjs`). These are plain JS files with JSDoc type annotations exporting a `ComponentDoc` object (typed via `@astryxdesign/cli/authoring`).

## Documentation Standard

Documentation lives in two places:

1. **File Headers** — Each source file has a structured JSDoc header with `@input`, `@output`, `@position`
2. **Component Docs** — `{Name}.doc.mjs` files in each component directory (props, features, examples)

**Update Protocol**: When modifying code, update the file's header comment. Look for `SYNC:` comments as reminders.