{"owner":"riverqueue","repo":"river","hasSkills":true,"totalSkillsCount":2,"totalTokensCount":3661,"categories":["root-instruction","cursor-rule"],"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md",".cursorrules (flutter-riverpod-cursorrules-prompt-file.mdc)"],"skills":{"AGENTS.md":"# River Coding Guidelines\n\n## Running Tests and Lint\n\n- **Tests**: use `make test` as the default. Only use `go test ...` when you must pass specific flags (e.g. `-run`, `-count`, `-race`, build tags, etc.) or need to debug a specific test in isolation.\n- **Lint**: use `make lint` as the default. Only call `golangci-lint ...` directly when you must pass specific flags.\n- Always run test and lint prior to considering a task complete, unless told otherwise (or if you did not touch any Go code/tests).\n- If your execution environment has a sandbox/permission model, run `make test` and `make lint` unsandboxed (full permissions) so results match local dev and CI.\n\n## Other Build/Test Commands\n\n- **Run all tests with race detector**: `make test/race`\n- **Run single test**: `cd $MODULE && go test ./path/to/package -run TestName`\n- **Run benchmark**: `make bench`\n- **Generate sqlc**: `make generate`. Use this any time a `.sql` file has been modified and we need to then regenerate `.sql.go` files from it.\n- **Run tidy when deps change**: `make tidy`\n\n## Code Style Guidelines\n\n- **Imports**: use gci sections - Standard, Default, github.com/riverqueue.\n- **Formatting**: use gofmt, gofumpt, goimports.\n- **JSON tags**: use snake_case for JSON field tags.\n- **Dependencies**: minimize external dependencies beyond standard library and pgx.\n- **SQL access (non-test code)**: avoid ad-hoc SQL strings in library/runtime code. Add or extend a sqlc query, regenerate with `make generate`, and expose it through the driver interface. Keep direct SQL for tests and benchmark/admin utilities only (for example, `pg_stat_statements` and `VACUUM`).\n- **Driver interface stability**: treat `riverdriver` as an internal adapter seam, not as an official external API. Its package comments explicitly say it should not be implemented or invoked by user code, and changes there are not considered semver-breaking. Do not preserve driver-interface methods or semantics for outside consumers; add, remove, or reshape them as needed to preserve or improve user-facing functionality.\n- **Cross-driver driver tests**: treat `riverdriver/riverdrivertest` as the shared conformance suite for driver behavior. When changing `riverdriver` or a concrete driver, update or extend `riverdrivertest` so the intended semantics are exercised across drivers, not only in a single driver-specific test.\n- **Error handling**: prefer context-rich errors; review linting rules before disabling them.\n- **Testing**: use require variants instead of assert.\n- **Helpers**: use `Func` suffix for function variables, not `Fn`.\n- **Documentation**: include comments for exported functions and types.\n- **Terminology**: prefer \"Postgres\" over \"PostgreSQL\".\n- **Naming**: use idiomatic Go names; see `.golangci.yaml` for allowed short variable names.\n\n## Package Naming and Organization\n\n- Package names are lowercase, short, and representative; avoid `common`, `util`, or overly broad names.\n- Use singular package names; avoid plurals like `httputils`.\n- Keep import paths clean; avoid `src/`, `pkg/`, or other repo-structure leakage.\n- Organize by responsibility instead of `models`/`types` buckets; keep types close to usage.\n- Do not export identifiers from `main` packages that only build binaries.\n- Add package docs, and use `doc.go` when documentation is long.\n\n## Code Organization\n\nAlphabetization is important when adding new code (do not reorganize existing code unless asked).\n\n- Types should be sorted alphabetically by name.\n- Struct field definitions on a type should be sorted alphabetically by name, unless there is a good reason to deviate (examples: ID fields first, grouping mutexed fields after a mutex, etc.).\n- When declaring an instance of a struct, fields should be sorted alphabetically by name unless a similar deviation is justified.\n- When defining methods on a type, they should be sorted alphabetically by name.\n- Constructors should come immediately after the type definition.\n- Keep all methods for a type grouped together, immediately after the type definition and any constructor(s), organized alphabetically by name. Do not intersperse methods with other types or functions, except in special cases where a small utility type is needed to support a method and not used elsewhere.\n- In unit tests, the outer test blocks should be sorted alphabetically by name. Inner test blocks should also be sorted alphabetically by name within the outer block.\n\n## Go Testing Conventions: Parallel Test Bundle + Setup Helpers\n\nThis repo uses a parallel test bundle pattern (inspired by Brandur's write-up: https://brandur.org/fragments/parallel-test-bundle) to keep parallel subtests isolated and setup/fixtures DRY.\n\n- **Always opt into parallel**:\n  - **Top-level tests**: the first statement in every `TestXxx` should be `t.Parallel()`.\n  - **Subtests**: the first statement in every `t.Run(..., func(t *testing.T) { ... })` should be `t.Parallel()`, unless the subtest is intentionally non-parallel and includes a short comment explaining why.\n- **Statement ordering and spacing**:\n  - **Top-level tests**: use `t.Parallel()`, then a blank line, then test preamble (`ctx`, `setup`, helpers), then a blank line before subtests/assertions.\n  - **Subtests**: use `t.Parallel()`, then a blank line, then subtest preamble.\n  - If a subtest calls `setup(...)`, prefer one blank line after the setup assignment before assertions/actions.\n  - For tiny/obvious subtests (one short statement after `t.Parallel()` or `setup(...)`), omitting one of these blank lines is acceptable.\n- **Context and setup ordering**:\n  - If `setup` needs `ctx` (`setup(ctx, t)`), assign/derive `ctx` before calling `setup`.\n  - If `setup` does not need `ctx` (`setup(t)`), call `setup` first and derive specialized contexts (`WithCancel`, `WithTimeout`) close to where they are used.\n  - Avoid creating/deriving `ctx` far from usage unless shared setup requires it.\n- **Prefer local bundles**:\n  - Define a `type testBundle struct { ... }` inside the `TestXxx` function containing the system under test and any fixtures frequently used across subtests.\n  - Each parallel subtest should call `setup(t)` to get a fresh bundle. Avoid sharing mutable state across parallel subtests.\n- **`setup` helper rules**:\n  - Define `setup` as a local closure in the test:\n    - `setup := func(t *testing.T) *testBundle { ... }`\n    - Always call `t.Helper()` at the top of `setup`.\n  - **Only accept a context parameter if it is needed**:\n    - **Default**: `setup(t)` should not take `ctx`.\n    - **If setup must derive/seed a context**: prefer returning it: `setup := func(t *testing.T) (*testBundle, context.Context)`.\n    - **If setup must be passed an existing context**: accept `ctx` as the first parameter: `setup := func(ctx context.Context, t *testing.T) *testBundle`.\n  - Keep `setup` deterministic and self-contained; it should only use the `*testing.T` (and `ctx` if explicitly required) passed in.\n- **Test signal instrumentation**:\n  - Prefer `rivershared/testsignal.TestSignal` in a `...TestSignals` struct with an `Init(tb)` helper over ad hoc `chan struct{}` fields in spies/fakes.\n  - Keep test-signal structs zero-value by default and call `Init(t)` only in tests that need to observe those signals.\n  - Wait for async events with `WaitOrTimeout()`. For negative assertions, use `RequireEmpty()` or `WaitC()` with a timeout select.\n  - Avoid custom channel signaling helpers and hand-managed channel capacities unless there is a specific, documented reason.\n\nTemplate:\n\n```go\nfunc TestThing(t *testing.T) {\n\tt.Parallel()\n\n\ttype testBundle struct {\n\t\t// Put SUT + common fixtures here.\n\t}\n\n\tsetup := func(t *testing.T) *testBundle {\n\t\tt.Helper()\n\n\t\treturn &testBundle{}\n\t}\n\n\tt.Run(\"CaseName\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tbundle := setup(t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n\n\tt.Run(\"CaseNameWithCtxRequiredBySetup\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tsetupWithCtx := func(ctx context.Context, t *testing.T) *testBundle {\n\t\t\tt.Helper()\n\n\t\t\t_ = ctx\n\t\t\treturn &testBundle{}\n\t\t}\n\n\t\tctx := context.Background()\n\t\tbundle := setupWithCtx(ctx, t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n}\n```\n",".cursorrules (flutter-riverpod-cursorrules-prompt-file.mdc)":"---\ndescription: \"Cursor rules for Flutter Riverpod.\"\nglobs: **/*\nalwaysApply: false\n---\n# AI Assistant Technical Instructions\n\nYou are an AI assistant with advanced problem-solving capabilities. Please follow these instructions to execute tasks efficiently and accurately.\n\nFirst, confirm the instructions received from the user:\n\n<instructions>\n{{instructions}}\n</instructions>\n\nPlease proceed with the following process based on these instructions:\n\n---\n\n## 1. Instruction Analysis and Planning\n\n<Task Analysis>\n- Summarize the main tasks concisely\n- Review the specified tech stack and consider implementation methods within those constraints  \n  **Note: Do not change versions listed in the tech stack without approval**\n- Identify key requirements and constraints\n- List potential challenges\n- Enumerate specific steps for task execution in detail\n- Determine the optimal execution order for these steps\n\n### Preventing Duplicate Implementation\n\nBefore implementation, verify:\n- Existence of similar functionality\n- Functions or components with identical or similar names\n- Duplicate API endpoints\n- Identification of processes that can be shared\n\nTake sufficient time for this section as it guides the entire subsequent process. Conduct thorough and comprehensive analysis.\n</Task Analysis>\n\n---\n\n## 2. Task Execution\n\n- Execute identified steps one by one\n- Report progress concisely after completing each step\n- Pay attention to the following during implementation:\n  - Adherence to proper directory structure\n  - Consistency in naming conventions\n  - Appropriate placement of shared processes\n\n---\n\n## 3. Quality Control and Problem Resolution\n\n- Quickly verify the execution results of each task\n- If errors or inconsistencies occur, address them through the following process:\n  a. Problem isolation and cause identification (log analysis, debug information verification)\n  b. Creation and implementation of countermeasures\n  c. Post-fix operation verification\n  d. Debug log confirmation and analysis\n\n- Record verification results in the following format:\n  a. Verification items and expected results\n  b. Actual results and discrepancies\n  c. Required countermeasures (if applicable)\n\n---\n\n## 4. Final Confirmation\n\n- Evaluate the entire deliverable once all tasks are completed\n- Verify consistency with original instructions and make adjustments as needed\n- Perform final confirmation that there are no duplicates in implemented functions\n\n---\n\n## 5. Results Report\n\nPlease report final results in the following format:\n\nmarkdown\n# Execution Results Report\n\n## Overview\n\n[Brief description of overall summary]\n\n## Execution Steps\n\n1. [Step 1 description and results]\n2. [Step 2 description and results]\n...\n\n## Final Deliverables\n\n[Details of deliverables, links if applicable]\n\n## Issue Resolution (if applicable)\n\n- Problems encountered and responses\n- Future considerations\n\n## Notes & Improvement Suggestions\n\n- [List any observations or suggestions for improvement]\n\n---\n\n## Important Notes\n\n- Always confirm any unclear points before beginning work\n- Report and obtain approval for any important decisions as they arise\n- Report unexpected problems immediately and propose solutions\n- **Do not make changes that are not explicitly instructed.** If changes seem necessary, first report them as proposals and implement only after approval\n- **UI/UX design changes (layout, colors, fonts, spacing, etc.) are prohibited** unless approved after presenting justification\n- **Do not arbitrarily change versions listed in the tech stack** (APIs, frameworks, libraries, etc.). If changes are necessary, clearly explain the reason and wait for approval before making any changes\n\n---\n\n# Tech Stack\n\n## Core Technologies\n\n- **AI Model: GPT-4**\n\n## Frontend\n\n- Flutter: ^3.22.0\n\n### State Management\n\n- Riverpod: ^2.6.1\n\n## BaaS\n\n- Firebase\n\n---\n\n## Project Structure\n\nPlease implement following this directory structure:\n\nlib/features/products/\n├── data/\n│   ├── models/\n│   │   ├── product_dto.dart\n│   │   └── product_category_dto.dart\n│   └── product_repository.dart\n├── presentation/\n│   ├── screens/\n│   │   ├── product_list_screen.dart\n│   │   └── product_details_screen.dart\n│   ├── controllers/\n│   │   └── product_list_controller.dart\n│   ├── widgets/\n│       └── product_card.dart\n├── domain/\n│   ├── models/\n│   │   ├── product.dart\n│   │   └── product_category.dart\n│   └── get_products_use_case.dart\n└── shared/\n    └── models/\n        └── address.dart\n\n## Placement Rules\n\n### Flutter Project Structure Placement Rules\n\nThis document outlines the placement rules for files and folders within the recommended Flutter project structure, focusing on scalability, maintainability, and adherence to Clean Architecture principles.\n\n#### Top-Level Structure\n\nlib/\n├── features/\n├── models/\n├── providers/\n├── routes/\n├── core/\n├── app.dart\n└── main.dart\n\n*   **lib/**: Contains all Dart code.\n*   **features/**: Feature-specific code.\n*   **models/**: Global models (use sparingly).\n*   **providers/**: Global providers (minimize use).\n*   **routes/**: App navigation.\n*   **core/**: Core app logic (networking, errors, DI).\n*   **app.dart**: Root widget.\n*   **main.dart**: Entry point.\n\n#### features/ Structure\n\nlib/features/\n└── <feature_name>/\n├── data/\n│   ├── models/\n│   └── <feature_name>_repository.dart\n├── presentation/\n│   ├── screens/\n│   ├── controllers/\n│   ├── widgets/\n├── domain/\n│   ├── models/\n│   └── <feature_name>.dart\n├── use_cases/\n└── shared/\n└── models/\n\n*   **<feature_name>/**: A feature (e.g., authentication, products).\n*   **data/**: Data access.\n    *   **models/**: Data Transfer Objects (DTOs).\n    *   **<feature_name>_repository.dart**: Data access logic.\n*   **presentation/**: UI.\n    *   **screens/**: UI screens (<feature_name>_<screen_name>_screen.dart).\n    *   **controllers/**: State management (<feature_name>_controller.dart).\n    *   **widgets/**: Feature-specific widgets (<widget_name>.dart).\n*   **domain/**: Business logic.\n    *   **models/**: Domain models.\n    *   **<feature_name>.dart**: Main entity.\n*   **use_cases/**: User interactions (<use_case_name>.dart).\n*   **shared/models/**: Models shared between *related* features.\n\n#### shared/ (Top-Level) Structure\n\nlib/shared/\n├── providers/\n├── widgets/\n├── models/\n└── services/\n\n*   **providers/**: Providers shared across *unrelated* features.\n*   **widgets/**: Widgets shared across *unrelated* features.\n*   **models/**: Models shared across *unrelated* features (use cautiously).\n*   **services/**: Utility classes.\n\n#### models/ (Top-Level) Structure\n\nlib/models/\n└── <model_name>.dart\n\n*   Global models (use sparingly).\n\n#### providers/ (Top-Level) Structure\n\nlib/providers/\n└── <provider_name>.dart\n\n*   Global providers (minimize use).\n\n#### core/ Structure\n\nlib/core/\n├── network/\n│   └── api_client.dart\n├── errors/\n│   └── exceptions.dart\n└── di/\n└── injection.dart\n\n*   **network/**: Networking code.\n*   **errors/**: Error handling.\n*   **di/**: Dependency injection.\n\n## Naming Conventions\n\n*   **Files:** snake_case (e.g., product_list_screen.dart).\n*   **Classes:** PascalCase (e.g., ProductListScreen).\n*   **Variables/Functions:** camelCase (e.g., productList).\n\n## Key Principles\n\n*   **Feature Isolation:** Self-contained feature code.\n*   **Separation of Concerns:** Separate data, logic, and UI.\n*   **Single Responsibility:** One purpose per class/file.\n*   **DRY:** Avoid code duplication.\n*   **Prefer Feature-Specific:** Prioritize feature-level placement.\n\nPlease adhere to the above content when executing tasks.\n"},"files":{"AGENTS.md":"# River Coding Guidelines\n\n## Running Tests and Lint\n\n- **Tests**: use `make test` as the default. Only use `go test ...` when you must pass specific flags (e.g. `-run`, `-count`, `-race`, build tags, etc.) or need to debug a specific test in isolation.\n- **Lint**: use `make lint` as the default. Only call `golangci-lint ...` directly when you must pass specific flags.\n- Always run test and lint prior to considering a task complete, unless told otherwise (or if you did not touch any Go code/tests).\n- If your execution environment has a sandbox/permission model, run `make test` and `make lint` unsandboxed (full permissions) so results match local dev and CI.\n\n## Other Build/Test Commands\n\n- **Run all tests with race detector**: `make test/race`\n- **Run single test**: `cd $MODULE && go test ./path/to/package -run TestName`\n- **Run benchmark**: `make bench`\n- **Generate sqlc**: `make generate`. Use this any time a `.sql` file has been modified and we need to then regenerate `.sql.go` files from it.\n- **Run tidy when deps change**: `make tidy`\n\n## Code Style Guidelines\n\n- **Imports**: use gci sections - Standard, Default, github.com/riverqueue.\n- **Formatting**: use gofmt, gofumpt, goimports.\n- **JSON tags**: use snake_case for JSON field tags.\n- **Dependencies**: minimize external dependencies beyond standard library and pgx.\n- **SQL access (non-test code)**: avoid ad-hoc SQL strings in library/runtime code. Add or extend a sqlc query, regenerate with `make generate`, and expose it through the driver interface. Keep direct SQL for tests and benchmark/admin utilities only (for example, `pg_stat_statements` and `VACUUM`).\n- **Driver interface stability**: treat `riverdriver` as an internal adapter seam, not as an official external API. Its package comments explicitly say it should not be implemented or invoked by user code, and changes there are not considered semver-breaking. Do not preserve driver-interface methods or semantics for outside consumers; add, remove, or reshape them as needed to preserve or improve user-facing functionality.\n- **Cross-driver driver tests**: treat `riverdriver/riverdrivertest` as the shared conformance suite for driver behavior. When changing `riverdriver` or a concrete driver, update or extend `riverdrivertest` so the intended semantics are exercised across drivers, not only in a single driver-specific test.\n- **Error handling**: prefer context-rich errors; review linting rules before disabling them.\n- **Testing**: use require variants instead of assert.\n- **Helpers**: use `Func` suffix for function variables, not `Fn`.\n- **Documentation**: include comments for exported functions and types.\n- **Terminology**: prefer \"Postgres\" over \"PostgreSQL\".\n- **Naming**: use idiomatic Go names; see `.golangci.yaml` for allowed short variable names.\n\n## Package Naming and Organization\n\n- Package names are lowercase, short, and representative; avoid `common`, `util`, or overly broad names.\n- Use singular package names; avoid plurals like `httputils`.\n- Keep import paths clean; avoid `src/`, `pkg/`, or other repo-structure leakage.\n- Organize by responsibility instead of `models`/`types` buckets; keep types close to usage.\n- Do not export identifiers from `main` packages that only build binaries.\n- Add package docs, and use `doc.go` when documentation is long.\n\n## Code Organization\n\nAlphabetization is important when adding new code (do not reorganize existing code unless asked).\n\n- Types should be sorted alphabetically by name.\n- Struct field definitions on a type should be sorted alphabetically by name, unless there is a good reason to deviate (examples: ID fields first, grouping mutexed fields after a mutex, etc.).\n- When declaring an instance of a struct, fields should be sorted alphabetically by name unless a similar deviation is justified.\n- When defining methods on a type, they should be sorted alphabetically by name.\n- Constructors should come immediately after the type definition.\n- Keep all methods for a type grouped together, immediately after the type definition and any constructor(s), organized alphabetically by name. Do not intersperse methods with other types or functions, except in special cases where a small utility type is needed to support a method and not used elsewhere.\n- In unit tests, the outer test blocks should be sorted alphabetically by name. Inner test blocks should also be sorted alphabetically by name within the outer block.\n\n## Go Testing Conventions: Parallel Test Bundle + Setup Helpers\n\nThis repo uses a parallel test bundle pattern (inspired by Brandur's write-up: https://brandur.org/fragments/parallel-test-bundle) to keep parallel subtests isolated and setup/fixtures DRY.\n\n- **Always opt into parallel**:\n  - **Top-level tests**: the first statement in every `TestXxx` should be `t.Parallel()`.\n  - **Subtests**: the first statement in every `t.Run(..., func(t *testing.T) { ... })` should be `t.Parallel()`, unless the subtest is intentionally non-parallel and includes a short comment explaining why.\n- **Statement ordering and spacing**:\n  - **Top-level tests**: use `t.Parallel()`, then a blank line, then test preamble (`ctx`, `setup`, helpers), then a blank line before subtests/assertions.\n  - **Subtests**: use `t.Parallel()`, then a blank line, then subtest preamble.\n  - If a subtest calls `setup(...)`, prefer one blank line after the setup assignment before assertions/actions.\n  - For tiny/obvious subtests (one short statement after `t.Parallel()` or `setup(...)`), omitting one of these blank lines is acceptable.\n- **Context and setup ordering**:\n  - If `setup` needs `ctx` (`setup(ctx, t)`), assign/derive `ctx` before calling `setup`.\n  - If `setup` does not need `ctx` (`setup(t)`), call `setup` first and derive specialized contexts (`WithCancel`, `WithTimeout`) close to where they are used.\n  - Avoid creating/deriving `ctx` far from usage unless shared setup requires it.\n- **Prefer local bundles**:\n  - Define a `type testBundle struct { ... }` inside the `TestXxx` function containing the system under test and any fixtures frequently used across subtests.\n  - Each parallel subtest should call `setup(t)` to get a fresh bundle. Avoid sharing mutable state across parallel subtests.\n- **`setup` helper rules**:\n  - Define `setup` as a local closure in the test:\n    - `setup := func(t *testing.T) *testBundle { ... }`\n    - Always call `t.Helper()` at the top of `setup`.\n  - **Only accept a context parameter if it is needed**:\n    - **Default**: `setup(t)` should not take `ctx`.\n    - **If setup must derive/seed a context**: prefer returning it: `setup := func(t *testing.T) (*testBundle, context.Context)`.\n    - **If setup must be passed an existing context**: accept `ctx` as the first parameter: `setup := func(ctx context.Context, t *testing.T) *testBundle`.\n  - Keep `setup` deterministic and self-contained; it should only use the `*testing.T` (and `ctx` if explicitly required) passed in.\n- **Test signal instrumentation**:\n  - Prefer `rivershared/testsignal.TestSignal` in a `...TestSignals` struct with an `Init(tb)` helper over ad hoc `chan struct{}` fields in spies/fakes.\n  - Keep test-signal structs zero-value by default and call `Init(t)` only in tests that need to observe those signals.\n  - Wait for async events with `WaitOrTimeout()`. For negative assertions, use `RequireEmpty()` or `WaitC()` with a timeout select.\n  - Avoid custom channel signaling helpers and hand-managed channel capacities unless there is a specific, documented reason.\n\nTemplate:\n\n```go\nfunc TestThing(t *testing.T) {\n\tt.Parallel()\n\n\ttype testBundle struct {\n\t\t// Put SUT + common fixtures here.\n\t}\n\n\tsetup := func(t *testing.T) *testBundle {\n\t\tt.Helper()\n\n\t\treturn &testBundle{}\n\t}\n\n\tt.Run(\"CaseName\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tbundle := setup(t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n\n\tt.Run(\"CaseNameWithCtxRequiredBySetup\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tsetupWithCtx := func(ctx context.Context, t *testing.T) *testBundle {\n\t\t\tt.Helper()\n\n\t\t\t_ = ctx\n\t\t\treturn &testBundle{}\n\t\t}\n\n\t\tctx := context.Background()\n\t\tbundle := setupWithCtx(ctx, t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n}\n```\n",".cursorrules (flutter-riverpod-cursorrules-prompt-file.mdc)":"---\ndescription: \"Cursor rules for Flutter Riverpod.\"\nglobs: **/*\nalwaysApply: false\n---\n# AI Assistant Technical Instructions\n\nYou are an AI assistant with advanced problem-solving capabilities. Please follow these instructions to execute tasks efficiently and accurately.\n\nFirst, confirm the instructions received from the user:\n\n<instructions>\n{{instructions}}\n</instructions>\n\nPlease proceed with the following process based on these instructions:\n\n---\n\n## 1. Instruction Analysis and Planning\n\n<Task Analysis>\n- Summarize the main tasks concisely\n- Review the specified tech stack and consider implementation methods within those constraints  \n  **Note: Do not change versions listed in the tech stack without approval**\n- Identify key requirements and constraints\n- List potential challenges\n- Enumerate specific steps for task execution in detail\n- Determine the optimal execution order for these steps\n\n### Preventing Duplicate Implementation\n\nBefore implementation, verify:\n- Existence of similar functionality\n- Functions or components with identical or similar names\n- Duplicate API endpoints\n- Identification of processes that can be shared\n\nTake sufficient time for this section as it guides the entire subsequent process. Conduct thorough and comprehensive analysis.\n</Task Analysis>\n\n---\n\n## 2. Task Execution\n\n- Execute identified steps one by one\n- Report progress concisely after completing each step\n- Pay attention to the following during implementation:\n  - Adherence to proper directory structure\n  - Consistency in naming conventions\n  - Appropriate placement of shared processes\n\n---\n\n## 3. Quality Control and Problem Resolution\n\n- Quickly verify the execution results of each task\n- If errors or inconsistencies occur, address them through the following process:\n  a. Problem isolation and cause identification (log analysis, debug information verification)\n  b. Creation and implementation of countermeasures\n  c. Post-fix operation verification\n  d. Debug log confirmation and analysis\n\n- Record verification results in the following format:\n  a. Verification items and expected results\n  b. Actual results and discrepancies\n  c. Required countermeasures (if applicable)\n\n---\n\n## 4. Final Confirmation\n\n- Evaluate the entire deliverable once all tasks are completed\n- Verify consistency with original instructions and make adjustments as needed\n- Perform final confirmation that there are no duplicates in implemented functions\n\n---\n\n## 5. Results Report\n\nPlease report final results in the following format:\n\nmarkdown\n# Execution Results Report\n\n## Overview\n\n[Brief description of overall summary]\n\n## Execution Steps\n\n1. [Step 1 description and results]\n2. [Step 2 description and results]\n...\n\n## Final Deliverables\n\n[Details of deliverables, links if applicable]\n\n## Issue Resolution (if applicable)\n\n- Problems encountered and responses\n- Future considerations\n\n## Notes & Improvement Suggestions\n\n- [List any observations or suggestions for improvement]\n\n---\n\n## Important Notes\n\n- Always confirm any unclear points before beginning work\n- Report and obtain approval for any important decisions as they arise\n- Report unexpected problems immediately and propose solutions\n- **Do not make changes that are not explicitly instructed.** If changes seem necessary, first report them as proposals and implement only after approval\n- **UI/UX design changes (layout, colors, fonts, spacing, etc.) are prohibited** unless approved after presenting justification\n- **Do not arbitrarily change versions listed in the tech stack** (APIs, frameworks, libraries, etc.). If changes are necessary, clearly explain the reason and wait for approval before making any changes\n\n---\n\n# Tech Stack\n\n## Core Technologies\n\n- **AI Model: GPT-4**\n\n## Frontend\n\n- Flutter: ^3.22.0\n\n### State Management\n\n- Riverpod: ^2.6.1\n\n## BaaS\n\n- Firebase\n\n---\n\n## Project Structure\n\nPlease implement following this directory structure:\n\nlib/features/products/\n├── data/\n│   ├── models/\n│   │   ├── product_dto.dart\n│   │   └── product_category_dto.dart\n│   └── product_repository.dart\n├── presentation/\n│   ├── screens/\n│   │   ├── product_list_screen.dart\n│   │   └── product_details_screen.dart\n│   ├── controllers/\n│   │   └── product_list_controller.dart\n│   ├── widgets/\n│       └── product_card.dart\n├── domain/\n│   ├── models/\n│   │   ├── product.dart\n│   │   └── product_category.dart\n│   └── get_products_use_case.dart\n└── shared/\n    └── models/\n        └── address.dart\n\n## Placement Rules\n\n### Flutter Project Structure Placement Rules\n\nThis document outlines the placement rules for files and folders within the recommended Flutter project structure, focusing on scalability, maintainability, and adherence to Clean Architecture principles.\n\n#### Top-Level Structure\n\nlib/\n├── features/\n├── models/\n├── providers/\n├── routes/\n├── core/\n├── app.dart\n└── main.dart\n\n*   **lib/**: Contains all Dart code.\n*   **features/**: Feature-specific code.\n*   **models/**: Global models (use sparingly).\n*   **providers/**: Global providers (minimize use).\n*   **routes/**: App navigation.\n*   **core/**: Core app logic (networking, errors, DI).\n*   **app.dart**: Root widget.\n*   **main.dart**: Entry point.\n\n#### features/ Structure\n\nlib/features/\n└── <feature_name>/\n├── data/\n│   ├── models/\n│   └── <feature_name>_repository.dart\n├── presentation/\n│   ├── screens/\n│   ├── controllers/\n│   ├── widgets/\n├── domain/\n│   ├── models/\n│   └── <feature_name>.dart\n├── use_cases/\n└── shared/\n└── models/\n\n*   **<feature_name>/**: A feature (e.g., authentication, products).\n*   **data/**: Data access.\n    *   **models/**: Data Transfer Objects (DTOs).\n    *   **<feature_name>_repository.dart**: Data access logic.\n*   **presentation/**: UI.\n    *   **screens/**: UI screens (<feature_name>_<screen_name>_screen.dart).\n    *   **controllers/**: State management (<feature_name>_controller.dart).\n    *   **widgets/**: Feature-specific widgets (<widget_name>.dart).\n*   **domain/**: Business logic.\n    *   **models/**: Domain models.\n    *   **<feature_name>.dart**: Main entity.\n*   **use_cases/**: User interactions (<use_case_name>.dart).\n*   **shared/models/**: Models shared between *related* features.\n\n#### shared/ (Top-Level) Structure\n\nlib/shared/\n├── providers/\n├── widgets/\n├── models/\n└── services/\n\n*   **providers/**: Providers shared across *unrelated* features.\n*   **widgets/**: Widgets shared across *unrelated* features.\n*   **models/**: Models shared across *unrelated* features (use cautiously).\n*   **services/**: Utility classes.\n\n#### models/ (Top-Level) Structure\n\nlib/models/\n└── <model_name>.dart\n\n*   Global models (use sparingly).\n\n#### providers/ (Top-Level) Structure\n\nlib/providers/\n└── <provider_name>.dart\n\n*   Global providers (minimize use).\n\n#### core/ Structure\n\nlib/core/\n├── network/\n│   └── api_client.dart\n├── errors/\n│   └── exceptions.dart\n└── di/\n└── injection.dart\n\n*   **network/**: Networking code.\n*   **errors/**: Error handling.\n*   **di/**: Dependency injection.\n\n## Naming Conventions\n\n*   **Files:** snake_case (e.g., product_list_screen.dart).\n*   **Classes:** PascalCase (e.g., ProductListScreen).\n*   **Variables/Functions:** camelCase (e.g., productList).\n\n## Key Principles\n\n*   **Feature Isolation:** Self-contained feature code.\n*   **Separation of Concerns:** Separate data, logic, and UI.\n*   **Single Responsibility:** One purpose per class/file.\n*   **DRY:** Avoid code duplication.\n*   **Prefer Feature-Specific:** Prioritize feature-level placement.\n\nPlease adhere to the above content when executing tasks.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/riverqueue/river/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# River Coding Guidelines\n\n## Running Tests and Lint\n\n- **Tests**: use `make test` as the default. Only use `go test ...` when you must pass specific flags (e.g. `-run`, `-count`, `-race`, build tags, etc.) or need to debug a specific test in isolation.\n- **Lint**: use `make lint` as the default. Only call `golangci-lint ...` directly when you must pass specific flags.\n- Always run test and lint prior to considering a task complete, unless told otherwise (or if you did not touch any Go code/tests).\n- If your execution environment has a sandbox/permission model, run `make test` and `make lint` unsandboxed (full permissions) so results match local dev and CI.\n\n## Other Build/Test Commands\n\n- **Run all tests with race detector**: `make test/race`\n- **Run single test**: `cd $MODULE && go test ./path/to/package -run TestName`\n- **Run benchmark**: `make bench`\n- **Generate sqlc**: `make generate`. Use this any time a `.sql` file has been modified and we need to then regenerate `.sql.go` files from it.\n- **Run tidy when deps change**: `make tidy`\n\n## Code Style Guidelines\n\n- **Imports**: use gci sections - Standard, Default, github.com/riverqueue.\n- **Formatting**: use gofmt, gofumpt, goimports.\n- **JSON tags**: use snake_case for JSON field tags.\n- **Dependencies**: minimize external dependencies beyond standard library and pgx.\n- **SQL access (non-test code)**: avoid ad-hoc SQL strings in library/runtime code. Add or extend a sqlc query, regenerate with `make generate`, and expose it through the driver interface. Keep direct SQL for tests and benchmark/admin utilities only (for example, `pg_stat_statements` and `VACUUM`).\n- **Driver interface stability**: treat `riverdriver` as an internal adapter seam, not as an official external API. Its package comments explicitly say it should not be implemented or invoked by user code, and changes there are not considered semver-breaking. Do not preserve driver-interface methods or semantics for outside consumers; add, remove, or reshape them as needed to preserve or improve user-facing functionality.\n- **Cross-driver driver tests**: treat `riverdriver/riverdrivertest` as the shared conformance suite for driver behavior. When changing `riverdriver` or a concrete driver, update or extend `riverdrivertest` so the intended semantics are exercised across drivers, not only in a single driver-specific test.\n- **Error handling**: prefer context-rich errors; review linting rules before disabling them.\n- **Testing**: use require variants instead of assert.\n- **Helpers**: use `Func` suffix for function variables, not `Fn`.\n- **Documentation**: include comments for exported functions and types.\n- **Terminology**: prefer \"Postgres\" over \"PostgreSQL\".\n- **Naming**: use idiomatic Go names; see `.golangci.yaml` for allowed short variable names.\n\n## Package Naming and Organization\n\n- Package names are lowercase, short, and representative; avoid `common`, `util`, or overly broad names.\n- Use singular package names; avoid plurals like `httputils`.\n- Keep import paths clean; avoid `src/`, `pkg/`, or other repo-structure leakage.\n- Organize by responsibility instead of `models`/`types` buckets; keep types close to usage.\n- Do not export identifiers from `main` packages that only build binaries.\n- Add package docs, and use `doc.go` when documentation is long.\n\n## Code Organization\n\nAlphabetization is important when adding new code (do not reorganize existing code unless asked).\n\n- Types should be sorted alphabetically by name.\n- Struct field definitions on a type should be sorted alphabetically by name, unless there is a good reason to deviate (examples: ID fields first, grouping mutexed fields after a mutex, etc.).\n- When declaring an instance of a struct, fields should be sorted alphabetically by name unless a similar deviation is justified.\n- When defining methods on a type, they should be sorted alphabetically by name.\n- Constructors should come immediately after the type definition.\n- Keep all methods for a type grouped together, immediately after the type definition and any constructor(s), organized alphabetically by name. Do not intersperse methods with other types or functions, except in special cases where a small utility type is needed to support a method and not used elsewhere.\n- In unit tests, the outer test blocks should be sorted alphabetically by name. Inner test blocks should also be sorted alphabetically by name within the outer block.\n\n## Go Testing Conventions: Parallel Test Bundle + Setup Helpers\n\nThis repo uses a parallel test bundle pattern (inspired by Brandur's write-up: https://brandur.org/fragments/parallel-test-bundle) to keep parallel subtests isolated and setup/fixtures DRY.\n\n- **Always opt into parallel**:\n  - **Top-level tests**: the first statement in every `TestXxx` should be `t.Parallel()`.\n  - **Subtests**: the first statement in every `t.Run(..., func(t *testing.T) { ... })` should be `t.Parallel()`, unless the subtest is intentionally non-parallel and includes a short comment explaining why.\n- **Statement ordering and spacing**:\n  - **Top-level tests**: use `t.Parallel()`, then a blank line, then test preamble (`ctx`, `setup`, helpers), then a blank line before subtests/assertions.\n  - **Subtests**: use `t.Parallel()`, then a blank line, then subtest preamble.\n  - If a subtest calls `setup(...)`, prefer one blank line after the setup assignment before assertions/actions.\n  - For tiny/obvious subtests (one short statement after `t.Parallel()` or `setup(...)`), omitting one of these blank lines is acceptable.\n- **Context and setup ordering**:\n  - If `setup` needs `ctx` (`setup(ctx, t)`), assign/derive `ctx` before calling `setup`.\n  - If `setup` does not need `ctx` (`setup(t)`), call `setup` first and derive specialized contexts (`WithCancel`, `WithTimeout`) close to where they are used.\n  - Avoid creating/deriving `ctx` far from usage unless shared setup requires it.\n- **Prefer local bundles**:\n  - Define a `type testBundle struct { ... }` inside the `TestXxx` function containing the system under test and any fixtures frequently used across subtests.\n  - Each parallel subtest should call `setup(t)` to get a fresh bundle. Avoid sharing mutable state across parallel subtests.\n- **`setup` helper rules**:\n  - Define `setup` as a local closure in the test:\n    - `setup := func(t *testing.T) *testBundle { ... }`\n    - Always call `t.Helper()` at the top of `setup`.\n  - **Only accept a context parameter if it is needed**:\n    - **Default**: `setup(t)` should not take `ctx`.\n    - **If setup must derive/seed a context**: prefer returning it: `setup := func(t *testing.T) (*testBundle, context.Context)`.\n    - **If setup must be passed an existing context**: accept `ctx` as the first parameter: `setup := func(ctx context.Context, t *testing.T) *testBundle`.\n  - Keep `setup` deterministic and self-contained; it should only use the `*testing.T` (and `ctx` if explicitly required) passed in.\n- **Test signal instrumentation**:\n  - Prefer `rivershared/testsignal.TestSignal` in a `...TestSignals` struct with an `Init(tb)` helper over ad hoc `chan struct{}` fields in spies/fakes.\n  - Keep test-signal structs zero-value by default and call `Init(t)` only in tests that need to observe those signals.\n  - Wait for async events with `WaitOrTimeout()`. For negative assertions, use `RequireEmpty()` or `WaitC()` with a timeout select.\n  - Avoid custom channel signaling helpers and hand-managed channel capacities unless there is a specific, documented reason.\n\nTemplate:\n\n```go\nfunc TestThing(t *testing.T) {\n\tt.Parallel()\n\n\ttype testBundle struct {\n\t\t// Put SUT + common fixtures here.\n\t}\n\n\tsetup := func(t *testing.T) *testBundle {\n\t\tt.Helper()\n\n\t\treturn &testBundle{}\n\t}\n\n\tt.Run(\"CaseName\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tbundle := setup(t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n\n\tt.Run(\"CaseNameWithCtxRequiredBySetup\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tsetupWithCtx := func(ctx context.Context, t *testing.T) *testBundle {\n\t\t\tt.Helper()\n\n\t\t\t_ = ctx\n\t\t\treturn &testBundle{}\n\t\t}\n\n\t\tctx := context.Background()\n\t\tbundle := setupWithCtx(ctx, t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n}\n```\n","isInternal":false,"tokens":1925,"sizeBytes":8197},{"name":".cursorrules","path":".cursorrules (flutter-riverpod-cursorrules-prompt-file.mdc)","rawUrl":"https://raw.githubusercontent.com/PatrickJS/awesome-cursorrules/main/rules/flutter-riverpod-cursorrules-prompt-file.mdc","title":"Awesome Cursorrules: flutter riverpod","category":"cursor-rule","format":"markdown","content":"---\ndescription: \"Cursor rules for Flutter Riverpod.\"\nglobs: **/*\nalwaysApply: false\n---\n# AI Assistant Technical Instructions\n\nYou are an AI assistant with advanced problem-solving capabilities. Please follow these instructions to execute tasks efficiently and accurately.\n\nFirst, confirm the instructions received from the user:\n\n<instructions>\n{{instructions}}\n</instructions>\n\nPlease proceed with the following process based on these instructions:\n\n---\n\n## 1. Instruction Analysis and Planning\n\n<Task Analysis>\n- Summarize the main tasks concisely\n- Review the specified tech stack and consider implementation methods within those constraints  \n  **Note: Do not change versions listed in the tech stack without approval**\n- Identify key requirements and constraints\n- List potential challenges\n- Enumerate specific steps for task execution in detail\n- Determine the optimal execution order for these steps\n\n### Preventing Duplicate Implementation\n\nBefore implementation, verify:\n- Existence of similar functionality\n- Functions or components with identical or similar names\n- Duplicate API endpoints\n- Identification of processes that can be shared\n\nTake sufficient time for this section as it guides the entire subsequent process. Conduct thorough and comprehensive analysis.\n</Task Analysis>\n\n---\n\n## 2. Task Execution\n\n- Execute identified steps one by one\n- Report progress concisely after completing each step\n- Pay attention to the following during implementation:\n  - Adherence to proper directory structure\n  - Consistency in naming conventions\n  - Appropriate placement of shared processes\n\n---\n\n## 3. Quality Control and Problem Resolution\n\n- Quickly verify the execution results of each task\n- If errors or inconsistencies occur, address them through the following process:\n  a. Problem isolation and cause identification (log analysis, debug information verification)\n  b. Creation and implementation of countermeasures\n  c. Post-fix operation verification\n  d. Debug log confirmation and analysis\n\n- Record verification results in the following format:\n  a. Verification items and expected results\n  b. Actual results and discrepancies\n  c. Required countermeasures (if applicable)\n\n---\n\n## 4. Final Confirmation\n\n- Evaluate the entire deliverable once all tasks are completed\n- Verify consistency with original instructions and make adjustments as needed\n- Perform final confirmation that there are no duplicates in implemented functions\n\n---\n\n## 5. Results Report\n\nPlease report final results in the following format:\n\nmarkdown\n# Execution Results Report\n\n## Overview\n\n[Brief description of overall summary]\n\n## Execution Steps\n\n1. [Step 1 description and results]\n2. [Step 2 description and results]\n...\n\n## Final Deliverables\n\n[Details of deliverables, links if applicable]\n\n## Issue Resolution (if applicable)\n\n- Problems encountered and responses\n- Future considerations\n\n## Notes & Improvement Suggestions\n\n- [List any observations or suggestions for improvement]\n\n---\n\n## Important Notes\n\n- Always confirm any unclear points before beginning work\n- Report and obtain approval for any important decisions as they arise\n- Report unexpected problems immediately and propose solutions\n- **Do not make changes that are not explicitly instructed.** If changes seem necessary, first report them as proposals and implement only after approval\n- **UI/UX design changes (layout, colors, fonts, spacing, etc.) are prohibited** unless approved after presenting justification\n- **Do not arbitrarily change versions listed in the tech stack** (APIs, frameworks, libraries, etc.). If changes are necessary, clearly explain the reason and wait for approval before making any changes\n\n---\n\n# Tech Stack\n\n## Core Technologies\n\n- **AI Model: GPT-4**\n\n## Frontend\n\n- Flutter: ^3.22.0\n\n### State Management\n\n- Riverpod: ^2.6.1\n\n## BaaS\n\n- Firebase\n\n---\n\n## Project Structure\n\nPlease implement following this directory structure:\n\nlib/features/products/\n├── data/\n│   ├── models/\n│   │   ├── product_dto.dart\n│   │   └── product_category_dto.dart\n│   └── product_repository.dart\n├── presentation/\n│   ├── screens/\n│   │   ├── product_list_screen.dart\n│   │   └── product_details_screen.dart\n│   ├── controllers/\n│   │   └── product_list_controller.dart\n│   ├── widgets/\n│       └── product_card.dart\n├── domain/\n│   ├── models/\n│   │   ├── product.dart\n│   │   └── product_category.dart\n│   └── get_products_use_case.dart\n└── shared/\n    └── models/\n        └── address.dart\n\n## Placement Rules\n\n### Flutter Project Structure Placement Rules\n\nThis document outlines the placement rules for files and folders within the recommended Flutter project structure, focusing on scalability, maintainability, and adherence to Clean Architecture principles.\n\n#### Top-Level Structure\n\nlib/\n├── features/\n├── models/\n├── providers/\n├── routes/\n├── core/\n├── app.dart\n└── main.dart\n\n*   **lib/**: Contains all Dart code.\n*   **features/**: Feature-specific code.\n*   **models/**: Global models (use sparingly).\n*   **providers/**: Global providers (minimize use).\n*   **routes/**: App navigation.\n*   **core/**: Core app logic (networking, errors, DI).\n*   **app.dart**: Root widget.\n*   **main.dart**: Entry point.\n\n#### features/ Structure\n\nlib/features/\n└── <feature_name>/\n├── data/\n│   ├── models/\n│   └── <feature_name>_repository.dart\n├── presentation/\n│   ├── screens/\n│   ├── controllers/\n│   ├── widgets/\n├── domain/\n│   ├── models/\n│   └── <feature_name>.dart\n├── use_cases/\n└── shared/\n└── models/\n\n*   **<feature_name>/**: A feature (e.g., authentication, products).\n*   **data/**: Data access.\n    *   **models/**: Data Transfer Objects (DTOs).\n    *   **<feature_name>_repository.dart**: Data access logic.\n*   **presentation/**: UI.\n    *   **screens/**: UI screens (<feature_name>_<screen_name>_screen.dart).\n    *   **controllers/**: State management (<feature_name>_controller.dart).\n    *   **widgets/**: Feature-specific widgets (<widget_name>.dart).\n*   **domain/**: Business logic.\n    *   **models/**: Domain models.\n    *   **<feature_name>.dart**: Main entity.\n*   **use_cases/**: User interactions (<use_case_name>.dart).\n*   **shared/models/**: Models shared between *related* features.\n\n#### shared/ (Top-Level) Structure\n\nlib/shared/\n├── providers/\n├── widgets/\n├── models/\n└── services/\n\n*   **providers/**: Providers shared across *unrelated* features.\n*   **widgets/**: Widgets shared across *unrelated* features.\n*   **models/**: Models shared across *unrelated* features (use cautiously).\n*   **services/**: Utility classes.\n\n#### models/ (Top-Level) Structure\n\nlib/models/\n└── <model_name>.dart\n\n*   Global models (use sparingly).\n\n#### providers/ (Top-Level) Structure\n\nlib/providers/\n└── <provider_name>.dart\n\n*   Global providers (minimize use).\n\n#### core/ Structure\n\nlib/core/\n├── network/\n│   └── api_client.dart\n├── errors/\n│   └── exceptions.dart\n└── di/\n└── injection.dart\n\n*   **network/**: Networking code.\n*   **errors/**: Error handling.\n*   **di/**: Dependency injection.\n\n## Naming Conventions\n\n*   **Files:** snake_case (e.g., product_list_screen.dart).\n*   **Classes:** PascalCase (e.g., ProductListScreen).\n*   **Variables/Functions:** camelCase (e.g., productList).\n\n## Key Principles\n\n*   **Feature Isolation:** Self-contained feature code.\n*   **Separation of Concerns:** Separate data, logic, and UI.\n*   **Single Responsibility:** One purpose per class/file.\n*   **DRY:** Avoid code duplication.\n*   **Prefer Feature-Specific:** Prioritize feature-level placement.\n\nPlease adhere to the above content when executing tasks.\n","tokens":1736,"sizeBytes":7959}],"systemPromptSnippet":"<yakaai_skills repo=\"riverqueue/river\">\n<!-- File: AGENTS.md (Tokens: ~1925 | Category: root-instruction) -->\n# River Coding Guidelines\n\n## Running Tests and Lint\n\n- **Tests**: use `make test` as the default. Only use `go test ...` when you must pass specific flags (e.g. `-run`, `-count`, `-race`, build tags, etc.) or need to debug a specific test in isolation.\n- **Lint**: use `make lint` as the default. Only call `golangci-lint ...` directly when you must pass specific flags.\n- Always run test and lint prior to considering a task complete, unless told otherwise (or if you did not touch any Go code/tests).\n- If your execution environment has a sandbox/permission model, run `make test` and `make lint` unsandboxed (full permissions) so results match local dev and CI.\n\n## Other Build/Test Commands\n\n- **Run all tests with race detector**: `make test/race`\n- **Run single test**: `cd $MODULE && go test ./path/to/package -run TestName`\n- **Run benchmark**: `make bench`\n- **Generate sqlc**: `make generate`. Use this any time a `.sql` file has been modified and we need to then regenerate `.sql.go` files from it.\n- **Run tidy when deps change**: `make tidy`\n\n## Code Style Guidelines\n\n- **Imports**: use gci sections - Standard, Default, github.com/riverqueue.\n- **Formatting**: use gofmt, gofumpt, goimports.\n- **JSON tags**: use snake_case for JSON field tags.\n- **Dependencies**: minimize external dependencies beyond standard library and pgx.\n- **SQL access (non-test code)**: avoid ad-hoc SQL strings in library/runtime code. Add or extend a sqlc query, regenerate with `make generate`, and expose it through the driver interface. Keep direct SQL for tests and benchmark/admin utilities only (for example, `pg_stat_statements` and `VACUUM`).\n- **Driver interface stability**: treat `riverdriver` as an internal adapter seam, not as an official external API. Its package comments explicitly say it should not be implemented or invoked by user code, and changes there are not considered semver-breaking. Do not preserve driver-interface methods or semantics for outside consumers; add, remove, or reshape them as needed to preserve or improve user-facing functionality.\n- **Cross-driver driver tests**: treat `riverdriver/riverdrivertest` as the shared conformance suite for driver behavior. When changing `riverdriver` or a concrete driver, update or extend `riverdrivertest` so the intended semantics are exercised across drivers, not only in a single driver-specific test.\n- **Error handling**: prefer context-rich errors; review linting rules before disabling them.\n- **Testing**: use require variants instead of assert.\n- **Helpers**: use `Func` suffix for function variables, not `Fn`.\n- **Documentation**: include comments for exported functions and types.\n- **Terminology**: prefer \"Postgres\" over \"PostgreSQL\".\n- **Naming**: use idiomatic Go names; see `.golangci.yaml` for allowed short variable names.\n\n## Package Naming and Organization\n\n- Package names are lowercase, short, and representative; avoid `common`, `util`, or overly broad names.\n- Use singular package names; avoid plurals like `httputils`.\n- Keep import paths clean; avoid `src/`, `pkg/`, or other repo-structure leakage.\n- Organize by responsibility instead of `models`/`types` buckets; keep types close to usage.\n- Do not export identifiers from `main` packages that only build binaries.\n- Add package docs, and use `doc.go` when documentation is long.\n\n## Code Organization\n\nAlphabetization is important when adding new code (do not reorganize existing code unless asked).\n\n- Types should be sorted alphabetically by name.\n- Struct field definitions on a type should be sorted alphabetically by name, unless there is a good reason to deviate (examples: ID fields first, grouping mutexed fields after a mutex, etc.).\n- When declaring an instance of a struct, fields should be sorted alphabetically by name unless a similar deviation is justified.\n- When defining methods on a type, they should be sorted alphabetically by name.\n- Constructors should come immediately after the type definition.\n- Keep all methods for a type grouped together, immediately after the type definition and any constructor(s), organized alphabetically by name. Do not intersperse methods with other types or functions, except in special cases where a small utility type is needed to support a method and not used elsewhere.\n- In unit tests, the outer test blocks should be sorted alphabetically by name. Inner test blocks should also be sorted alphabetically by name within the outer block.\n\n## Go Testing Conventions: Parallel Test Bundle + Setup Helpers\n\nThis repo uses a parallel test bundle pattern (inspired by Brandur's write-up: https://brandur.org/fragments/parallel-test-bundle) to keep parallel subtests isolated and setup/fixtures DRY.\n\n- **Always opt into parallel**:\n  - **Top-level tests**: the first statement in every `TestXxx` should be `t.Parallel()`.\n  - **Subtests**: the first statement in every `t.Run(..., func(t *testing.T) { ... })` should be `t.Parallel()`, unless the subtest is intentionally non-parallel and includes a short comment explaining why.\n- **Statement ordering and spacing**:\n  - **Top-level tests**: use `t.Parallel()`, then a blank line, then test preamble (`ctx`, `setup`, helpers), then a blank line before subtests/assertions.\n  - **Subtests**: use `t.Parallel()`, then a blank line, then subtest preamble.\n  - If a subtest calls `setup(...)`, prefer one blank line after the setup assignment before assertions/actions.\n  - For tiny/obvious subtests (one short statement after `t.Parallel()` or `setup(...)`), omitting one of these blank lines is acceptable.\n- **Context and setup ordering**:\n  - If `setup` needs `ctx` (`setup(ctx, t)`), assign/derive `ctx` before calling `setup`.\n  - If `setup` does not need `ctx` (`setup(t)`), call `setup` first and derive specialized contexts (`WithCancel`, `WithTimeout`) close to where they are used.\n  - Avoid creating/deriving `ctx` far from usage unless shared setup requires it.\n- **Prefer local bundles**:\n  - Define a `type testBundle struct { ... }` inside the `TestXxx` function containing the system under test and any fixtures frequently used across subtests.\n  - Each parallel subtest should call `setup(t)` to get a fresh bundle. Avoid sharing mutable state across parallel subtests.\n- **`setup` helper rules**:\n  - Define `setup` as a local closure in the test:\n    - `setup := func(t *testing.T) *testBundle { ... }`\n    - Always call `t.Helper()` at the top of `setup`.\n  - **Only accept a context parameter if it is needed**:\n    - **Default**: `setup(t)` should not take `ctx`.\n    - **If setup must derive/seed a context**: prefer returning it: `setup := func(t *testing.T) (*testBundle, context.Context)`.\n    - **If setup must be passed an existing context**: accept `ctx` as the first parameter: `setup := func(ctx context.Context, t *testing.T) *testBundle`.\n  - Keep `setup` deterministic and self-contained; it should only use the `*testing.T` (and `ctx` if explicitly required) passed in.\n- **Test signal instrumentation**:\n  - Prefer `rivershared/testsignal.TestSignal` in a `...TestSignals` struct with an `Init(tb)` helper over ad hoc `chan struct{}` fields in spies/fakes.\n  - Keep test-signal structs zero-value by default and call `Init(t)` only in tests that need to observe those signals.\n  - Wait for async events with `WaitOrTimeout()`. For negative assertions, use `RequireEmpty()` or `WaitC()` with a timeout select.\n  - Avoid custom channel signaling helpers and hand-managed channel capacities unless there is a specific, documented reason.\n\nTemplate:\n\n```go\nfunc TestThing(t *testing.T) {\n\tt.Parallel()\n\n\ttype testBundle struct {\n\t\t// Put SUT + common fixtures here.\n\t}\n\n\tsetup := func(t *testing.T) *testBundle {\n\t\tt.Helper()\n\n\t\treturn &testBundle{}\n\t}\n\n\tt.Run(\"CaseName\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tbundle := setup(t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n\n\tt.Run(\"CaseNameWithCtxRequiredBySetup\", func(t *testing.T) {\n\t\tt.Parallel()\n\n\t\tsetupWithCtx := func(ctx context.Context, t *testing.T) *testBundle {\n\t\t\tt.Helper()\n\n\t\t\t_ = ctx\n\t\t\treturn &testBundle{}\n\t\t}\n\n\t\tctx := context.Background()\n\t\tbundle := setupWithCtx(ctx, t)\n\n\t\t// ... use `bundle` in assertions/actions ...\n\t})\n}\n```\n\n<!-- File: .cursorrules (flutter-riverpod-cursorrules-prompt-file.mdc) (Tokens: ~1736 | Category: cursor-rule) -->\n---\ndescription: \"Cursor rules for Flutter Riverpod.\"\nglobs: **/*\nalwaysApply: false\n---\n# AI Assistant Technical Instructions\n\nYou are an AI assistant with advanced problem-solving capabilities. Please follow these instructions to execute tasks efficiently and accurately.\n\nFirst, confirm the instructions received from the user:\n\n<instructions>\n{{instructions}}\n</instructions>\n\nPlease proceed with the following process based on these instructions:\n\n---\n\n## 1. Instruction Analysis and Planning\n\n<Task Analysis>\n- Summarize the main tasks concisely\n- Review the specified tech stack and consider implementation methods within those constraints  \n  **Note: Do not change versions listed in the tech stack without approval**\n- Identify key requirements and constraints\n- List potential challenges\n- Enumerate specific steps for task execution in detail\n- Determine the optimal execution order for these steps\n\n### Preventing Duplicate Implementation\n\nBefore implementation, verify:\n- Existence of similar functionality\n- Functions or components with identical or similar names\n- Duplicate API endpoints\n- Identification of processes that can be shared\n\nTake sufficient time for this section as it guides the entire subsequent process. Conduct thorough and comprehensive analysis.\n</Task Analysis>\n\n---\n\n## 2. Task Execution\n\n- Execute identified steps one by one\n- Report progress concisely after completing each step\n- Pay attention to the following during implementation:\n  - Adherence to proper directory structure\n  - Consistency in naming conventions\n  - Appropriate placement of shared processes\n\n---\n\n## 3. Quality Control and Problem Resolution\n\n- Quickly verify the execution results of each task\n- If errors or inconsistencies occur, address them through the following process:\n  a. Problem isolation and cause identification (log analysis, debug information verification)\n  b. Creation and implementation of countermeasures\n  c. Post-fix operation verification\n  d. Debug log confirmation and analysis\n\n- Record verification results in the following format:\n  a. Verification items and expected results\n  b. Actual results and discrepancies\n  c. Required countermeasures (if applicable)\n\n---\n\n## 4. Final Confirmation\n\n- Evaluate the entire deliverable once all tasks are completed\n- Verify consistency with original instructions and make adjustments as needed\n- Perform final confirmation that there are no duplicates in implemented functions\n\n---\n\n## 5. Results Report\n\nPlease report final results in the following format:\n\nmarkdown\n# Execution Results Report\n\n## Overview\n\n[Brief description of overall summary]\n\n## Execution Steps\n\n1. [Step 1 description and results]\n2. [Step 2 description and results]\n...\n\n## Final Deliverables\n\n[Details of deliverables, links if applicable]\n\n## Issue Resolution (if applicable)\n\n- Problems encountered and responses\n- Future considerations\n\n## Notes & Improvement Suggestions\n\n- [List any observations or suggestions for improvement]\n\n---\n\n## Important Notes\n\n- Always confirm any unclear points before beginning work\n- Report and obtain approval for any important decisions as they arise\n- Report unexpected problems immediately and propose solutions\n- **Do not make changes that are not explicitly instructed.** If changes seem necessary, first report them as proposals and implement only after approval\n- **UI/UX design changes (layout, colors, fonts, spacing, etc.) are prohibited** unless approved after presenting justification\n- **Do not arbitrarily change versions listed in the tech stack** (APIs, frameworks, libraries, etc.). If changes are necessary, clearly explain the reason and wait for approval before making any changes\n\n---\n\n# Tech Stack\n\n## Core Technologies\n\n- **AI Model: GPT-4**\n\n## Frontend\n\n- Flutter: ^3.22.0\n\n### State Management\n\n- Riverpod: ^2.6.1\n\n## BaaS\n\n- Firebase\n\n---\n\n## Project Structure\n\nPlease implement following this directory structure:\n\nlib/features/products/\n├── data/\n│   ├── models/\n│   │   ├── product_dto.dart\n│   │   └── product_category_dto.dart\n│   └── product_repository.dart\n├── presentation/\n│   ├── screens/\n│   │   ├── product_list_screen.dart\n│   │   └── product_details_screen.dart\n│   ├── controllers/\n│   │   └── product_list_controller.dart\n│   ├── widgets/\n│       └── product_card.dart\n├── domain/\n│   ├── models/\n│   │   ├── product.dart\n│   │   └── product_category.dart\n│   └── get_products_use_case.dart\n└── shared/\n    └── models/\n        └── address.dart\n\n## Placement Rules\n\n### Flutter Project Structure Placement Rules\n\nThis document outlines the placement rules for files and folders within the recommended Flutter project structure, focusing on scalability, maintainability, and adherence to Clean Architecture principles.\n\n#### Top-Level Structure\n\nlib/\n├── features/\n├── models/\n├── providers/\n├── routes/\n├── core/\n├── app.dart\n└── main.dart\n\n*   **lib/**: Contains all Dart code.\n*   **features/**: Feature-specific code.\n*   **models/**: Global models (use sparingly).\n*   **providers/**: Global providers (minimize use).\n*   **routes/**: App navigation.\n*   **core/**: Core app logic (networking, errors, DI).\n*   **app.dart**: Root widget.\n*   **main.dart**: Entry point.\n\n#### features/ Structure\n\nlib/features/\n└── <feature_name>/\n├── data/\n│   ├── models/\n│   └── <feature_name>_repository.dart\n├── presentation/\n│   ├── screens/\n│   ├── controllers/\n│   ├── widgets/\n├── domain/\n│   ├── models/\n│   └── <feature_name>.dart\n├── use_cases/\n└── shared/\n└── models/\n\n*   **<feature_name>/**: A feature (e.g., authentication, products).\n*   **data/**: Data access.\n    *   **models/**: Data Transfer Objects (DTOs).\n    *   **<feature_name>_repository.dart**: Data access logic.\n*   **presentation/**: UI.\n    *   **screens/**: UI screens (<feature_name>_<screen_name>_screen.dart).\n    *   **controllers/**: State management (<feature_name>_controller.dart).\n    *   **widgets/**: Feature-specific widgets (<widget_name>.dart).\n*   **domain/**: Business logic.\n    *   **models/**: Domain models.\n    *   **<feature_name>.dart**: Main entity.\n*   **use_cases/**: User interactions (<use_case_name>.dart).\n*   **shared/models/**: Models shared between *related* features.\n\n#### shared/ (Top-Level) Structure\n\nlib/shared/\n├── providers/\n├── widgets/\n├── models/\n└── services/\n\n*   **providers/**: Providers shared across *unrelated* features.\n*   **widgets/**: Widgets shared across *unrelated* features.\n*   **models/**: Models shared across *unrelated* features (use cautiously).\n*   **services/**: Utility classes.\n\n#### models/ (Top-Level) Structure\n\nlib/models/\n└── <model_name>.dart\n\n*   Global models (use sparingly).\n\n#### providers/ (Top-Level) Structure\n\nlib/providers/\n└── <provider_name>.dart\n\n*   Global providers (minimize use).\n\n#### core/ Structure\n\nlib/core/\n├── network/\n│   └── api_client.dart\n├── errors/\n│   └── exceptions.dart\n└── di/\n└── injection.dart\n\n*   **network/**: Networking code.\n*   **errors/**: Error handling.\n*   **di/**: Dependency injection.\n\n## Naming Conventions\n\n*   **Files:** snake_case (e.g., product_list_screen.dart).\n*   **Classes:** PascalCase (e.g., ProductListScreen).\n*   **Variables/Functions:** camelCase (e.g., productList).\n\n## Key Principles\n\n*   **Feature Isolation:** Self-contained feature code.\n*   **Separation of Concerns:** Separate data, logic, and UI.\n*   **Single Responsibility:** One purpose per class/file.\n*   **DRY:** Avoid code duplication.\n*   **Prefer Feature-Specific:** Prioritize feature-level placement.\n\nPlease adhere to the above content when executing tasks.\n</yakaai_skills>"}