AGENTS.md ยท diff
git:20260923.2bec811 to git:20260928.0136905
3 added, 0 removed. Audit A to A.
# AGENTS.md
## Project Shape
Starwind UI is a pnpm/Turbo monorepo for Astro, React, Vue 3.5 beta, and Svelte 5 beta components,
framework-neutral Runtime controllers, generated Primitive adapters, and the `starwind` CLI.
- `packages/runtime`: behavior-only DOM controllers and component subpath exports.
- `packages/astro` and `packages/react`: generated first-party Primitive adapters.
- `packages/vue`: generated Vue 3.5 public-beta Primitive adapters. The beta remains outside the
stable Runtime, Astro, and React fixed package group.
- `packages/svelte`: generated Svelte 5 public-beta Primitive adapters for Svelte `>=5.29.0 <6`.
- `packages/cli`: CLI commands, registries, migrations, and project integration.
- `apps/demo` and `apps/react-demo`: complete Astro and React integration demos.
- `apps/vue-demo`: public Vue beta integration and review demo.
- `apps/svelte-demo`: public Svelte beta integration and review demo.
- `scripts/portable-runtime`: adapter contracts, generators, smoke tests, and measurement tooling.
Use pnpm for package work. Package metadata requires Node `>=22.12.0`; CI uses Node 24.
## Useful Commands
```bash
pnpm install
pnpm build
pnpm verify
pnpm test:run
pnpm test:coverage
pnpm typecheck
pnpm lint:check
pnpm format:check
pnpm demo:smoke
pnpm react-demo:smoke
pnpm vue-demo:smoke
pnpm runtime:generate:all
pnpm runtime:registry:generate
pnpm runtime:size:check
```
## Contribution Conventions
- Runtime behavior belongs in `packages/runtime`; framework adapters wire props, refs, events, and
markup to Runtime behavior rather than reimplementing it.
- Generated adapter outputs should be changed through contracts, specs, or generators and then
regenerated.
- Keep TypeScript strict and ESM-only.
- Put tests in the established `tests` homes rather than adding colocated `__tests__` directories.
- Preserve `data-slot` for public part identity and use `data-sw-*` for Runtime discovery hooks.
- Add deferred styled version intent under `.changeset/styled-components/` for changed existing
components; the generated Version Packages PR consolidates manifest bumps. Regenerate registry
artifacts rather than editing generated registry JSON by hand.
- Add deferred primitive version intent under `.changeset/primitive-components/` for changed
existing vendored primitives. Use normal SemVer: `patch` for compatible fixes, `minor` for
backward-compatible capabilities, and `major` for breaking changes.
- Add a Changeset for package-facing changes. Follow the beta release policy for
`@starwind-ui/vue` and `@starwind-ui/svelte`. Demo workspaces remain private.
+ - Before writing or editing a Changeset or changelog, apply the Release Note Writing rules in
+ `docs/release/versioning.md` and use the `write-changeset` skill when available. This requirement
+ applies during implementation and release preparation without an explicit skill request.
- Follow `docs/release/versioning.md`. Existing component changes schedule a `starwind` patch
independently from their component bump. A brand-new stable component schedules a `starwind`
minor.
- Never create, modify, or approve a `starwind` major Changeset without express user consent for
that CLI major in the current task.
- Use conventional commits such as `feat(runtime): ...`, `fix(cli): ...`, or `docs: ...`.
Before handoff, run the narrowest relevant tests and report any checks that were not run.