@open-agent-toolkit/cli 0.3.7 → 0.3.9

package/assets/docs/workflows/projects/implementation-execution.md

@@ -47,8 +47,9 @@ flowchart LR
 
   P --> Report["Phase report\nverification + commits"]
   Report --> Root
-  Root --> R["Independent phase reviewer"]
-  R -->|pass| Book["Bookkeeping + next phase"]
+  Root --> Ledger["Commit task ledger\npre-review bookkeeping"]
+  Ledger --> R["Independent phase reviewer"]
+  R -->|pass| Book["Review-outcome bookkeeping\n+ next phase"]
   R -->|blocking findings| Fix["Resume phase implementer\nbounded fix scope"]
   Fix --> R2["Fresh root-owned review round"]
 ```
@@ -241,7 +242,14 @@ already part of the next phase's base.
 
 The root sends the reviewer a fresh scope containing the authoritative phase
 commit range, task IDs and boundaries, project artifacts, and verification
-evidence. The review passes with zero Critical and zero High findings.
+evidence. The root commits the phase's task ledger — task rows, the resume
+pointer, and any settled recovery marker — before it dispatches the reviewer,
+so the reviewed head is never stale by construction. Review-outcome
+bookkeeping — the Reviews row and its disposition, the Orchestration Run, and
+the deferred project-log entries — is out of scope at the reviewed head: the
+root writes it after the review returns. In a parallel group the phase worktree
+does not carry the root ledger, so the reviewer brief names the task ledger out
+of scope as well. The review passes with zero Critical and zero High findings.
 Medium and Low findings are recorded without blocking the phase.
 
 ## Final Exit-Gate Boundary
@@ -278,14 +286,20 @@ contradictory, or ambiguous correlation fails closed. A valid accepted run or
 completed receive is never duplicated.
 
 Freshness is bound to the reviewed HEAD and a versioned implementation
-fingerprint. New generations use an `effective-delta-v1` fingerprint over
+fingerprint. New generations use an `effective-delta-v2` fingerprint over
 Git's canonical NUL-delimited raw tree delta. The generation persists the
 logical PR/default-branch base ref, requires one merge base, and hashes full
 base and final modes and object IDs with rename detection disabled. This makes
 same-file base changes visible while excluding commit history and human diff
 context. Every effective-delta path is included except the exact project
-`state.md` file that carries the digest and would otherwise be self-referential;
-that structured state is validated independently.
+`state.md` file that carries the digest and would otherwise be self-referential
+(that structured state is validated independently) and everything under
+`.oat/projects/` and `.oat/repo/`: project artifacts and repository records
+such as reviews, summaries, backlog items, and decisions never make the exit
+gate stale. `.oat/templates/`, `.oat/scripts/`, `.oat/config*.json`, and
+`.oat/sync/` stay fingerprinted. A stored `effective-delta-v1` value keeps its
+original meaning (only the `state.md` carrier excluded) and is never
+reinterpreted; the next generation after it goes stale uses v2.
 
 Recognized closeout-only descendants preserve a valid result: gate artifacts
 and receipts, project tracking and project-log appends,
@@ -301,8 +315,8 @@ A merge, rebase, or base update preserves the result only when its full
 effective delta matches that rolling checkpoint. Conflict resolution or
 branch-owned implementation, test, skill, template, or workflow changes that
 alter the delta make the result stale, require a current final lifecycle review,
-and start a new gate generation. No implementation or closeout output path is
-excluded from the comparison. Legacy unqualified fingerprints retain the older
+and start a new gate generation. Beyond the version's own exclusion set, no
+implementation or closeout output path is excluded from the comparison. Legacy unqualified fingerprints retain the older
 fail-closed descendant-path behavior and are not migrated in place.
 
 This narrow merge-only exemption relies on fresh repository CI, automated

package/assets/docs/workflows/projects/lifecycle.md

@@ -158,13 +158,11 @@ filesystem operation. Deleting or archiving the old scaffold does not make the
 roadmap stop promising its work, so completion checks the claim against the
 prose that still makes it.
 
-When a quick project consolidates earlier scaffolds, quick-start records
+When a quick or lite project consolidates earlier scaffolds, the workflow that
+scaffolds it (`oat-project-quick-start` or `oat-project-lite`) records
 `absorbed_projects` and `absorbed_backlog_ids` in that project's `state.md`
-frontmatter. Those two fields are the only inputs the sweep takes.
-
-Recording them is a quick-mode step today. A lite project that consolidates
-earlier scaffolds records nothing, so the sweep finds no inputs and degrades to
-its recorded note rather than checking that project's surfaces.
+frontmatter, with the same field shapes in both modes. Those two fields are the
+only inputs the sweep takes.
 
 Inside the project-log completion gate — after the log status probe and before
 the roll-up and seal — completion searches the active planning surfaces for each

package/assets/docs/workflows/projects/retro.md

@@ -84,6 +84,13 @@ Per-item statuses and frontmatter rollups make interrupted and repeated runs
 resumable. The promotions rollup covers RP apply-items; the filing rollup covers
 UP items plus RP file-items.
 
+Every run ends with a final report walkthrough that links the artifact and
+explains each `RP-*` and `UP-*` item (ID, title, summary, why it matters,
+current disposition and destination, and next action), grouped into apply,
+repository filing, and upstream filing items, or states that no items were
+proposed. It appears in interactive and non-interactive runs, whatever happened
+to apply and filing.
+
 ### Project-log receipt
 
 When a project log exists, generate mode appends this one-line structural

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.7",
-  "docs-config": "0.3.7",
-  "docs-theme": "0.3.7",
-  "docs-transforms": "0.3.7"
+  "cli": "0.3.9",
+  "docs-config": "0.3.9",
+  "docs-theme": "0.3.9",
+  "docs-transforms": "0.3.9"
 }

package/assets/skills/oat-agent-instructions-analyze/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.12.2
+  version: 1.12.4
 ---
 
 # Agent Instructions Analysis
@@ -259,7 +259,7 @@ documentation inventory from Step 2 to:
 **Provider-specific validation:**
 
 - **AGENTS.md**: Check section structure, command accuracy, size budget.
-- **CLAUDE.md**: Verify `@AGENTS.md` import if present, check for content duplication with AGENTS.md.
+- **CLAUDE.md**: Read the shim strategy with `oat config get instructions.claude.shims`. Under a shim strategy (`pointer`, `symlink`, or `copy`), verify the `@AGENTS.md` import if present and check for content duplication with AGENTS.md. Under `none` (the default), Claude Code reads AGENTS.md itself through its built-in `agents-md` plugin, which stands down while a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists on the session's path: a root file affects the whole project, a nested file affects sessions started in its directory or below; record each such file as a High finding whose fix is to remove it or to configure a shim strategy and run `oat instructions sync`. Take the authoritative list from `oat instructions validate --json` `.warnings[]` (code `claude_md_hides_agents_md`), which covers the whole repository including `CLAUDE.local.md` (exact-case names only); the discovery script also lists `CLAUDE.local.md` under the claude provider. When a warning's `linkedBy` is non-empty, that file holds the only copy of the instructions behind those AGENTS.md links: the fix is to replace each linking AGENTS.md with the file's content first and only then remove the file; never recommend plain removal for it. When `.warnings[]` also holds a `claude_md_blocks_shim_removal` item, removal under `none` is all or nothing and is blocked: report its `paths` (the files with content of their own) as the High finding, whose fix is to move each file's content into an AGENTS.md or remove it (for a file its `linkedBy` maps to AGENTS.md links, replace each linking AGENTS.md with the file's content first) and then rerun `oat instructions sync`; list its `wouldRemove` as the CLAUDE.md files that sync then removes. Those files get no `claude_md_hides_agents_md` warning of their own while the block holds, so read them from the block item rather than reporting them as missing.
 - **Claude rules** (`.claude/rules/*.md`): Validate `paths` frontmatter if conditional.
 - **Cursor rules** (`.cursor/rules/*.mdc`): Validate frontmatter fields (`alwaysApply`, `globs`, `description`).
 - **Copilot instructions** (`.github/instructions/*.instructions.md`): Validate `applyTo` frontmatter.
@@ -306,7 +306,7 @@ These checks are mandatory even when the missing file does not appear in the dis
 
 Provider baseline examples:
 
-- **Claude**: if a directory has `AGENTS.md` and the claude provider is active but the matching `CLAUDE.md` shim is missing, record an explicit recommendation to create `CLAUDE.md` with the canonical `@AGENTS.md` import. This applies to **every** directory with an `AGENTS.md` — root and nested alike (e.g., `packages/cli/AGENTS.md` → `packages/cli/CLAUDE.md`).
+- **Claude**: only when a shim strategy is configured (`instructions.claude.shims` is `pointer`, `symlink`, or `copy`): if a directory has `AGENTS.md` and the claude provider is active but the matching `CLAUDE.md` shim is missing, record an explicit recommendation to create `CLAUDE.md` with the canonical `@AGENTS.md` import. This applies to **every** directory with an `AGENTS.md` — root and nested alike (e.g., `packages/cli/AGENTS.md` → `packages/cli/CLAUDE.md`). Under `none`, the default, recommend no `CLAUDE.md`: Claude Code loads AGENTS.md natively, and a shim in some directories but not others makes it ignore the AGENTS.md files that lack one.
 - **Copilot**: if the copilot provider is active but `.github/copilot-instructions.md` is missing, record an explicit recommendation to create the minimal Copilot shim.
 - **agents_md / codex**: no extra always-on shim beyond `AGENTS.md`.
 
@@ -314,7 +314,7 @@ Do not leave these as implied apply-time behavior. They must appear in the analy
 
 **Chained recommendations for new AGENTS.md files:**
 
-When a coverage-gap recommendation proposes creating a **new** `AGENTS.md` in a subdirectory, also emit the corresponding provider-baseline recommendations for that directory in the same artifact. For example, if the analysis recommends creating `packages/cli/AGENTS.md` and the claude provider is active, it must also recommend creating `packages/cli/CLAUDE.md` with `@AGENTS.md`. Do not defer these to a follow-up analysis — they belong in the same artifact so `oat-agent-instructions-apply` can generate both files in one pass.
+When a coverage-gap recommendation proposes creating a **new** `AGENTS.md` in a subdirectory, also emit the corresponding provider-baseline recommendations for that directory in the same artifact. For example, if the analysis recommends creating `packages/cli/AGENTS.md`, the claude provider is active, and a shim strategy is configured, it must also recommend creating `packages/cli/CLAUDE.md` with `@AGENTS.md`. Do not defer these to a follow-up analysis — they belong in the same artifact so `oat-agent-instructions-apply` can generate both files in one pass.
 
 **In delta mode:** Only assess directories that contain files changed since the last tracked commit. Skip unchanged directories.
 

package/assets/skills/oat-agent-instructions-analyze/references/analysis-artifact-template.md

@@ -119,11 +119,11 @@ None | {numbered list}
 
 Missing always-on provider compatibility files that should exist even when no corresponding file was discovered during inventory.
 
-| #   | Provider  | Required Path                     | Format             | Reason                                             | Evidence     | Severity      |
-| --- | --------- | --------------------------------- | ------------------ | -------------------------------------------------- | ------------ | ------------- |
-| 1   | `claude`  | `CLAUDE.md`                       | Claude import shim | {claude active + AGENTS.md present + shim missing} | {exact refs} | {High/Medium} |
-| 2   | `copilot` | `.github/copilot-instructions.md` | Copilot shim       | {copilot active + shim missing}                    | {exact refs} | {High/Medium} |
-| ... |           |                                   |                    |                                                    |              |               |
+| #   | Provider  | Required Path                     | Format             | Reason                                                                                                                    | Evidence     | Severity      |
+| --- | --------- | --------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------- | ------------ | ------------- |
+| 1   | `claude`  | `CLAUDE.md`                       | Claude import shim | {claude active + shim strategy configured (`instructions.claude.shims` is not `none`) + AGENTS.md present + shim missing} | {exact refs} | {High/Medium} |
+| 2   | `copilot` | `.github/copilot-instructions.md` | Copilot shim       | {copilot active + shim missing}                                                                                           | {exact refs} | {High/Medium} |
+| ... |           |                                   |                    |                                                                                                                           |              |               |
 
 {Or: "No provider baseline gaps identified."}
 

package/assets/skills/oat-agent-instructions-analyze/references/docs/rules-files.md

@@ -125,13 +125,16 @@ User-level rules go in `~/.claude/rules/` and apply to all projects (lower prior
 
 ### 2.6 AGENTS.md Support
 
-**AGENTS.md is NOT natively supported by Claude Code** (GitHub issue #6235 has 2,700+ upvotes, still open). The recommended workaround is a one-line `CLAUDE.md`:
+Source: `anthropics/claude-code` `mods/agents-md` README, as of v2.1.278.
 
-```markdown
-@AGENTS.md
-```
+**Claude Code reads AGENTS.md natively** through its built-in `agents-md` plugin. Its `instructionFiles` option defaults to `claude-md-or-agents-md`; the other values are `claude-md`, `claude-md-and-agents-md`, and `managed-only`.
+
+- **Default mode stands down on any CLAUDE.md.** In `claude-md-or-agents-md`, the plugin loads no AGENTS.md for the session when any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or any directory above it up to the project root; the engine then loads only CLAUDE.md files. A root `CLAUDE.md` or a personal `CLAUDE.local.md` therefore hides every AGENTS.md, and shims in some directories but not others hide every AGENTS.md without one.
+- **`claude-md-and-agents-md`** loads both; an AGENTS.md that a CLAUDE.md already imports or links is not loaded twice.
+- **Only user or managed settings can set the option** (`~/.claude/settings.json`, `--settings`, or managed settings); a project's `.claude/settings.json` cannot.
+- **Nested gaps:** nested AGENTS.md files attach on a text `Read` only (not on `@`-mentions, IDE selections, or notebook, image, or PDF reads), and `--add-dir` directories contribute no AGENTS.md.
 
-This leverages @-import. Alternative: symlink `ln -s AGENTS.md CLAUDE.md`.
+The one-line `CLAUDE.md` shim (`@AGENTS.md`, or `ln -s AGENTS.md CLAUDE.md`) is now **opt-in**: use it for Claude Code releases before the plugin, for users who set `instructionFiles` to `claude-md`, or when the nested gaps above matter, and then keep a shim beside every AGENTS.md. In OAT this is `instructions.claude.shims` (`none` by default; `pointer`, `symlink`, or `copy` to opt in), applied by `oat instructions sync`; see the OAT docs page `provider-sync/instruction-sync.md` (§ Claude Code and AGENTS.md).
 
 ### 2.7 Skills vs CLAUDE.md vs Rules
 
@@ -411,12 +414,12 @@ All three providers support file-pattern-based activation — this is the unifyi
 
 ### 5.4 AGENTS.md Support
 
-| Provider    | Native support                   | Nested                 | Import mechanism     |
-| ----------- | -------------------------------- | ---------------------- | -------------------- |
-| Claude Code | **No** (use `@AGENTS.md` import) | N/A                    | `@path` in CLAUDE.md |
-| Cursor      | **Yes** (first-class)            | Yes (hierarchical)     | N/A — read directly  |
-| Copilot     | **Yes** (`**/AGENTS.md`)         | Yes (nearest wins)     | N/A — read directly  |
-| Codex       | **Yes** (primary format)         | Yes (override pattern) | N/A — native         |
+| Provider    | Native support                                                                                                                                            | Nested                          | Import mechanism                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
+| Claude Code | **Yes** (built-in `agents-md` plugin; stands down while any CLAUDE.md, `.claude/CLAUDE.md`, or `CLAUDE.local.md` is on the path to the working directory) | Yes (attached on a text `Read`) | Opt-in `@AGENTS.md` shim in CLAUDE.md |
+| Cursor      | **Yes** (first-class)                                                                                                                                     | Yes (hierarchical)              | N/A — read directly                   |
+| Copilot     | **Yes** (`**/AGENTS.md`)                                                                                                                                  | Yes (nearest wins)              | N/A — read directly                   |
+| Codex       | **Yes** (primary format)                                                                                                                                  | Yes (override pattern)          | N/A — native                          |
 
 ---
 

package/assets/skills/oat-agent-instructions-analyze/references/quality-checklist.md

@@ -27,7 +27,7 @@ Per-file evaluation criteria for agent instruction files. Use this checklist to
 
 ### 4. Size Within Budget
 
-- [ ] Root files (AGENTS.md, CLAUDE.md): <300 lines (hard max 500)
+- [ ] Root files (AGENTS.md, and CLAUDE.md when a shim strategy is configured): <300 lines (hard max 500)
 - [ ] Scoped/package files: 40–150 lines
 - [ ] Individual rules files: <80 lines
 - [ ] Always-on baseline load is estimated and kept comfortably below the task budget
@@ -44,7 +44,7 @@ Per-file evaluation criteria for agent instruction files. Use this checklist to
 
 ### 6. Precedence Clear
 
-- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md)
+- [ ] Override semantics are explicit (nearest-wins for AGENTS.md, import directives for CLAUDE.md when a shim strategy is configured)
 - [ ] No ambiguous or conflicting instructions across scope levels
 - **Severity if failing:** Medium
 

package/assets/skills/oat-agent-instructions-analyze/scripts/resolve-instruction-files.sh

@@ -10,7 +10,7 @@
 #
 # File patterns per provider:
 #   agents_md → **/AGENTS.md
-#   claude    → **/CLAUDE.md, .claude/rules/*.md
+#   claude    → **/CLAUDE.md, **/CLAUDE.local.md, .claude/rules/*.md
 #   cursor    → .cursor/rules/*.mdc, .cursor/rules/*.md
 #   copilot   → .github/copilot-instructions.md, .github/instructions/*.instructions.md
 #   cline     → .cline/rules/*
@@ -58,8 +58,9 @@ discover_agents_md() {
 }
 
 discover_claude() {
-  # CLAUDE.md files
-  find_exclude -name 'CLAUDE.md' | while read -r f; do
+  # CLAUDE.md and personal CLAUDE.local.md files (either one makes Claude
+  # Code's default agents-md mode ignore AGENTS.md)
+  find_exclude -name 'CLAUDE.md' -o -name 'CLAUDE.local.md' | while read -r f; do
     local rel="${f#"$REPO_ROOT"/}"
     printf 'claude\t%s\n' "$rel"
   done

package/assets/skills/oat-agent-instructions-analyze/scripts/resolve-providers.sh

@@ -78,11 +78,21 @@ resolve_from_sync_config() {
 }
 
 resolve_from_auto_detect() {
-  # Scan for provider directories
-  [[ -d "${REPO_ROOT}/.claude" || -f "${REPO_ROOT}/CLAUDE.md" ]] && providers+=("claude")
-  [[ -d "${REPO_ROOT}/.cursor" ]] && providers+=("cursor")
-  [[ -d "${REPO_ROOT}/.github/instructions" || -f "${REPO_ROOT}/.github/copilot-instructions.md" ]] && providers+=("copilot")
-  [[ -d "${REPO_ROOT}/.cline" ]] && providers+=("cline")
+  # Scan for provider directories. Each test is an `if` block so a false test
+  # never becomes the function's exit status under `set -e`.
+  if [[ -d "${REPO_ROOT}/.claude" || -f "${REPO_ROOT}/CLAUDE.md" ]]; then
+    providers+=("claude")
+  fi
+  if [[ -d "${REPO_ROOT}/.cursor" ]]; then
+    providers+=("cursor")
+  fi
+  if [[ -d "${REPO_ROOT}/.github/instructions" || -f "${REPO_ROOT}/.github/copilot-instructions.md" ]]; then
+    providers+=("copilot")
+  fi
+  if [[ -d "${REPO_ROOT}/.cline" ]]; then
+    providers+=("cline")
+  fi
+  return 0
 }
 
 interactive_confirm() {
@@ -103,7 +113,8 @@ interactive_confirm() {
   echo "" >&2
   echo "Available providers: claude, cursor, copilot, cline, codex" >&2
   echo -n "Add any additional providers? (comma-separated, or Enter to skip): " >&2
-  read -r additional
+  # EOF (for example Ctrl-D) means no additional providers, not failure.
+  read -r additional || additional=""
 
   if [[ -n "$additional" ]]; then
     IFS=',' read -ra items <<< "$additional"

package/assets/skills/oat-agent-instructions-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.7.2
+  version: 1.7.3
 ---
 
 # Agent Instructions Apply
@@ -204,7 +204,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 **For provider baseline gaps (always-on provider files):**
 
 - Treat them as first-class recommendations from the artifact, not as implied apply-time behavior
-- Examples include missing Claude `CLAUDE.md` import shims and missing `.github/copilot-instructions.md` shims
+- Examples include missing Claude `CLAUDE.md` import shims (recommended only when `instructions.claude.shims` is a shim strategy: `pointer`, `symlink`, or `copy`) and missing `.github/copilot-instructions.md` shims
 - Carry forward the artifact's evidence refs, confidence, and disclosure mode into the plan
 - If the artifact marks a provider-baseline recommendation `omit`, do not include it in the apply plan
 - If the artifact marks a provider-baseline recommendation `ask_user`, include it with the evidence and require explicit user approval
@@ -240,7 +240,7 @@ recommendation so plan review and generation stay aligned to the same pack file.
 **Multi-format composition order:**
 
 1. **AGENTS.md first** — the canonical, provider-agnostic file
-2. **CLAUDE.md** — if claude provider is active, ensure `@AGENTS.md` import exists
+2. **CLAUDE.md** — only if the claude provider is active and a shim strategy is configured (`oat config get instructions.claude.shims` returns `pointer`, `symlink`, or `copy`), ensure the `@AGENTS.md` import exists. Under `none`, the default, create no `CLAUDE.md`: Claude Code reads AGENTS.md itself, and a CLAUDE.md makes it ignore AGENTS.md for sessions started in that file's directory or below (project-wide for a root file)
 3. **Glob-scoped rules** — author once in canonical format at `.agents/rules/{name}.md` with YAML frontmatter (`description`, `globs`, `activation`)
    - `activation` MUST be one of `always`, `glob`, `agent-requested`, `manual` — any other value (e.g. `auto`) is rejected by `oat sync`. Use `glob` (with `globs`) for file-targeted rules; see `frontmatter/canonical-rule.md` for the full activation matrix.
    - Provider-specific rule files are generated by `oat sync --scope project`

package/assets/skills/oat-agent-instructions-apply/references/docs/rules-files.md

@@ -125,13 +125,16 @@ User-level rules go in `~/.claude/rules/` and apply to all projects (lower prior
 
 ### 2.6 AGENTS.md Support
 
-**AGENTS.md is NOT natively supported by Claude Code** (GitHub issue #6235 has 2,700+ upvotes, still open). The recommended workaround is a one-line `CLAUDE.md`:
+Source: `anthropics/claude-code` `mods/agents-md` README, as of v2.1.278.
 
-```markdown
-@AGENTS.md
-```
+**Claude Code reads AGENTS.md natively** through its built-in `agents-md` plugin. Its `instructionFiles` option defaults to `claude-md-or-agents-md`; the other values are `claude-md`, `claude-md-and-agents-md`, and `managed-only`.
+
+- **Default mode stands down on any CLAUDE.md.** In `claude-md-or-agents-md`, the plugin loads no AGENTS.md for the session when any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` exists in the working directory or any directory above it up to the project root; the engine then loads only CLAUDE.md files. A root `CLAUDE.md` or a personal `CLAUDE.local.md` therefore hides every AGENTS.md, and shims in some directories but not others hide every AGENTS.md without one.
+- **`claude-md-and-agents-md`** loads both; an AGENTS.md that a CLAUDE.md already imports or links is not loaded twice.
+- **Only user or managed settings can set the option** (`~/.claude/settings.json`, `--settings`, or managed settings); a project's `.claude/settings.json` cannot.
+- **Nested gaps:** nested AGENTS.md files attach on a text `Read` only (not on `@`-mentions, IDE selections, or notebook, image, or PDF reads), and `--add-dir` directories contribute no AGENTS.md.
 
-This leverages @-import. Alternative: symlink `ln -s AGENTS.md CLAUDE.md`.
+The one-line `CLAUDE.md` shim (`@AGENTS.md`, or `ln -s AGENTS.md CLAUDE.md`) is now **opt-in**: use it for Claude Code releases before the plugin, for users who set `instructionFiles` to `claude-md`, or when the nested gaps above matter, and then keep a shim beside every AGENTS.md. In OAT this is `instructions.claude.shims` (`none` by default; `pointer`, `symlink`, or `copy` to opt in), applied by `oat instructions sync`; see the OAT docs page `provider-sync/instruction-sync.md` (§ Claude Code and AGENTS.md).
 
 ### 2.7 Skills vs CLAUDE.md vs Rules
 
@@ -411,12 +414,12 @@ All three providers support file-pattern-based activation — this is the unifyi
 
 ### 5.4 AGENTS.md Support
 
-| Provider    | Native support                   | Nested                 | Import mechanism     |
-| ----------- | -------------------------------- | ---------------------- | -------------------- |
-| Claude Code | **No** (use `@AGENTS.md` import) | N/A                    | `@path` in CLAUDE.md |
-| Cursor      | **Yes** (first-class)            | Yes (hierarchical)     | N/A — read directly  |
-| Copilot     | **Yes** (`**/AGENTS.md`)         | Yes (nearest wins)     | N/A — read directly  |
-| Codex       | **Yes** (primary format)         | Yes (override pattern) | N/A — native         |
+| Provider    | Native support                                                                                                                                            | Nested                          | Import mechanism                      |
+| ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------- |
+| Claude Code | **Yes** (built-in `agents-md` plugin; stands down while any CLAUDE.md, `.claude/CLAUDE.md`, or `CLAUDE.local.md` is on the path to the working directory) | Yes (attached on a text `Read`) | Opt-in `@AGENTS.md` shim in CLAUDE.md |
+| Cursor      | **Yes** (first-class)                                                                                                                                     | Yes (hierarchical)              | N/A — read directly                   |
+| Copilot     | **Yes** (`**/AGENTS.md`)                                                                                                                                  | Yes (nearest wins)              | N/A — read directly                   |
+| Codex       | **Yes** (primary format)                                                                                                                                  | Yes (override pattern)          | N/A — native                          |
 
 ---
 

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.9
+  version: 1.2.10
 ---
 
 # Dispatching OAT Subagents