@agent-native/core 0.127.1 → 0.128.0

package/corpus/core/src/templates/chat/.agents/skills/create-skill/SKILL.md

@@ -1,221 +0,0 @@
----
-name: create-skill
-description: >-
-  How to create new skills for an agent-native app. Use when adding a new
-  skill, documenting a pattern the agent should follow, or creating reusable
-  guidance for the agent.
-scope: dev
-metadata:
-  internal: true
----
-
-# Create a Skill
-
-## When to Use
-
-Create a new skill when:
-
-- There's a pattern the agent should follow repeatedly.
-- A multi-step workflow needs reliable, step-by-step guidance.
-- You want to scaffold files from a template.
-
-Don't create a skill when:
-
-- The guidance already exists in another skill — extend it instead.
-- You're documenting something the agent already knows (e.g., how to write
-  TypeScript).
-- It's a one-off — put it in `AGENTS.md` (for everyone) or `memory/MEMORY.md`
-  (personal, per-user). See **capture-learnings**.
-
-## Interview
-
-Before writing the skill, answer these:
-
-1. **What should this skill enable?** — The core purpose in one sentence.
-2. **Which of the four areas does it serve?** — UI, actions, skills/instructions,
-   or application state (see the **adding-a-feature** skill). Most skills are
-   about how to touch one or more of these correctly.
-3. **When should it trigger?** — Describe the situations in natural language.
-   Be slightly pushy — over-triggering is better than under-triggering.
-4. **Does it involve context awareness?** — Does the agent need to know what the
-   user is looking at? If so, reference the `navigation` application-state key and
-   the `view-screen` action pattern. See the **context-awareness** skill.
-5. **What type of skill?** — Pattern, Workflow, or Generator (see below).
-6. **Does it need supporting files?** — References (read-only context) or none.
-   Keep it minimal; push depth into `references/`.
-
-## Skill Types and Templates
-
-### Pattern (architectural rule)
-
-For documenting how things should be done:
-
-```markdown
----
-name: my-pattern
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Pattern Name]
-
-## Rule
-
-[One sentence: what must be true]
-
-## Why
-
-[Why this rule exists]
-
-## How
-
-[How to follow it, with code examples]
-
-## Don't
-
-[Common violations]
-
-## Related Skills
-
-[Which skills compose with this one]
-```
-
-### Workflow (step-by-step)
-
-For multi-step implementation tasks:
-
-```markdown
----
-name: my-workflow
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Workflow Name]
-
-## Prerequisites
-
-[What must be in place first]
-
-## Steps
-
-[Numbered steps with code examples]
-
-## Verification
-
-[How to confirm it worked]
-
-## Troubleshooting
-
-[Common issues and fixes]
-
-## Related Skills
-```
-
-### Generator (scaffolding)
-
-For creating files from templates:
-
-```markdown
----
-name: my-generator
-description: >-
-  [Under 40 words. What it covers AND when it should trigger.]
----
-
-# [Generator Name]
-
-## Usage
-
-[How to invoke — what args/inputs are needed]
-
-## What Gets Created
-
-[List of files and their purpose]
-
-## Template
-
-[The template content with placeholders]
-
-## After Generation
-
-[What to do next — wire up sync, add routes, register the action, etc.]
-
-## Related Skills
-```
-
-## Naming Conventions
-
-- Hyphen-case only: `[a-z0-9-]`, max 64 characters.
-- Pattern skills: descriptive names (`storing-data`, `delegate-to-agent`).
-- Workflow/generator skills: verb-noun (`create-skill`, `capture-learnings`).
-- The directory name must match the `name` in frontmatter.
-
-## Skill Scope (runtime vs dev)
-
-An optional `scope` frontmatter field controls which agent loads the skill:
-
-- `both` (default when omitted) — loaded by connected repo agents and the
-  in-app runtime agent. Use for any skill both audiences should follow.
-- `runtime` — loaded only by the in-app runtime agent.
-- `dev` — meant for the human's coding agent (e.g. Claude Code) only. **Excluded
-  from the runtime agent everywhere**: not in the system-prompt skills block and
-  not in `docs-search` results.
-
-Use `scope: dev` for internal-only skills that should guide connected repo
-agents such as Codex or Claude Code, but should not affect the deployed
-production agent. Do not use `metadata.internal` for runtime visibility; that
-field is catalog/package metadata and is intentionally not treated as
-production exclusion.
-
-```markdown
----
-name: release-checklist
-description: >-
-  Steps for cutting a release. Use when preparing or publishing a new version.
-scope: dev
----
-```
-
-Leave `scope` off for normal skills — the default (`both`) keeps them loading at
-runtime, so this is fully backward compatible. To make a dev-only skill visible
-to your coding agent but hidden from the runtime agent, mark it `scope: dev` and
-optionally mirror it under `.claude/skills/<name>/SKILL.md` (Claude Code reads
-`.claude/skills/` independently of the runtime's `.agents/skills/`).
-
-## Tips
-
-- **Keep descriptions under 40 words** — they load into context on every
-  conversation. State what the skill does AND when to trigger it.
-- **Keep SKILL.md lean (under ~500 lines)** — move detailed content to
-  `references/` files (progressive disclosure).
-- **Use standard markdown headings** — no XML tags or custom formats.
-
-## Anti-Patterns
-
-- **Inline LLM calls** — skills must not call LLMs directly. All AI work goes
-  through the agent chat (see **delegate-to-agent**).
-- **Introducing databases** — data lives in SQL via Drizzle (see **storing-data**).
-- **Ignoring sync** — if a skill creates data, mention wiring `useDbSync` /
-  `useActionQuery` so the UI updates (see **real-time-sync**).
-- **Vague descriptions** — "Helps with development" won't trigger. Be specific
-  about _when_.
-- **Pure documentation** — skills should guide action, not just explain concepts.
-
-## File Structure
-
-```
-.agents/skills/my-skill/
-├── SKILL.md              # Main skill (required)
-└── references/           # Optional supporting context
-    └── detailed-guide.md
-```
-
-## Related Skills
-
-- **adding-a-feature** — The four-area model every skill ultimately serves.
-- **writing-agent-instructions** — How to write AGENTS.md and skills well for
-  apps and templates you ship to others.
-- **capture-learnings** — When a learning graduates to reusable guidance, create
-  a skill; one-offs go to `AGENTS.md` or `memory/MEMORY.md`.
-- **self-modifying-code** — The agent can create new skills (Tier 2 modification).

package/corpus/core/src/templates/chat/.agents/skills/customizing-agent-native/SKILL.md

@@ -1,220 +0,0 @@
----
-name: customizing-agent-native
-description: >-
-  How to configure, compose, or eject Agent Native features into app-owned
-  code. Use when overriding shared components or integrations, customizing a
-  template, adding UI to chat or headless apps, or inspecting package source.
-scope: dev
-metadata:
-  internal: true
----
-
-# Customizing Agent Native
-
-## Rule
-
-Start with the app's registered design system and local UI adapters, then use
-the public feature's props, semantic components, controller, product slots,
-and callbacks. If those seams are not enough, use the eject CLI to transfer
-the smallest supported feature into the app and make that copy app-owned.
-Never edit `node_modules`, deep-import a private source file at runtime, or
-patch an `@agent-native/*` package.
-
-Use this order:
-
-1. Set brand tokens with the build-time theme configuration when tokens are
-   enough.
-2. Register company components in `app/design-system.ts` with
-   `defineDesignSystem`, then pass that definition to `ToolkitProvider`.
-3. Configure a public feature through its semantic components, headless
-   controller, and product-level render slots.
-4. Compose app primitives behind the app's local UI adapter layer.
-5. Eject the smallest feature into app-owned source.
-6. Propose a new Toolkit seam when the same override is useful in two apps.
-
-Ejection is for intentional product customization, not for hiding an upgrade
-failure or replacing Core runtime behavior.
-
-## Use A Company Design System
-
-Keep the explicit, typed registration seam in `app/design-system.ts`:
-
-```tsx
-import { defineDesignSystem } from "@agent-native/toolkit/design-system";
-import {
-  AcmeActionButtonAdapter,
-  AcmeDialogAdapter,
-} from "./design-system/acme-adapter";
-
-export const designSystem = defineDesignSystem({
-  name: "Acme",
-  components: {
-    ActionButton: AcmeActionButtonAdapter,
-    Dialog: AcmeDialogAdapter,
-  },
-});
-```
-
-Adapters translate the semantic Toolkit contract into company component props.
-They are ordinary React components and may use MUI-style providers, React Aria,
-CSS modules, CSS-in-JS, or another styling runtime. `className` and `style` are
-optional interoperability hooks, not Tailwind or CVA requirements.
-
-The contract has nine leaf components (`ActionButton`, `IconButton`,
-`TextField`, `TextArea`, `Spinner`, `Skeleton`, `Status`, `Surface`, `Avatar`)
-and eight behavior components (`Tooltip`, `Menu`, `Popover`, `Dialog`,
-`Picker`, `Checkbox`, `Switch`, `Tabs`). `Picker` covers select and combobox
-behavior, not date picking. Behavior adapters own their portal, focus,
-keyboard, dismissal, and stacking implementation while honoring the semantic
-props and `portalContainer` interop contract.
-
-App product code imports standard controls from its local adapter path, usually
-`@/components/ui/*`. Do not import `@agent-native/toolkit/ui/*` directly from
-pages, routes, or domain components. That bypasses the app seam and makes a
-future design-system replacement incomplete. Toolkit feature packages remain
-valid imports; configure their presentation through the registered semantic
-components, controller, and product slots.
-
-Run the published conformance kit against a complete adapter in its own CI:
-
-```tsx
-import { assertDesignSystemConformance } from "@agent-native/toolkit/conformance";
-import { DESIGN_SYSTEM_CONTRACT_VERSION } from "@agent-native/toolkit/design-system";
-
-await assertDesignSystemConformance({
-  adapterName: "Acme",
-  components,
-  contractVersion: DESIGN_SYSTEM_CONTRACT_VERSION,
-});
-```
-
-New components and optional props are minor contract changes. Required props,
-removed APIs, or behavioral changes require a new contract major.
-
-## Customize A Shared Feature
-
-Prefer feature-level headless controllers over rebuilding individual widgets.
-One controller must power both the Toolkit default view and every custom render
-path so behavior, actions, analytics, accessibility state, and error handling
-cannot drift. Use a product-level render slot to replace the view while keeping
-that controller. Eject only when the controller and slots cannot express the
-required product behavior.
-
-## Eject A Feature
-
-Discover and inspect the ejection units published by installed first-party
-packages before changing source:
-
-```bash
-agent-native eject --list
-agent-native eject inspect <unit>
-agent-native eject <unit> --app <app>
-agent-native eject <unit> --app <app> --apply
-```
-
-The command is dry-run by default. It prints the file closure, consumer import
-rewrites, protected package contracts, and verification commands before
-writing. `--apply` copies the package-version-matched source into the app and
-rewrites only imports covered by the unit manifest.
-
-Every first-party public ejection unit must have a complete manifest. If one is
-missing, treat that as a framework coverage bug instead of inventing a copy
-recipe. For an unknown third-party package, use the emitted add-style blueprint
-as a starting point. Protected runtime behavior is never copied; follow the
-reported configuration, adapter, or extension seam instead.
-
-Applied ejections are recorded in the committed
-`agent-native.ejections.json`, including package version, manifest digest,
-target hashes, and import rewrites. Use the recorded state to review drift or
-undo an unchanged ejection:
-
-```bash
-agent-native eject diff <unit> --app <app>
-agent-native eject restore <unit> --app <app>
-agent-native eject restore <unit> --app <app> --apply
-```
-
-Restore is hash-gated. It refuses to remove locally edited files or reverse
-changed imports and prints their diff instead. Keep an edited ejection as
-app-owned code, or reconcile those edits before restoring it.
-
-## Find The Installed Implementation
-
-Use the source that matches the installed package version:
-
-```bash
-pnpm action docs-search --query "<component or feature>"
-pnpm action source-search --query "<component or symbol>"
-rg -n "<component or symbol>" node_modules/@agent-native/toolkit/src
-rg -n "<component or symbol>" node_modules/@agent-native/core/corpus
-```
-
-- Toolkit publishes readable TypeScript under
-  `node_modules/@agent-native/toolkit/src/` for selective UI adoption.
-- Core and first-party template source lives under
-  `node_modules/@agent-native/core/corpus/core/` and
-  `node_modules/@agent-native/core/corpus/templates/`.
-- Treat those trees as read-only references. Prefer `agent-native eject` so the
-  package manifest selects the complete source closure and rewrites imports.
-  Manual inspection is still useful for deciding whether to configure,
-  compose, eject, or propose a shared seam.
-
-Do not manually guess at sibling dependencies. The ejection manifest owns the
-required file closure and keeps protected contracts on public package imports.
-
-## Preserve The Agent-Native Contract
-
-UI ownership may change; product contracts should not:
-
-- Keep app operations in `defineAction` actions and call them through
-  `useActionQuery`, `useActionMutation`, or another named client helper.
-- Keep navigation, selection, and focused-object state visible through the
-  existing application-state keys.
-- Keep AI work in the shared agent chat instead of adding direct LLM calls.
-- Keep auth, access checks, persistence, chat transport, and agent execution in
-  Core. Do not copy those runtimes into the app.
-- Keep local adapters narrow so package upgrades still improve every surface
-  the app has not intentionally taken ownership of.
-- Keep page, route, and domain code on local UI adapter imports. Never reach
-  around the registered design system with direct Toolkit UI primitive imports.
-
-## App Shapes
-
-- **Template app:** begin with `app/design-system.ts`, its local UI adapters,
-  and domain UI. Use Toolkit features for repeated workspace behavior; eject
-  only the unit being customized.
-- **Chat app:** keep `AgentChatSurface`, thread state, and chat transport in
-  Core. Compose or eject Toolkit presentation such as chat-history UI around it.
-- **Headless app:** stay action-first while no UI is needed. When adding a UI,
-  use the Chat template as the on-ramp or add Toolkit components without
-  replacing the existing actions.
-- **Workspace:** put one-app overrides in that app. Promote a local component
-  to `packages/shared` only when multiple workspace apps use it.
-
-## After Ejecting
-
-- Commit `agent-native.ejections.json` with the app-owned files and rewrites.
-- Remove unused dependencies and imports from the ejected files.
-- Keep visible text in the app's localization catalogs.
-- Run the manifest verification commands plus the app's formatter, typecheck,
-  and focused tests.
-- Re-check the installed source during future package upgrades; the app-owned
-  ejection does not receive upstream fixes automatically. Use `eject diff` to
-  distinguish recorded output from subsequent local edits.
-
-## Don't
-
-- Don't edit or import from `node_modules/@agent-native/*/src` at runtime.
-- Don't add `pnpm.overrides`, patches, or resolutions for Agent Native packages.
-- Don't copy Core auth, DB, action, agent-loop, or transport internals.
-- Don't manually copy a first-party unit with a missing recipe; fix its manifest.
-- Don't eject a full package when a prop, slot, wrapper, or smaller unit works.
-- Don't fork feature state into a custom view; consume the feature's controller.
-
-## Related Skills
-
-- `agent-native-docs` — version-matched docs and source lookup
-- `agent-native-toolkit` — shared-vs-app-owned architecture boundary
-- `self-modifying-code` — safe app source edits
-- `upgrade-agent-native` — supported package upgrade path
-- `adding-a-feature` — UI/action/instructions/application-state parity

package/corpus/core/src/templates/chat/.agents/skills/delegate-to-agent/SKILL.md

@@ -1,263 +0,0 @@
----
-name: delegate-to-agent
-description: >-
-  How to delegate all AI work to the agent chat. Use when delegating AI work
-  from UI or scripts to the agent, when a user asks for agent behavior or
-  LLM-powered features, when tempted to add inline LLM calls, or when sending
-  messages to the agent from application code.
-scope: dev
-metadata:
-  internal: true
----
-
-# Delegate All AI to the Agent
-
-## Rule
-
-The UI never calls an LLM directly. Product workflows are delegated to the
-agent through the chat bridge so users can see, steer, and audit the work.
-Server-side one-shot model calls are an explicit escape hatch for narrow text
-transforms only; use `completeText()` from `@agent-native/core/server` when the
-work intentionally does not need tools, chat history, or run state.
-
-## Why
-
-The agent is the single AI interface. It has context about the full project, can read/write any file, and can run scripts. Inline LLM calls bypass this — they create a shadow AI that doesn't know what the agent knows and can't coordinate with it.
-
-## How
-
-**From the UI (client):**
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-
-sendToAgentChat({
-  message: "Generate a summary of this document",
-  context: documentContent, // optional hidden context (not shown in chat UI)
-  submit: true, // auto-submit to the agent
-});
-```
-
-**From the UI, in the background:**
-
-```ts
-import { sendToAgentChat } from "@agent-native/core/client/agent-chat";
-
-sendToAgentChat({
-  message: "Analyze this import and create any missing records",
-  context: `Import batch id: ${batchId}`,
-  submit: true,
-  newTab: true,
-  background: true,
-  openSidebar: false,
-});
-```
-
-This is still a full agent run: tools, actions, thread state, and run tracking
-all remain active. It simply does not focus or open the sidebar.
-
-**From scripts (Node):**
-
-```ts
-import { agentChat } from "@agent-native/core";
-
-agentChat.submit("Process the uploaded images and create thumbnails");
-```
-
-**For narrow server-side text transforms:**
-
-```ts
-import { completeText } from "@agent-native/core/server";
-
-const result = await completeText({
-  systemPrompt: "Return exactly one sentiment label.",
-  input: messageBody,
-  maxOutputTokens: 12,
-  temperature: 0,
-});
-```
-
-Wrap user-facing uses in actions so the UI and agent share the same operation.
-Do not call provider SDKs directly.
-
-**From the UI, detecting when agent is done:**
-
-```ts
-import { useAgentChatGenerating } from "@agent-native/core/client/agent-chat";
-
-function MyComponent() {
-  const isGenerating = useAgentChatGenerating();
-  // Show loading state while agent is working
-}
-```
-
-## `submit` vs Prefill
-
-The `submit` option controls whether the message is sent automatically or placed in the chat input for user review:
-
-| `submit` value | Behavior                                | Use when                                                                            |
-| -------------- | --------------------------------------- | ----------------------------------------------------------------------------------- |
-| `true`         | Auto-submits to the agent immediately   | Routine operations the user has already approved                                    |
-| `false`        | Prefills the chat input for user review | High-stakes operations (deleting data, modifying code, API calls with side effects) |
-| omitted        | Uses the project's default setting      | General-purpose delegation                                                          |
-
-```ts
-// Auto-submit: routine operation
-sendToAgentChat({ message: "Update the project summary", submit: true });
-
-// Prefill: let user review before sending
-sendToAgentChat({
-  message: "Delete all projects older than 30 days",
-  submit: false,
-});
-```
-
-## Capture user input first when generating from a prompt
-
-Buttons that produce new content ("New Design", "Create Dashboard", "Make Deck", "Generate Form") need the user's prompt as input. **Never hardcode a generic message** — the result will be a generic generation the user didn't actually ask for.
-
-**Bad** — auto-submits a placeholder message; the user never said what they wanted:
-
-```tsx
-<Button
-  onClick={() =>
-    sendToAgentChat({ message: "make a design", submit: true })
-  }
->
-  New Design
-</Button>
-```
-
-**Good** — Popover anchored to the button captures the prompt, then submits it:
-
-```tsx
-<Popover open={open} onOpenChange={setOpen}>
-  <PopoverTrigger asChild>
-    <Button>New Design</Button>
-  </PopoverTrigger>
-  <PopoverContent className="w-96">
-    <Textarea
-      autoFocus
-      value={prompt}
-      onChange={(e) => setPrompt(e.target.value)}
-      placeholder="What do you want to design?"
-    />
-    <Button
-      onClick={() => {
-        sendToAgentChat({ message: prompt, submit: true });
-        setOpen(false);
-        setPrompt("");
-      }}
-    >
-      Create
-    </Button>
-  </PopoverContent>
-</Popover>
-```
-
-**Always ask for input first when** the output depends on a prompt the user must provide — "design what?", "deck about what?", "dashboard for which metric?", "form for which use case?".
-
-**Auto-submit without input is fine when intent is unambiguous:**
-
-- "Try to fix" on a tool error — submits the error details with a clear fix instruction
-- "Retry the last operation" after a transient failure
-- Single-purpose buttons where there is nothing meaningful for the user to add
-
-If you find yourself writing `submit: true` with a hardcoded creative verb (`"design a..."`, `"write a..."`, `"build a..."`), stop and add a Popover.
-
-## Delegating to a Sub-Agent (Agent Teams)
-
-`sendToAgentChat()` delegates from app code _to_ the agent. The other axis of
-delegation is the agent handing work _to a sub-agent_ through the Agent Teams
-run-manager. The main chat stays the orchestrator: it spawns sub-agents, then
-reads and integrates their results.
-
-### When to spawn a sub-agent vs do it yourself
-
-- **Do it yourself** when the work is small, on the critical path, or tightly
-  coupled to what you're already doing. Sub-agent overhead and coordination risk
-  outweigh the benefit.
-- **Spawn a sub-agent** for a self-contained unit of work that can run
-  independently — a disjoint investigation, an isolated implementation slice, a
-  long-running search — especially when it frees the main thread to keep
-  orchestrating.
-
-### Briefing contract
-
-Every sub-agent brief must specify four things, or the sub-agent will guess:
-
-- **Objective** — the one concrete outcome it owns, in a sentence.
-- **Context** — the facts it needs (paths, prior findings, constraints) so it
-  doesn't re-derive them.
-- **Output** — the exact shape you want back (a summary, a file edited, a list
-  of paths, a yes/no with rationale).
-- **Boundaries** — what it must NOT touch (files, branches, side effects) and
-  when to stop and report rather than push forward.
-
-### Fan-out discipline
-
-- **Default to a single sub-agent.** Most delegation is one focused task.
-- **Spawn multiple only for genuinely independent units** that don't share state
-  or files. Never parallelize coupled work — if B needs A's output, run them in
-  sequence.
-- **Cap parallel fan-out at ~3.** More sub-agents means more synthesis cost and
-  more chance of conflicting edits to the same area.
-
-### Synthesis discipline
-
-- **Read every result** before concluding — don't act on the first one back.
-- **Reconcile conflicts** between sub-agent findings explicitly; decide which is
-  right rather than averaging or ignoring.
-- **Integrate into one answer.** The main thread produces the single coherent
-  result; it never just forwards raw sub-agent transcripts to the user.
-
-Background sub-agents must use the core run-manager / Agent Teams infrastructure
-rather than ad-hoc LLM calls.
-
-## Don't
-
-- Don't `import Anthropic from "@anthropic-ai/sdk"` in client or server code
-- Don't `import OpenAI from "openai"` in client or server code
-- Don't make direct API calls to any LLM provider
-- Don't use AI SDK functions like `generateText()`, `streamText()`, etc.
-- Don't build "AI features" that bypass the agent chat
-- Don't auto-submit a hardcoded prompt for generative actions — capture user input first (see above)
-- Don't use `completeText()` for workflows that need tools, database writes,
-  auditability, user steering, or multi-step reasoning. Use the agent chat
-  instead, optionally with `background: true`.
-
-## Exception
-
-Scripts may call external APIs (image generation, search, etc.) — but the AI
-reasoning and orchestration still goes through the agent. A script is a tool
-the agent uses, not a replacement for the agent.
-
-`completeText()` is allowed for small server-side transforms such as
-classification, extraction, rewriting a short string, or normalizing messy
-provider text. It deliberately runs with `tools: []` and does not create chat
-thread state.
-
-## When to Use A2A Instead
-
-`sendToAgentChat()` delegates work to the **local** agent — the one running alongside your app. When the work should go to a **different** agent entirely (e.g., asking an analytics agent for data, or a calendar agent for availability), use the A2A (agent-to-agent) protocol instead.
-
-```ts
-import { callAgent } from "@agent-native/core/a2a";
-
-// Call a different agent — not the local agent chat
-const stats = await callAgent(
-  "https://analytics.example.com",
-  "What were last week's signups?",
-  { apiKey: process.env.ANALYTICS_A2A_KEY },
-);
-```
-
-See the **a2a-protocol** skill for the full pattern.
-
-## Related Skills
-
-- **a2a-protocol** — When the work goes to a different agent, not the local one
-- **actions** — The agent invokes actions via `pnpm action <name>` to perform complex operations
-- **self-modifying-code** — The agent operates through the chat bridge to make code changes
-- **storing-data** — The agent writes results to the database after processing requests
-- **real-time-sync** — The UI updates automatically when the agent writes data