Document project route structure skill

2026-04-15 10:25:55 +02:00
parent b7977a81a1
commit 4a3a53b693
2 changed files with 67 additions and 0 deletions
@@ -0,0 +1,66 @@
+---
+name: project-route-structure
+description: "Always apply in this project when creating, moving, or refactoring Laravel route definitions in routes/*.php; changing route prefixes, names, middleware, scoped bindings, or route files; or adding frontend-facing endpoints that Wayfinder generates. Documents the KanbanGit route-file layout and grouping conventions."
+---
+
+# Project Route Structure
+
+## When to Apply
+
+Activate this skill whenever work in this project changes:
+
+- `routes/*.php`
+- Route names, URI prefixes, middleware groups, scoped bindings, or controller route registrations
+- Frontend-facing endpoints that require regenerated Wayfinder output
+
+Use this together with `laravel-best-practices`. Also activate `wayfinder-development` when route changes affect generated frontend route/action imports.
+
+## Route Files
+
+- `routes/web.php` is the web entry point only. Keep public shell routes here, such as `home` and `dashboard`, then require domain route files.
+- `routes/projects.php` owns all `projects.*` routes.
+- `routes/admin.php` owns all `admin.*` routes.
+- `routes/teams.php` owns all `teams.*` routes.
+- `routes/settings.php` owns account settings routes, but keeps their existing route names such as `profile.edit`, `security.edit`, and `git-connections.edit`.
+
+Add a new route file only when a domain gets large enough to stand alone. Otherwise, extend the existing domain file.
+
+## Grouping Pattern
+
+- Put shared middleware, URI prefixes, route name prefixes, and controller declarations on groups instead of repeating them on each route.
+- Prefer this nesting order when it reads naturally: `middleware(...)`, `prefix(...)`, `name(...)`, `controller(...)`, then `group(...)`.
+- Keep public route names stable unless the user explicitly asks for a public interface change.
+- Keep route URIs stable when reorganizing route files; this kind of change should be structural.
+- Use `function (): void` for route group closures.
+
+## Project Routes
+
+Project routes should follow this shape:
+
+- Top-level group: `middleware(['auth', 'verified'])`, `prefix('projects')`, `name('projects.')`.
+- Project create/store routes live under `can:create-project`.
+- Routes under `{project}` use project gates by capability:
+  - Read pages: `can:view-project,project`
+  - Mutations: `can:write-project,project`
+  - Project settings and access management: `can:admin-project,project`
+  - Project delete: `can:access-admin`
+- `projects/{project}/permissions/...` must not be inside `Route::scopeBindings()`, because `Project` does not define `users()` or `teams()` child relationships.
+- Use `Route::scopeBindings()` only around nested project resources that should bind through project-owned relationships, such as tickets and project settings children.
+- Keep ticket subroutes grouped under `tickets.` and settings subroutes grouped under `settings.`.
+
+## Settings Routes
+
+- Keep the `settings` URI prefix grouped.
+- Keep profile edit/update behind `auth` only.
+- Keep profile deletion, security, git connections, and appearance behind `auth` plus `verified`.
+- Do not rename settings routes to a `settings.*` namespace unless the frontend/tests are intentionally updated.
+
+## Verification
+
+After changing route files:
+
+1. Run `php artisan route:list --except-vendor`.
+2. Run `php artisan wayfinder:generate --with-form --no-interaction` when any route signature, name, method, or controller action changed.
+3. Run `vendor/bin/pint --dirty --format agent` for PHP route formatting.
+4. Run the affected feature tests, usually `php artisan test --compact tests/Feature/Projects tests/Feature/Teams tests/Feature/Admin tests/Feature/Settings`.
+5. Run `git diff --check` before finalizing.