From a73607128e187a4fe5c7acf0ca5bb7e1040fe0ee Mon Sep 17 00:00:00 2001
From: gn-kim-k <171027203+gn-kim-k@users.noreply.github.com>
Date: Tue, 20 Oct 2026 17:30:17 +0100
Subject: [PATCH 1/2] docs: check upstream Kratos before implementing fork
 changes

---
 AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md |  5 +++++
 2 files changed, 56 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000000..dee8cec0d5e3
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,51 @@
+# Agent guidance for the Goodnotes Kratos fork
+
+This repository is the Goodnotes fork of [Ory Kratos](https://github.com/ory/kratos).
+The Goodnotes integration branch is `goodnotes`; target fork pull requests there
+unless the task explicitly specifies another branch. The inherited
+`CONTRIBUTING.md` describes upstream's `master` workflow.
+
+## Check upstream before implementing
+
+Before implementing a change or fix, check whether upstream Ory Kratos already
+contains a suitable solution. This applies to application behavior, tests,
+dependencies, build tooling, and CI. Prefer reusing upstream work over inventing
+and maintaining a parallel implementation in this fork.
+
+1. Identify the affected behavior and files in this fork.
+2. Inspect the corresponding current upstream code and relevant commits, pull
+   requests, issues, and release notes. Search by the symptom or error as well
+   as the affected symbols or paths; checking only our fork or one keyword is
+   not enough to conclude that upstream has no fix. Keep the investigation
+   proportional to the change.
+3. If a suitable upstream change exists, inspect its complete patch, tests,
+   prerequisites, and any follow-up fixes. Check compatibility with our version
+   and Goodnotes-specific behavior before adopting it.
+   - Prefer `git cherry-pick -x <commit>` when the patch and its necessary
+     prerequisites fit this fork.
+   - Otherwise, port the smallest relevant change and its regression tests.
+     Preserve upstream attribution and explain any adaptations.
+   - Treat an unmerged upstream PR as a candidate to review, not as an accepted
+     or released fix.
+4. If no applicable upstream change exists, proceed with the normal local
+   implementation and testing workflow. An upstream solution that cannot
+   safely be ported also permits a local fix; document the incompatibility.
+
+Use GitHub or a verified upstream Git remote for this investigation. Inspect
+remote URLs rather than assuming that `origin` points to Ory. Do not merge all
+of upstream or pull in unrelated changes merely to obtain one fix.
+
+## Record evidence and validate the result
+
+In the PR description, record the upstream repository and ref or commit checked,
+the relevant search scope, and the outcome:
+
+- For a cherry-pick or port, link the upstream PR and commit, describe adaptations
+  and required prerequisites, and report the tests run against this fork.
+- For a local implementation, summarize what was checked and why no upstream
+  change applies. If upstream could not be inspected, state that limitation;
+  do not present an unavailable check as evidence that no fix exists.
+
+Upstream tests passing does not prove compatibility with this fork. Run focused
+regression tests here, including coverage of affected Goodnotes-specific
+behavior, and report validation gaps explicitly.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..cc26c068a878
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,5 @@
+# Claude Code guidance
+
+Read and follow [AGENTS.md](AGENTS.md) before planning or making changes.
+It contains the repository-wide instructions, including checking upstream Ory
+Kratos for an existing change before implementing a local solution.

From e19b3d79195d7328734e0f5b8dd3dcc6aac58694 Mon Sep 17 00:00:00 2001
From: gn-kim-k <171027203+gn-kim-k@users.noreply.github.com>
Date: Tue, 20 Oct 2026 17:40:56 +0100
Subject: [PATCH 2/2] docs: symlink Claude guidance to AGENTS.md

---
 CLAUDE.md | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)
 mode change 100644 => 120000 CLAUDE.md

diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index cc26c068a878..000000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,5 +0,0 @@
-# Claude Code guidance
-
-Read and follow [AGENTS.md](AGENTS.md) before planning or making changes.
-It contains the repository-wide instructions, including checking upstream Ory
-Kratos for an existing change before implementing a local solution.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 000000000000..47dc3e3d863c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file