agents-md-kit 0.0.0-stage → 0.1.1

package/core/files/.claude/skills/backend-security/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: backend-security
+description: Security rules for backend and full-stack web applications, based on OWASP guidance. Use when implementing authentication, authorization, sessions/tokens, input handling, file uploads, secrets, headers, CORS, dependencies, or when reviewing code for vulnerabilities.
+---
+
+# Backend and Web Security Rules
+
+Security is a requirement of every feature, not a later phase. Apply defense in depth and least privilege. Reference: OWASP Top 10 and the OWASP ASVS / Cheat Sheet Series.
+
+## 1. Authentication
+
+- Don't build your own crypto or auth protocols. Use a vetted library, framework feature or identity provider (OIDC/OAuth 2.1, Auth0, Cognito, Keycloak, etc.).
+- Hash passwords with **Argon2id** (or scrypt/bcrypt as fallback) using a unique salt and tuned cost. Never MD5/SHA-1/plain SHA-256 for passwords.
+- Enforce reasonable password policy: minimum length (12+ recommended), allow long passphrases and paste, check against breached-password lists. Don't force arbitrary complexity or periodic rotation.
+- Offer MFA (TOTP, WebAuthn/passkeys). Require it for admin and sensitive actions.
+- Rate-limit and lock out/slow down repeated failed logins. Return identical messages for unknown user vs wrong password.
+- Password reset: single-use, short-lived, high-entropy tokens stored hashed. Don't reveal whether an email exists. Invalidate sessions after a password change.
+
+## 2. Sessions and Tokens
+
+- Session cookies: `HttpOnly; Secure; SameSite=Lax` (or `Strict`), with a sensible `Path`/`Domain`, and the `__Host-` prefix where possible. Regenerate the session ID on login and privilege change. Expire on idle and absolute timeouts, and invalidate on logout server-side.
+- JWTs: use short-lived access tokens, validate signature, `iss`, `aud`, `exp`, and the algorithm allowlist (never accept `alg: none`). Use refresh-token rotation with revocation/reuse detection. Don't put sensitive data in the payload (it's only encoded, not encrypted).
+- Don't store tokens in `localStorage` for browser apps if avoidable (XSS-exposed). Prefer HttpOnly cookies.
+- CSRF: with cookie-based auth, use `SameSite` plus anti-CSRF tokens (or double-submit/Origin checks) on state-changing requests.
+
+## 3. Authorization (Most Common Failure: Broken Access Control)
+
+- Deny by default. Enforce authorization **on the server, on every request**, for every resource. Hiding UI elements is not security.
+- Check ownership/permissions of the specific object (prevent IDOR): `WHERE id = ? AND owner_id = currentUser`.
+- Centralize policy (RBAC/ABAC/policy engine) instead of scattered `if` checks. Test permission rules explicitly.
+- Apply least privilege to users, service accounts, API keys and DB credentials.
+- Protect against mass assignment: bind only allowlisted fields. Never let clients set `role`, `isAdmin`, `ownerId`, etc.
+- Multi-tenant apps: scope every query by tenant (consider row-level security).
+
+## 4. Injection and Input Handling
+
+- **SQL:** always use parameterized queries/prepared statements or an ORM's safe APIs. Never concatenate user input into SQL. Whitelist dynamic identifiers (column names, sort fields).
+- **NoSQL/ORM operators, LDAP, OS commands, templates, XPath:** treat all as injection sinks. Avoid shelling out. If necessary, use argument arrays, never string commands.
+- **XSS:** encode/escape output by context (HTML, attribute, JS, URL). Frameworks like React escape by default, so avoid `dangerouslySetInnerHTML`, and sanitize with a vetted library (DOMPurify) if HTML must be rendered.
+- **SSRF:** when fetching user-supplied URLs, allowlist hosts/schemes, block private/link-local/metadata IP ranges (e.g. `169.254.169.254`), re-validate after DNS resolution and redirects.
+- **Path traversal:** never build file paths from user input directly. Normalize and confine to a base directory, or use generated IDs.
+- **Deserialization:** don't deserialize untrusted data with native object serializers (pickle, Java serialization). Use plain JSON with schema validation.
+- **Open redirects:** allowlist redirect targets.
+- **XXE:** disable external entity processing in XML parsers.
+
+## 5. File Uploads
+
+- Enforce size limits, allowed extensions **and** verify content type by magic bytes. Don't trust the client's `Content-Type` or filename.
+- Store outside the web root or in object storage. Rename to random IDs. Serve with `Content-Disposition` and a safe type, ideally from a separate domain.
+- Scan for malware when appropriate. Re-encode images to strip payloads/metadata. Never execute uploaded files.
+
+## 6. Secrets and Data Protection
+
+- No secrets in source control, logs, error messages, URLs or client bundles. Use a secrets manager. Rotate secrets. Scan commits for leaks (gitleaks, GitHub secret scanning). Anything shipped to the browser is public.
+- TLS 1.2+ everywhere (internal traffic too). Enable HSTS.
+- Encrypt sensitive data at rest (disk/DB encryption, field-level for highly sensitive data), with managed keys (KMS).
+- Collect and retain the minimum personal data. Support deletion/export (GDPR/LGPD obligations where applicable). Mask or tokenize payment data. Prefer a PCI-compliant provider so card data never touches your servers.
+- Don't log personal data or secrets. Redact.
+
+## 7. HTTP Security Headers
+
+```
+Strict-Transport-Security: max-age=63072000; includeSubDomains; preload
+Content-Security-Policy: default-src 'self'; script-src 'self'; object-src 'none'; base-uri 'self'; frame-ancestors 'none'
+X-Content-Type-Options: nosniff
+Referrer-Policy: strict-origin-when-cross-origin
+Permissions-Policy: camera=(), microphone=(), geolocation=()
+Cross-Origin-Opener-Policy: same-origin
+```
+
+- Roll out CSP in report-only mode first, and prefer nonces/hashes over `'unsafe-inline'`.
+- Use `frame-ancestors` (or `X-Frame-Options`) to prevent clickjacking.
+- Remove version-revealing headers (`Server`, `X-Powered-By`).
+- Cache-control `no-store` on sensitive responses.
+
+## 8. CORS
+
+- Allowlist specific origins. Never reflect arbitrary `Origin`, and never use `Access-Control-Allow-Origin: *` with credentials.
+- Restrict allowed methods and headers to what is needed. CORS is a browser rule, not an authorization mechanism.
+
+## 9. Rate Limiting and Abuse Prevention
+
+- Apply rate limits per IP/user/API key, with stricter limits on auth, password reset, OTP, search and expensive endpoints. Return `429` + `Retry-After`.
+- Set request body size limits, timeouts and pagination caps. Guard against ReDoS (avoid catastrophic regexes) and GraphQL query depth/complexity abuse.
+- Add CAPTCHA/bot protection to signup and contact forms where abuse is likely.
+
+## 10. Dependencies and Supply Chain
+
+- Keep lockfiles committed. Automate updates and vulnerability scans (Dependabot, Renovate, `npm audit`, `pip-audit`, Trivy).
+- Review new dependencies (maintenance, popularity, install scripts). Prefer fewer dependencies.
+- Pin container base images, build from trusted sources, sign artifacts where possible. Run containers as non-root with minimal capabilities.
+- Use Subresource Integrity (SRI) for third-party scripts and CDNs.
+
+## 11. Logging, Monitoring and Incident Response
+
+- Log security events (logins, failures, permission denials, password/role changes, admin actions) with who/what/when/where. Protect log integrity and access.
+- Alert on anomalies (spikes in 401/403/429, unusual geographies, mass downloads).
+- Have an incident response plan: contacts, revocation of keys/sessions, communication, and post-mortems.
+
+## 12. Secure Development Process
+
+- Threat-model new features (STRIDE: spoofing, tampering, repudiation, info disclosure, DoS, elevation).
+- Add SAST, dependency and secret scanning to CI, and DAST/pen-testing for production systems.
+- Code review includes a security pass. Use the checklist below.
+- Fail securely: on error, deny access rather than allow.
+
+## Review Checklist
+
+- [ ] Auth via vetted library/provider; passwords hashed with Argon2id/bcrypt; MFA available
+- [ ] Cookies `HttpOnly; Secure; SameSite`; JWT claims validated; CSRF handled
+- [ ] Server-side authorization on every resource; IDOR and mass assignment prevented
+- [ ] Parameterized queries; output encoding; SSRF/path-traversal/open-redirect guards
+- [ ] Upload validation and safe storage
+- [ ] No secrets in code/logs/client; TLS + HSTS; sensitive data encrypted
+- [ ] Security headers and CSP set; strict CORS allowlist
+- [ ] Rate limiting, size limits, timeouts
+- [ ] Dependencies scanned and pinned; security events logged and monitored

package/core/files/.claude/skills/changelog-and-versioning/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: changelog-and-versioning
+description: Rules for maintaining CHANGELOG.md (Keep a Changelog format) and Semantic Versioning. Use when making any user-facing change, fixing a bug, deprecating or removing a feature, preparing a release, or deciding a version number.
+---
+
+# Changelog and Versioning
+
+The changelog tells **users and operators** what changed between versions. It is not a copy of the git log. Git records every commit, the changelog records what matters to someone upgrading.
+
+## Modes: automated and manual
+
+Check which mode applies before touching `CHANGELOG.md`: **automated mode applies only if `release-please-config.json` exists at the repository root.** Otherwise use manual mode.
+
+**Automated mode (release-please).** `release-please-config.json` and the release-please workflow generate `CHANGELOG.md` and the version bump from Conventional Commits.
+- The squash-merged PR title (a Conventional Commit) **is** the changelog entry. Write it for the reader: the user-visible effect, not the implementation.
+- Do **not** hand-edit `CHANGELOG.md` or version fields. release-please keeps a "release PR" open. Merging it updates the changelog, bumps the version and tags `vX.Y.Z`. Fix wording by editing the release PR before merging.
+- Sections follow Keep a Changelog names: `feat` becomes Added, `fix` becomes Fixed, `perf` and `revert` become Changed. `docs`, `refactor`, `test`, `build`, `ci`, `chore` and `style` are hidden. Breaking changes (`!` or a `BREAKING CHANGE:` footer) get their own call-out and a major bump. For security fixes use `fix(security): ...` and say so plainly. For deprecations and removals use clear wording, and `!` when breaking.
+
+**Manual mode.** If there is no `release-please-config.json` at the repository root, follow sections 1-5 below and keep an `[Unreleased]` section. Never mix the two modes. Section 6 (SemVer) applies to both.
+
+## 1. Format (Keep a Changelog 1.1.0)
+
+`CHANGELOG.md` at the repository root, newest release first, with an `Unreleased` section at the top:
+
+```markdown
+# Changelog
+
+All notable changes to this project are documented in this file.
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- Passkey login for web accounts. (#482)
+
+## [1.4.0] - 2026-11-11
+
+### Added
+- ...
+
+### Changed
+- ...
+
+### Deprecated
+- ...
+
+### Removed
+- ...
+
+### Fixed
+- ...
+
+### Security
+- ...
+
+[Unreleased]: https://github.com/org/repo/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/org/repo/compare/v1.3.0...v1.4.0
+```
+
+**Sections (use only those that apply, in this order)**
+
+| Section | Content |
+|---|---|
+| Added | New features |
+| Changed | Changes to existing behavior |
+| Deprecated | Features that will be removed soon |
+| Removed | Features removed in this release |
+| Fixed | Bug fixes |
+| Security | Vulnerability fixes (reference CVE/advisory when public) |
+
+## 2. What to Log (and What Not To)
+
+**Log** anything a user, API consumer, operator or integrator would notice or must act on:
+- New or changed features, UI behavior, API endpoints/fields, CLI flags, config options, environment variables
+- Bug fixes visible to users
+- Performance changes that are noticeable
+- Deprecations and removals, with migration guidance
+- Security fixes
+- Required actions for upgrading (migrations, config changes)
+- Dependency changes only when they affect users (new minimum runtime version, license change)
+
+**Don't log**
+- Internal refactors, formatting, test-only changes, CI tweaks, comment/docs typos
+- Individual commits, work-in-progress details, or developer chatter
+
+## 3. Writing Entries
+
+- Write for the **reader**, in plain language, describing the effect and not the implementation.
+  - Good: "Fixed duplicate charges when the payment button was clicked twice."
+  - Bad: "Refactored PaymentService.create to use idempotency middleware."
+- Start with a past-tense or neutral verb (Added, Fixed, Removed) or a clear noun phrase. Be consistent.
+- One line per change, with a reference (issue/PR number) where possible.
+- **Breaking changes** are called out clearly with migration steps, ideally prefixed `**BREAKING:**`.
+- Don't use vague entries ("Various fixes", "Improvements", "Bug fixes").
+- Use ISO dates (`YYYY-MM-DD`). Never use relative dates.
+
+## 4. When to Update (Workflow)
+
+- **With the change, in the same PR/commit.** Add the entry under `## [Unreleased]` in the appropriate section. A PR that changes user-facing behavior without a changelog entry is incomplete.
+- Pure internal changes (`refactor`, `test`, `ci`, `style`, `chore`, internal `docs`) usually need no entry.
+- Mapping from Conventional Commits:
+
+| Commit | Changelog |
+|---|---|
+| `feat` | Added (or Changed) |
+| `fix` | Fixed (or Security) |
+| `perf` | Changed |
+| `feat!` / `BREAKING CHANGE` | Changed/Removed + **BREAKING** note |
+| `revert` | Fixed/Changed, as appropriate |
+| `docs`, `refactor`, `test`, `ci`, `chore`, `style` | usually none |
+
+## 5. Release Process
+
+1. Decide the version number from the changes (section 6).
+2. In `CHANGELOG.md`: rename `[Unreleased]` content into `## [X.Y.Z] - YYYY-MM-DD`, then add a fresh empty `## [Unreleased]` above it. Update the comparison links at the bottom.
+3. Update the version in the manifest files (`package.json`, `pyproject.toml`, etc.).
+4. Commit: `chore(release): vX.Y.Z`.
+5. Create an annotated tag `vX.Y.Z` and push. CI builds and publishes from the tag.
+6. Publish release notes (GitHub Release) using the changelog section for that version.
+
+Automation is welcome (release-please, semantic-release, changesets). If used, keep a human edit pass so entries read well for users, and don't mix automated and manual formats.
+
+## 6. Semantic Versioning (MAJOR.MINOR.PATCH)
+
+| Bump | When | Example |
+|---|---|---|
+| **MAJOR** | Backward-incompatible changes to the public API/contract | 1.4.2 → 2.0.0 |
+| **MINOR** | Backward-compatible new functionality; deprecations | 1.4.2 → 1.5.0 |
+| **PATCH** | Backward-compatible bug fixes | 1.4.2 → 1.4.3 |
+
+- Define what the "public API" is for this project (HTTP API, library exports, CLI, config schema, DB schema if consumed externally).
+- `0.y.z` is initial development: anything may change. Move to `1.0.0` when the API is considered stable or in production use.
+- Pre-releases: `1.5.0-rc.1`, `1.5.0-beta.2`. Build metadata: `1.5.0+build.7`.
+- Never change or re-publish an already-released version. Fix forward with a new version.
+- Deprecate first (MINOR), then remove in the next MAJOR, with at least one release of notice and a migration path.
+- Web applications without external API consumers may use date-based or build-number versions, but still keep a changelog.
+
+## 7. Examples
+
+```markdown
+## [Unreleased]
+
+### Added
+- Export orders to CSV from the Orders page. (#511)
+
+### Fixed
+- Cart total no longer shows NaN when a coupon expires during checkout. (#517)
+
+### Security
+- Fixed an access control flaw that allowed viewing other customers' invoices by changing the URL ID. (GHSA-xxxx-xxxx-xxxx)
+
+## [2.0.0] - 2026-11-11
+
+### Changed
+- **BREAKING:** `GET /v1/orders` now returns cursor-based pagination (`nextCursor`) instead of `page`/`pageSize`. See the migration guide in docs/migrations/2.0.md.
+
+### Removed
+- **BREAKING:** Dropped Node 18 support; Node 20+ is required.
+```
+
+## Review Checklist
+
+- [ ] Manual mode: user-facing change has an entry under `[Unreleased]` in the correct section. Automated mode: the PR title reads as the release note
+- [ ] Entry describes the user-visible effect, is specific, and references the issue/PR
+- [ ] Breaking changes and deprecations flagged with migration steps
+- [ ] Version bump matches the change types (SemVer)
+- [ ] On release: date set, new empty `Unreleased` added, links updated, tag created
+- [ ] No internal-only noise, no secrets or sensitive vulnerability details before a fix is public

package/core/files/.claude/skills/database-best-practices/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: database-best-practices
+description: Rules for database design, queries, migrations and data access (primarily relational/SQL). Use when designing schemas, writing queries or ORM code, adding indexes, writing migrations, handling transactions, or diagnosing slow queries and N+1 problems.
+---
+
+# Database Best Practices
+
+Examples use SQL (PostgreSQL-flavored). Principles apply to MySQL and most relational databases, and many apply to NoSQL.
+
+## 1. Schema Design
+
+- Model the domain first. Normalize to at least 3NF by default, and denormalize deliberately only for measured read performance.
+- Every table has a primary key. Choose stable surrogate keys (`bigint` identity or UUIDv7/ULID for distributed/public IDs). Don't use mutable business data (emails) as primary keys.
+- Use the correct types:
+  - Money: `numeric(p,s)` or integer minor units, never `float`.
+  - Time: `timestamptz` stored in UTC. Convert at the edges.
+  - Booleans as `boolean`. Enums via `enum`/lookup table/`CHECK` constraint. JSON columns (`jsonb`) only for genuinely flexible data, not as a way to skip modeling.
+- Enforce integrity in the database, not only in app code:
+  - `NOT NULL` by default, `UNIQUE`, `CHECK`, and **foreign keys** with deliberate `ON DELETE` behavior.
+- Naming: consistent, lowercase `snake_case`, singular or plural table names (pick one), `<table>_id` for foreign keys, `created_at` / `updated_at` on tables.
+- Soft delete (`deleted_at`) only when needed (audit/recovery), and remember to filter it consistently (partial indexes and unique constraints must account for it).
+- Many-to-many via a join table with a composite unique key.
+
+## 2. Indexing
+
+- Index primary keys (automatic), foreign keys, and columns used in `WHERE`, `JOIN`, `ORDER BY` of frequent queries.
+- Composite indexes: put equality columns first, then range/sort columns. Order matters. An index on `(a, b)` serves queries on `a` and `a,b`, not `b` alone.
+- Use partial indexes and covering indexes (`INCLUDE`) for hot paths.
+- Don't over-index. Each index slows writes and uses storage. Remove unused indexes (check usage statistics).
+- Verify with `EXPLAIN (ANALYZE, BUFFERS)`. Look for sequential scans on large tables, row estimate mismatches and sorts spilling to disk.
+- Avoid patterns that defeat indexes: functions on indexed columns (`WHERE lower(email) = ...` without a functional index), leading wildcards (`LIKE '%abc'`), implicit type casts.
+- For text search use full-text search (`tsvector`/GIN, or a search engine) rather than `LIKE '%term%'`.
+
+## 3. Queries and Data Access
+
+- **Never** build SQL from strings with user input. Use parameters (see `backend-security`).
+- Select only the needed columns. Avoid `SELECT *` in application code.
+- Avoid **N+1 queries**: load related data with joins, `IN (...)` batching, or ORM eager loading (`include`/`joinedload`/`prefetch_related`). Watch query counts per request in development and tests.
+- Paginate everything that can grow. Prefer keyset (seek) pagination (`WHERE (created_at, id) < (?, ?) ORDER BY created_at DESC, id DESC LIMIT 50`) over large `OFFSET`.
+- Push filtering, aggregation and sorting into the database instead of in application memory.
+- Use bulk operations for batch writes (`INSERT ... VALUES (...),(...)`, `COPY`, bulk APIs), in chunks.
+- Use `EXISTS` rather than `COUNT(*) > 0` for existence checks.
+- Set statement timeouts and lock timeouts to protect the database from runaway queries.
+- Use read replicas for heavy reads only when replication lag is acceptable, and route deliberately.
+
+## 4. ORM Usage
+
+- ORMs are fine for CRUD. Drop to hand-written SQL for complex reporting or performance-critical queries.
+- Keep ORM entities inside the data-access layer (repositories). Return domain objects/DTOs to services (DIP).
+- Understand the SQL your ORM generates. Log slow queries and inspect them.
+- Don't rely on lazy loading in request handlers, which causes hidden N+1.
+
+## 5. Transactions and Concurrency
+
+- Wrap multi-step writes that must be atomic in one transaction. Keep transactions short and don't do network calls or user interaction inside them.
+- Know your isolation level (PostgreSQL default is Read Committed). Use `SERIALIZABLE` or explicit locks for tricky invariants.
+- Prevent lost updates: optimistic locking (`version` column: `UPDATE ... WHERE id = ? AND version = ?`) or `SELECT ... FOR UPDATE`.
+- Use unique constraints plus upserts (`INSERT ... ON CONFLICT`) to make operations idempotent and race-safe, instead of check-then-insert.
+- Acquire locks in a consistent order to avoid deadlocks. Retry on serialization failures/deadlocks.
+- Use `SELECT ... FOR UPDATE SKIP LOCKED` for job-queue style workloads.
+
+## 6. Migrations
+
+- All schema changes are versioned migration files in source control (Flyway, Liquibase, Prisma Migrate, Alembic, Knex, EF Migrations). Never alter production schema by hand.
+- Migrations are repeatable in CI against a fresh database and applied automatically in the pipeline.
+- Make them **backward compatible** using the expand → migrate → contract pattern so old and new app versions can run at the same time:
+  1. Expand: add new nullable column/table/index.
+  2. Deploy the app writing to both / reading the new one. Backfill data in batches.
+  3. Contract: remove old columns after all code stops using them.
+- Avoid long locks on big tables: add indexes `CONCURRENTLY` (PostgreSQL), add columns without volatile defaults where the engine requires a rewrite, backfill in batches, and add `NOT NULL`/FK constraints in a safe two-step way (`NOT VALID` then `VALIDATE`).
+- Never edit an already-applied migration. Add a new one. Have a rollback/forward-fix plan.
+- Keep schema migrations and large data migrations separate.
+
+## 7. Backups, Recovery and Operations
+
+- Automated backups with point-in-time recovery. **Test restores regularly**. A backup that has never been restored is not a backup.
+- Define RPO/RTO. Monitor replication, disk, connections, locks, slow queries, bloat/vacuum health.
+- Use connection pooling (PgBouncer or the app pool), sized deliberately (not one connection per request). Know the max connections limit.
+- Use least-privilege DB users: the app can't `DROP`, and migrations use a separate privileged role. Separate read-only users for analytics.
+- Keep dev/staging data anonymized. Never copy raw production personal data into lower environments.
+
+## 8. Choosing a Data Store
+
+- Default to a relational database (PostgreSQL is a strong general-purpose choice). Add other stores for specific needs, not by habit:
+  - Redis: caching, rate limits, ephemeral state, queues.
+  - Document stores: truly schema-flexible aggregates.
+  - Search engines (Elasticsearch/OpenSearch/Meilisearch): full-text relevance, faceting.
+  - Object storage (S3-compatible): files and large blobs. Store only the key/metadata in the DB.
+  - Analytical stores (warehouse/columnar): reporting and heavy aggregation, separated from the OLTP database.
+- Each additional datastore adds operational cost. Justify it (YAGNI).
+
+## 9. Data Privacy and Lifecycle
+
+- Classify personal and sensitive data. Encrypt where required. Limit who and what can read it.
+- Define retention and deletion procedures (including backups and derived data). Keep audit trails for sensitive changes.
+
+## Review Checklist
+
+- [ ] Primary keys, correct types, NOT NULL, FKs, unique/check constraints
+- [ ] Indexes match query patterns; verified with EXPLAIN; no unused/duplicate indexes
+- [ ] Parameterized queries; no `SELECT *`; no N+1; pagination everywhere
+- [ ] Transactions short and correct; race conditions handled by constraints/locks/versions
+- [ ] Migrations versioned, backward compatible, safe on large tables
+- [ ] Backups tested; connection pooling; least-privilege DB users; timeouts set

package/core/files/.claude/skills/git-commit-and-workflow/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: git-commit-and-workflow
+description: Git commit, branch and pull request best practices using Conventional Commits. Use whenever creating commits, naming branches, preparing pull requests, writing commit messages, or when asked to commit, push, merge or release code.
+---
+
+# Git Commit and Workflow Rules
+
+A good history lets people (and agents) understand *what changed and why* without reading every diff, and lets tools generate changelogs and versions automatically.
+
+## 1. Commit Message Format (Conventional Commits 1.0)
+
+```
+<type>(<optional scope>): <subject>
+
+<optional body: what and why, wrapped at ~72 chars>
+
+<optional footers: BREAKING CHANGE, Refs, Co-authored-by>
+```
+
+**Types**
+
+| Type | Use for | Version bump |
+|---|---|---|
+| `feat` | New user-facing capability | minor |
+| `fix` | Bug fix | patch |
+| `perf` | Performance improvement | patch |
+| `refactor` | Code change with no behavior change | none |
+| `docs` | Documentation only | none |
+| `test` | Adding/fixing tests | none |
+| `build` | Build system, dependencies | none |
+| `ci` | CI configuration | none |
+| `style` | Formatting only (no logic) | none |
+| `chore` | Maintenance not fitting above | none |
+| `revert` | Reverting a commit | depends |
+
+**Subject rules**
+- Imperative mood: "add", "fix", "remove" (not "added", "fixes").
+- Lowercase after the colon, no trailing period, 72 characters or fewer.
+- Describe the change's effect, not the activity ("fix crash on empty cart", not "fix bug" or "update stuff").
+- Scope is the module/area: `feat(auth): add passkey login`.
+
+**Body**
+- Explain **why** the change was needed and any trade-offs or alternatives. The diff already shows *what*.
+- Wrap at about 72 characters. Separate from the subject with a blank line.
+
+**Footers**
+- Breaking change: `BREAKING CHANGE: <what broke and how to migrate>` or `!` after type/scope (`feat(api)!: remove v1 endpoints`). Triggers a major version bump.
+- Issue links: `Refs: #123`, `Closes: #123`.
+
+**Examples**
+
+```
+feat(checkout): add idempotency key to payment creation
+
+Duplicate submissions on flaky networks created double charges.
+The key is stored for 24h and replays the original response.
+
+Closes: #482
+```
+
+```
+fix(auth): reject JWTs with alg=none
+
+BREAKING CHANGE: tokens signed without a signature are no longer accepted.
+```
+
+## 2. Commit Hygiene
+
+- **Atomic commits:** one logical change per commit. A commit should build and pass tests on its own.
+- Keep tests and docs for a change in the same commit as the change.
+- Separate refactors/formatting from behavior changes (never hide a logic change inside a reformat commit).
+- Don't commit: secrets, `.env` files, credentials, build output, `node_modules`, large binaries, editor/OS files. Maintain `.gitignore`.
+- No `WIP`, `fix stuff`, `asdf` commits on shared branches. Squash or rewrite local-only commits before pushing.
+- Review `git status` and `git diff --staged` before every commit. Stage intentionally (`git add -p` or specific paths), not blindly `git add -A`.
+- Run lint, type check and relevant tests before committing. Use pre-commit hooks (husky, lefthook, pre-commit) and `commitlint` to enforce format.
+
+## 3. Branching
+
+- Default to **trunk-based development**: short-lived branches (ideally under 2 days), merged often into `main`. Use feature flags for unfinished work.
+- Branch names: `<type>/<short-kebab-description>` with an optional issue ID: `feat/passkey-login`, `fix/482-double-charge`, `chore/bump-eslint`.
+- `main` is always deployable and protected: required reviews, passing CI, no direct pushes, no force pushes.
+- Keep branches updated by rebasing on `main` (for private branches) or merging, per team convention. Be consistent.
+
+## 4. Pull Requests
+
+- Small and focused: ideally under about 400 changed lines, one concern each. Split large work into stacked or sequential PRs.
+- Title follows Conventional Commits (squash-merge uses it as the commit message).
+- Description includes: **what and why**, how it was tested, screenshots for UI, migration/rollback notes, linked issue, breaking changes.
+- Self-review the diff before requesting review. Remove debug code and commented-out code.
+- CI must pass. Address review comments with follow-up commits, then squash on merge (or keep a clean history if rebase-merging).
+- Prefer **squash merge** for feature branches (one clean commit per PR) unless the individual commits are well crafted and meaningful.
+
+PR template:
+
+```markdown
+## Summary
+<!-- What changed and why -->
+
+## Changes
+-
+
+## Testing
+<!-- How you verified it: tests added, manual steps -->
+
+## Risks / Rollback
+<!-- Migrations, flags, breaking changes, how to revert -->
+
+## Checklist
+- [ ] Tests added/updated and passing
+- [ ] Docs / OpenAPI updated
+- [ ] PR title is a Conventional Commit written for the changelog reader (if release-please is configured, it becomes the release note)
+- [ ] MEMORY.md updated (if new lasting knowledge)
+```
+
+## 5. Safety Rules (Especially for AI Agents)
+
+- **Commit only when the user or project workflow asks for it.** Don't push, merge or open PRs unprompted.
+- Never `git push --force` to shared branches (`main`, release branches). If a force push is needed on your own branch, use `--force-with-lease`.
+- Never rewrite (amend, rebase, reset) commits that have already been pushed and shared.
+- Never bypass hooks or checks (`--no-verify`, `--no-gpg-sign`) to make a commit pass. Fix the underlying failure.
+- Never use destructive commands (`git reset --hard`, `git clean -fd`, `git checkout .`, branch deletion) without explicit confirmation, because they can destroy uncommitted work.
+- If secrets were committed, treat them as compromised: rotate them first, then clean history.
+- Don't commit unrelated changes you didn't make or don't understand. Leave them and mention them.
+- If a pre-commit hook modifies files, review the changes and include them in a new commit rather than amending something already pushed.
+
+## 6. Releases and Tags
+
+- Version with Semantic Versioning (`MAJOR.MINOR.PATCH`). See `changelog-and-versioning`.
+- Tag releases `vX.Y.Z` (annotated: `git tag -a v1.4.0 -m "v1.4.0"`). Releases are built from tags in CI.
+- If release-please is configured (a `release-please-config.json` at the repository root), the PR title becomes the release note: merging the release PR updates `CHANGELOG.md`, bumps the version and tags `vX.Y.Z`. Use squash merges so the PR title becomes the commit message. Otherwise update `CHANGELOG.md` by hand. See `changelog-and-versioning` for both modes.
+- Hotfixes: branch from the release tag, fix, tag a patch release, and merge the fix back to `main`.
+
+## Review Checklist
+
+- [ ] Message follows `type(scope): subject`, imperative, ≤72 chars, explains why in the body
+- [ ] One logical change; tests and docs included; builds and passes locally
+- [ ] No secrets, generated files or unrelated changes staged
+- [ ] Branch name and PR title follow convention; PR is small and described
+- [ ] No force pushes, no skipped hooks, no history rewrites of shared commits
+- [ ] Commit/PR title written as a release note; changelog updated per `changelog-and-versioning`; MEMORY.md updated when required