Agent App Modify
You are changing an EXISTING app. Everything in the agent-app-creator skill
applies (ownership rule, schema/verbs/UI order, kit usage, honesty rule) —
this skill covers only what differs.
Step 0: Locate and understand
- Find the project: read
agent_file_system/workspace/agent_app_projects.json
or use the project id/path given in your instruction.
- Read the project's
AGENT_APP.md (current plan/entities/ops) and
reference/requirements.md. Read manifest.json for authMode and port.
- If something broke, read the logs FIRST:
{project_path}/logs/frontend_console.log and
{project_path}/logs/pocketbase.log.
- If the request is ambiguous, ask 1 batch of clarifying questions
(a FINAL
send_message (continue_work=false — the reply wakes the session)).
- Record the request in the spec BEFORE editing code: append a dated
entry to
reference/requirements.md under a ## Changes section (create
the section if absent):
- 2026-08-05: <the user's request, stated as a checkable capability>.
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 validation 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.
Rules for changing a live app
- Ownership is unchanged: edit only
frontend/src/app/, pb/pb_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), pb/pb_hooks/ops.pb.js (+ new *.pb.js / *.js helper
modules), operations.json (non-system), triggers.json, AGENT_APP.md.
Adding/changing an agent trigger (app fires the agent): declare it in
triggers.json first — see the creator skill's references/TRIGGERS.md;
the gate re-derives capabilities.triggers on relaunch, and fires of
undeclared names are refused in-app.
- Schema changes are additive migrations. The user's data lives in
pb/pb_data/ — never delete it, never drop-and-recreate collections that
hold data. To alter a collection, write a new migration that loads and
updates it (app.findCollectionByNameOrId(...) → modify → app.save(...)).
- Relation fields need the target collection's ID —
app.findCollectionByNameOrId('<name>').id, never the name.
- Record the delta in
AGENT_APP.md (what changed, new entities/ops).
Finish
agent_app_notify_ready(project_id="<PROJECT_ID>") # gate + boot SHADOW env
agent_app_walk_verify(project_id="<PROJECT_ID>") # verify + PROMOTE
walk_verify drives the app in a real browser (Playwright) against the
requirements and PROMOTES on a clean verdict. notify_ready also auto-invokes
the server ops your change touched and reports any failure with its response
body — fix those before you call walk_verify.
These run in the shadow environment: notify_ready gates your code and
boots the project's OWN tree a second time on a hidden port with a FRESH,
EMPTY database — migrations replay at boot, so only data your migrations
seed exists. Nothing is copied: your edits ARE the running candidate. The
user's live app keeps serving the previously promoted build, untouched, and
its data is NEVER cloned. Test freely against the shadow URL it returns
(create whatever test records you need — they are thrown away).
walk_verify drives the shadow in a real (headless) browser; a clean
verdict is what PROMOTES your change to the live app (new migrations apply
to the real data at its boot) and announces it.
- The shadow DB starts empty every time. If a feature needs data to be
visible, either seed it in a migration (survives promote) or create test
records through the app/API after
notify_ready (shadow-only,
disposable).
- While a shadow is up,
agent-app ops/run/data <project_path> target IT
automatically — you never pass the hidden port yourself.
- Never run
agent-app validate (without --outRoot) or agent-app dev against the
real project dir of a RUNNING app — the in-place build overwrites the
served frontend. notify_ready gates safely for you.
- Never write test data to the live app (its DB is the user's real
data; agent test writes outside the shadow are refused). Do all testing
after
notify_ready, against the shadow URL. GET /api/_a2app answers
env: "dev" (= shadow) or env: "live" if you need to confirm which
instance a port is.
HONESTY RULE: the change is live only when agent_app_walk_verify returns
status: success — never tell the user a change is live when the relaunch,
verification or deploy failed. On failure the user's app still runs the
previous working version.
When verification comes back with defects
Failing features come back as a fix brief: defect cards with evidence, plus
an ATTEMPT LOG — every previous round, the cause signature of each
defect, what moved between rounds (cause identical, cause changed,
gone, new) and any streak across them. It reports and stops; reading it
is yours, and so is how you spend the round.
Two things you can write into that record. Each round is a fresh run that
remembers nothing of the last one, so what is not written here is not known
next round:
agent_app_report_finding(project_id="<ID>", ruled_out=["not the grant — dry-run of send_gmail returns 200"]) — causes you eliminated, and what
eliminated them. Quoted back in every later brief.
agent_app_report_finding(project_id="<ID>", blocked_question="Which calendar should bookings write to?") — ends the work and puts one
question to the user. For something you cannot GET (a decision, an
account, a credential), not something you have not solved. It is also the
only way to stop that the tracker does not read as walking out.
Repeating a failure does not end the work; only the mission budget does.
1---2name: agent-app-modify3description: Modify an existing Agent App application (PocketBase + React kit) — add features, change design, fix bugs — then re-validate and relaunch it.4action-sets:5 - file_operations6 - code_execution7 - agent_app8metadata:9 source: https://skillmd.com/skills/craftos-dev/agent-app-modify10---1112# Agent App Modify1314You are changing an EXISTING app. Everything in the agent-app-creator skill15applies (ownership rule, schema/verbs/UI order, kit usage, honesty rule) —16this skill covers only what differs.1718## Step 0: Locate and understand19201. Find the project: read `agent_file_system/workspace/agent_app_projects.json`21 or use the project id/path given in your instruction.222. Read the project's `AGENT_APP.md` (current plan/entities/ops) and23 `reference/requirements.md`. Read `manifest.json` for `authMode` and port.243. If something broke, read the logs FIRST:25 `{project_path}/logs/frontend_console.log` and26 `{project_path}/logs/pocketbase.log`.274. If the request is ambiguous, ask 1 batch of clarifying questions28 (a FINAL `send_message` (`continue_work=false` — the reply wakes the session)).295. **Record the request in the spec BEFORE editing code**: append a dated30 entry to `reference/requirements.md` under a `## Changes` section (create31 the section if absent):32 `- 2026-08-05: <the user's request, stated as a checkable capability>`.33 NEVER rewrite the existing sections — they are the delivered contract;34 `## Changes` is append-only. The verifier checks every entry there, so an35 unrecorded change is an unverified change (and a recorded one can never36 be silently dropped by a later modify).37 **SUPERSESSION — the one permitted edit to old entries**: when the new38 request REVERSES or REPLACES an earlier `## Changes` entry (the user39 changed their mind, or the old entry demanded an approach the platform40 now rejects), wrap the stale entry in `~~strikethrough~~` — do not delete41 it (it stays as history) and do not leave it live (the verifier enforces42 every unstruck line, and contradictory live entries make the spec43 unsatisfiable: an app once went STUCK three times because old entries44 demanded a handler the validation gate forbids while the new entry45 forbade it — no code could satisfy both). Strike ONLY entries the new46 request genuinely contradicts, never entries you merely failed to build.4748## Rules for changing a live app4950- **Ownership is unchanged**: edit only `frontend/src/app/`, `pb/pb_migrations/`51 (NEW files only — never edit, rename, or delete an applied migration: the52 filename is its identity in the live DB, and a renamed one makes the app53 unable to boot), `pb/pb_hooks/ops.pb.js` (+ new `*.pb.js` / `*.js` helper54 modules), `operations.json` (non-system), `triggers.json`, `AGENT_APP.md`.55 Adding/changing an agent trigger (app fires the agent): declare it in56 `triggers.json` first — see the creator skill's `references/TRIGGERS.md`;57 the gate re-derives `capabilities.triggers` on relaunch, and fires of58 undeclared names are refused in-app.59- **Schema changes are additive migrations.** The user's data lives in60 `pb/pb_data/` — never delete it, never drop-and-recreate collections that61 hold data. To alter a collection, write a new migration that loads and62 updates it (`app.findCollectionByNameOrId(...)` → modify → `app.save(...)`).63- **Relation fields need the target collection's ID** —64 `app.findCollectionByNameOrId('<name>').id`, never the name.65- Record the delta in `AGENT_APP.md` (what changed, new entities/ops).6667## Finish6869```70agent_app_notify_ready(project_id="<PROJECT_ID>") # gate + boot SHADOW env71agent_app_walk_verify(project_id="<PROJECT_ID>") # verify + PROMOTE72```7374walk_verify drives the app in a real browser (Playwright) against the75requirements and PROMOTES on a clean verdict. notify_ready also auto-invokes76the server ops your change touched and reports any failure with its response77body — fix those before you call walk_verify.7879These run in the **shadow environment**: `notify_ready` gates your code and80boots the project's OWN tree a second time on a hidden port with a **FRESH,81EMPTY database** — migrations replay at boot, so only data your migrations82seed exists. Nothing is copied: your edits ARE the running candidate. The83user's live app keeps serving the previously promoted build, untouched, and84its data is NEVER cloned. Test freely against the shadow URL it returns85(create whatever test records you need — they are thrown away).86`walk_verify` drives the shadow in a real (headless) browser; a clean87verdict is what PROMOTES your change to the live app (new migrations apply88to the real data at its boot) and announces it.8990- **The shadow DB starts empty every time.** If a feature needs data to be91 visible, either seed it in a migration (survives promote) or create test92 records through the app/API after `notify_ready` (shadow-only,93 disposable).94- **While a shadow is up, `agent-app ops/run/data <project_path>` target IT95 automatically** — you never pass the hidden port yourself.96- **Never run `agent-app validate` (without --outRoot) or `agent-app dev` against the97 real project dir of a RUNNING app** — the in-place build overwrites the98 served frontend. `notify_ready` gates safely for you.99- **Never write test data to the live app** (its DB is the user's real100 data; agent test writes outside the shadow are refused). Do all testing101 after `notify_ready`, against the shadow URL. `GET /api/_a2app` answers102 `env: "dev"` (= shadow) or `env: "live"` if you need to confirm which103 instance a port is.104105HONESTY RULE: the change is live only when `agent_app_walk_verify` returns106`status: success` — never tell the user a change is live when the relaunch,107verification or deploy failed. On failure the user's app still runs the108previous working version.109110## When verification comes back with defects111112Failing features come back as a fix brief: defect cards with evidence, plus113an **ATTEMPT LOG** — every previous round, the cause signature of each114defect, what moved between rounds (`cause identical`, `cause changed`,115`gone`, `new`) and any streak across them. It reports and stops; reading it116is yours, and so is how you spend the round.117118Two things you can write into that record. Each round is a fresh run that119remembers nothing of the last one, so what is not written here is not known120next round:121122- `agent_app_report_finding(project_id="<ID>", ruled_out=["not the grant —123 dry-run of send_gmail returns 200"])` — causes you eliminated, and what124 eliminated them. Quoted back in every later brief.125- `agent_app_report_finding(project_id="<ID>", blocked_question="Which126 calendar should bookings write to?")` — ends the work and puts one127 question to the user. For something you cannot GET (a decision, an128 account, a credential), not something you have not solved. It is also the129 only way to stop that the tracker does not read as walking out.130131Repeating a failure does not end the work; only the mission budget does.