diff --git a/.deepreview b/.deepreview
index 1b599602..5ae763a6 100644
--- a/.deepreview
+++ b/.deepreview
@@ -470,6 +470,30 @@ job_schema_instruction_compatibility:
- FAIL: Incompatibilities found. List each with the file path, line
reference, the incompatible content, and what the schema actually says.
+agents_md_claude_md_symlink:
+ description: "Ensure every AGENTS.md file has a sibling CLAUDE.md symlink pointing to it, because Claude Code reads CLAUDE.md but ignores AGENTS.md."
+ match:
+ include:
+ - "**/AGENTS.md"
+ review:
+ strategy: individual
+ instructions: |
+ Claude Code reads CLAUDE.md for project context but does not read AGENTS.md.
+ Every AGENTS.md file MUST have a sibling CLAUDE.md that is a symlink pointing
+ to AGENTS.md, so that Claude Code picks up the same content.
+
+ Check whether a CLAUDE.md symlink exists in the same directory as the matched
+ AGENTS.md file. If it is missing or is not a symlink to AGENTS.md, create it:
+
+ ln -sf AGENTS.md
/CLAUDE.md
+
+ The symlink target MUST be the relative path "AGENTS.md" (not an absolute path),
+ so the link remains valid after the directory is moved or cloned.
+
+ Output Format:
+ - PASS: CLAUDE.md symlink exists and points to AGENTS.md.
+ - FAIL: Symlink missing or incorrect — describe the current state and the fix applied.
+
nix_claude_wrapper:
description: "Ensure flake.nix always wraps the claude command with the required plugin dirs."
match:
diff --git a/.deepwork/jobs/test_job_flow/CLAUDE.md b/.deepwork/jobs/test_job_flow/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/.deepwork/jobs/test_job_flow/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/.deepwork/jobs/update_job_schema/CLAUDE.md b/.deepwork/jobs/update_job_schema/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/.deepwork/jobs/update_job_schema/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/doc/debugging_history/CLAUDE.md b/doc/debugging_history/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/doc/debugging_history/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md b/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md
new file mode 120000
index 00000000..47dc3e3d
--- /dev/null
+++ b/src/deepwork/standard_jobs/deepwork_jobs/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
index 2ffa836a..45aec33f 100755
--- a/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
+++ b/src/deepwork/standard_jobs/deepwork_jobs/make_new_job.sh
@@ -128,6 +128,10 @@ This folder and its subfolders are managed using `deepwork_jobs` workflows.
2. **Direct edits** are fine for minor instruction tweaks
EOF
+ # Create CLAUDE.md symlink pointing to AGENTS.md so Claude Code picks up the context
+ # (Claude Code reads CLAUDE.md but ignores AGENTS.md)
+ ln -s AGENTS.md "$job_path/CLAUDE.md"
+
# Copy .deepreview template if available
if [[ -f "$script_dir/template.deepreview" ]]; then
cp "$script_dir/template.deepreview" "$job_path/.deepreview"
@@ -139,6 +143,7 @@ EOF
echo " ├── .deepreview"
fi
echo " ├── AGENTS.md"
+ echo " ├── CLAUDE.md -> AGENTS.md"
echo " ├── steps/"
echo " ├── hooks/.gitkeep"
echo " ├── scripts/.gitkeep"