@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/create-skill/SKILL.md

@@ -0,0 +1,221 @@
+---
+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/templates/tasks/.agents/skills/delegate-to-agent/SKILL.md

@@ -0,0 +1,263 @@
+---
+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";
+
+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";
+
+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";
+
+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

package/corpus/templates/tasks/.agents/skills/efficient-fable/README.md

@@ -0,0 +1,75 @@
+# /efficient-fable
+
+Use Claude Fable where it is worth paying for judgment.
+
+`/efficient-fable` helps a Fable-class model orchestrate codebase-heavy work
+without spending premium tokens on every scan, log, browser run, and bounded
+edit. Fable keeps the hard calls: decomposition, architecture, product tradeoffs,
+synthesis, risk, and final review. Lighter agents do the repeatable heavy
+passes.
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="assets/fable-orchestrator-dark.png">
+  <source media="(prefers-color-scheme: light)" srcset="assets/fable-orchestrator.png">
+  <img alt="Fable orchestrator diagram" src="assets/fable-orchestrator.png">
+</picture>
+
+## What It Does
+
+- Splits large work into research, coding, and testing lanes.
+- Tells Fable to choose the strategy, validation direction, and review bar.
+- Encourages cheaper agents to scan repos, summarize docs, reduce logs, run
+  browser checks, and attempt bounded patches.
+- Keeps evidence flowing back to Fable as files, commands, diffs, failures, and
+  uncertainties.
+- Uses self-contained handoff packets so delegated agents can work without
+  hidden context from the orchestrator chat.
+- Reminds Fable to verify important delegated claims before relying on them.
+
+## When To Use It
+
+Use this when the task is too broad for one expensive model pass: unfamiliar
+repos, long test output, multi-file changes, product/architecture ambiguity, or
+validation work that can run in parallel.
+
+Skip it for tiny fixes, highly coupled edits, or judgment-sensitive debugging
+where delegating would create more coordination cost than it saves.
+
+## Testing Guidance
+
+Fable should suggest the validation direction and name the scripts or browser
+flows that matter. Lighter agents can run those checks, collect screenshots,
+reduce logs, and report whether failures look real, flaky, or environmental.
+
+The point is not to outsource responsibility. Fable still decides what signal is
+trustworthy.
+
+## Delegation Quality
+
+Good handoffs include the repo path, exact objective, in-scope and out-of-scope
+areas, expected evidence, verification commands, and stop conditions. A lighter
+agent should know when to stop and report instead of widening the task on its
+own.
+
+Fable should treat delegated reports as leads. For important decisions, it
+reopens the cited files or logs and checks that the evidence really supports the
+claim.
+
+## Diagram
+
+Editable Excalidraw source:
+[`assets/fable-orchestrator.excalidraw`](assets/fable-orchestrator.excalidraw)
+
+Rendered PNGs:
+[`assets/fable-orchestrator.png`](assets/fable-orchestrator.png)
+and
+[`assets/fable-orchestrator-dark.png`](assets/fable-orchestrator-dark.png)
+
+## Install
+
+```sh
+npx @agent-native/skills@latest add --skill efficient-fable --update-instructions
+```
+
+Use `--update-instructions` when you want the Fable delegation convention added
+to `AGENTS.md` or `CLAUDE.md` automatically.

package/corpus/templates/tasks/.agents/skills/efficient-fable/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: efficient-fable
+description: Use when running Claude Fable on codebase-heavy or token-heavy work and the user wants Fable to orchestrate research, coding, and testing while cheaper subagents do bounded heavy lifting.
+---
+
+# Efficient Fable
+
+Use Claude Fable as the orchestrator, architect, synthesizer, and final judge.
+Use cheaper subagents for token-heavy research, coding, testing, and
+summarization that do not require Fable's full judgment.
+
+## Where Fable Shines
+
+Reserve Fable for:
+
+- Decomposing ambiguous work into clean parallel slices.
+- Architecture, product, and safety tradeoffs.
+- Reading conflicting subagent reports and deciding what matters.
+- Integrating partial implementations into one coherent plan.
+- Final review, risk assessment, and user-facing synthesis.
+
+## Delegation Pattern
+
+1. Name the expensive-token risk: large repo search, long logs, broad docs, or
+   repetitive edits.
+2. Split independent work into subagents before reading everything yourself.
+3. Use cheaper models for research scans, inventory, search summaries, narrow
+   bug hunts, browser/testing passes, test output reduction, and bounded code
+   edits.
+4. Ask subagents for concise evidence: files, line references, commands run,
+   diffs, uncertainties, and stop conditions they hit.
+5. Spend Fable tokens on the decision layer: compare results, resolve conflicts,
+   choose the implementation path, and review the final patch.
+
+Prefer parallel subagents when the slices do not depend on each other. Keep
+blocking or highly coupled work local.
+
+## Handoff Packets
+
+Write delegated prompts as if the subagent has no useful chat context. Include
+only the context it needs:
+
+- The repo path and exact objective.
+- The files, packages, or surfaces in scope and anything explicitly out of
+  scope.
+- The evidence format to return: files, line refs, commands, diffs, failures,
+  screenshots, and uncertainty.
+- The verification commands or browser flows to run, plus what success should
+  look like when that is knowable.
+- Stop conditions: if the code does not match the prompt, a command fails after
+  a reasonable retry, or the task needs out-of-scope files, stop and report
+  instead of improvising.
+
+## Vetting Delegated Work
+
+Treat subagent reports as leads, not facts. Before using a high-impact finding,
+opening a PR, or telling the user the work is done, Fable should reopen the
+important cited files, confirm the relevant line refs or failures, and review
+the final diff against the task. Let lighter agents gather signal; keep
+truth-judgment with Fable.
+
+## Common Scenarios
+
+Treat these as soft defaults, not rigid rules:
+
+- Research: ask lighter agents to scan docs, prior art, APIs, and repo surfaces;
+  Fable decides what evidence changes the plan.
+- Coding: give cheaper agents bounded edits or candidate patches; Fable owns
+  shared-file coordination, integration, and final review.
+- Testing: have Fable suggest the validation direction and the scripts or
+  browser checks that matter. Let lighter agents run targeted tests, browser
+  flows, screenshots, and log reduction, then report exact commands, failures,
+  likely causes, and whether failures look flaky, environmental, or real.
+- Debugging: use cheaper agents to cluster logs, reproduce issues, and try
+  small fixes; Fable decides which diagnosis is most trustworthy.
+
+If a task is tiny or the validation itself needs delicate judgment, keep it
+with Fable.
+
+## Diagram
+
+Use `assets/fable-orchestrator.excalidraw` when a visual explanation helps.
+
+## Claims
+
+For codebase-heavy work, it is reasonable to describe this as up to 3-5x more
+cost-efficient and 2-4x faster when independent research, coding, or testing
+slices can run in parallel. Treat those as workload-dependent estimates, not
+guarantees.
+
+Good launch copy:
+
+> Make Claude Fable more efficient by using cheaper subagents for token-heavy
+> research, coding, and testing, saving Fable for judgment, architecture,
+> synthesis, and final review.