@agent-native/core 0.101.14 → 0.102.1

package/corpus/templates/tasks/.agents/skills/adding-a-feature/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: adding-a-feature
+description: >-
+  The four-area checklist every new feature must complete. Use when adding any
+  feature, integration, or capability to ensure the agent and UI stay in parity.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Adding a Feature — The Four-Area Checklist
+
+## Rule
+
+Every new feature MUST update all four areas. Skipping any one breaks the agent-native contract — the agent and UI must always be equal partners.
+
+## Why
+
+Agent-native apps are defined by parity: everything the UI can do, the agent can do, and vice versa. A feature that only has UI is invisible to the agent. A feature that only has scripts is invisible to the user. A feature without app-state sync means the agent is blind to what the user is doing.
+
+## The Checklist
+
+When you add a new feature, work through these four areas in order:
+
+### 1. UI Component
+
+Build the user-facing interface — a page, component, dialog, or route. Use `useActionQuery` and `useActionMutation` from `@agent-native/core/client` to call actions for data fetching and mutations. Do not create a custom REST endpoint just so React can call action-backed data; the action endpoint already exists.
+
+**Auto-refresh on agent writes is non-negotiable** — when the agent mutates data, the UI must reflect the change without a manual refresh. There are two paths, and you must pick the right one:
+
+- **`useActionQuery` / `useActionMutation`** — covered automatically. The framework's `useDbSync` invalidates `["action"]` on every change event, so every `useActionQuery` hook refetches on agent activity. No extra wiring required. **Prefer this path.**
+- **Raw `useQuery` with custom keys** — needs explicit wiring. Fold `useChangeVersions([<source>, "action"])` from `@agent-native/core/client` into the `queryKey` and set `placeholderData: (prev) => prev`. The `action` source is the reliable signal (the agent runner emits it after every successful tool call); the resource-specific source (`"dashboards"`, `"analyses"`, `"settings"`, etc.) is bonus when emitted. Without this wiring, agent writes will be invisible until manual refresh — that breaks the framework's #1 promise.
+
+  ```tsx
+  import { useChangeVersions } from "@agent-native/core/client";
+  import { useQuery } from "@tanstack/react-query";
+
+  const v = useChangeVersions(["dashboards", "action"]);
+  useQuery({
+    queryKey: ["dashboard", id, v],
+    queryFn: () => fetchDashboard(id),
+    placeholderData: (prev) => prev, // no flicker on refetch
+  });
+  ```
+
+  See the `real-time-sync` skill for the full pattern and source catalog.
+
+### 2. Action
+
+Create an action in `actions/` using `defineAction`. This serves double duty: the agent calls it as a tool, and the UI calls it through `useActionQuery` / `useActionMutation` while the framework owns the HTTP transport. Set `http: { method: "GET" }` for read actions, leave default for writes, or set `http: false` for agent-only actions like `navigate` and `view-screen`.
+
+Before adding a new route or endpoint, inspect the existing actions. Reuse an
+action if it already covers the business operation, extend it if the shared
+contract is incomplete, or create a new `defineAction` if the agent and UI both
+need the capability. Do not add pass-through `/api/*` routes that re-export
+actions. If client code needs a new framework/app route, expose a named helper
+or hook first and use that helper from components and docs.
+
+For provider-backed analysis/query/reporting integrations, do not turn every
+provider endpoint or filter into a rigid action. Prefer the shared
+`provider-api-catalog` / `provider-api-docs` / `provider-api-request` pattern
+from `@agent-native/core/provider-api`, then add narrow convenience actions only
+for workflows that truly deserve a first-class shortcut. Treat this as a
+capability requirement, not a nice-to-have: convenience actions must not become
+the ceiling of what the agent can ask the provider to do. Pair broad provider
+access with staging or sandboxed code execution when responses may be too large
+for chat context. If provider credentials live on resource/share rows, add the
+scoped resolver first so broad access preserves the same ownership boundary as
+the app UI.
+
+If the feature needs credentials, design the credential path in the same change.
+Never hardcode API keys, tokens, webhook URLs, signing secrets, private
+Builder/internal data, or customer data in the action, UI, seed data, fixtures,
+docs, prompts, or generated extension/app content. Register required secrets,
+use OAuth helpers, or read scoped values from the vault/credential store.
+
+If the feature involves attachments, images, recordings, screenshots, exports,
+or other file-like payloads, design the upload path in the same change:
+provider upload first, then URL/id/blob handle in SQL. Do not add base64/binary
+columns or stuff files into `application_state`.
+
+**If the action produces or lists a navigable resource**, add a `link` builder that returns `{ url: buildDeepLink({ app, view, params }), label }`. External coding agents and MCP hosts (Claude / ChatGPT / Claude Code / Cowork / Codex, over MCP/A2A) then surface an "Open in … →" deep link that drops the user back into the running UI focused on the record — for free. If a compatible MCP host should render an inline review/edit surface, also add `mcpApp` with `embedApp()` so the action embeds the real React app route instead of a one-off HTML UI. The `link` builder and `mcpApp` metadata must be pure and synchronous (no I/O). Any external-agent read/ingest action must be `http: { method: "GET" }` + `readOnly: true` + `publicAgent: { expose: true, readOnly: true, requiresAuth: true }`. See the `external-agents` skill.
+
+### 3. Skills / Instructions
+
+Update `AGENTS.md` and/or create a skill in `.agents/skills/` if the feature introduces patterns the agent needs to know. At minimum, add the new actions to the action table in the template's `AGENTS.md`.
+
+Reusable actions are part of the app contract, not just implementation detail. When an action is useful outside one screen, update agent instructions in the same change so app agents know when to call it, which arguments matter, and what output to preserve. If the capability is workflow-heavy, cross-app, provider-backed, or has a non-obvious sequence of actions, add or update a skill instead of burying the behavior in one long `AGENTS.md` paragraph.
+
+Instruction examples may name secret keys like `SLACK_WEBHOOK`, but must use
+placeholders such as `${keys.SLACK_WEBHOOK}` or `<SLACK_WEBHOOK>`. Do not paste
+real keys, internal data, or customer data into instructions as examples.
+
+If the feature adds or changes visible UI copy, prompts, toasts, labels, empty
+states, or formatting, read `internationalization` and update the app's i18n
+catalogs in the same change.
+
+For app-backed skills, declare skill visibility in the app-skill manifest:
+
+- `internal` — only the app's own agents should use it.
+- `exported` — marketplace installs receive it, but the app does not need it loaded internally.
+- `both` — shared between the app's internal agents and exported marketplace bundles.
+
+### 4. Application State Sync
+
+Expose navigation and selection state so the agent knows what the user is looking at. Write to the `navigation` app-state key on route changes. Update the `view-screen` action to fetch relevant data for the new feature. Add a `navigate` command if the agent needs to open the new view.
+
+## Examples
+
+### Adding "compose email" to a mail app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Compose panel with tabs, to/cc/bcc fields, body editor. Use `useActionQuery`/`useActionMutation` for data. |
+| Action          | `manage-draft` action (create/update/delete drafts), `send-email` action                 |
+| Skills/AGENTS   | Document compose state shape, draft lifecycle, action args in AGENTS.md                  |
+| App-state sync  | `compose-{id}` keys for each draft tab, `navigation` includes compose state              |
+
+### Adding "create form" to a forms app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | Form builder page with drag-and-drop fields, preview, settings. Use `useActionQuery` for lists. |
+| Action          | `create-form` action, `update-form` action, `list-forms` action (GET)                    |
+| Skills/AGENTS   | Document form schema shape, field types, validation rules in AGENTS.md                   |
+| App-state sync  | `navigation` includes `{ view: "form-builder", formId: "..." }`, `view-screen` fetches form data |
+
+### Adding "chart type" to an analytics app
+
+| Area            | What to build                                                                            |
+| --------------- | ---------------------------------------------------------------------------------------- |
+| UI              | New chart component, chart type selector in dashboard                                    |
+| Action          | `create-chart` or `update-dashboard` action that sets chart type and config              |
+| Skills/AGENTS   | Document supported chart types, config options, data requirements                        |
+| App-state sync  | `navigation` includes selected chart/dashboard, `view-screen` returns chart config       |
+
+## Adding a new route
+
+Templates are single-page apps with client-side routing. The app shell (AgentSidebar + top-level nav) MUST persist across navigation — it is mounted once, either in `root.tsx` around `<Outlet />` or via a pathless `_app.tsx` layout route that all authed routes nest under.
+
+**Never wrap each new route in its own `<AppLayout>` / `<Layout>`.** That causes React to unmount the entire app shell on every navigation, reloading the agent sidebar and destroying in-progress work.
+
+- If the template has `<AppLayout>` in `root.tsx` — just render page content in your new route file, nothing else.
+- If the template has `app/routes/_app.tsx` (pathless layout) — name your new route `_app.<segment>.tsx` to inherit the shell, or bare `<segment>.tsx` for public routes that should NOT have the shell.
+- If a page needs per-route data (e.g. highlighting the active item in the sidebar), read it in the layout from `useParams()` / `useLocation()`. Don't pass it as a prop through every route file.
+
+See the "Client-Side Routing" section in the root `CLAUDE.md` for full details.
+
+## Anti-Patterns
+
+- **Per-route `<AppLayout>` wrappers** — Every route file wraps its content in `<AppLayout>` or `<Layout>`. React sees a different component at the outlet on each nav and unmounts the whole shell, causing the agent sidebar to reload on every click. Mount the shell once above `<Outlet />` (root.tsx or `_app.tsx` pathless layout).
+- **UI without actions** — The user can create forms but the agent cannot. The agent says "I don't have access to that" when it should be able to do it.
+- **Actions without AGENTS.md** — The actions exist but the agent doesn't know about them because they're not documented. The agent reinvents solutions instead of using the actions.
+- **Duplicate API routes** — Creating `/api/` routes for operations that actions already handle, including pass-through routes that just call or repackage an action. Use `useActionQuery`/`useActionMutation` instead.
+- **Raw client route calls** — Teaching or adding `fetch("/_agent-native/...")`,
+  `fetch(agentNativePath(...))`, or template `/api/*` calls in components for
+  normal app work. Add a named client helper/hook and call that instead.
+- **Features without app-state** — The agent cannot see that the user is looking at a specific form, email, or chart. It asks "which one?" instead of acting on the current selection.
+- **Actions without UI** — The agent can do something the user cannot. This is less common but still breaks parity.
+
+## Verification
+
+After completing all four areas, verify:
+
+1. Can the user perform the operation from the UI?
+2. Can the agent perform the same operation via actions?
+3. Does `pnpm action view-screen` show the relevant state when the user is using the feature?
+4. Can the agent navigate to the feature view via the `navigate` action?
+5. Is the feature documented in AGENTS.md with action names and args?
+6. Are credentials and sensitive data supplied only through approved runtime
+   channels, with no hardcoded real keys, tokens, webhook URLs, Builder/internal
+   data, or customer data?
+
+## One more area — sharing
+
+If the feature stores **user-authored resources** (documents, dashboards, forms, decks, etc.), make them ownable so they get private-by-default semantics and a share dialog for free. See the `sharing` skill.
+
+TL;DR: spread `ownableColumns()` into the resource table, pair it with `createSharesTable(...)`, call `registerShareableResource(...)`, wrap list/read queries with `accessFilter`, guard writes with `assertAccess`, and drop `<ShareButton>` in the resource header. The `share-resource`, `unshare-resource`, `list-resource-shares`, and `set-resource-visibility` actions are auto-mounted framework-wide.
+
+## Related Skills
+
+- **sharing** — How to make a new resource ownable (private by default, share with users/orgs/public)
+- **context-awareness** — How to expose UI state to the agent (area 4 in detail)
+- **actions** — How to create actions with `defineAction` and the `http` option (area 2 in detail)
+- **external-agents** — Add a `link` builder so external agents (MCP/A2A) get an "Open in … →" deep link
+- **create-skill** — How to create skills for new patterns (area 3 in detail)
+- **storing-data** — Where to store the feature's data
+- **real-time-sync** — How the UI stays in sync when the agent writes data
+- **internationalization** — How to update localized UI copy and catalogs

package/corpus/templates/tasks/.agents/skills/agent-native-docs/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: agent-native-docs
+description: >-
+  How to find version-matched Agent Native framework docs and source bundled in
+  node_modules. Use before implementing or answering questions about
+  @agent-native/core APIs, generated apps, workspaces, templates, or advanced
+  features.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Agent Native Docs Lookup
+
+## Rule
+
+Before implementing or explaining non-trivial Agent Native behavior, read the
+version-matched docs installed with `@agent-native/core`. When examples,
+imports, or implementation details matter, inspect the packaged source corpus
+too.
+
+## Why
+
+Generated apps and workspaces may be on a different framework version than the
+public docs or model memory. The installed package is the source that matches
+the app in front of you. It also includes a source-only corpus of core and
+first-party templates so agents can replicate current best-practice patterns
+without needing the framework monorepo checkout.
+
+## How
+
+From a generated app directory:
+
+```bash
+pnpm action docs-search --query "<feature>"
+pnpm action docs-search --slug <slug>
+pnpm action docs-search --list
+pnpm action source-search --query "<pattern>"
+pnpm action source-search --path templates/plan/AGENTS.md
+pnpm action source-search --list
+```
+
+The headless `pnpm agent` loop and built-in app agent also expose a read-only
+`docs-search` tool with the same `query`, `slug`, and `list` options, plus a
+read-only `source-search` tool with `query`, `path`, and `list`.
+
+If the action runner is unavailable, search the package directly:
+
+```bash
+rg -n "actions|automations|a2a|sharing" node_modules/@agent-native/core/docs
+rg -n "defineAction|useActionQuery" node_modules/@agent-native/core/corpus
+```
+
+Then read `node_modules/@agent-native/core/docs/AGENTS.md` or the matching file
+under `node_modules/@agent-native/core/docs/content/`. For source examples,
+read files under `node_modules/@agent-native/core/corpus/core/` or
+`node_modules/@agent-native/core/corpus/templates/`.
+
+## Useful Slugs
+
+| Need | Slugs |
+| --- | --- |
+| Actions and typed client calls | `actions`, `client` |
+| SQL, auth, access, sharing | `database`, `authentication`, `security`, `sharing` |
+| UI state visible to the agent | `context-awareness` |
+| Headless and chat-first apps | `pure-agent-apps`, `agent-surfaces`, `using-your-agent` |
+| Automations and schedules | `automations`, `recurring-jobs` |
+| Cross-app and external agents | `a2a-protocol`, `external-agents`, `mcp-protocol`, `mcp-apps` |
+| Skills and instructions | `skills-guide`, `writing-agent-instructions` |
+
+## Don't
+
+- Do not rely on memory for framework APIs when package docs are present.
+- Do not add custom REST wrappers for app data before reading `actions`.
+- Do not add inline LLM calls before reading `using-your-agent` and
+  `agent-surfaces`.

package/corpus/templates/tasks/.agents/skills/agent-watchdog/README.md

@@ -0,0 +1,43 @@
+# /agent-watchdog
+
+Audit another agent's work from a session, transcript, PR, branch, or run
+summary.
+
+`/agent-watchdog` is for the common handoff where one agent needs to watch
+another agent finish, then check whether the work actually matches what was
+asked.
+
+## What It Does
+
+- Resolves Codex, Claude Code, PR, branch, transcript, or pasted run artifacts.
+- Waits for completion when the user asks to watch.
+- Reconstructs the original request and later scope changes.
+- Checks the agent's claims against diffs, files, tests, CI, screenshots, and
+  review state.
+- Reports gaps, weak verification, scope drift, and residual risk.
+- Makes narrow fixes when the user explicitly authorizes repair.
+
+## When To Use It
+
+Use it when a user says things like:
+
+- "Watch this session until done and audit it."
+- "Claude finished, check what it did and fix gaps."
+- "Compare these two agents' work."
+- "Babysit this PR and make sure the agent actually handled the feedback."
+
+Skip it for normal code review when there is no other agent session or run to
+audit.
+
+## Modes
+
+- Watch only: monitor and report, no edits.
+- Audit: inspect the work and produce a gap report, no edits.
+- Audit and fix: repair clear gaps with targeted validation.
+- Compare: evaluate multiple sessions against the same request.
+
+## Install
+
+```sh
+npx @agent-native/skills@latest add --skill agent-watchdog
+```

package/corpus/templates/tasks/.agents/skills/agent-watchdog/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: agent-watchdog
+description: Use when asked to watch, babysit, audit, review, compare, or fix another agent's work from a Codex session ID, Claude Code session/transcript, chat/thread link, PR, branch, log, or pasted run summary. Monitor until the other agent is done or blocked, reconstruct what the user asked, inspect what the agent actually changed and verified, report gaps, and optionally make scoped fixes when the user authorizes repair.
+---
+
+# Agent Watchdog
+
+Watch another agent's work like a reviewer with a pager: wait for completion
+when needed, reconstruct the request, verify the evidence, and close the gap
+between what was asked and what actually happened.
+
+## Choose The Mode
+
+Infer the mode from the user's wording:
+
+- **Watch only:** monitor a session, PR, branch, CI run, or transcript until it
+  reaches a terminal state. Do not edit files.
+- **Audit:** read the prompt, transcript, diff, tests, CI, comments, screenshots,
+  or final claims and return a gap report. Do not edit files.
+- **Audit and fix:** audit first, then make narrow fixes for clear gaps. Avoid
+  broad rewrites, branch movement, or speculative changes.
+- **Compare:** when given multiple sessions or agents, compare their work against
+  the same original request and reconcile the important differences.
+
+If authority is unclear, default to audit-only and say what you would fix.
+
+## Resolve The Target
+
+1. Identify every artifact the user supplied: session ID, transcript path,
+   thread URL, PR, branch, commit, CI run, issue, Slack link, or pasted summary.
+2. Use the host's native thread/history tools, local transcript files, repo
+   logs, GitHub tools, or pasted content to resolve the artifact. Prefer the
+   most direct source over summaries.
+3. If the artifact is still running and the user asked to watch, poll at a
+   reasonable interval until it is done, blocked, stale, or clearly waiting on a
+   human/external system.
+4. If the artifact cannot be resolved, ask for the missing identifier or path.
+
+## Reconstruct The Contract
+
+Build a compact contract before judging the work:
+
+- Original user request and any later changes in scope.
+- Explicit constraints: branch rules, no-edit requests, deadlines, package
+  versions, validation expectations, design requirements, or security/privacy
+  limits.
+- Implied acceptance criteria: user-visible behavior, tests, CI, docs, deploys,
+  screenshots, review replies, or status updates.
+- The other agent's final claims and any "could not do" caveats.
+
+Treat the user's request as the source of truth, not the other agent's summary.
+
+## Audit The Evidence
+
+Inspect evidence, not vibes:
+
+- Read changed files and relevant unchanged files around the touched paths.
+- Check git status/diff without reverting unrelated work.
+- Compare commands the agent claimed to run with actual output when available.
+- Inspect failed or skipped tests, CI logs, browser screenshots, review
+  comments, deploy output, and error traces.
+- For PR/review work, verify unresolved threads and CI state from the source
+  system when tools are available.
+- For UI work, prefer screenshots or browser checks over prose claims.
+
+Classify each issue as:
+
+- **Gap:** requested behavior is missing or incomplete.
+- **Bug:** the implementation likely fails or regresses behavior.
+- **Verification miss:** the work may be right but the evidence is weak.
+- **Scope drift:** the agent changed something unrelated or skipped a constraint.
+- **No issue:** the concern is already handled, with evidence.
+
+## Fix Narrowly
+
+When the user authorized repair:
+
+1. Fix only gaps with clear evidence.
+2. Preserve unrelated local changes and do not move branches unless explicitly
+   asked for that branch operation.
+3. Use existing repo patterns and targeted tests.
+4. Re-run the smallest useful validation after each meaningful fix.
+5. If a fix would require a product decision, credential, destructive action, or
+   broad rewrite, stop and report the decision instead of guessing.
+
+## Report
+
+Lead with the outcome. Keep the report short enough to scan:
+
+```md
+Status
+- Done, blocked, stale, or still running.
+
+Requested
+- What the user asked the watched agent to do.
+
+Observed
+- What the watched agent changed, claimed, and verified.
+
+Gaps
+- Missing behavior, bugs, weak verification, or scope drift.
+
+Fixes made
+- Files changed and validation run. Omit this section for audit-only work.
+
+Remaining risk
+- Anything still unverified or waiting on CI/review/deploy/human input.
+```
+
+Name exact files, commands, PRs, or thread IDs when they matter.

package/corpus/templates/tasks/.agents/skills/agent-watchdog/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Agent Watchdog"
+  short_description: "Audit another agent session and fix gaps."
+  default_prompt: "Use $agent-watchdog to watch or audit an agent session, then report or fix gaps."

package/corpus/templates/tasks/.agents/skills/capture-learnings/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: capture-learnings
+description: >-
+  Capture and apply accumulated knowledge via structured memory. Use when the
+  user gives feedback, shares preferences, corrects a mistake, or when you
+  discover something worth remembering for future conversations.
+user-invocable: false
+metadata:
+  internal: true
+---
+
+# Capture Learnings
+
+This is background knowledge, not a slash command. **Organization learnings and your personal memory index are loaded at the start of every conversation, including Slack/integration turns.** Capture durable context proactively when you learn something worth remembering.
+
+## How to Read & Write Memories
+
+Memories are stored as **resources** in the SQL database, not as files on disk.
+
+- **Team/organization knowledge:** shared `LEARNINGS.md`. Read it first, merge the new fact, then write the full updated file with the `resources` tool using `scope: "shared"`. Shared scope resolves to the active organization; it must never leak to another organization in the same deployment.
+- **Personal knowledge:** `memory/MEMORY.md` plus `memory/<name>.md`, written with `save-memory`.
+
+- **Save a memory:** `save-memory --name <name> --type <type> --description "..." --content "..."`
+- **Read a memory:** `resource-read --path memory/<name>.md`
+- **Delete a memory:** `delete-memory --name <name>`
+- **List all memories:** `resource-list --prefix memory/`
+
+## Memory Types
+
+| Type | Use for |
+|------|---------|
+| `user` | Preferences, role, personal context, contacts |
+| `feedback` | Corrections, confirmed approaches, things to avoid or repeat |
+| `project` | Ongoing work context, decisions, deadlines, status |
+| `reference` | Pointers to external systems, URLs, API details |
+
+## When to Capture
+
+### Team and organization knowledge (`LEARNINGS.md`, shared scope)
+- Canonical destinations and workflows (for example, which Content database receives a type of Slack request)
+- Required intake fields, ownership, prioritization conventions, metric definitions, and approved terminology
+- Durable external references that the whole team needs, including the canonical page/database URL
+- Corrections or decisions that should affect every organization member's future Slack and app conversations
+
+Store the fact and a concise provenance link when available. Do not paste full private conversations, customer data, credentials, or secrets into learnings. Put stable always-on policy in shared `AGENTS.md`; put learned facts and evolving conventions in shared `LEARNINGS.md`.
+
+### User Preferences & Memory (`user`)
+- **Tone and style** — "I prefer casual tone", "don't use emojis", "keep replies short"
+- **Personal context** — contacts, relationships, habits ("my wife's email is...", "I'm in PST timezone")
+- **Workflow preferences** — "always CC my assistant", "I like to review before sending"
+- **Role and expertise** — "I'm a data scientist", "new to React"
+
+### Feedback & Corrections (`feedback`)
+- **Corrections** — user says "no, do it this way" → capture the right way
+- **Confirmed approaches** — user validates a non-obvious choice ("yes, that's perfect")
+- **Repeated friction** — you hit the same issue twice; save it
+
+### Project Context (`project`)
+- **Ongoing work** — who is doing what, why, by when
+- **Decisions** — why something is done a certain way
+- **Status** — current state of initiatives
+
+### References (`reference`)
+- **External systems** — "bugs are tracked in Linear project INGEST"
+- **URLs** — dashboards, documentation, tools
+- **API quirks** — undocumented behavior, version-specific gotchas
+
+### Don't Capture
+- Things obvious from reading the code
+- Standard language/framework behavior
+- Temporary debugging notes
+- Anything already in AGENTS.md, shared LEARNINGS.md, or skills
+- Ephemeral task details (use tasks/plans instead)
+
+## Key Rules
+
+1. **Save proactively — don't ask permission.** When you learn something durable, save it immediately at the correct scope.
+2. **Choose scope by audience.** Organization workflow or reference → shared `LEARNINGS.md`; one person's preference/context → personal memory.
+3. **One memory per topic** — e.g. `coding-style`, `project-alpha`, not one giant dump
+4. **Read before updating** — if a memory exists, read it first and merge, don't overwrite
+5. **Keep descriptions concise** — the index is loaded every conversation
+6. **Memories are SQL-backed** — they persist across sessions and are not in git; still minimize sensitive content
+
+## Graduation
+
+When a memory is referenced repeatedly, it may belong in AGENTS.md or a skill:
+- Saving a personal memory is lightweight (auto-apply, personal scope)
+- Shared LEARNINGS.md is the lightweight organization knowledge layer
+- Updating AGENTS.md or a skill is heavier (affects all users/agents)

package/corpus/templates/tasks/.agents/skills/change-summary/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: change-summary
+description: >-
+  End agent responses that include code changes with a Change summary table
+  (Code / Tests / Config / Docs) and per-file line counts from git diff.
+metadata:
+  internal: true
+---
+
+# Change Summary
+
+When you modify this repo, **end every response that includes code changes** with a **Change summary** section.
+
+## Required format
+
+Split the summary into four buckets. Omit a bucket only when nothing changed in it.
+
+```md
+## Change summary
+
+### Code
+| File | + | − |
+|------|---|---|
+| `path/to/file.ts` | 12 | 3 |
+
+**Subtotal:** +N −M across K files
+
+### Tests
+| File | + | − |
+|------|---|---|
+| `path/to/file.test.ts` | 4 | 1 |
+
+**Subtotal:** +N −M across K files
+
+### Config
+| File | + | − |
+|------|---|---|
+| `server/plugins/db.ts` | 1 | 1 |
+
+**Subtotal:** +N −M across K files
+
+### Docs
+| File | + | − |
+|------|---|---|
+| `AGENTS.md` | 2 | 2 |
+
+**Subtotal:** +N −M across K files
+
+**Total:** +N −M across K files
+```
+
+## How to classify files
+
+| Bucket | Include |
+|--------|---------|
+| **Code** | `actions/*.ts` (non-test), `app/**`, `server/**` except test-only helpers |
+| **Tests** | `**/*.test.ts`, `**/test-*.ts`, in-memory test DB SQL in `server/db/test-tasks-table.ts` |
+| **Config** | DB migrations and table defs (`server/plugins/db.ts`, `server/db/schema.ts`), `package.json`, `tsconfig*.json`, `vite.config.*`, CI/workflow YAML, env templates |
+| **Docs** | `*.md`, skill files under `.agents/skills/` and `.claude/skills/` |
+
+New untracked files: list under the right bucket with **+lines 0** (all lines are additions).
+
+Renames/deletes: show the old path with deletions and the new path with additions, or one row with net +/−.
+
+## How to compute counts
+
+Prefer git over guessing:
+
+```bash
+git diff --numstat
+git status --short   # for untracked files
+wc -l <new-file>     # line count for new files
+```
+
+Use line counts from `git diff --numstat` (added, removed). Do not approximate from memory.
+
+## When to include it
+
+- Always after implementation, refactor, or fix commits in the working tree.
+- Skip only for pure Q&A with **no** file edits.
+- If the user asked only for a review with no changes, skip the summary.
+
+Place the change summary **before** the final 🟢/🟡/🔴 status line.