Workspace Conventions
The long-form detail behind the workspace AGENTS.md core rules. Read this
before adding shared code, storing files or secrets, creating workspace
resources, or looking up framework APIs.
Framework Docs Lookup
Read agent-native-docs for the lookup workflow (framework-search first, then
the focused docs-search / source-search readers, and the rg fallback).
The workspace-specific slugs it does not list are workspace and
multi-app-workspace. Feature flags and other specialized workflows are
optional; read their skill only when the app uses them. Use package docs for framework APIs,
the package corpus for reusable framework/template patterns, and this
AGENTS.md plus .agents/skills/ for workspace-specific conventions.
Before building common workspace or agent UI, read agent-native-toolkit to
inventory existing public kits and installed package seams. Read
customizing-agent-native before adapting shared UI. Use the supported
ladder: configure → compose → eject the smallest unit → propose a shared seam.
Preview before --apply, commit agent-native.ejections.json, and never edit
node_modules or eject protected runtime contracts.
Shared Conventions
- All AI/LLM behavior goes through the app's agent chat. UI and server code
must not call model providers, AI SDK
generateText() / streamText(), or
other inline LLM APIs directly. Use sendToAgentChat() for local app-agent
work, including hidden context and submit: false prefill/review flows.
Keep actions deterministic and focused. If a workflow is framed as research,
analysis, generation, recommendation, or synthesis, let the agent
orchestrate provider/data actions in the open AgentSidebar instead of hiding
the work in one opaque action or a separate follow-up textbox.
Only use useAgentChatContext, setAgentChatContextItem,
listAgentChatContext, removeAgentChatContextItem, and
clearAgentChatContext when UI needs two-way sync with staged context chips.
Read .agents/skills/delegate-to-agent/SKILL.md before building agent-driven
UI or "AI" features.
- Put shared code in
packages/shared only when multiple apps need it.
- Keep app-specific screens, actions, state, and skills inside
apps/<app>.
- SQL is for structured records, metadata, references, and searchable text. Store
large files/blob payloads (base64,
data: URLs, images, video/audio, PDFs,
ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob
storage and persist only URLs, ids, or handles.
- Store shared runtime configuration in the workspace root
.env; use
apps/<app>/.env only for app-specific overrides. For public app behavior,
prefer the default in agent-native.config.ts and use the deterministic
AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH> alias only when a non-secret value
needs a deployment override. Never hardcode API keys,
tokens, webhook URLs, signing secrets, private Builder/internal data, customer
data, or credential-looking literals in source, docs, prompts, fixtures,
application state, action responses, or generated app content. Use
secrets/OAuth/runtime configuration and obvious placeholders in examples.
- Each app deploys its own
/* page function, and that function ships whatever
the app's server bundle depends on — including a dependency only a background
job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,
media processing, ML), read .agents/skills/performance/SKILL.md §9 and keep
that work in a background function or job. A dependency belonging to one app
does not belong in packages/shared.
- Prefer framework defaults until the workspace has a real custom rule,
component, plugin, action, or skill to share.
- Keep the Workspace files view for user-authored or user-requested resources.
Agents may create hidden
agent_scratch resources for temporary working
notes, scripts, task plans, or intermediate outputs, but should promote them
to normal workspace visibility only when the user explicitly asks to keep or
manage the file.
- Runtime-editable global resources can be managed from Dispatch Resources.
Use
AGENTS.md or instructions/<slug>.md for always-on guardrails,
skills/<slug>/SKILL.md for workspace skills, context/<slug>.md for
personas/positioning/messaging/company facts/brand guidelines, and
agents/<slug>.md for custom agent profiles. Scope them to All apps when
every workspace app should inherit them. All-app resources are inherited at
runtime; do not copy or sync them into individual apps.
- Which hosted first-party apps (Mail, Calendar, Content, ...) exist in the
workspace is set by
agent-native.builtinAgents in the root
package.json: { "mode": "all" | "none" | "selected", "include": [...] }
(absent means "all"; ids must be template names; restart
agent-native dev after editing). It never touches mounted workspace apps
or connected remote agents, and set-mcp-app-access stays a separate MCP
routing permission.
Related Skills
- adding-workspace-apps — Creating and mounting a new app under
apps/.
- agent-native-docs — The full docs and source-corpus lookup workflow.
- agent-native-toolkit — Inventory of shared workspace and agent UI.
- customizing-agent-native — The configure → compose → eject ladder.
- delegate-to-agent — Routing every AI feature through the agent chat.
- performance — Load cost, and (§9) cold-start artifact size per app.
- secrets — Registering API keys and service credentials.
- storing-data — Where structured data and large payloads belong.
1---2name: workspace-conventions3description: >-4 Shared conventions for a multi-app Agent-Native workspace: finding5 version-matched framework docs and source, shared vs app-owned code, file and6 blob storage, env and secrets, agent scratch files, and Dispatch Resources.7 Use when working across workspace apps, storing files or credentials, or8 looking up framework APIs.9scope: dev10metadata:11 source: https://skillmd.com/skills/builderio/workspace-conventions12---1314# Workspace Conventions1516The long-form detail behind the workspace `AGENTS.md` core rules. Read this17before adding shared code, storing files or secrets, creating workspace18resources, or looking up framework APIs.1920## Framework Docs Lookup2122Read `agent-native-docs` for the lookup workflow (`framework-search` first, then23the focused `docs-search` / `source-search` readers, and the `rg` fallback).2425The workspace-specific slugs it does not list are `workspace` and26`multi-app-workspace`. Feature flags and other specialized workflows are27optional; read their skill only when the app uses them. Use package docs for framework APIs,28the package corpus for reusable framework/template patterns, and this29`AGENTS.md` plus `.agents/skills/` for workspace-specific conventions.3031Before building common workspace or agent UI, read `agent-native-toolkit` to32inventory existing public kits and installed package seams. Read33`customizing-agent-native` before adapting shared UI. Use the supported34ladder: configure → compose → eject the smallest unit → propose a shared seam.35Preview before `--apply`, commit `agent-native.ejections.json`, and never edit36`node_modules` or eject protected runtime contracts.3738## Shared Conventions3940- All AI/LLM behavior goes through the app's agent chat. UI and server code41 must not call model providers, AI SDK `generateText()` / `streamText()`, or42 other inline LLM APIs directly. Use `sendToAgentChat()` for local app-agent43 work, including hidden `context` and `submit: false` prefill/review flows.44 Keep actions deterministic and focused. If a workflow is framed as research,45 analysis, generation, recommendation, or synthesis, let the agent46 orchestrate provider/data actions in the open AgentSidebar instead of hiding47 the work in one opaque action or a separate follow-up textbox.48 Only use `useAgentChatContext`, `setAgentChatContextItem`,49 `listAgentChatContext`, `removeAgentChatContextItem`, and50 `clearAgentChatContext` when UI needs two-way sync with staged context chips.51 Read `.agents/skills/delegate-to-agent/SKILL.md` before building agent-driven52 UI or "AI" features.53- Put shared code in `packages/shared` only when multiple apps need it.54- Keep app-specific screens, actions, state, and skills inside `apps/<app>`.55- SQL is for structured records, metadata, references, and searchable text. Store56 large files/blob payloads (base64, `data:` URLs, images, video/audio, PDFs,57 ZIPs, screenshots, thumbnails, session replay chunks) in configured file/blob58 storage and persist only URLs, ids, or handles.59- Store shared runtime configuration in the workspace root `.env`; use60 `apps/<app>/.env` only for app-specific overrides. For public app behavior,61 prefer the default in `agent-native.config.ts` and use the deterministic62 `AGENT_NATIVE_CONFIG_<UPPER_SNAKE_PATH>` alias only when a non-secret value63 needs a deployment override. Never hardcode API keys,64 tokens, webhook URLs, signing secrets, private Builder/internal data, customer65 data, or credential-looking literals in source, docs, prompts, fixtures,66 application state, action responses, or generated app content. Use67 secrets/OAuth/runtime configuration and obvious placeholders in examples.68- Each app deploys its own `/*` page function, and that function ships whatever69 the app's server bundle depends on — including a dependency only a background70 job uses. Before an app takes on a heavy runtime (headless browser, ffmpeg,71 media processing, ML), read `.agents/skills/performance/SKILL.md` §9 and keep72 that work in a background function or job. A dependency belonging to one app73 does not belong in `packages/shared`.74- Prefer framework defaults until the workspace has a real custom rule,75 component, plugin, action, or skill to share.76- Keep the Workspace files view for user-authored or user-requested resources.77 Agents may create hidden `agent_scratch` resources for temporary working78 notes, scripts, task plans, or intermediate outputs, but should promote them79 to normal workspace visibility only when the user explicitly asks to keep or80 manage the file.81- Runtime-editable global resources can be managed from Dispatch Resources.82 Use `AGENTS.md` or `instructions/<slug>.md` for always-on guardrails,83 `skills/<slug>/SKILL.md` for workspace skills, `context/<slug>.md` for84 personas/positioning/messaging/company facts/brand guidelines, and85 `agents/<slug>.md` for custom agent profiles. Scope them to All apps when86 every workspace app should inherit them. All-app resources are inherited at87 runtime; do not copy or sync them into individual apps.88- Which hosted first-party apps (Mail, Calendar, Content, ...) exist in the89 workspace is set by `agent-native.builtinAgents` in the root90 `package.json`: `{ "mode": "all" | "none" | "selected", "include": [...] }`91 (absent means `"all"`; ids must be template names; restart92 `agent-native dev` after editing). It never touches mounted workspace apps93 or connected remote agents, and `set-mcp-app-access` stays a separate MCP94 routing permission.9596## Related Skills9798- **adding-workspace-apps** — Creating and mounting a new app under `apps/`.99- **agent-native-docs** — The full docs and source-corpus lookup workflow.100- **agent-native-toolkit** — Inventory of shared workspace and agent UI.101- **customizing-agent-native** — The configure → compose → eject ladder.102- **delegate-to-agent** — Routing every AI feature through the agent chat.103- **performance** — Load cost, and (§9) cold-start artifact size per app.104- **secrets** — Registering API keys and service credentials.105- **storing-data** — Where structured data and large payloads belong.