The starting point for new UAMS Statamic add-ons. It is a GitHub template repository: generate a new repository from it, then follow the steps below. It was extracted from UAMS-Web/statamic-multisite-forms and holds only the generic parts, with none of that add-on's code or documentation.
composer.jsonwith a placeholder name and namespace, and asrc/ServiceProvider.phpstub.- A Pest and Orchestra Testbench scaffold:
tests/Unitboots nothing,tests/Integrationboots a minimal Statamic throughtests/TestCase.php. - Tool configuration:
phpunit.xml,pint.json,rector.phpandrector-sweep.php,phpstan.neon.dist,vite.config.jsandvitest.config.js. The committedresources/distis the build of two empty Control Panel entry files. - The generic guards in
scripts/, with their tests, and the local patches inpatches/forpestphp/pest-plugin-mutate. .github/: workflows, the setup action, issue and pull request templates, and Dependabot..githooks/pre-commit, wired bycomposer install.docs/DECISIONS.md, the decision log, with the log's rules.- A wiki skeleton in
docs/wiki/(Home, sidebar, footer, and one skeleton page per page shape), thepublish-wiki.ymlworkflow that publishes it on each release, and thegithub-wikiskill that records how the publishing action behaves. AGENTS.md, the agent instructions, and Statamic'smarketplace-reviewskill in.claude/skills/and.agents/skills/.docs/DEVELOPMENT.md(developing against a host),docs/SUBMISSION.md(the Packagist and Marketplace checklist), a placeholderconfig/statamic-addon-template.php, and the tests that pin the README andcomposer.json(tests/Unit/ReadmeTest.php,tests/Unit/SubmissionReadinessTest.php) and a host-bound smoke test (tests/Feature/HostRegistersAddonTest.php).
- Synced files (the rules and skills the sync writes into
.agents/,.claude/and.cursor/, and the generated section ofAGENTS.md). A new add-on onboards to the sync inUAMS-Web/uams-claude-skillsinstead of carrying a snapshot, so it never starts with a stale copy. See Onboard to the sync. LICENSE, and thelicensefield incomposer.json. The choice waits on the general decision from UAMS legal inUAMS-Web/uams-statamic#261.docs/SPEC.md, the add-on's wiki pages and the add-on's own code.
The template targets PHP 8.4 or later and Statamic 6.35 or later, matching composer.json. An add-on's own README states its floors the same way, and tests/Unit/ReadmeTest.php fails when they drift from composer.json.
Developing against a host application is covered in the development guide, and the Packagist and Marketplace steps in the submission checklist.
-
Use Use this template on GitHub to create the new repository.
-
Replace every placeholder. This lists them all:
grep -rniE "addon[-_ ]?template" --exclude-dir=vendor --exclude-dir=node_modules --exclude-dir=.git --exclude=package-lock.json --exclude=composer.lock .
composer.json:name,description,keywords,homepage,support, the twopsr-4namespaces,extra.statamicandextra.laravel.providers.package.json:name.- The
UAMSWeb\AddonTemplatenamespace insrc/andtests/. Make itUAMSWeb\Aether\<Product>, orUAMSWeb\Aether\<Family>\<Product>where a family groups packages: every add-on in the Aether ecosystem sits underUAMSWeb\Aether\. The level staysUAMSWeb\<Product>only for an add-on outside that ecosystem, and the family level is optional there too. Theautoload.psr-4key maps that whole prefix tosrc/(PSR-4 allows a prefix of any depth), so the files undersrc/do not move when the prefix changes. A prefix has one owner or none, and two packages never map the same one. NeitherUAMSWeb\Aether\nor a family level that no package owns is mapped by anyone:UAMSWeb\Aether\Forms\Settings\andUAMSWeb\Aether\Forms\Multisite\are two packages' keys, and no package mapsUAMSWeb\Aether\Forms\. A package may instead own its prefix with a companion nested inside it: one package mapsUAMSWeb\Aether\People\and another mapsUAMSWeb\Aether\People\ListingsManagement\. Composer picks the longest matching prefix, so a nested prefix works only when the outer package has no directory undersrc/named after the inner one (here, nosrc/ListingsManagement/in theUAMSWeb\Aether\People\package). tests/Integration/ServiceProviderTest.php: the package name.config/statamic-addon-template.php: rename it to the add-on's handle (the package name without its vendor), and the tag intests/Integration/ServiceProviderTest.phpanddocs/DEVELOPMENT.md. Delete it and its test if the add-on has no settings.AGENTS.md: the "About this repository" paragraph.docs/DEVELOPMENT.mdanddocs/SUBMISSION.md: the package name, and the host's name.tests/Feature/HostRegistersAddonTest.php: the namespace and package name.docs/wiki/: every page, and the repository name and version in_Footer.md,_Sidebar.mdandHome.md..github/pull_request_template.mdand the header of.github/workflows/ci.yml: the repository name. Keep theRUN_REMOTE_CIgate on every job: a generated add-on is public, where it does nothing while the variable is unset, andscripts/remote-ci-gate.test.mjsfails if a job lacks it.
-
Replace this README with the add-on's own. It has to state
PHP 8.4 or laterandStatamic 6.35 or later(the floors incomposer.json), showcomposer require uams-web/statamic-addon-templatewith the add-on's package name, and linkdocs/DEVELOPMENT.mdanddocs/SUBMISSION.md;tests/Unit/ReadmeTest.phpchecks all of it. Once the add-on has a license, the README names it and linksLICENSE. -
Replace the seed entry in
docs/DECISIONS.mdwith the add-on's own first decision, or keep it and add yours after it. The decision-log guard needs at least one entry. -
Run
composer install, which installs the dependencies, appliespatches/and setscore.hooksPathto.githooks. Then runcomposer update --lockifcomposer.lockneeds to follow the new name. -
Run
npm ciaftercomposer install(@statamic/cmsis afile:link intovendor/), thencomposer ciandnpm run test:scripts. -
Apply the repository settings and its ruleset with the command in Apply the repository settings, and do the steps it leaves for a person (the wiki's first page among them) from What the command leaves for a person.
Write the add-on under src/, with tests under tests/Unit and tests/Integration. Control Panel assets go in resources/js and resources/css; run npm run build and commit resources/dist, because a Composer install does not run npm. Delete the Vite files, the built-assets job and tests/Unit/ViteBuildTest.php together if the add-on has no Control Panel assets.
The checks call in ci.yml passes mutate: false. The template's src/ holds no code a mutator changes, so the chain's mutation pass would create no mutants and fail on a push to main. Once the add-on has code, delete that input: the chain's mutate job then runs composer mutate on the classes a pull request changes (and passes, saying why, when it changes none) and on everything composer mutate covers for a push. The @pest-mutate-ignore line on ServiceProvider's $vite property can go once a test covers those lines or the property is gone.
Add the repository to shared/manifest.json in UAMS-Web/uams-claude-skills, with the profiles core, php, pest, laravel, laravel-package, statamic, statamic-package, tests and quality, following that repository's shared/README.md ("Adding a repository"). The sync then opens a pull request that adds the rules and skills to .claude/, .agents/ and .cursor/, and inserts its generated section into AGENTS.md after the introduction. The copies of marketplace-review here are byte-identical to the download until UAMS-Web/uams-claude-skills#177 replaces them with synced copies, and github-wiki may become shared (UAMS-Web/uams-claude-skills#172), so expect the sync pull request to touch both.
There is nothing to restore by hand afterwards. The sync delivers .github/workflows/synced-checks.yml, which carries the Synced files (no hand-edited rules or skills) and Mutation instrument (a mutant child can launch) jobs. Do not copy either job into ci.yml: two jobs under one name report one check. This template's ci.yml has neither job, and a composer test:mutation-instrument script is optional: define one only to scope the probe to the suites the add-on's own mutation run uses, and the delivered workflow then runs it in place of the delivered script.
From the new repository's root, with gh signed in as someone who administers it, run the command in plan mode first:
node .claude/skills/repository-settings/scripts/apply-addon-settings.mjs UAMS-Web/<repo>It only reads: it prints each setting and ruleset change it would make and writes nothing. Run it again with --apply to make them:
node .claude/skills/repository-settings/scripts/apply-addon-settings.mjs UAMS-Web/<repo> --apply--apply asks "Apply N changes? [y/N]" before the first write, and reads every change back afterwards. The command is delivered by the sync (the repository-settings skill), so run this step after Onboard to the sync has merged. What it sets, and why, is in that skill; this README does not list it.
- Add the repository to the sync's manifest and dispatch the sync, as in Onboard to the sync.
- Create the wiki's first page, before the add-on's first release. In the new repository, open the Wiki tab, choose Create the first page and save it. A repository generated from the template does not get a wiki, and the wiki's git repository does not exist until a first page does, so
publish-wiki.ymlfails on its push without it. The first publish replaces that page withdocs/wiki/. Also restrict wiki editing to collaborators (Settings, Features), since a publish overwrites browser edits. Thegithub-wikiskill has the detail. Deletepublish-wiki.ymlanddocs/wiki/if the add-on will have no wiki. - Tags, releases and Packagist, per the submission checklist.
- A
LICENSEandcomposer.json'slicensefield, onceUAMS-Web/uams-statamic#261is decided.
The generic tooling is meant to move into the sync later, so it sits in plain files (scripts/, the configuration files, .github/) with nothing in them specific to an add-on. Keep it that way: add-on logic goes in src/ and tests/, not in the tooling.