self-modifying-code

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.
scope	dev
metadata	{"internal":true}

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:

const el = document.documentElement;
el.dataset.currentView = view;
el.dataset.selectedId = selectedItem?.id || "";

Expose richer context via window.__appState for complex state:

(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).

Keep localized copy in catalogs — When editing visible UI copy, labels, toasts, empty states, prompts, or formatting, read internationalization and update app/i18n/en-US.ts plus existing locale catalogs instead of leaving new inline strings in components.

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

• storing-data — Tier 1 modifications (data files) are the safest and most common
• actions — The agent can create or modify actions to add new capabilities
• delegate-to-agent — Self-modification requests come through the agent chat
• real-time-sync — Database writes trigger change events to update the UI
• internationalization — UI copy, language catalogs, locale switching, and RTL-safe edits