From d62043d76d22a5d662281c32789dc9c1c43597fa Mon Sep 17 00:00:00 2001
From: satyaborg <satya.borg@gmail.com>
Date: Mon, 17 Aug 2026 21:06:55 +1000
Subject: [PATCH 1/2] feat: detect legacy Codex skill shadows

---
 README.md                |  2 ++
 scripts/devloop_test.sh  | 10 ++++++++++
 scripts/skill_helpers.sh | 13 +++++++++++++
 3 files changed, 25 insertions(+)

diff --git a/README.md b/README.md
index 9df080c..4af2e1e 100644
--- a/README.md
+++ b/README.md
@@ -66,6 +66,8 @@ Devloop ships two agent skills, installed into `~/.claude/skills` and `~/.agents
 - [`devloop-spec`](skills/devloop-spec/SKILL.md) — interviews when scope is unclear, then writes one concrete, devloop-ready spec with optional HTML rendering.
 - [`devloop-review`](skills/devloop-review/SKILL.md) — judges each pass against the spec and engineering quality gates, returning ACCEPT, REJECT, or UNCLEAR with fix instructions.
 
+Codex reads its user skills from `~/.agents/skills`. `devloop doctor` warns when obsolete `~/.codex/skills/devloop-*` shadows remain.
+
 ## Runtime
 
 - Uses an isolated sibling git worktree by default; pass `--in-place` to stay in the current worktree.
diff --git a/scripts/devloop_test.sh b/scripts/devloop_test.sh
index cfcea6c..d41890a 100755
--- a/scripts/devloop_test.sh
+++ b/scripts/devloop_test.sh
@@ -3156,6 +3156,16 @@ contains "$doctor_output" "$install_home/.agents/skills/devloop-spec" "doctor Co
 contains "$doctor_output" "$install_home/.claude/skills/devloop-spec" "doctor Claude skill"
 ok "doctor"
 
+mkdir -p "$install_home/.codex/skills/devloop-spec"
+ln -s "$install_home/.agents/skills/devloop-review" "$install_home/.codex/skills/devloop-review"
+doctor_legacy_codex_output="$(HOME="$install_home" PATH="$bin_dir:$tool_bin:$fake_bin:$PATH" "$bin_dir/devloop" doctor 2>&1)" || fail "doctor rejected legacy Codex skill shadows"
+contains "$doctor_legacy_codex_output" "[warn] legacy Codex skill shadow: $install_home/.codex/skills/devloop-spec" "doctor legacy Codex directory"
+contains "$doctor_legacy_codex_output" "[warn] legacy Codex skill shadow: $install_home/.codex/skills/devloop-review" "doctor legacy Codex symlink"
+contains "$doctor_legacy_codex_output" "canonical skill: $install_home/.agents/skills/devloop-spec" "doctor canonical Codex skill"
+contains "$doctor_legacy_codex_output" "devloop doctor: ready" "doctor legacy Codex shadows remain non-blocking"
+rm -rf "$install_home/.codex"
+ok "doctor detects legacy Codex skill shadows"
+
 no_gh_bin="$work/no-gh-bin"
 mkdir -p "$no_gh_bin"
 for tool in codex claude glow gum fzf tmux; do
diff --git a/scripts/skill_helpers.sh b/scripts/skill_helpers.sh
index da3627e..f34f737 100644
--- a/scripts/skill_helpers.sh
+++ b/scripts/skill_helpers.sh
@@ -214,6 +214,18 @@ EOF
   return "$status"
 }
 
+devloop_doctor_legacy_codex_skills() {
+  local skills_dir="$HOME/.codex/skills"
+  local name dest canonical
+
+  for name in devloop-spec devloop-review; do
+    dest="$skills_dir/$name"
+    if [ ! -e "$dest" ] && [ ! -L "$dest" ]; then continue; fi
+    canonical="$HOME/.agents/skills/$name"
+    printf '[warn] legacy Codex skill shadow: %s (remove it; canonical skill: %s)\n' "$dest" "$canonical"
+  done
+}
+
 devloop_doctor_skills_in_dir() {
   local root="$1"
   local skills_dir="$2"
@@ -356,6 +368,7 @@ devloop_doctor() {
   devloop_doctor_command tmux || status=1
   printf '\nSkills\n'
   devloop_doctor_skills "$root" || status=1
+  devloop_doctor_legacy_codex_skills
   devloop_doctor_github
 
   if [ "$status" -eq 0 ]; then

From 35f77af31045662e5a3740e5d9cc339c0afafebb Mon Sep 17 00:00:00 2001
From: satyaborg <satya.borg@gmail.com>
Date: Mon, 17 Aug 2026 21:08:50 +1000
Subject: [PATCH 2/2] chore: remove legacy skill note

---
 README.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/README.md b/README.md
index 4af2e1e..9df080c 100644
--- a/README.md
+++ b/README.md
@@ -66,8 +66,6 @@ Devloop ships two agent skills, installed into `~/.claude/skills` and `~/.agents
 - [`devloop-spec`](skills/devloop-spec/SKILL.md) — interviews when scope is unclear, then writes one concrete, devloop-ready spec with optional HTML rendering.
 - [`devloop-review`](skills/devloop-review/SKILL.md) — judges each pass against the spec and engineering quality gates, returning ACCEPT, REJECT, or UNCLEAR with fix instructions.
 
-Codex reads its user skills from `~/.agents/skills`. `devloop doctor` warns when obsolete `~/.codex/skills/devloop-*` shadows remain.
-
 ## Runtime
 
 - Uses an isolated sibling git worktree by default; pass `--in-place` to stay in the current worktree.