diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..9fbc92d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,79 @@
+# action-gh-release
+
+This repository is maintained as a small, user-facing GitHub Action with a relatively wide compatibility surface.
+Optimize for stability, reproducibility, and clear user value over broad rewrites.
+
+## Core Rules
+
+- Prefer narrow behavior fixes over structural churn.
+- Reproduce current behavior on `master` before changing code.
+- Treat GitHub platform behavior as distinct from action behavior.
+  If GitHub controls the outcome, prefer docs or clearer errors over brittle workarounds.
+- Do not revive stale PRs mechanically.
+  Reuse the idea if it still has value, but reimplement on top of current `master`.
+- Avoid standalone refactors with no clear user-facing benefit.
+
+## Current Architecture
+
+- `src/main.ts` is the orchestration layer: parse config, validate inputs, create/update release, upload assets, finalize, set outputs.
+- `src/github.ts` owns release semantics: lookup, create/update/finalize, asset upload, race handling, and GitHub API interaction.
+- `src/util.ts` owns parsing and path normalization.
+- Keep behavior-specific logic in `src/github.ts` or `src/util.ts`; avoid growing `src/main.ts` with ad-hoc feature branches.
+
+## Bug-Fix Workflow
+
+- Reproduce the issue against current `master` first.
+- When available, use the companion consumer harness repo `action-gh-release-test`.
+- Capture exact workflow run URLs and release URLs before claiming a fix.
+- If the issue is really a docs/usage or platform-limit case, document it and close it as such instead of forcing a code change.
+- If a historical issue no longer reproduces on current `master`, prefer a short closeout note that asks the reporter to open a fresh issue if they still see it.
+
+## Feature Triage
+
+- Ship features only when there is clear user value or repeated demand.
+- Small convenience features are fine, but they should stay small.
+- Weak-demand features should not expand parsing complexity, cross-platform ambiguity, or maintenance surface.
+- For old feature PRs:
+  - check whether current `master` already covers the behavior
+  - prefer a tiny docs clarification if the behavior exists but is poorly explained
+  - close stale feature PRs when the idea is obsolete, low-value, or badly shaped for the current codebase
+
+## Contract Sync
+
+When behavior changes, keep the external contract in sync:
+
+- update `README.md`
+- update `action.yml`
+- update tests under `__tests__/`
+- regenerate `dist/index.js` with `npm run build`
+
+Docs-only changes do not need `dist/index.js` regeneration.
+
+## Verification
+
+For code changes, run:
+
+- `npm run fmtcheck`
+- `npm run typecheck`
+- `npm run build`
+- `npm test`
+
+For behavior changes, also run the relevant external regression workflow(s) in `action-gh-release-test` against the exact ref under test.
+
+## Release and Triage Conventions
+
+- Keep PR labels accurate. Release notes depend on them.
+  - bug fixes: `bug`
+  - docs-only changes: `documentation`
+  - additive features: `feature` or `enhancement`
+  - dependency updates: `dependencies`
+- Prefer manual issue/PR closeouts with a short rationale over implicit assumptions.
+- Do not auto-close old PRs or issues through unrelated docs PRs.
+
+## Implementation Preferences
+
+- Preserve the current upload/finalize flow unless there is strong evidence it needs to change.
+- Prefer upload-time semantics over filesystem mutation.
+- Be careful with parsing changes around `files`, path handling, and Windows compatibility.
+- Be careful with race-condition fixes; verify both local tests and consumer-repo concurrency harnesses.
+- Do not assume a refactor is safe just because tests are green. This action’s behavior is heavily shaped by GitHub API edge cases.