Agents Start Here

Agents Start Here

Read the owner's global/repository AGENTS.md and its applicable linked standards before edits. This repository follows the Laravel Composer package standards; application scaffolding, application base classes and application deployment topology do not apply.

Project and boundaries

Repository: moztopia/moztopia-access. The linked owner-approved Moztopia Access Project #49 governs code, tests and this wiki. Source major: 0. Public release: 0.9.1 — Padlock, MIT licensed. The owner explicitly authorized the initial develop/main PR merges, publication and finished WIP cleanup; future releases still follow the owner’s normal controls. moztopia-notifications is a structural/tooling reference, not a dependency or a source for Access domain behavior. No Spatie implementation or dependency is used.

Before work, verify repository/Project linkage in both directions and create/reuse a bounded issue. Complete issue type, labels, parent/dependencies, organization Priority, Size, human engineering Estimate and Planned week for selected work. Use Status Backlog → Ready → In progress → Testing → Done, plus Horizon. Do not mark incomplete acceptance Done.

Implement on wip/{major}/{issue-number}-{slug}. Use develop as the major-zero integration destination after verifying it exists and serves that line. Never edit/push directly to an existing integration branch; follow PR, review, version and tag controls. Do not merge to main, choose a license, publish to Packagist, create a GitHub release, or introduce deployment infrastructure without authorization. Proposed source versions in a PR do not constitute a release.

Package contracts

Read scope semantics, the API and concurrency boundaries before changes. Preserve explicit scope, UUIDv7 entity keys, no implicit admin powers, no current-team state, fresh database checks and membership cleanup. Trusted PHP methods target a user; the host authorizes the actor separately. No automatic Gate callbacks may override host policies.

Prefer assignRole, assignPermission and assignTeam, paired with revokeRole, revokePermission and revokeTeam, in new examples. Follow API Naming: one explicit mutation vocabulary, no aliases or compatibility bridges. Package traits must live in src/Traits/ with the corresponding namespace. Team lookup names are application-defined and unique; no example name is a package convention.

Use strict PHP, PSR-4, Pest/Testbench and Pint. Keep DocBlocks with summaries and a blank line following the closing delimiter. Use native Laravel facilities and minimal dependencies. Do not add an application, a generic repository layer, role inheritance, deny rules, invitations, nested teams or caching without an approved scope change and tests.

Run the verification commands, including real-engine constraints and concurrency tests. Never run the destructive test fixture suite on an application database. Reconcile requirements against issue/Project coverage before commits and handoff. Record exact test combinations, failures and limitations; broad version constraints are not verification evidence.

Wiki maintenance

Add /wiki/ to the parent .gitignore before cloning its actual .wiki.git remote there. This wiki's discovered branch is master; rediscover rather than assuming it will remain so. Review diffs, fetch/reconcile and push through Git, without force. Wiki changes use parent issues and Project metadata; no separate Project or PR bypass in the parent repository. Record the wiki commit on issue #4. Preserve _Footer.md and accurate licensing references.