@agent-native/core 0.2.7 → 0.3.1

package/src/templates/default/.agents/skills/frontend-design/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: frontend-design
+description: >-
+  Create distinctive, production-grade frontend interfaces with high design
+  quality. Use when building web components, pages, artifacts, posters, or
+  applications (websites, landing pages, dashboards, React components,
+  HTML/CSS layouts, or when styling/beautifying any web UI). Generates
+  creative, polished UI that avoids generic AI aesthetics.
+license: Complete terms in LICENSE.txt
+source: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md
+---
+
+# Frontend Design
+
+This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+
+The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+
+## Design Thinking
+
+Before coding, understand the context and commit to a BOLD aesthetic direction:
+- **Purpose**: What problem does this interface solve? Who uses it?
+- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
+- **Constraints**: Technical requirements (framework, performance, accessibility).
+- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
+
+**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work — the key is intentionality, not intensity.
+
+Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
+- Production-grade and functional
+- Visually striking and memorable
+- Cohesive with a clear aesthetic point-of-view
+- Meticulously refined in every detail
+
+## Frontend Aesthetics Guidelines
+
+Focus on:
+- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
+- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
+- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (`animation-delay`) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
+- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
+- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
+
+## Anti-Patterns to Avoid
+
+NEVER use generic AI-generated aesthetics like:
+- Overused font families (Inter, Roboto, Arial, system fonts)
+- Clichéd color schemes (particularly purple gradients on white backgrounds)
+- Predictable layouts and component patterns
+- Cookie-cutter design that lacks context-specific character
+
+Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+
+## Implementation Notes
+
+**Match implementation complexity to the aesthetic vision.** Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
+
+In the agent-native framework context:
+- Agent-native apps use React 18, Vite, TailwindCSS, and shadcn/ui
+- Custom styles go in component CSS or Tailwind classes — never inline styles
+- For complex visual effects, use a `<style>` tag in the component or a dedicated CSS file
+- Fonts can be loaded from Google Fonts via `@import` in a CSS file or `<link>` in `index.html`
+- Animation libraries: prefer CSS transitions and keyframes; use Framer Motion for complex sequences
+- All new UI components should be placed in `client/components/`
+
+## Related Skills
+
+- **self-modifying-code** — The agent can edit source code to apply design changes
+- **files-as-database** — Design configuration can be stored as JSON in `data/` for agent-editable theming

package/src/templates/default/.agents/skills/scripts/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: scripts
+description: >-
+  How to create and run agent-callable scripts in scripts/. Use when creating
+  a new script, adding an API integration, implementing a complex agent
+  operation, or running pnpm script commands.
+---
+
+# Agent Scripts
+
+## Rule
+
+Complex operations the agent needs to perform are implemented as scripts in `scripts/`. The agent runs them via `pnpm script <name>`.
+
+## Why
+
+Scripts give the agent callable tools with structured input/output. They keep the agent's chat context clean (no massive code blocks), they're reusable, and they can be tested independently.
+
+## How to Create a Script
+
+Create `scripts/my-script.ts`:
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail, agentChat } from "@agent-native/core";
+
+export default async function myScript(args: string[]) {
+  loadEnv();
+
+  const parsed = parseArgs(args);
+  const input = parsed.input;
+  if (!input) fail("--input is required");
+
+  const outputPath = parsed.output ?? "data/result.json";
+  const raw = fs.readFileSync(input, "utf-8");
+  const data = JSON.parse(raw) as unknown;
+
+  fs.writeFileSync(outputPath, JSON.stringify(data, null, 2));
+  agentChat.submit(`Processed ${input}, result saved to ${outputPath}`);
+}
+```
+
+## How to Run
+
+```bash
+pnpm script my-script --input data/source.json --output data/result.json
+```
+
+## Script Dispatcher
+
+The default template uses core's `runScript()` in `scripts/run.ts`:
+
+```ts
+import { runScript } from "@agent-native/core";
+runScript();
+```
+
+This is the canonical approach for new apps. Script names must be lowercase with hyphens only (e.g., `my-script`).
+
+## Guidelines
+
+- **One script, one job.** Keep scripts focused on a single operation. The agent composes multiple script calls for complex operations.
+- **Use `parseArgs()`** for structured argument parsing. It converts `--key value` pairs to a `Record<string, string>`.
+- **Use `loadEnv()`** if the script needs environment variables (API keys, etc.).
+- **Use `fail()`** for user-friendly error messages (exits with message, no stack trace).
+- **Write results to files.** The agent and UI will pick them up via the file watcher.
+- **Use `agentChat.submit()`** to report results or errors back to the agent chat.
+- **Import from `@agent-native/core`** — Don't redefine `parseArgs()` or other utilities locally.
+
+## Common Patterns
+
+**API integration script** (e.g., image generation):
+
+```ts
+import fs from "fs";
+import { parseArgs, loadEnv, fail } from "@agent-native/core";
+
+export default async function generateImage(args: string[]) {
+  loadEnv();
+  const parsed = parseArgs(args);
+  const prompt = parsed.prompt;
+  if (!prompt) fail("--prompt is required");
+
+  const outputPath = parsed.output ?? "data/generated-image.png";
+  const imageUrl = await callImageAPI(prompt);
+  const buffer = await fetch(imageUrl).then((r) => r.arrayBuffer());
+  fs.writeFileSync(outputPath, Buffer.from(buffer));
+}
+```
+
+**Data processing script:**
+
+```ts
+import fs from "fs";
+import { parseArgs, fail } from "@agent-native/core";
+
+export default async function transform(args: string[]) {
+  const parsed = parseArgs(args);
+  const source = parsed.source;
+  if (!source) fail("--source is required");
+
+  const data = JSON.parse(fs.readFileSync(source, "utf-8")) as unknown[];
+  const result = data.map(transformItem);
+  fs.writeFileSync(source, JSON.stringify(result, null, 2));
+}
+```
+
+## Troubleshooting
+
+- **Script not found** — Check that the filename matches the command name exactly. `pnpm script foo-bar` looks for `scripts/foo-bar.ts`.
+- **Args not parsing** — Ensure args use `--key value` or `--key=value` format. Boolean flags use `--flag` (sets value to `"true"`).
+- **Script runs but UI doesn't update** — Make sure results are written to a path under `data/` that the file watcher monitors.
+
+## Related Skills
+
+- **files-as-database** — Scripts read/write data files in `data/`
+- **delegate-to-agent** — The agent invokes scripts via `pnpm script <name>`
+- **sse-file-watcher** — File writes from scripts trigger SSE events to update the UI

package/src/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: self-modifying-code
+description: >-
+  How the agent can modify the app's own source code. Use when the agent needs
+  to edit components, routes, styles, or scripts, when designing UI for agent
+  editability, or when deciding what the agent should and shouldn't modify.
+---
+
+# Self-Modifying Code
+
+## Rule
+
+The agent can edit the app's own source code — components, routes, styles, scripts. This is a feature, not a bug. Design your app expecting this.
+
+## Why
+
+An agent-native app isn't just an app the agent can _use_ — it's an app the agent can _change_. The agent can fix bugs, add features, adjust styles, and restructure code. This makes the agent a true collaborator, not just an operator.
+
+## Modification Taxonomy
+
+Not all modifications are equal. Use this to decide what level of care is needed:
+
+| Tier          | What                  | Examples                                         | After modifying                   |
+| ------------- | --------------------- | ------------------------------------------------ | --------------------------------- |
+| 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
+| 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
+| 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+
+## Git Checkpoint Pattern
+
+Before modifying source code (Tier 2+), create a rollback point:
+
+1. Commit or stash current state
+2. Make the edit
+3. Run `pnpm typecheck && pnpm lint`
+4. If verification fails → revert with `git checkout -- <file>`
+5. If verification passes → continue
+
+This ensures the agent can experiment without breaking the app.
+
+## Designing for Agent Editability
+
+Make your app easy for the agent to understand and modify:
+
+**Expose UI state via `data-*` attributes** so the agent knows what's selected:
+
+```ts
+const el = document.documentElement;
+el.dataset.currentView = view;
+el.dataset.selectedId = selectedItem?.id || "";
+```
+
+**Expose richer context via `window.__appState`** for complex state:
+
+```ts
+(window as any).__appState = {
+  selectedId: id,
+  currentLayout: layout,
+  itemCount: items.length,
+};
+```
+
+**Use configuration-driven rendering** — Extract visual decisions (colors, layouts, sizes) into JSON config files in `data/`. The agent can modify the config (Tier 1) instead of the component source (Tier 2).
+
+## Don't
+
+- Don't modify `.env` files or files containing secrets
+- Don't modify `@agent-native/core` package internals
+- Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
+- Don't skip the typecheck/lint step after editing source code
+- Don't make source changes without a git checkpoint to roll back to
+
+## Related Skills
+
+- **files-as-database** — Tier 1 modifications (data files) are the safest and most common
+- **scripts** — The agent can create or modify scripts to add new capabilities
+- **delegate-to-agent** — Self-modification requests come through the agent chat
+- **sse-file-watcher** — Source and data file edits trigger SSE events to update the UI

package/src/templates/default/.agents/skills/sse-file-watcher/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: sse-file-watcher
+description: >-
+  How to keep the UI in sync with agent changes via Server-Sent Events. Use
+  when setting up real-time file sync, adding SSE to a new data directory,
+  wiring query invalidation for new data models, or debugging UI not updating.
+---
+
+# SSE File Watcher
+
+## Rule
+
+The UI stays in sync with agent changes through Server-Sent Events. When the agent writes a file, the UI updates automatically — no polling, no manual refresh.
+
+## Why
+
+The agent modifies files on disk, but the UI runs in the browser. SSE bridges this gap: a file watcher on the server detects changes, streams them to the browser, and React Query invalidates the relevant caches. This is what makes the "files as database" pattern feel real-time.
+
+## How It Works
+
+1. **Server** watches the data directory with chokidar:
+
+   ```ts
+   import { createFileWatcher, createSSEHandler } from "@agent-native/core";
+   const watcher = createFileWatcher("./data");
+   app.get("/api/events", createSSEHandler(watcher));
+   ```
+
+2. **Client** listens for changes and invalidates React Query caches:
+
+   ```ts
+   import { useFileWatcher } from "@agent-native/core";
+   useFileWatcher({ queryClient, queryKeys: ["files", "projects"] });
+   ```
+
+3. When the agent writes to `data/`, chokidar detects it, SSE pushes the event, and React Query refetches the affected queries.
+
+## Don't
+
+- Don't poll for changes — SSE handles it
+- Don't create per-model `fs.watch()` instances — `createFileWatcher("./data")` watches recursively. One watcher is enough.
+- Don't create your own EventSource connections alongside `useFileWatcher` — use the `onEvent` callback for custom handling
+
+## Query Key Mapping
+
+By default, `useFileWatcher` invalidates all listed query keys on every file change. For apps with multiple data models, this causes unnecessary refetches. Use path-based filtering via the `onEvent` callback:
+
+```ts
+useFileWatcher({
+  queryClient,
+  queryKeys: [], // don't auto-invalidate everything
+  onEvent: (data) => {
+    if (data.path?.includes("projects")) {
+      queryClient.invalidateQueries({ queryKey: ["projects"] });
+    } else if (data.path?.includes("settings")) {
+      queryClient.invalidateQueries({ queryKey: ["settings"] });
+    }
+  },
+});
+```
+
+To prevent cache thrashing during rapid agent writes, set `staleTime` on your queries:
+
+```ts
+useQuery({
+  queryKey: ["projects"],
+  queryFn: fetchProjects,
+  staleTime: 2000, // don't refetch within 2 seconds
+});
+```
+
+## Performance
+
+When the agent writes many files rapidly (e.g., during self-modification), each write fires a chokidar event → SSE broadcast → React Query invalidation. This can cause excessive refetching.
+
+Mitigations:
+
+- Use `staleTime: 2000` on React Query to debounce refetches
+- Use path-based filtering (see Query Key Mapping) to limit which queries invalidate
+
+## Troubleshooting
+
+| Symptom                            | Check                                                                                                           |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------- |
+| UI not updating after agent writes | Is `useFileWatcher` called with the correct `queryClient`? Are the `queryKeys` matching your `useQuery` keys?   |
+| SSE not firing                     | Open browser devtools → Network tab → filter by EventStream. Is `/api/events` connected? Is the server running? |
+| Watcher not detecting changes      | Is the path correct? `createFileWatcher("./data")` is relative to CWD. Check the server's working directory.    |
+| Constant reconnections             | Check for server crashes in terminal output.                                                                    |
+| High CPU / event storms            | The agent is writing many files rapidly. Add `staleTime` to queries and use path-based filtering.               |
+
+## Related Skills
+
+- **files-as-database** — SSE watches the data files that store application state
+- **scripts** — Script outputs written to `data/` trigger SSE events
+- **self-modifying-code** — Agent code edits trigger SSE events; rapid edits can cause event storms

package/src/templates/default/.claude/settings.json

@@ -1,68 +1,86 @@
-{
-  "permissions": {
-    "allow": [
-      "Read",
-      "Edit",
-      "Write",
-      "Glob",
-      "Grep",
-      "Bash(ls *)",
-      "Bash(pwd)",
-      "Bash(echo *)",
-      "Bash(cat *)",
-      "Bash(head *)",
-      "Bash(tail *)",
-      "Bash(find *)",
-      "Bash(wc *)",
-      "Bash(sort *)",
-      "Bash(diff *)",
-      "Bash(which *)",
-      "Bash(mkdir *)",
-      "Bash(cp *)",
-      "Bash(mv *)",
-      "Bash(touch *)",
-      "Bash(node *)",
-      "Bash(npx *)",
-      "Bash(npm *)",
-      "Bash(pnpm *)",
-      "Bash(tsx *)",
-      "Bash(tsc *)",
-      "Bash(vitest *)",
-      "Bash(jest *)",
-      "Bash(eslint *)",
-      "Bash(prettier *)",
-      "Bash(git status*)",
-      "Bash(git log *)",
-      "Bash(git diff *)",
-      "Bash(git show *)",
-      "Bash(git branch*)",
-      "Bash(git add *)",
-      "Bash(git commit *)",
-      "Bash(git checkout *)",
-      "Bash(git switch *)",
-      "Bash(git stash *)",
-      "Bash(git merge *)",
-      "Bash(git rebase *)",
-      "Bash(git pull *)",
-      "Bash(git blame *)",
-      "Bash(git rev-parse *)",
-      "Bash(git remote -v)",
-      "Bash(chmod *)",
-      "Bash(gh *)"
-    ],
-    "deny": [
-      "Bash(rm -rf *)",
-      "Bash(sudo *)",
-      "Bash(git push --force *)",
-      "Bash(git push -f *)",
-      "Bash(git reset --hard *)",
-      "Bash(git clean -f *)",
-      "Bash(dd *)",
-      "Bash(mkfs *)",
-      "Bash(kill -9 *)",
-      "Bash(killall *)",
-      "Bash(shutdown *)",
-      "Bash(reboot *)"
-    ]
-  }
-}
+{
+  "permissions": {
+    "allow": [
+      "Read",
+      "Edit",
+      "Write",
+      "Glob",
+      "Grep",
+      "NotebookEdit",
+      "WebFetch",
+      "WebSearch",
+      "Bash(ls *)",
+      "Bash(pwd)",
+      "Bash(echo *)",
+      "Bash(cat *)",
+      "Bash(head *)",
+      "Bash(tail *)",
+      "Bash(find *)",
+      "Bash(wc *)",
+      "Bash(sort *)",
+      "Bash(uniq *)",
+      "Bash(diff *)",
+      "Bash(which *)",
+      "Bash(env)",
+      "Bash(mkdir *)",
+      "Bash(cp *)",
+      "Bash(mv *)",
+      "Bash(touch *)",
+      "Bash(chmod *)",
+      "Bash(node *)",
+      "Bash(npx *)",
+      "Bash(npm *)",
+      "Bash(pnpm *)",
+      "Bash(yarn *)",
+      "Bash(tsx *)",
+      "Bash(tsc *)",
+      "Bash(vitest *)",
+      "Bash(jest *)",
+      "Bash(eslint *)",
+      "Bash(prettier *)",
+      "Bash(git status*)",
+      "Bash(git log *)",
+      "Bash(git diff *)",
+      "Bash(git show *)",
+      "Bash(git branch*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git checkout *)",
+      "Bash(git switch *)",
+      "Bash(git stash *)",
+      "Bash(git merge *)",
+      "Bash(git rebase *)",
+      "Bash(git pull *)",
+      "Bash(git blame *)",
+      "Bash(git rev-parse *)",
+      "Bash(git worktree *)",
+      "Bash(git remote -v)",
+      "Bash(gh *)",
+      "Bash(curl *)",
+      "Bash(grep *)",
+      "Bash(rg *)",
+      "Bash(sed *)",
+      "Bash(awk *)",
+      "Bash(jq *)",
+      "Bash(rm *)"
+    ],
+    "deny": [
+      "Bash(rm -rf /)",
+      "Bash(rm -rf /*)",
+      "Bash(rm -rf ~)",
+      "Bash(rm -rf ~/*)",
+      "Bash(sudo *)",
+      "Bash(git push --force *)",
+      "Bash(git push -f *)",
+      "Bash(git reset --hard *)",
+      "Bash(git clean -f *)",
+      "Bash(dd *)",
+      "Bash(mkfs *)",
+      "Bash(kill -9 *)",
+      "Bash(killall *)",
+      "Bash(pkill *)",
+      "Bash(shutdown *)",
+      "Bash(reboot *)"
+    ]
+  }
+}

package/src/templates/default/.prettierrc

@@ -1,5 +1,5 @@
-{
-  "tabWidth": 2,
-  "useTabs": false,
-  "trailingComma": "all"
-}
+{
+  "tabWidth": 2,
+  "useTabs": false,
+  "trailingComma": "all"
+}