git:20260911.ecebe45 to git:20260911.91cb813

---

name: modify

activity: modify

description: Modify an existing Agent App — add features, change design, fix bugs — then re-validate, verify, and relaunch it. Load for a code change to an app that already exists. The creator skill's rules still apply.

---

# 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 `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`, the trigger manifest,

and `AGENT_APP.md`. Adding/changing an agent trigger: declare it in the trigger

manifest first; fires of undeclared names are refused in-app.

- **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: **per your stack**.)

- 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> promote # pre-promote backup, then apply new migrations to live

```

- **The dev DB starts empty every time.** If a feature needs data to be visible,

- **Never run `agent-app validate` or `agent-app dev` in a way that rebuilds the live

project dir in place** — it overwrites the served frontend and blanks the user's

- **Never write test data to the live app** (its DB is the user's real data; agent

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.