Imported from caunt/IpaStore (AGENTS.md). Install upstream with npx skills add caunt/IpaStore. Copyright stays with the author.

IpaStore — Agent & Contributor Guidelines

These rules are strict. All contributions — whether from humans or AI agents — must follow them without exception. Reviewers will reject any PR that violates these guidelines.

1. Modern C# Conventions

Language & Runtime

• Target net10.0 exclusively. Do not add any downgrade target-framework entries.
• Enable <Nullable>enable</Nullable> and <ImplicitUsings>enable</ImplicitUsings> in every .csproj.
• Never suppress nullable warnings with ! (null-forgiving operator) unless the surrounding code makes nullability provably impossible and a brief comment explains why.

Code Style

• Use file-scoped namespaces (namespace Foo.Bar;) — never block-scoped.
• Use primary constructors for classes and records whenever all constructor work is assignment-only.
• Prefer records (record, record struct) for immutable data shapes.
• Prefer init over set for properties that are only written during construction.
• Use pattern matching (is, switch expressions, list patterns) over type-casting chains.
• Use collection expressions ([a, b, c]) instead of new List<T> { } or new[] { }.
• Use var when the type is obvious from the right-hand side; spell out the type when it aids clarity.
• Prefer async/await over .Result/.Wait(). Never block on async code.
• Use ValueTask when a method is expected to complete synchronously most of the time.
• Prefer LINQ for query logic; avoid it in tight hot paths.
• Throw specific exceptions (ArgumentNullException.ThrowIfNull, ArgumentOutOfRangeException.ThrowIfNegativeOrZero, etc.) rather than generic ones.
• Use ArgumentNullException.ThrowIfNull and similar static helpers instead of manual null checks + throw.
• Keep methods short and focused — a single screen of code is a guideline, not a hard limit, but prefer splitting when a method has multiple distinct responsibilities.
• No magic numbers or magic strings — use named constants or enums.
• XML doc comments (/// <summary>) are required on all public and protected members.

Formatting

• 4 spaces — no tabs.
• Opening brace on the same line for methods and types (Allman is not used here).
• One blank line between members; two blank lines between top-level type declarations.
• No trailing whitespace. Files must end with a single newline.

Naming

Project Structure

• All production source lives under src/.
• All test projects live under tests/ (mirroring the src/ hierarchy).
• Project names follow the pattern IpaStore.<AreaName> (e.g. IpaStore.Core, IpaStore.Api).

2. Git Commit Conventions

Every commit message must follow Conventional Commits (https://www.conventionalcommits.org) with a gitmoji prefix.

Format

<type>(<scope>): <emoji> <short description>

[optional body]

[optional footer(s)]

• emoji — one gitmoji (see table below), placed after the type(scope): prefix.
• type — lowercase conventional-commit type.
• scope — optional, lowercase, names the project or area changed (e.g. playground, core, ci).
• short description — imperative mood, lowercase, no trailing period, ≤ 72 chars total (including emoji and type).
• body — wrapped at 72 chars; explains why, not what.
• footer — Fixes #<issue>, Closes #<issue>, BREAKING CHANGE: <description>, co-authors, etc.

Examples

feat(core): ✨ add package version resolver

Resolves version conflicts by preferring the highest compatible semver
range rather than the first declaration.

Closes #42

fix(api): 🐛 return 404 when package is not found

Previously the endpoint returned 500 because the repository threw
InvalidOperationException instead of returning null.

Fixes #17

refactor(playground): ♻️ replace List<T> initializers with collection expressions

test(core): ✅ add unit tests for version resolver edge cases

3. Git Emoji Reference

Use exactly one emoji per commit. Choose the one that best describes the primary intent of the change.

If none of the above fits perfectly, choose the closest match — do not invent new emoji.

4. Branch Naming

<type>/<short-kebab-description>

Examples: feat/version-resolver, fix/404-on-missing-package, docs/contributing-guide

5. Pull Request Rules

• Title must follow the same <type>(<scope>): <emoji> <description> format as a commit.
• Every PR must reference the issue it resolves (Closes #<n>) unless it is a chore with no associated issue.
• Squash-merge is preferred; keep the squash commit message in conventional-commit format.
• All CI checks must be green before merging.
• At least one approving review is required.