Add nextcloud-php-app skill: from an empty directory to a released Nextcloud PHP app

[oleksandr-nc]

A complete guide to building Nextcloud PHP apps, from an empty directory to a release tarball, with a runnable reference app and browser verification. Everything in it was executed against live Nextcloud 33, 34 and 35 instances, and then tested by four fresh agents who had only the guide: the last two built complete apps (a reading list, a team standup log) in 11 and 12 minutes each, all requirements green, and their findings are folded back in.

What is here

• skills/nextcloud-php-app/: a seven-stage runbook (scaffold, browser, data, settings, Vue + Vite, PHPUnit + Psalm + php-cs-fixer, package and release) and a Playwright runbook.
• assets/minimal_php_app/: an installable app that carries every stage: manifest, IBootstrap, attribute routes, template plus page script, navigation, migration + entity + QBMapper, admin settings with a full round trip (initial state out, admin-only PUT back), a plain-JavaScript frontend that works without any build and a Vue frontend behind the same template and the same tests, two PHPUnit suites (mocked controllers; real-database mapper), Psalm and php-cs-fixer configuration, a 7-test Playwright suite that passes against both frontends and on all three Nextcloud versions, and make appstore.
• rename.sh: turns a copy into your own app, validates its inputs first and refuses to finish unless the result is clean.
• tests/verify.py gained a slow check that installs the reference app and asserts what the runbook promises; CI gained a job that renames, schema-checks, builds, unit-tests, analyses and packages the reference app on every push.

What the agent rounds and the review changed

Rounds 1 and 2 (earlier): migrations run on re-enable, not on version bump; the migration ledger; the rename script instead of a prose recipe.

Rounds 3 and 4: the reference migration runs on the very first enable, so decide the first table before enabling; a NOT NULL column with empty default cannot be added to an existing table; the settings stage now consumes the initial state it provides; two Vite entries; NcCheckboxRadioSwitch swallows role clicks; unique indexes and REASON_UNIQUE_CONSTRAINT_VIOLATION; second users need a policy-compliant password; the Vue-first order is explicitly fine.

Multi-version testing: Nextcloud 33 renders the app menu inline (links), 34+ as a popover (menuitem); the first-run wizard modal intercepts clicks on fresh instances; both handled in the reference suite.

An adversarial review pass found no blockers and 31 corrections, all applied: the identifier limit is 63 not 30, rename.sh now survives &, |, \ and names containing "minimal", validates the namespace, and never edits itself; nextcloud/ocp is pinned to the lowest supported branch; migration ordering, the migrations:execute guard caveat and several attributions were corrected.

Two apps built by the agent rounds are left installed on the dev instance (readinglist, standupnotes) for anyone who wants to look; the reports are in /workspace/notes/nextcloud-skills/.