bilersan · Oct 22, 2026
@@ -58,6 +58,20 @@ For significant decisions:
 
 -->
 
+## [2026-10-22-205524] ctx init writes the agent instructions to AGENTS.md; CLAUDE.md becomes an @AGENTS.md import
+
+**Status**: Accepted
+
+**Context**: AGENTS.md (agents.md, stewarded by the Agentic AI Foundation under the Linux Foundation since 2025-12-09) is read natively by Codex, Copilot, Cursor, Gemini CLI, OpenCode, Pi and, since Claude Code 2.1.277 (2026-09-18), by Claude Code when no CLAUDE.md is present in the tree. ctx init wrote the bootstrap instructions only to CLAUDE.md, while ctx setup codex/opencode/pi deployed a second, older AGENTS.md template; mixed-tool teams got two diverging texts and non-Claude users got nothing from ctx init. Upstream issue ActiveMemory/ctx#197.
+
+**Decision**: ctx init writes the agent instructions to AGENTS.md; CLAUDE.md becomes an @AGENTS.md import
+
+**Rationale**: One tool-neutral template (internal/assets/integrations/agents.md), loaded once by every agent. ctx init creates or merges AGENTS.md with the same merge.OrCreate semantics CLAUDE.md had, between the ctx:agents markers the setup deployers already recognise. CLAUDE.md keeps a ctx block that is only an @AGENTS.md import: the Claude Code fallback needs 2.1.277, is unavailable in some sessions, and any hand-written CLAUDE.md in the tree switches it off, which is exactly the --merge case. Alternatives rejected: AGENTS.md only (silent loss on older Claude Code or once a CLAUDE.md appears), full content in both files (two copies, loaded twice), a symlink (not portable to Windows checkouts; agents.Deploy rejects symlinks).
+
+**Consequence**: ctx init writes AGENTS.md (ctx:agents ... ctx:agents:end) and a CLAUDE.md whose ctx:context block is the bridge; existing projects migrate with ctx init --reset --merge, which turns the old full block into the bridge and creates AGENTS.md. ctx setup agents|codex|opencode|pi now ship the richer shared template. Supersedes the 2026-01-25 decision 'Removed AGENTS.md from project root' (archive/decisions-consolidated-2026-02-26.md), whose premise that no tool auto-loads AGENTS.md no longer holds. Spec: specs/init-agents-md.md.
+
+---
+
 ## [2026-09-05-195906] Pi extension deploys as a flat single file (.pi/extensions/ctx.ts) with no package.json
 
 **Status**: Accepted

@@ -41,7 +41,7 @@ ctx init [flags]
 |-------------|-------|-----------------------------------------------------------------------------|
 | `--force`   | `-f`  | Overwrite existing context files                                            |
 | `--minimal` | `-m`  | Only create essential files (`TASKS.md`, `DECISIONS.md`, `CONSTITUTION.md`) |
-| `--merge`   |       | Auto-merge `ctx` content into existing `CLAUDE.md`                          |
+| `--merge`   |       | Auto-merge `ctx` content into existing `AGENTS.md` and `CLAUDE.md`          |
 
 **Creates**:
 
@@ -53,7 +53,11 @@ ctx init [flags]
   ([Phase KB](../recipes/build-a-knowledge-base.md)). Embedded
   templates are copied; existing files are preserved.
 - `.claude/settings.local.json` with pre-approved `ctx` permissions
-- `CLAUDE.md` with bootstrap instructions (or merges into existing)
+- `AGENTS.md` with the agent bootstrap instructions (or merges them into an
+  existing one): the open standard read by Claude Code, Codex, Copilot,
+  Cursor and others
+- `CLAUDE.md` as a bridge whose `ctx` block is an `@AGENTS.md` import, so
+  Claude Code loads the same text (or merges the bridge into an existing one)
 
 Claude Code hooks and skills are provided by the **`ctx` plugin**
 (see [Integrations](../operations/integrations.md#claude-code-full-integration)).

@@ -29,7 +29,7 @@ ctx setup <tool> [flags]
 
 | Tool          | Description                                                        |
 |---------------|--------------------------------------------------------------------|
-| `agents`      | Generic `AGENTS.md` (read natively by Codex, OpenCode, and others) |
+| `agents`      | Generic `AGENTS.md`, the file `ctx init` also writes (read natively by Claude Code, Codex, OpenCode, and others) |
 | `claude-code` | Redirects to plugin install instructions                           |
 | `codex`       | OpenAI Codex CLI (hooks, MCP, skills, `AGENTS.md`)                 |
 | `cursor`      | Cursor IDE                                                         |

@@ -259,8 +259,8 @@ ctx system bootstrap
 ```
 
 This prints the resolved context directory, the files in it, and the
-operating rules. The `CLAUDE.md` template instructs the agent to run this
-automatically. See [CLI Reference: bootstrap](../cli/bootstrap.md#ctx-system-bootstrap).
+operating rules. The `AGENTS.md` template (imported by `CLAUDE.md`) instructs
+the agent to run this automatically. See [CLI Reference: bootstrap](../cli/bootstrap.md#ctx-system-bootstrap).
 
 ## The Two Skills You Should Always Use
 
@@ -278,7 +278,7 @@ session end are the **highest-value skills** in the entire catalog:
 Let's provide some **context**, because this is **important**:
 
 Although the agent *will* **eventually** discover your context through
-`CLAUDE.md → AGENT_PLAYBOOK.md`, `/ctx-remember`
+`AGENTS.md → AGENT_PLAYBOOK.md`, `/ctx-remember`
 **hydrates the full context up front** (*tasks, decisions,
 recent sessions*) so the agent **starts informed** rather than
 piecing things together over several turns.

@@ -391,7 +391,7 @@ ctx system bootstrap -q       # just the context directory path
 ctx system bootstrap --json   # structured output for automation
 ```
 
-The `CLAUDE.md` template instructs the agent to run this as its first action.
+The `AGENTS.md` template instructs the agent to run this as its first action.
 Every nudge (*context checkpoint, persistence reminder, etc.*) also includes a
 `Context: <dir>` footer that re-anchors the agent to the correct directory
 throughout the session.

@@ -61,22 +61,24 @@ This gives you:
 | Component                     | Purpose                |
 |-------------------------------|------------------------|
 | `.context/`                   | All context files      |
-| `CLAUDE.md`                   | Bootstrap instructions |
+| `AGENTS.md`                   | Bootstrap instructions |
+| `CLAUDE.md`                   | `@AGENTS.md` import    |
 | Plugin hooks                  | Lifecycle automation   |
 | Plugin skills                 | Agent Skills           |
 
 ### How It Works
 
 ```mermaid
 graph TD
-    A[Session Start] --> B[Claude reads CLAUDE.md]
+    A[Session Start] --> B[Claude reads CLAUDE.md, which imports AGENTS.md]
     B --> C[PreToolUse hook runs]
     C --> D[ctx agent loads context]
     D --> E[Work happens]
     E --> F[Session End]
 ```
 
-1. **Session start**: Claude reads `CLAUDE.md`, which tells it to check `.context/`
+1. **Session start**: Claude reads `CLAUDE.md`, which imports `AGENTS.md`; the
+   instructions there tell it to check `.context/`
 2. **First tool use**: `PreToolUse` hook runs `ctx agent` and emits the context
    packet (*subsequent invocations within the cooldown window are silent*)
 3. **Next session**: Claude reads context files and continues with context

@@ -29,30 +29,41 @@ which tools your team uses.
 
 | You have...                          | Command                                           | What happens                                         |
 |--------------------------------------|---------------------------------------------------|------------------------------------------------------|
-| Nothing (*greenfield*)               | `ctx init`                                        | Creates `.context/`, `CLAUDE.md`, permissions        |
-| Existing `CLAUDE.md`                 | `ctx init --merge`                                | Backs up your file, inserts `ctx` block after the H1 |
-| Existing `CLAUDE.md` + `ctx` markers | `ctx init --reset`                                | Replaces the `ctx` block, leaves your content intact |
+| Nothing (*greenfield*)               | `ctx init`                                        | Creates `.context/`, `AGENTS.md`, `CLAUDE.md`, permissions |
+| Existing `AGENTS.md` or `CLAUDE.md`  | `ctx init --merge`                                | Backs up the file, inserts the `ctx` block after its H1 |
+| Existing file + `ctx` markers        | `ctx init --reset`                                | Replaces the `ctx` block, leaves your content intact |
 | `.cursorrules` / `.aider.conf.yml`   | `ctx init`                                        | `ctx` ignores those files: they coexist cleanly      |
-| Team repo, first adopter             | `ctx init --merge && git add .context/ CLAUDE.md` | Initialize and commit for the team                   |
+| Team repo, first adopter             | `ctx init --merge && git add .context/ AGENTS.md CLAUDE.md` | Initialize and commit for the team         |
 
 ---
 
-## Existing `CLAUDE.md`
+## Existing `AGENTS.md` or `CLAUDE.md`
 
 This is the most common scenario:
 
-You have a `CLAUDE.md` with project-specific instructions and don't want to 
+You have an `AGENTS.md` or `CLAUDE.md` with project-specific instructions and
+don't want to 
 lose them.
 
-!!! tip "You Own `CLAUDE.md`"
-    **After initialization, `CLAUDE.md` is yours: edit it freely**.
+`ctx` writes its instructions to `AGENTS.md`, the file Claude Code, Codex,
+Copilot, Cursor and other agents read, between `<!-- ctx:agents -->` and
+`<!-- ctx:agents:end -->`. `CLAUDE.md` gets a much smaller block between
+`<!-- ctx:context -->` and `<!-- ctx:end -->`: an `@AGENTS.md` import that
+makes Claude Code load the same text (a `CLAUDE.md` without it would make
+Claude Code ignore `AGENTS.md` altogether). Both files are handled the same
+way below.
+
+!!! tip "You Own Both Files"
+    **After initialization, `AGENTS.md` and `CLAUDE.md` are yours: edit them
+    freely**.
 
     Add project instructions, remove sections you don't need, reorganize as 
     you see fit.
 
-    The only part `ctx` manages is the block between the `<!-- ctx:context -->`
-    and `<!-- ctx:end -->` markers; everything outside those markers is yours
-    to change at any time.
+    The only parts `ctx` manages are the blocks between the markers
+    (`<!-- ctx:agents -->` ... `<!-- ctx:agents:end -->` in `AGENTS.md`,
+    `<!-- ctx:context -->` ... `<!-- ctx:end -->` in `CLAUDE.md`); everything
+    outside those markers is yours to change at any time.
 
     If you remove the markers, nothing breaks: `ctx` simply treats the file 
     as having no `ctx` content and will offer to merge again on the next 
@@ -61,20 +72,20 @@ lose them.
 
 ### What `ctx init` Does
 
-When `ctx init` detects an existing `CLAUDE.md`, it checks for `ctx` markers
-(`<!-- ctx:context -->` ... `<!-- ctx:end -->`):
+When `ctx init` detects an existing `AGENTS.md` or `CLAUDE.md`, it checks the
+file for its `ctx` markers:
 
 | State                      | Default behavior         | With `--merge`            | With `--force`                  |
 |----------------------------|--------------------------|---------------------------|---------------------------------|
-| No `CLAUDE.md`             | Creates from template    | Creates from template     | Creates from template           |
+| No file                    | Creates from template    | Creates from template     | Creates from template           |
 | Exists, no `ctx` markers   | **Prompts** to merge     | Auto-merges (*no prompt*) | Auto-merges (*no prompt*)       |
 | Exists, has `ctx` markers  | Skips (*already set up*) | Skips                     | Replaces the `ctx` block only   |
 
 ### The `--merge` Flag
 
 `--merge` auto-merges without prompting. The merge process:
 
-1. **Backs up** your existing `CLAUDE.md` to `CLAUDE.md.<timestamp>.bak`;
+1. **Backs up** the existing file to `<file>.<timestamp>.bak`;
 2. **Finds the H1 heading** (e.g., `# My Project`) in your file;
 3. **Inserts** the `ctx` block immediately after it;
 4. **Preserves** everything else untouched.
@@ -83,7 +94,7 @@ Your content before and after the `ctx` block remains exactly as it was.
 
 ### Before / After Example
 
-**Before**: your existing `CLAUDE.md`:
+**Before**: your existing `AGENTS.md`:
 
 ```markdown
 # My Project
@@ -104,15 +115,15 @@ Your content before and after the `ctx` block remains exactly as it was.
 ```markdown
 # My Project
 
-<!-- ctx:context -->
+<!-- ctx:agents -->
 <!-- DO NOT REMOVE: This marker indicates ctx-managed content -->
 
 ## IMPORTANT: You Have Persistent Memory
 
 This project uses Context (`ctx`) for context persistence across sessions.
 ...
 
-<!-- ctx:end -->
+<!-- ctx:agents:end -->
 
 ## Build Commands
 
@@ -128,47 +139,70 @@ This project uses Context (`ctx`) for context persistence across sessions.
 Your build commands and code style sections are untouched. The `ctx` block sits
 between markers and can be updated independently.
 
+Your `CLAUDE.md`, if you have one, receives only the bridge:
+
+```markdown
+# My Project
+
+<!-- ctx:context -->
+<!-- DO NOT REMOVE: This marker indicates ctx-managed content -->
+<!-- ctx keeps the agent instructions in AGENTS.md, the open standard
+     read by Claude Code, Codex, Copilot, Cursor and others; the line
+     below imports them into Claude Code. -->
+@AGENTS.md
+<!-- ctx:end -->
+
+## Build Commands
+...
+```
+
 ### The `--force` Flag
 
-If your `CLAUDE.md` already has `ctx` markers (from a previous `ctx init`), the
-default behavior is to skip it. Use `--force` to replace the `ctx` block with the
+If your `AGENTS.md` or `CLAUDE.md` already has `ctx` markers (from a previous
+`ctx init`), the default behavior is to skip it. Use `--force` to replace the `ctx` block with the
 latest template: This is useful after **upgrading** `ctx`:
 
 ```bash
 ctx init --reset
 ```
 
-This only replaces content between `<!-- ctx:context -->` and `<!-- ctx:end -->`.
-Your own content outside the markers is preserved. A timestamped backup is
-created before any changes.
+This only replaces the content between the markers. Your own content outside
+them is preserved. A timestamped backup is created before any changes.
+
+Upgrading from a `ctx` release that wrote the full instructions into
+`CLAUDE.md`? The same command moves them: the old `CLAUDE.md` block becomes
+the `@AGENTS.md` import and `AGENTS.md` is created with the instructions.
 
 ### Undoing a Merge
 
 Every merge creates a backup:
 
 ```bash
-$ ls CLAUDE.md*.bak
+$ ls AGENTS.md*.bak CLAUDE.md*.bak
+AGENTS.md.1738000000.bak
 CLAUDE.md.1738000000.bak
 ```
 
 To restore:
 
 ```bash
+cp AGENTS.md.1738000000.bak AGENTS.md
 cp CLAUDE.md.1738000000.bak CLAUDE.md
 ```
 
 Or if you are using `git`, simply:
 
 ```bash
-git checkout CLAUDE.md
+git checkout AGENTS.md CLAUDE.md
 ```
 
 ---
 
 ## Existing `.cursorrules` / Aider / Copilot
 
 `ctx` doesn't touch tool-specific config files. It creates its own files
-(`.context/`, `CLAUDE.md`) and coexists with whatever you already have.
+(`.context/`, `AGENTS.md`, `CLAUDE.md`) and coexists with whatever you already
+have.
 
 ### What Does `ctx` Create?
 
@@ -177,7 +211,7 @@ git checkout CLAUDE.md
 | `.context/` directory                                                                       | `.cursorrules`                    |
 | `CLAUDE.md` (*or merges into*)                                                              | `.aider.conf.yml`                 |
 | `.claude/settings.local.json` (*seeded by `ctx init`; the plugin manages hooks and skills*) | `.github/copilot-instructions.md` |
-|                                                                                             | `.windsurfrules`                  |
+| `AGENTS.md` (*or merges into*)                                                              | `.windsurfrules`                  |
 |                                                                                             | Any other tool-specific config    |
 
 Claude Code hooks and skills are provided by the **`ctx` plugin**,
@@ -254,7 +288,7 @@ With those in place, committing is straightforward:
 ctx init --merge
 
 # Commit context files (journals and keys are already gitignored)
-git add .context/ CLAUDE.md
+git add .context/ AGENTS.md CLAUDE.md
 git commit -m "Add ctx context management"
 git push
 ```
@@ -295,7 +329,8 @@ Common conflict scenarios:
 You don't need the whole team to switch at once:
 
 1. One person runs `ctx init --merge` and commits;
-2. `CLAUDE.md` instructions work immediately for Claude Code users;
+2. `AGENTS.md` works immediately for Claude Code, Codex, Copilot, Cursor and
+   every other agent that reads it (`CLAUDE.md` imports it for Claude Code);
 3. Other tool users can adopt at their own pace using `ctx setup <tool>`;
 4. Context files benefit everyone who reads them, even without tool integration.
 
@@ -334,11 +369,12 @@ If you used `--merge`, check that your original content is intact:
 
 ```bash
 # Your original content should still be there
-cat CLAUDE.md
+cat AGENTS.md
 
-# The ctx block should be between markers
-grep -c "ctx:context" CLAUDE.md  # Should print 1
-grep -c "ctx:end" CLAUDE.md      # Should print 1
+# The ctx block should be between markers, and CLAUDE.md should import it
+grep -c "<!-- ctx:agents -->" AGENTS.md  # Should print 1
+grep -c "ctx:agents:end" AGENTS.md       # Should print 1
+grep -c "@AGENTS.md" CLAUDE.md            # Should print 1
 ```
 
 ---

@@ -47,13 +47,13 @@ Or use the `/_ctx-command-audit` skill after the rename.
 # Install the new binary
 make build && sudo make install
 
-# Regenerate CLAUDE.md and permissions
+# Regenerate AGENTS.md, CLAUDE.md and permissions
 ctx init --reset --merge
 ```
 
 `--merge` preserves your knowledge files (TASKS.md, DECISIONS.md,
-etc.) while regenerating infrastructure (permissions, CLAUDE.md
-managed sections).
+etc.) while regenerating infrastructure (permissions, AGENTS.md and
+CLAUDE.md managed sections).
 
 ## Step 3: Update the Plugin
 
@@ -114,7 +114,7 @@ in the release notes using this template:
 The old name is removed (no deprecation alias).
 
 **Action required**:
-1. Run `ctx init --reset --merge` to update CLAUDE.md
+1. Run `ctx init --reset --merge` to update AGENTS.md and CLAUDE.md
 2. Update any scripts referencing `ctx old-command`
 3. Update hook configs if applicable
 

@@ -13,7 +13,7 @@ icon: lucide/arrow-up-circle
 
 ## Upgrade
 
-New versions of `ctx` may ship updated permissions, `CLAUDE.md` directives,
+New versions of `ctx` may ship updated permissions, `AGENTS.md` directives,
 or plugin hooks and skills.
 
 !!! tip "Claude Code User?"
@@ -45,7 +45,7 @@ ctx init --reset --merge
 
 | Category           | Examples                                                                                                                                        | Changes between versions?     |
 |--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------|
-| **Infrastructure** | `.claude/settings.local.json` (permissions), ctx-managed sections in `CLAUDE.md`, **`ctx` plugin** (hooks + skills)                               | Yes                           |
+| **Infrastructure** | `.claude/settings.local.json` (permissions), ctx-managed sections in `AGENTS.md` and `CLAUDE.md`, **`ctx` plugin** (hooks + skills)                               | Yes                           |
 | **Knowledge**      | `.context/TASKS.md`, `DECISIONS.md`, `LEARNINGS.md`, `CONVENTIONS.md`, `ARCHITECTURE.md`, `GLOSSARY.md`, `CONSTITUTION.md`, `AGENT_PLAYBOOK.md` | **No**: this is **your** data |
 
 Infrastructure is regenerated by `ctx init` and plugin updates.
@@ -72,7 +72,9 @@ ctx init --reset --merge
 ```
 
 * `--force` regenerates infrastructure files (permissions, ctx-managed
-  sections in `CLAUDE.md`).
+  sections in `AGENTS.md` and `CLAUDE.md`). Coming from a release that
+  wrote the instructions into `CLAUDE.md`, this moves them into
+  `AGENTS.md` and leaves an `@AGENTS.md` import behind.
 * `--merge` preserves your content outside `ctx` markers.
 
 Knowledge files (`.context/TASKS.md`, `DECISIONS.md`, etc.) are **preserved