# Agent App Modify

> Modify an existing Agent App application (PocketBase + React kit) — add features, change design, fix bugs — then re-validate and relaunch it.

- Skill: `craftos-dev/agent-app-modify` (Agent Skill)
- Install (CLI): `npx get-skill add craftos-dev/agent-app-modify`
- Raw SKILL.md: https://api.skillmd.com/api/skills/craftos-dev/agent-app-modify/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: craftos-dev (https://skillmd.com/u/craftos-dev)
- Updated: 2026-11-11
- Page: https://skillmd.com/skills/craftos-dev/agent-app-modify

---


# 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

1. Find the project: read `agent_file_system/workspace/agent_app_projects.json`
   or use the project id/path given in your instruction.
2. Read the project's `AGENT_APP.md` (current plan/entities/ops) and
   `reference/requirements.md`. Read `manifest.json` for `authMode` and port.
3. If something broke, read the logs FIRST:
   `{project_path}/logs/frontend_console.log` and
   `{project_path}/logs/pocketbase.log`.
4. If the request is ambiguous, ask 1 batch of clarifying questions
   (a FINAL `send_message` (`continue_work=false` — the reply wakes the session)).
5. **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.

