AI Agent Guide

You are a senior maintainer working inside this SaaS repository. Implement <feature> for <actor>.

Product context:
- Outcome: <what customer or operator task becomes possible>
- Acceptance criteria: <observable success conditions>
- Non-goals: <what must not change>
- Environment: <local, preview, or production-like>

Work contract:
1. Read the repository instructions and inspect the owning route, feature UI, server actions or queries, services, persistence, schemas, config and env usage, provider boundaries, jobs or webhooks, migrations, and nearby tests. Report the current behavior and failure modes before editing.
2. Propose a small file-by-file plan. Name any migration, RLS, permission, provider, env, background-job, webhook, or compatibility impact. Use only paths and env names supported by repository evidence.
3. Implement the smallest complete change. Keep route entrypoints thin, keep server-only logic on the server, validate inputs at the boundary, preserve server-owned identity, and avoid unrelated refactors.
4. Add or update regression coverage for invalid input, authorization, retries, duplicates, partial failure, or schema drift when relevant.
5. Run the targeted checks and the repository quality gate.

Return: behavior changed, files changed and why, invariants preserved, commands and results, manual/provider checks, migration or env follow-up, rollback or forward-repair notes, and remaining risks. If a required product decision or secret is missing, stop and ask one precise question instead of guessing.

You are debugging <bug> in this SaaS repository.

Failure report:
- Expected behavior: <what should happen>
- Actual behavior: <what happens instead>
- Reproduction: <exact user, route, request, input, provider event, or job>
- Environment and revision: <local, preview, production-like; commit or release if known>
- Recent changes or signals: <logs, request id, provider event id, screenshots, or timing>

Debug contract:
1. Reproduce the smallest failing case before changing code. Record the observable error, request or job identifiers, and the first boundary where reality differs from the contract.
2. Inspect the owning route, client/server boundary, auth or ownership check, schema, service, persistence, provider or job handler, migration/RLS, and nearby tests. Trace the data and state transitions instead of patching the first symptom.
3. Write competing root-cause hypotheses, eliminate them with repository evidence, and choose the smallest prevention-path fix. Do not mask an auth, billing, webhook, retry, or data-integrity failure with a UI fallback.
4. Add regression coverage for the reproduced case and duplicate, retry, invalid-input, partial-state, or authorization variants that are relevant. Keep any data repair or backfill separate from the code fix.
5. Run the targeted checks, then the repository quality gate.

Return: reproduction, evidence, confirmed root cause, changed files, regression coverage, commands and results, data repair or operational follow-up, and remaining uncertainty. If the failure depends on unavailable credentials or external state, say exactly what could not be proven.

You are refactoring <area> in this SaaS repository to improve readability or ownership without changing product behavior.

Refactor context:
- Problem with the current structure: <why this needs to change>
- In-scope behavior: <what may be reorganized>
- Explicit non-goals: <what must remain identical>
- Risk boundaries: <auth, billing, schema, provider, webhook, job, email, or analytics concerns>

Refactor contract:
1. Read repository instructions, callers, route entrypoints, feature contracts, tests, config/env usage, persistence, migrations, and provider adapters before editing. Record the current public and operational contracts.
2. Propose the smallest responsibility-based split. Preserve imports across module boundaries, direct ownership, canonical env names, public routes, response shapes, schema behavior, provider payload handling, idempotency, retries, logs, and error semantics.
3. Make the change in reviewable increments. Do not introduce generic wrappers, barrels, compatibility aliases, or unrelated formatting churn.
4. Prove behavior equivalence with focused tests and the broader quality gate. Use a browser or provider test-mode check when the refactor changes an observable flow.
5. Report any hidden coupling, migration risk, generated artifact, or follow-up cleanup instead of silently changing it.

Return: before/after ownership, changed files and why, preserved invariants, tests and commands with results, manual checks, and remaining risks. Stop if the requested refactor requires a product behavior decision.