diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..3f12847
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,18 @@
+# Agent instructions
+
+Read [`CONTRIBUTING.md`](CONTRIBUTING.md) before changing anything. The parts
+most often missed:
+
+- **Behaviour or spec change? Draft the OpenSpec change first**, before writing
+  the code — see [OpenSpec changes](CONTRIBUTING.md#openspec-changes). A small
+  fix that leaves every spec as-is does not need one.
+- **Never hand-edit `openspec/specs/`.** It is generated when a change is
+  archived; fix the delta and re-archive.
+- **Run the [local checks](CONTRIBUTING.md#local-checks-before-opening-a-pr)**
+  before opening a PR.
+- **Keep the container's security posture intact** — the privilege-drop,
+  capability set, and credential opt-in model are load-bearing (see [Threat
+  model](README.md#threat-model)).
+
+Architecture, threat model, and the version-pin refresh workflow are in
+[`README.md`](README.md).
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bc3a50d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,3 @@
+# Agent instructions
+
+See [`AGENTS.md`](AGENTS.md).
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b30acb5..9fcf8ef 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -8,14 +8,41 @@ Contributions to `claude-docker` are welcome from anyone.
 2. Make your change. Keep the container's security posture intact — the
    privilege-drop, capability set, and credential opt-in model are load-bearing
    (see [Threat model](README.md#threat-model)).
-3. Non-trivial behaviour changes are tracked with OpenSpec change proposals
-   under [`openspec/changes/`](openspec/); follow the existing ones as a
-   template.
+3. If the change touches behaviour or a spec, follow [OpenSpec
+   changes](#openspec-changes) below.
 4. Open a PR against `main`; a maintainer will review before it is merged.
 
 By submitting a contribution, you agree that it is licensed under the
 [Apache License 2.0](LICENSE), the same license as the project.
 
+## OpenSpec changes
+
+Anything that changes behaviour or touches an existing spec needs an OpenSpec
+change — new features, behaviour changes, and fixes that alter a documented
+requirement. A small fix that leaves every spec as-is does not.
+
+Draft the change *before* writing the code, then:
+
+1. **Draft** — `/opsx:propose` writes `proposal.md`, `design.md`, `tasks.md` and
+   the spec deltas under `openspec/changes/<change>/`.
+2. **Apply** — `/opsx:apply` implements the tasks and ticks them off.
+3. **Validate** — `openspec validate <change> --strict` must pass.
+4. **Archive** — `/opsx:archive` moves the change into
+   [`openspec/changes/archive/`](openspec/changes/archive/) and syncs its deltas
+   into [`openspec/specs/`](openspec/specs/).
+5. **Open the PR** with the code, the archived change, and the synced specs in
+   it.
+
+The `/opsx:*` commands come from OpenSpec's own agent integration — run
+`openspec init` once to install them for your coding agent. Without an agent,
+the `openspec` CLI shipped in the image covers the same ground.
+`openspec/specs/` is generated by step 4 — never hand-edit it; fix the delta
+and re-archive.
+
+For a change that reshapes the project, have the artifacts reviewed after step 1
+and before step 2: rewriting a proposal is cheap, redoing an implementation is
+not.
+
 ## Local checks before opening a PR
 
 CI runs these on every PR; running them locally first is faster: