AGENTS.md

1# Plugin Directory Guide
2 
3This directory owns Open Design plugin content and plugin authoring material.
4 
5## Boundaries
6 
7- `plugins/_official/` contains bundled first-party plugins. The daemon boot walker scans only this subtree and registers it as `source_kind='bundled'`.
8- `plugins/spec/` is the portable plugin specification and authoring kit. It is documentation, starter material, and example source for contributors and external agents; it must not be treated as an installed first-party catalog.
9- Keep runnable plugin examples portable: every example should have a `SKILL.md`; add `open-design.json` only as the OD sidecar.
10- Keep `SKILL.md` bodies free of OD-only marketplace metadata. Put OD display, inputs, preview, pipeline, capabilities, and source information in `open-design.json`.
11- Do not import app-private code from plugin content. A plugin may reference OD atoms, design systems, craft docs, assets, scripts, MCP servers, or connectors through the manifest.
12 
13## Authoring Rules
14 
15- New spec examples belong under `plugins/spec/examples/<plugin-id>/`.
16- New first-party bundled plugins belong under `plugins/_official/<tier>/<plugin-id>/` only when the product should auto-register them on daemon startup.
17- Use the v1 JSON schema at `docs/schemas/open-design.plugin.v1.json`.
18- Contribution-facing spec docs are bilingual. When editing `README.md`, `SPEC.md`, `CONTRIBUTING.md`, `AGENT-DEVELOPMENT.md`, or example README files under `plugins/spec/`, update the matching `*.zh-CN.md` mirror in the same change.
19- Prefer TypeScript for project-owned scripts. Avoid adding new `.js`, `.mjs`, or `.cjs` files unless they are generated, vendored, or explicitly allowlisted by `scripts/guard.ts`.
20- Keep example plugins concise and agent-readable. Move long reference material to `references/` and tell the agent when to load it.
21 
22## Validation
23 
24For plugin content changes, run:
25 
26```bash
27pnpm guard
28pnpm --filter @open-design/plugin-runtime typecheck
29```
30 
31When the daemon CLI is built and available, also validate runnable plugin folders with:
32 
33```bash
34od plugin validate ./plugins/spec/examples/&lt;plugin-id&gt;
35```
36