AskMyDocs

Build, version-bump, sign and upload the AskMyDocs Desktop Tauri app (desktop/) to TestFlight / App Store Connect. Codifies the exact flow that shipped build 0.1.0 on 2026-06-23 — `tauri ios build --export-method app-store-connect`, automatic distribution signing, the transient export-error retry, and the Xcode Organizer GUI upload. Trigger when the user asks to "send/upload the app to TestFlight", "build the iOS app", "ship a new beta", bump the iOS version/build number, or distribute desktop/ to Apple.

After EVERY commit-push-PR cycle, the agent MUST loop on Copilot review + CI status until ALL Copilot comments resolved AND ALL CI checks green. NEVER stop after a single push. Trigger when opening a PR with `gh pr create`, after `gh pr push`, or when user asks to "fix PR" / "address review" / "make CI green". Applies to ALL repos lopadova/* and padosoft/*. The loop is mandatory for current and future sessions and for any developer working on this codebase.

How to wire an admin SPA page (or the chat) to the global TEAM (= tenant) switcher in the topbar — every authenticated route lives under /app/{teamHash}/…, the X-Tenant-Id header is automatic via the shared axios client, switching team rewrites the URL hash + clears the TanStack cache + remounts the route outlet, project options must come from tenant-scoped endpoints. Trigger when wiring an admin page to the team scope, when adding a NEW admin page / route / feature folder under frontend/src/features/, when adding a `navigate(...)` call, when touching a project picker / project filter, or when a page shows stale cross-team data after a team switch.

Every Eloquent query against tenant-aware tables MUST be scoped to the active tenant_id. Use `forTenant($tenantId)` scope (provided by BelongsToTenant trait) or explicit `where('tenant_id', $ctx->current())`. The TenantContext singleton holds the active tenant; never bypass it. Trigger when writing services / scopes / controllers that query tenant-aware models, when reviewing PRs that touch persistence, or when investigating R30 architecture test failures.

Author and maintain the AskMyDocs Mintlify documentation site under /docs-site/. Every page is a deep, academic, standalone explainer (motivation → theory → design+Mermaid diagram → data model → ADR rationale → worked example → gotchas) — NOT a condensed README paste. Trigger when adding or changing a capability that ships user-facing behaviour, when editing README feature tables / changelog / roadmap (R45 doc-site parity), when adding a page to /docs-site/, or when editing docs.json navigation.

CONSUMER-SIDE template — use in a consumer repository that posts knowledge to AskMyDocs, NOT when editing AskMyDocs itself. Triggers when the team wants to bootstrap or refresh the ENTIRE canonical knowledge base of a repository in one pass: survey the codebase, plan the typed-document inventory, and emit a full cross-wikilinked kb/ tree (project-index + modules + decisions + standards + integrations + domain-concepts + runbooks + rejected-approaches). Draft only — produces Markdown files under kb/ for human review, never commits and never POSTs. Example triggers: generate the canonical docs for this repo, compile the knowledge base, bootstrap kb/ from the codebase, document the whole project in canonical mode.

Order test tearDown so the RefreshDatabase rollback runs BEFORE Mockery::close(), so an unmet mock expectation can never skip the rollback and cascade an "active transaction" suite-wide failure (R41).

Every tenant-aware Eloquent model in app/Models/ MUST `use BelongsToTenant;` and have `tenant_id` in $fillable (or use `$guarded = ['id']`). The TenantContext singleton is set by ResolveTenant middleware (HTTP) or `--tenant=X` CLI option. v3 backward compat is preserved by `default 'default'` everywhere. Trigger when adding a new Eloquent model under app/Models/, when modifying $fillable on an existing model, when creating a new migration that adds a domain table, or when reviewing PRs that touch persistence.

R32 — every new protected route / API / admin screen / Gate / role MUST be added to the RBAC authorization-matrix test before merge. Use whenever you add or change a route group, a Gate::define, a role, a permission, or an admin SPA screen.

Escape every meta-character for every operator — LIKE (`%`, `_`, `\\`), fnmatch (`FNM_PATHNAME` for paths), regex (`.` / `+` / `*` / `?` / grouping chars), CSV env vars (trim + filter). Partial escaping is broken escaping. Trigger when editing a controller that runs LIKE against user input, a scope/policy that calls fnmatch on glob lists, a shell/CI script that treats a host list as a regex, or a config file that splits a CSV env var.

Implementare il backend di una pagina admin Laravel complessa con FormRequest, DTO/filter object, service di query/aggregation, controller thin e route. Trigger quando si crea o refactora un endpoint admin con filtri, KPI, tabelle paginate o export, o quando si tocca un controller in app/Http/Controllers/Api/Admin/ o un servizio in app/Services/Admin/.

Audit di componenti UI e servizi esistenti PRIMA di creare una nuova interfaccia admin, per decidere REUSE / EXTEND / CREATE-DOMAIN / CREATE-GLOBAL su ciascun pezzo. Default a REUSE. Trigger quando l'utente chiede di costruire una nuova pagina admin, un nuovo dashboard, un nuovo wizard o di refactorare interfacce admin disomogenee — sempre prima di scrivere codice frontend nuovo.

Implementare la parte frontend di una pagina admin complessa Laravel — entrypoint pagina, api client, gestione filtri, rendering tabella/KPI/charts, stati empty/loading/error. Trigger quando si tocca un componente sotto frontend/src/features/admin/ o resources/views/admin/, quando si implementa la UI di un dashboard / wizard / modal admin, o quando si refactora una vista admin esistente.

Orchestratore end-to-end per creare o rifattorizzare una pagina admin Laravel complessa (Laravel 13.x + PHP 8.3+) — audit componenti, contratto BE/FE, implementazione BE, implementazione FE, test e hardening. Trigger quando l'utente chiede una nuova pagina admin con filtri / KPI / tabelle / export / grafici / modal, o un refactor di interfacce admin disomogenee.

Creare endpoint API moderni in Laravel 13 con la pipeline route → controller thin → FormRequest → DTO → service/action → JsonResource/ResourceCollection → feature test HTTP. Trigger quando l'utente chiede di aggiungere una nuova rotta API in routes/api.php, un nuovo controller in app/Http/Controllers/Api/, o quando si espone una nuova capability come endpoint REST/JSON.

Pattern base per introdurre un controller Laravel (web/api/admin) su Laravel 13.x + PHP 8.3+ — FormRequest per validazione non banale, DTO/command object per payload ricco, delega a service/action, return view/resource/redirect coerente, almeno un feature test. Trigger quando l'utente chiede di creare un nuovo controller in app/Http/Controllers/, una nuova rotta che ha bisogno di un handler dedicato, o quando si scaffolda un nuovo entry-point HTTP.

Scaffolding di un CRUD admin standard Laravel — model + migration coerenti, FormRequest di create/update, controller resource o equivalente, view index/create/edit oppure API endpoints, test di create/update/delete + validazione. Trigger quando l'utente chiede di creare un CRUD per un nuovo dominio (es. "fai il CRUD per Tag / Project / Setting"), o quando si tocca uno dei 5 file di un CRUD esistente in modo strutturale.

Introdurre un nuovo disco o flusso file in un progetto Laravel — definire il disk in config/filesystems.php, centralizzare naming/path, usare stream per file grandi, chiarire visibilità/retention/cleanup, evitare path string sparsi. Trigger quando l'utente chiede di aggiungere un nuovo disco (es. nuovo bucket S3 o storage path), di gestire upload/download di file grandi, o quando si introduce un helper di filesystem in app/Support/.

Creare un service o action object Laravel (Laravel 13.x + PHP 8.3+) con input esplicito (parametri o DTO), una responsabilità chiara, dipendenze iniettate e output deterministico. Trigger quando l'utente chiede di estrarre logica da un controller, di creare una nuova classe in app/Services/ o app/Actions/, o quando un controller cresce oltre la pura orchestrazione.

Aggiungere test per nuovo codice Laravel 13.x + PHP 8.3+ — unit test per logica pura/service, feature test per HTTP/auth/validation/persistence, browser/E2E solo per journey critici. Continua col framework già scelto dal repo (PHPUnit per AskMyDocs). Trigger quando l'utente chiede di scrivere test per una nuova feature/service/controller, quando si tocca codice senza coverage, o quando si verifica un fix con regression test.

Workflow enterprise per test E2E Playwright — discovery (config/runner/scope), authoring con locator semantici e tag, execution mirata con artifact (trace/screenshot/report), diagnose con classificazione test/app/env/flaky, report finale con summary pass/fail/flaky e follow-up. Trigger quando si scrive una nuova spec di user journey, si estende una suite esistente, si fa un run mirato per file/folder/tag, o quando si diagnostica un test intermittente — per refactor strutturali della suite Playwright complementare a `playwright-e2e` (R12) e `ci-failure-investigation` (R22).

For AskMyDocs (which has v3 stable on main), each major release works in its own `feature/v4.x` integration branch. Sub-branches per sottotask target `feature/v4.x`, not main. Merge to main happens ONCE per major release when RC complete + CI green + acceptance criteria passed. For new repos (padosoft/*) PRs target main directly. Trigger when creating a feature branch on AskMyDocs, when opening a PR on AskMyDocs, when planning a new release cycle, or when user asks about branching/merging strategy.

When `gh pr checks` shows a Playwright (or any E2E) job red, NEVER guess fixes from the test name alone. Pull the failed-job log, the playwright-report.zip artefact, and the inline Laravel log dump BEFORE editing code — false-iteration cycles cost 4–8 min each plus a misleading next-iteration baseline. Trigger when a CI job has failed and the next step is "fix the failure", or when investigating Playwright/E2E timeouts, 500s, hangs, or flakes on a PR. Mirrors CLAUDE.md §R22.

At the end of every Wn weekly milestone on AskMyDocs `feature/vX.Y` (CI green + closure status doc shipped), tag `vX.Y.0-rcN` on the integration branch's exact closure-commit SHA with a refreshed README. Final `vX.Y.0` GA fires only when the last Wn of the cycle closes (W8 for v4.0) and `feature/vX.Y` merges into `main` per R37. Trigger after merging the LAST sub-task PR of any Wn closure on AskMyDocs, or when the user asks "should we tag rc?" / "release candidate" / "milestone tag".

Schema, signature, env-var, and config snippets in CLAUDE.md, .github/copilot-instructions.md, README.md and SKILL.md files must match the real code. Verify against migrations, models, config files, and Artisan signatures before merging. Trigger when editing any documentation file that quotes column names, env vars, command flags, route paths, or config keys; or when changing a migration / model / command / config / route in a way that any of those docs reference.

Every React component in the AskMyDocs frontend must expose stable data-testid attributes on actionable elements, meaningful ARIA landmarks and labels, and predictable network/error states so Playwright E2E tests can exercise complex UI flows deterministically. Trigger when editing any file under frontend/src/, when writing new components, when refactoring markup, or when adding API calls / error handling / async boundaries in the SPA.

Keep bulk DB operations on knowledge_documents / knowledge_chunks / embedding_cache / chat_logs memory-bounded. Use chunkById/cursor, push filters into SQL with whereNotIn + array_chunk, avoid ->get() followed by PHP-side filtering. Trigger when editing DocumentDeleter, PruneDeletedDocumentsCommand, PruneEmbeddingCacheCommand, PruneChatLogsCommand, KbIngestFolderCommand, or any new sweep/backfill/prune that can see more than a few hundred rows.

Author and maintain Playwright end-to-end scenarios for the AskMyDocs React SPA. Every UI-touching PR ships with at least one happy-path and one failure-path scenario covering the changed feature. Trigger when adding or modifying files under e2e/, when creating a new FE feature folder under frontend/src/features/, when updating a feature that already has a .spec.ts, or when a PR body mentions "UI coverage / E2E / playwright".

UI dropdowns, filters, and file-extension handling derive from the real DB / API domain, not from a hard-coded sample. Applies to project-key filters, time-window selectors, role lists, file-extension handling in file-name derivation. Trigger when editing any component with a `<select>`, when adding a CLI/HTTP filter that mirrors a cache key, when deriving output filenames from a path, or when seeding fixtures that will drive production-like admin features.

Every actionable element in the React SPA must be programmatically announced to assistive tech AND reachable via keyboard. Applies to inputs, buttons, dropdowns, tooltips, checkboxes, tree widgets, dialog controls. Trigger when editing any component under frontend/src/, especially forms (inputs + selects + textareas), custom tree/tab/listbox widgets, tooltip/popover components, and dialog-hosted permission matrices. Complements R11 (testid contract) with the a11y surface.

When a React component owns cached state in an imperative library (CodeMirror EditorView, canvas, D3, monaco) or a ref mirroring server state, every effect branch that re-reads the source must also sync the cached copy. Optimistic updates stay cached until refetch resolves. NaN-derived values are guarded before equality checks. `.map()` of multi-element rows wraps in a KEYED `<Fragment>` — the key on an inner element does not satisfy React. Trigger when editing components that host imperative editors (SourceTab), chat mutations, URL-param-driven activeId state, or any table/list where `.map()` returns multiple siblings per iteration.

FE payload shapes must match BE validator shapes; E2E specs must post what the controller accepts; TanStack parent routes host children via `<Outlet />`; Artisan wrappers distinguish positional from option signatures. Trigger when editing a FE `api.ts` file, a controller `FormRequest` / inline `validate()`, a new TanStack Router route tree, or when wrapping Artisan commands via `Artisan::call`.

Any single-use / rate-limit / auth / nonce check must hold the lock until the invariant is RECORDED — or the invariant does not exist. `lockForUpdate()` read + `update()` write must live in the SAME `DB::transaction` closure. Concurrency-sensitive state gets DB-level UNIQUE backing where the business rule demands it. One occurrence mints a skill + rule because the blast radius is RCE-class (single-use bypass, TOCTOU, signed-URL replay). Trigger when editing any service that consumes nonces, confirm tokens, rate counters, auth bypasses, or single-use resources.

Never return 200 with an empty / null / NaN body where 4xx or 5xx is the correct semantic. Applies to endpoints, PDF renderers, log readers, React Query fetchers, chart components, and any code path where a failure silently becomes a "successful" response. Trigger when editing controllers that return files / previews, services that wrap an external call, React Query fetchers, renderer classes in `app/Services/Admin/Pdf/`, log-reader services, or chart components with array-reduction math.

A test body must exercise the behaviour its name promises. Ordering tests use strictly-monotonic fixtures with strict comparisons. Global-state mutations (env, DI, window.location, Date.now) are restored in afterEach. Failure-path tests actually fire the failure. Trigger when editing any *.test.tsx / tests/**/*.php / *.spec.ts file, or when adding a new test — especially tests with names starting with "enables", "disables", "rejects", "returns empty", "orders", "handles failure".

Copy-paste templates for writing Playwright E2E scenarios in AskMyDocs. Use when starting a new `frontend/e2e/*.spec.ts` file, setting up a new setup-project (admin/viewer/editor), or when you need a proven pattern for data-state waits, failure injection, CRUD flows, or wizard flows. Templates are aligned with R11 (testids) / R12 (coverage) / R13 (real data, external-only stubs).

Canonical columns (doc_id, slug, canonical_type, canonical_status, is_canonical, retrieval_priority, source_of_truth, frontmatter_json) and the kb_nodes / kb_edges / kb_canonical_audit tables are load-bearing — every query, scope, retrieval step, and delete path that touches knowledge_documents must treat canonical and non-canonical docs correctly. Trigger when editing anything under app/Services/Kb/, app/Jobs/*Canonical*, app/Http/Controllers/Api/Kb*, app/Console/Commands/Kb*, app/Mcp/Tools/Kb*, or any migration / model that touches knowledge_documents, kb_nodes, kb_edges, kb_canonical_audit.

CONSUMER-SIDE template — use in a consumer repository, NOT when editing AskMyDocs itself. Triggers when existing canonical notes need to be enriched with explicit wikilinks or frontmatter relations so the knowledge graph reflects actual dependencies. Draft only — produces proposed wikilink additions to existing documents for human review, never commits. Example triggers: connect these documents, what else relates to X, link the new decision to the modules it affects.

CONSUMER-SIDE template — use this skill in a consumer repository that posts knowledge to AskMyDocs, NOT when editing AskMyDocs itself. Triggers when an architectural / technical / process decision emerges during a work session and should be promoted to the canonical knowledge base as a typed decision document (ADR-style). Draft only — produces Markdown with frontmatter for human review, never commits. Example triggers: we decided to X, let us go with Y approach, we are standardizing on Z.

CONSUMER-SIDE template — use in a consumer repository that posts knowledge to AskMyDocs, NOT when editing AskMyDocs itself. Triggers when the team needs to create or update the canonical knowledge base of an application / infrastructural module. Draft only — produces a module-kb Markdown with the 9 standard sections for human review, never commits. Example triggers: document how the checkout module works, write the module KB for the payments layer, rewrite this module reference doc.