modify

# Modify You are changing an EXISTING app. Everything in the **creator** skill applies (ownership rule, modules-before-entities, schema/operations/UI order, the Agent App Quality Standard, honesty rule) — this skill covers only what differs. The Quality Standard (`../QUALITY.md`) applies to every change: a modification that leaves a screen below the standard — or drags one below it — comes back from the verifier as a defect. Changed screens use the app's existing design tokens and components; a change that introduces a second visual system is a defect, not a refresh. If the change must break a specific item, record the item number and reason in `### Conventions and overrides` (Part B, `## Quality Conformance`) in `reference/requirements.md`, exactly as at creation. A change that alters a Quality Conformance decision updates that Q-entry in the same edit — the entries describe the app as it IS. ## First, route the request Decide per request — nothing is routed in advance. A **data change** (create/update/delete records, invoke an operation) is *operation*, not modification: use the **operator** skill directly, no rebuild. A **code change** (new feature, entity, operation, or UI change) continues below. ## Step 0: Locate and understand 1. Use the project directory you were given; read `reference/blueprint.md` (your stack's map — files, schema/migration API, operations, UI, gate), `AGENT_APP.md` (current plan/entities/operations) and `reference/requirements.md`. Read `manifest.json` for `authMode` and port. Not given a directory? `agent-app list` shows every known app with its path, port, and status, and commands accept a registered app id or name wherever they accept a directory. Also read `agent-app global` — the user's cross-app conventions apply to changes too, with this app's `reference/requirements.md` winning any conflict. A global rule (ticked or user-written) that touches what you are changing gets mirrored into `### Conventions and overrides` (Part B, `## Quality Conformance`) if it is not there yet — the verifier reads only the app's spec and the Quality Standard. 2. If something broke, **read the logs FIRST** before changing anything — the real cause is in them, not in your guess. 3. If the request is ambiguous, ask one batch of clarifying questions, then wait. 4. **Record the request in the spec BEFORE editing code**: append a dated entry to `reference/requirements.md` under a `## Changes` section (create it if absent), stated as a checkable capability: `- 2026-01-15: the user can archive a board`. NEVER rewrite the existing sections — they are the delivered contract; `## Changes` is append-only. The verifier checks every entry there, so an unrecorded change is an unverified change (and a recorded one can never be silently dropped by a later modify). - **Supersession — the one permitted edit to old entries**: when the new request REVERSES or REPLACES an earlier `## Changes` entry (the user changed their mind, or the old entry demanded an approach the platform now rejects), wrap the stale entry in `~~strikethrough~~` — do not delete it (it stays as history) and do not leave it live (the verifier enforces every unstruck line, and contradictory live entries make the spec unsatisfiable: an app once went STUCK three times because old entries demanded a handler the gate forbids while the new entry forbade it — no code could satisfy both). Strike ONLY entries the new request genuinely contradicts, never entries you merely failed to build. 5. **Append the work to `reference/tasks.md`** before coding it: one task per `## Changes` entry (or coherent group), citing the entry — `- [ ] T-n (Changes 2026-01-15): …`. Tick on completion; completed tasks are never deleted. The gate requires the ledger; the recorded-then-built order is what keeps the spec, the tasks, and the code telling one story. ## Rules for changing a live app - **Ownership is unchanged**: edit only your app/View code, schema migrations (NEW files only — never edit, rename, or delete an applied migration: the filename is its identity in the live DB, and a renamed one makes the app unable to boot), operation implementations, non-system `operations.json`, your app's declared event types, and `AGENT_APP.md`. Adding an app→agent trigger: declare the event type first, where your blueprint declares them — an undeclared type is refused at the moment of firing, inside the operation, in front of a user. Removing one is a breaking change for anything polling that capability. - **Schema changes are additive migrations.** The user's data is live — never delete it, never drop-and-recreate collections that hold data. To alter a collection, write a new migration that loads and updates it. (Migration API and relation-field rules: see `reference/blueprint.md`.) - **On a multi-user app, every new entity is scoped.** Decide whose records it holds exactly as the creator skill says: a person's own data is scoped to the signed-in person, nothing is readable without signing in, and never a public (`""`) rule. Switching an app to `multi-user` means deciding whose every existing record is first. The gate fails an entity a stranger can read. - Record the delta in `AGENT_APP.md` (what changed, new modules/entities/operations). - **Adding an entity or operation? Name its module first.** Every one belongs to exactly one declared module (`manifest.json`), and an operation also needs typed `params` — plus `entity` and optionally `appliesWhen` when it acts on a record. The gate rejects a declaration that names no module or an undeclared one. - **When a module outgrows its screen, split it.** Every describe level is capped at 2,000 characters and the gate walks the running app to check it. Growth means adding and splitting modules; lengthening a flat list is not an option the gate will accept. Record the split in `## Modules` in `AGENT_APP.md`, in the spec's `## System Overview` map, and regroup the affected Features under the new `### Module:` headings. ## Finish ``` agent-app <dir> dev # boot the CANDIDATE on a hidden port with a fresh DB agent-app <dir> validate # the gate — measures the dev instance, records the gate pass # then the walk-verify skill — the verifier drives the dev URL agent-app <dir> stop # stop the LIVE app (promote refuses while it serves; dev stays up) agent-app <dir> promote # requires the gate pass; backup, apply migrations, destroy dev agent-app <dir> serve # bring the changed app back up agent-app <dir> open # and show it to the user (see below) ``` **How the dev environment works — read this once, it removes all guesswork:** - **Nothing is copied. Your edits ARE the running candidate.** `dev` boots the project's own tree a second time on a hidden port with a fresh database and `A2APP_ENV=dev`. The live app (if serving) keeps running the code and View it loaded at its own boot, untouched — edit freely while the user works. - **The dev database is disposable and rebuilt from your migrations on every `dev`.** Only data your migrations seed exists; live data is NEVER cloned in. Reference data the app needs must be seeded in a migration (it survives promote); test records you create through the dev app are thrown away with the instance. Each `dev` re-proves the whole migration chain from empty. - **While the dev instance is up, every operate command targets IT automatically** — `a2app <dir> …`, `data`, and `validate`'s budget walk. You never pass the hidden port yourself (it is in `dev` output and `.a2app/dev.json` when a browser needs it). If the instance died, operate commands refuse loudly with the remedy — they never silently fall back to live, so test writes cannot leak into user data. - **View edits are hot on dev** (refresh the page); **backend/hook edits need `agent-app <dir> dev` again** (a fresh boot is cheap and re-proves the chain). The live app serves a boot-time snapshot of the View, so nothing you edit reaches users until promote + serve. - **`promote` refuses without a fresh gate pass.** `validate` records a pass bound to the exact tree it gated, and only counts as promotable when the budget walk ran against the dev instance. Any edit after `validate` invalidates the pass — the order is always: edit → `dev` (if backend changed) → `validate` → promote. On success promote destroys the dev instance; on failure it keeps it (and the pass) for the retry. - Abandoning a change? `agent-app <dir> stop --dev` tears the candidate down and routes operate commands back to live. `promote` applies migrations and launches NOTHING, so a change is not in front of the user until you serve again. Do not end a modify at `promote`. **Agent work.** When the change adds or changes a feature that queues agent work, or the user asks about agent work, finish with the creator skill's step 6 after promote + serve: run `agent-app <dir> bridge`, and leave a bridge running only on the user's explicit yes in this conversation, after telling them which harness it launches, that it runs until `agent-app <dir> bridge stop` (beyond this session and `stop`), and that each queued task starts an agent run that may cost money. Without a yes, give them the command and say tasks will wait. Skip this for unrelated changes. A bridge you ran with `--once` or `--foreground` against dev is a test, not the handoff: stop a `--foreground` one (Ctrl+C, or kill it) as soon as the test ends, and never leave it running in the background. **Showing the app to the user.** A running app is not a delivered app until the person can see it. The framework cannot know what your harness can do, so YOU decide which of these you are: - **You have a browser tool** (a built-in browser pane, a Chrome extension): run `agent-app <dir> open --print-only` and open the returned `url` with your own tool, so the app appears in context. `--print-only` is what stops the CLI also spawning a separate window — without it the user gets two. - **You do not**: run `agent-app <dir> open`. It uses the opener the harness declared (`AGENT_APP_OPEN_CMD`), else the OS browser. `open` hands a URL to the browser; it CANNOT reload a tab the user already had open. A loaded page can only be replaced from inside itself, which is what the View's update watcher (`/_a2app/update.js` — see `reference/blueprint.md`) is for. After a code change it reloads the tab itself when the page holds no unsaved input, and falls back to offering a reload when it does — a half-filled form is never discarded without asking. **Use `agent-app <dir> open --if-needed`** after a promote: it opens a browser only when nobody already has the app on screen, so a tab that is about to reload itself does not also get a duplicate opened over it. Keep that script tag when you rewrite a View. A DATA change is different and must not reload: the watcher announces it as a `a2app:datachange` event on `window` (identity's `dataVersion` moved) and the View re-reads. If you rewrite a View, keep a listener for it, and guard the re-render the same way — re-rendering over a form someone is filling in loses their work exactly as a reload would. Either way, give the user the URL in your reply. `"opened": false` in the result is NOT a failure — it means the environment has no browser to spawn (SSH, CI, headless) and the printed URL is how the user gets there. `agent-app <dir> serve --open` does the serve and the open in one step where you do not need the URL first. - **The dev DB starts empty every time.** If a feature needs data to be visible, seed it in a migration (which survives promote). - **Never write test data to the live app** (its DB is the user's real data). You should never need to try: while the dev instance is up, every `a2app` command targets it, and the live View is a boot-time snapshot your edits cannot reach. Which instance you are talking to is a structural fact — the operate client verifies the dev route before answering — not something you infer from a port number. - **If promote or the promoted app goes wrong**, the mandatory pre-promote backup is the way back: `agent-app <dir> restore` captures current state first and rolls back automatically on failure. HONESTY RULE: the change is live only when walk-verify returns a pass — never tell the user a change is live when the relaunch, verification, or promotion failed. On failure the user's app still runs the previous working version, and you say so.