diff --git a/.claude/skills/README.md b/.claude/skills/README.md
index da7cd16..833dc35 100644
--- a/.claude/skills/README.md
+++ b/.claude/skills/README.md
@@ -5,6 +5,9 @@ required to build or run the app. Start with `CONTRIBUTING.md` for dependencies
 and verification; use whatever terminal, browser or native-window tools your
 agent environment provides.
 
+Follow `AGENTS.md` for issue tracking: internal and contributor work both use
+this repository's GitHub Issues, not Linear.
+
 | Skill | Purpose | Requirements beyond the contributor setup |
 | --- | --- | --- |
 | `bus-live-test` | Exercise bot messaging and guardrails | Node 22+; real Claude sessions require consent and an authenticated CLI |
diff --git a/.claude/skills/release/SKILL.md b/.claude/skills/release/SKILL.md
index d3cd310..cb140a3 100644
--- a/.claude/skills/release/SKILL.md
+++ b/.claude/skills/release/SKILL.md
@@ -60,7 +60,7 @@ cargo update --workspace --offline
 `@xterm/addon-web-links` dependency, not ours. Leave it.
 
 Commit as `chore(release): bump version to X.Y.Z`, open the PR against `main`
-with the usual What/Why/How tested body and link the primary issue. Before
+with the usual What/Why/How tested body and link the primary GitHub issue (`#123`). Before
 pushing, run `pnpm run verify` (typecheck, tests, lint, builds and visual checks).
 Regenerate dependency notices with `pnpm notices:generate` when versions or
 lockfiles change; follow `third-party/README.md` for the pinned toolchain.
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..0a1c94f
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,41 @@
+# Gravity agent instructions
+
+## Issue tracking
+
+- Use GitHub Issues in this repository for all Gravity work, including internal
+  maintainer tasks, bugs, plans, and follow-ups. Do not create or update Linear
+  issues for Gravity. This overrides shared agent guidance that requires Linear
+  or `USE-XXX` identifiers.
+- Use `gh issue list`, `gh issue view`, and `gh issue create` to find or track
+  work. Reuse a relevant issue instead of creating duplicates.
+- Reference GitHub issue numbers (`#123`) in plans and pull requests. Use
+  `Fixes #123` only when merging the PR completes that issue.
+- Keep credentials, private paths, account details, and private project data out
+  of public issues. Follow `SECURITY.md` for vulnerability reports. Do not copy
+  an old private backlog into public issues without reviewing it for disclosure
+  and confirming the migration scope.
+
+## Workflow
+
+- Read `CONTRIBUTING.md`. Outline a brief plan for non-trivial changes, then
+  implement authorized work without repeated permission requests.
+- Use pnpm and run `pnpm run verify` before considering work complete. Report
+  any unavailable checks; use hosted visual CI if local Docker is unavailable.
+- Preserve existing edits. Ask before deleting files, discarding changes,
+  rewriting history, force-pushing, or applying irreversible migrations.
+- Never bypass hooks or branch protections. Release publication requires
+  authorization; a code or documentation change alone does not authorize it.
+
+## Code and pull requests
+
+- Keep changes concise and preserve strict TypeScript checks. No `any`,
+  unchecked type assertions, or non-null assertions. Narrow unknown inputs.
+- Use static imports, braces for control flow, explicit return types for
+  exported functions, and readonly types where mutation is unnecessary.
+- Prefer shared code over duplication.
+- Use conventional commits with concise imperative subjects.
+- Target `main`. PR descriptions must have **What**, **Why**, and **How tested**
+  sections, reference the relevant GitHub issue, and state rollout requirements
+  and validation limitations.
+- Keep communication brief. Include `file_path:line_number` when referencing
+  code. Do not send announcements or third-party messages without authorization.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..7d7b66b
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,8 @@
+# Gravity
+
+Read and follow [AGENTS.md](AGENTS.md) for this repository's workflow and code
+conventions. Gravity uses GitHub Issues for both contributor and internal work;
+the repository instructions override shared guidance requiring Linear.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and verification, and
+[.claude/skills/README.md](.claude/skills/README.md) for optional agent workflows.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 355694d..ea4d06c 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -6,6 +6,19 @@ expected and actual behavior. Remove tokens, personal paths, and private project
 content from logs and screenshots. See [SECURITY.md](SECURITY.md) for security
 reports.
 
+## Issue tracking
+
+GitHub Issues is the source of truth for all Gravity work, including internal
+maintainer tasks and follow-ups. Use this repository's issues instead of Linear
+or `USE-XXX` identifiers. Search for an existing issue before opening one, and
+reference it as `#123` in discussions and pull requests. Use `Fixes #123` when a
+PR fully resolves the issue.
+
+The same workflow applies to coding agents; see [AGENTS.md](AGENTS.md). Review
+private backlog items for sensitive information before proposing any migration
+to public issues. Security reports belong in the private channel described in
+[SECURITY.md](SECURITY.md).
+
 ## Development setup
 
 Use a current stable Rust toolchain, Node.js 22, and pnpm 11. Building the native