devframe packages one devtool integration - RPC, SPA, diagnostics, CLI/build/embedded outputs - and @devframes/hub orchestrates many of them for hub UI providers.
.agents/ describes what the code does and why. It is a map, not a standard:
where the two disagree, the packages' src/ and test suites win, and the docs get fixed.
- MUST, MUST NOT, SHOULD and MAY use RFC 2119 meanings. They mark real invariants - layer boundaries, wire contracts, output shapes - not house style.
- Prose MUST follow the canonical vocabulary in
docs/content/8.references/1.terms.md: the tool is "a devframe", never bareclient/host/server/agent/plugin(02). - Event, broadcast, shared-state and channel names MUST come from the
DEVFRAME_EVENTS/HUB_EVENTSmaps, kept in lockstep with the Events Reference - no re-typed string literals (04). - Node-side warnings and errors MUST be coded
DFdiagnostics viadevframe/utils/nostics- no ad-hocconsole.*/throw new Error(08). devframeand every@devframes/*package MUST stay validator-neutral: nozod/valibot/arktypein runtimedependencies; schemas type against Standard Schema (04).- Dependencies go through the pnpm catalogs (
catalog:<name>); versions MUST NOT be pinned in apackage.json(03). - Before a PR, all gates MUST pass:
pnpm lint && pnpm knip && pnpm test && pnpm typecheck && pnpm build. Commits follow Conventional Commits.
- A feature that only makes sense when multiple tools share a UI belongs in a hub
package;
devframestays single-integration and headless - no banners, no default styling, no opinionated stdout (01). - Adapter code that may run standalone MUST NOT hardcode mount paths; SPAs build with relative asset paths and discover their base at runtime (01).
- The framework kits keep two subpaths (
.../single,.../hub) parallel across Vite/Nuxt/Next; the bare root throws (05). - The two reference hosts (
examples/custom-hub-vite,examples/custom-hub-next) stay at feature parity - a change to one lands in the other in the same PR (07). - UI builds on
@antfu/designsemantic tokens and its component vocabulary - no hardcoded palettes, no bespoke nav/button/tab shapes; shadow-root surfaces build on Wind3 (06).
| Task | Read |
|---|---|
| Layering, design principles, mount paths, CLI composition | 01 positioning |
| Canonical names for every concept | 02 terminology |
| Stack, repo layout, commands, typecheck/knip/starter machinery | 03 stack & commands |
| RPC ids, event maps, validator neutrality, imports, factory exports | 04 conventions |
@devframes/vite/nuxt/next subpath shape and peers |
05 framework kits |
@antfu/design preset, tokens, ports, shadow-root CSS, Storybook |
06 design system |
| Reference host parity rules | 07 hub examples |
DF codes, ranges, adding an error |
08 diagnostics |
Writing rules for docs/ |
09 docs style |