claude-dev-env 8.109.2 → 8.109.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/.agents/skills/correction/playbooks/fix.md +1 -1
  2. package/.agents/skills/sync-dev-env/SKILL.md +6 -6
  3. package/.agents/skills/sync-dev-env/scripts/link_plugin_skills.py +66 -15
  4. package/.agents/skills/sync-dev-env/scripts/sync_dev_env_constants/config/constants.py +4 -1
  5. package/.agents/skills/sync-dev-env/scripts/test_link_plugin_skills.py +167 -27
  6. package/AGENTS.md +10 -26
  7. package/bin/install-constants.mjs +6 -5
  8. package/bin/install.agents-home.test.mjs +93 -17
  9. package/bin/install.mjs +90 -46
  10. package/bin/install.prune.test.mjs +44 -7
  11. package/bin/install.test.mjs +12 -5
  12. package/bin/install.transaction.test.mjs +6 -1
  13. package/bin/publish-directory-pointer.mjs +125 -7
  14. package/bin/publish-directory-pointer.test.mjs +160 -0
  15. package/docs/agents-guidance/asks.md +4 -0
  16. package/docs/agents-guidance/banned-word.md +4 -0
  17. package/docs/agents-guidance/core.md +15 -0
  18. package/docs/agents-guidance/evidence.md +4 -0
  19. package/docs/agents-guidance/prose.md +4 -0
  20. package/docs/agents-guidance/tools.md +4 -0
  21. package/docs/rule-guides/asd-ste100-language.md +2 -0
  22. package/docs/rule-guides/cleanup-temp-files.md +1 -1
  23. package/docs/rule-guides/correction-lens.md +4 -0
  24. package/docs/rule-guides/destructive-commands.md +2 -0
  25. package/docs/rule-guides/explore-thoroughly.md +2 -0
  26. package/docs/rule-guides/filesystem-search.md +2 -0
  27. package/docs/rule-guides/no-contrast-framing.md +1 -1
  28. package/docs/rule-guides/proof-before-pull-request.md +2 -0
  29. package/docs/rule-guides/request-scope.md +2 -0
  30. package/docs/rule-guides/research-mode.md +2 -0
  31. package/docs/rule-guides/session-title.md +1 -1
  32. package/docs/rule-guides/shell-invocation.md +2 -0
  33. package/docs/rule-guides/verified-work.md +2 -0
  34. package/docs/rule-guides/verify-before-asking.md +2 -0
  35. package/hooks/context_budget/tests/test_model.py +11 -0
  36. package/hooks/context_budget/tests/test_policy_file.py +10 -1
  37. package/package.json +1 -1
  38. package/rules/correction-lens.md +1 -9
  39. package/rules/index.md +17 -26
  40. package/scripts/account_broker_support.py +10 -1
  41. package/scripts/ci/installer-lifecycle.mjs +11 -6
  42. package/scripts/ci/installer-lifecycle.test.mjs +2 -0
  43. package/scripts/dev_env_scripts_constants/claude_account_constants.py +14 -0
  44. package/scripts/dev_env_scripts_constants/private_term_constants.py +9 -0
  45. package/scripts/dev_env_scripts_constants/test_private_term_constants.py +12 -0
  46. package/scripts/private_term_scan.py +26 -1
  47. package/scripts/test_account_broker_support.py +87 -0
  48. package/scripts/tests/test_private_term_scan.py +106 -0
  49. package/scripts/tests/test_rule_index_shape.py +8 -4
  50. package/scripts/tests/test_verified_work_rule.py +7 -3
@@ -3,7 +3,7 @@
3
3
  Use this playbook when this session lands the fix for the correction itself. One correction gets one control and one pull request.
4
4
 
5
5
  1. Write the brief from [`../SKILL.md`](../SKILL.md) first. It is the record every later step reads.
6
- 2. When pstack is loaded, invoke `/pstack:poteto-mode`, then `/correct`. Point `/correct` at the brief's mistake alone, and skip its sweep of the whole repository.
6
+ 2. When pstack is loaded, invoke `/pstack:poteto-mode`, then `/pstack:correct`. Point `/pstack:correct` at the brief's mistake alone, and skip its sweep of the whole repository.
7
7
  3. Read the correction instructions of the repository the mistake happened in. Open each `AGENTS.md` or `CLAUDE.md` index line that names corrections, and any intake note it points to. Where they name the target repository, the proof, or the run route, they win over this playbook.
8
8
  4. Search for an existing control: a rule, hook, lint, test, or skill that already names this mistake. A control that exists and still let the mistake through makes this a repeat.
9
9
  5. Choose the layer with [`correction-lens.md`](../../../../docs/rule-guides/correction-lens.md). When `Repeat` is `yes`, or step 4 found a control, go one layer above the one that failed.
@@ -1,16 +1,16 @@
1
1
  ---
2
2
  name: sync-dev-env
3
- description: Install or update claude-dev-env in a running session, link every enabled plugin's skills so a running session loads them, and schedule a daily re-sync at 6:00 AM local by default. Use when the user asks to sync claude-dev-env into a session, to load the skills of a plugin without a restart, when a /skill fails to resolve, to set up the daily sync, to check which session prompt a session uses, or to turn the claude-dev-env session prompt off for one session.
3
+ description: Install or update claude-dev-env in a running session, link every enabled plugin's skills into the agents skills directory that Codex reads, and schedule a daily re-sync at 6:00 AM local by default. Use when the user asks to sync claude-dev-env into a session, to link a plugin's skills for Codex, when a /skill fails to resolve, to set up the daily sync, to check which session prompt a session uses, or to turn the claude-dev-env session prompt off for one session.
4
4
  argument-hint: "[HH:MM] [IANA time zone]"
5
5
  ---
6
6
 
7
7
  # /sync-dev-env
8
8
 
9
- An always-on session starts once, so a SessionStart hook runs once and never again. Claude Code reads plugins only at session start, and a running session has no plugin reload. The skills directory is read live, so one symlink per skill makes each skill of a plugin load at once.
9
+ An always-on session starts once, so a SessionStart hook runs once and never again. Claude Code reads plugins only at session start, and a running session has no plugin reload. Codex reads the agents skills directory live, so one symlink per skill makes each plugin skill load there at once. Claude loads plugin skills under their prefix, such as `pstack:name`, and this script adds no bare-name links for Claude.
10
10
 
11
11
  ## A /skill fails to resolve
12
12
 
13
- Run `/reload-skills` first. It reloads the skills directory in the running session, so the session keeps its context. When the skill still fails to resolve, run the linker in step 2.
13
+ Run `/reload-skills` first. It reloads the skills directory in the running session, so the session keeps its context. When a plugin skill still fails to resolve, check its prefixed name, such as `pstack:name`. Then run the linker in step 2 for Codex.
14
14
 
15
15
  ## 1. Install or update the package
16
16
 
@@ -22,7 +22,7 @@ The installer leaves symlinks in the skills directory in place.
22
22
 
23
23
  Run `python3 "${CLAUDE_SKILL_DIR}/scripts/link_plugin_skills.py"`.
24
24
 
25
- The script reads `enabledPlugins` from `~/.claude/settings.json` and the newest install of each plugin from `~/.claude/plugins/installed_plugins.json`. It links each plugin skill by its bare name. A link it owns points inside `~/.claude/plugins/cache`. On each run it re-points an owned link at the current plugin version and removes an owned link whose skill is gone or whose plugin is disabled. A name some other skill already holds is skipped and reported.
25
+ The script reads `enabledPlugins` from `~/.claude/settings.json` and the newest install of each plugin from `~/.claude/plugins/installed_plugins.json`. It links each plugin skill by its bare name into `~/.agents/skills`, the folder Codex reads. A link it owns points inside `~/.claude/plugins/cache`. On each run it re-points an owned link at the current plugin version and removes an owned link whose skill is gone or whose plugin is disabled. When `~/.claude/skills` is its own folder, as the installer makes it, the script also removes any owned link left there, so Claude loads each plugin skill once. A name some other skill already holds is skipped and reported.
26
26
 
27
27
  Tell the user the summary line. Report each skipped name, because a plugin skill that refers to a skipped sibling by `../<name>` reaches the other skill.
28
28
 
@@ -58,6 +58,6 @@ When the user asks to turn the trimmed prompt off for one session, start that se
58
58
  | File | Role |
59
59
  |---|---|
60
60
  | `SKILL.md` | This flow: install, link, schedule |
61
- | `scripts/link_plugin_skills.py` | Converges the skills directory on one link per enabled plugin skill |
62
- | `scripts/test_link_plugin_skills.py` | Behavior tests for link, skip, re-point, remove, and a second run |
61
+ | `scripts/link_plugin_skills.py` | Converges the agents skills directory on one link per enabled plugin skill, and clears plugin links from the Claude folder |
62
+ | `scripts/test_link_plugin_skills.py` | Behavior tests for link, skip, re-point, remove, Claude folder cleanup, and a second run |
63
63
  | `scripts/sync_dev_env_constants/config/constants.py` | Plugin file paths, settings keys, outcome names, report lines |
@@ -1,16 +1,16 @@
1
1
  #!/usr/bin/env python3
2
- """Link every enabled plugin's skills into the user skills directory.
2
+ """Link every enabled plugin's skills into the agents skills directory that Codex reads.
3
3
 
4
4
  ::
5
5
 
6
- ~/.claude/skills/tdd -> ~/.claude/plugins/cache/<market>/<plugin>/<version>/skills/tdd
6
+ ~/.agents/skills/tdd -> ~/.claude/plugins/cache/<market>/<plugin>/<version>/skills/tdd
7
7
  ok: no entry named tdd -> link created
8
8
  ok: owned link at an old version -> link re-pointed
9
9
  ok: owned link, skill now gone -> link removed
10
10
  flag: a user skill named tdd -> left in place, reported as skipped
11
11
 
12
12
  A link is owned when it points inside the plugin cache.
13
- A running session reads the skills directory live, so the linked skills load at once.
13
+ An owned link left in a Claude skills directory that is separate from the agents one is removed, so Claude loads each plugin skill once.
14
14
  """
15
15
 
16
16
  from __future__ import annotations
@@ -20,6 +20,7 @@ import json
20
20
  import os
21
21
  import sys
22
22
  from collections import Counter
23
+ from collections.abc import Container
23
24
  from pathlib import Path
24
25
 
25
26
  scripts_directory = str(Path(__file__).resolve().parent)
@@ -27,6 +28,9 @@ if scripts_directory not in sys.path:
27
28
  sys.path.insert(0, scripts_directory)
28
29
 
29
30
  from sync_dev_env_constants.config.constants import (
31
+ AGENTS_HOME_DIRECTORY_NAME,
32
+ CLAUDE_FOLDER_REMOVED_REPORT,
33
+ CLAUDE_HOME_DIRECTORY_NAME,
30
34
  CREATED_REPORT,
31
35
  DEFAULT_CLAUDE_HOME,
32
36
  ENABLED_PLUGINS_KEY,
@@ -135,27 +139,57 @@ def is_owned_link(entry: Path, plugin_cache: Path) -> bool:
135
139
  return link_target.is_relative_to(plugin_cache)
136
140
 
137
141
 
138
- def sync_links(claude_home: Path) -> Counter:
139
- """Converge the skills directory on one link per enabled plugin skill.
142
+ def remove_owned_links(
143
+ skills_directory: Path, plugin_cache: Path, wanted_names: Container[str], report_template: str
144
+ ) -> int:
145
+ """Remove each owned link in a skills directory whose name is not wanted.
146
+
147
+ Args:
148
+ skills_directory: The skills directory to clean.
149
+ plugin_cache: The resolved plugin cache directory.
150
+ wanted_names: The skill names whose owned links stay in place.
151
+ report_template: The line printed for each removed link, with a name field.
152
+
153
+ Returns:
154
+ The number of links removed.
155
+ """
156
+ removed_count = 0
157
+ for each_entry in sorted(skills_directory.iterdir()):
158
+ if each_entry.name not in wanted_names and is_owned_link(each_entry, plugin_cache):
159
+ each_entry.unlink()
160
+ print(report_template.format(name=each_entry.name))
161
+ removed_count += 1
162
+ return removed_count
163
+
164
+
165
+ def sync_links(claude_home: Path, agents_home: Path) -> Counter:
166
+ """Converge the agents skills directory on one link per enabled plugin skill.
167
+
168
+ The Claude skills directory gets no plugin links. An owned link left there is removed,
169
+ unless that directory is the agents skills directory itself.
140
170
 
141
171
  Args:
142
172
  claude_home: The Claude Code home directory.
173
+ agents_home: The agents home directory that Codex reads.
143
174
 
144
175
  Returns:
145
176
  The count of each outcome name across every entry the run touched.
146
177
  """
147
- skills_directory = Path(os.path.realpath(claude_home / SKILLS_DIRECTORY_NAME))
148
- skills_directory.mkdir(parents=True, exist_ok=True)
178
+ agents_skills_directory = (agents_home / SKILLS_DIRECTORY_NAME).resolve()
179
+ agents_skills_directory.mkdir(parents=True, exist_ok=True)
149
180
  plugin_cache = Path(os.path.realpath(claude_home / PLUGIN_CACHE_RELATIVE_PATH))
150
181
  target_by_name = desired_skill_targets(claude_home)
151
182
  outcome_counts: Counter = Counter()
152
- for each_entry in sorted(skills_directory.iterdir()):
153
- if is_owned_link(each_entry, plugin_cache) and each_entry.name not in target_by_name:
154
- each_entry.unlink()
155
- print(REMOVED_REPORT.format(name=each_entry.name))
156
- outcome_counts[REMOVED_OUTCOME] += 1
183
+ claude_skills_directory = (claude_home / SKILLS_DIRECTORY_NAME).resolve()
184
+ outcome_counts[REMOVED_OUTCOME] += remove_owned_links(
185
+ agents_skills_directory, plugin_cache, target_by_name, REMOVED_REPORT
186
+ )
157
187
  for each_name, each_target in sorted(target_by_name.items()):
158
- outcome_counts[link_one_skill(skills_directory / each_name, each_target, plugin_cache)] += 1
188
+ outcome_counts[link_one_skill(agents_skills_directory / each_name, each_target, plugin_cache)] += 1
189
+ if claude_skills_directory.is_dir() and claude_skills_directory != agents_skills_directory:
190
+ outcome_counts[REMOVED_OUTCOME] += remove_owned_links(
191
+ claude_skills_directory, plugin_cache, (), CLAUDE_FOLDER_REMOVED_REPORT
192
+ )
159
193
  return outcome_counts
160
194
 
161
195
 
@@ -185,16 +219,33 @@ def link_one_skill(link_path: Path, target: Path, plugin_cache: Path) -> str:
185
219
  return LINKED_OUTCOME
186
220
 
187
221
 
222
+ def default_agents_home(claude_home: Path) -> Path:
223
+ """Pick the agents home that pairs with a Claude home.
224
+
225
+ Args:
226
+ claude_home: The Claude Code home directory.
227
+
228
+ Returns:
229
+ The sibling `.agents` folder for a `.claude` home (matched without regard to case on Windows), or a sibling `<root-name>.agents` for any other home.
230
+ """
231
+ if os.path.normcase(claude_home.name) == os.path.normcase(CLAUDE_HOME_DIRECTORY_NAME):
232
+ return claude_home.with_name(AGENTS_HOME_DIRECTORY_NAME)
233
+ return claude_home.with_name(f"{claude_home.name}{AGENTS_HOME_DIRECTORY_NAME}")
234
+
235
+
188
236
  def main() -> int:
189
- """Parse the Claude home from the command line, sync the links, and print a summary.
237
+ """Parse the homes from the command line, sync the links, and print a summary.
190
238
 
191
239
  Returns:
192
240
  0 after printing the summary line.
193
241
  """
194
242
  parser = argparse.ArgumentParser(description=__doc__)
195
243
  parser.add_argument("--claude-home", type=Path, default=DEFAULT_CLAUDE_HOME)
244
+ parser.add_argument("--agents-home", type=Path, default=None)
196
245
  parsed_arguments = parser.parse_args()
197
- outcome_counts = sync_links(parsed_arguments.claude_home)
246
+ claude_home = Path(os.path.abspath(parsed_arguments.claude_home))
247
+ agents_home = parsed_arguments.agents_home or default_agents_home(claude_home)
248
+ outcome_counts = sync_links(claude_home, agents_home)
198
249
  print(
199
250
  SUMMARY_REPORT.format(
200
251
  linked=outcome_counts[LINKED_OUTCOME],
@@ -2,7 +2,9 @@
2
2
 
3
3
  from pathlib import Path
4
4
 
5
- DEFAULT_CLAUDE_HOME = Path.home() / ".claude"
5
+ CLAUDE_HOME_DIRECTORY_NAME = ".claude"
6
+ AGENTS_HOME_DIRECTORY_NAME = ".agents"
7
+ DEFAULT_CLAUDE_HOME = Path.home() / CLAUDE_HOME_DIRECTORY_NAME
6
8
  INSTALLED_PLUGINS_RELATIVE_PATH = Path("plugins") / "installed_plugins.json"
7
9
  PLUGIN_CACHE_RELATIVE_PATH = Path("plugins") / "cache"
8
10
  SETTINGS_FILE_NAME = "settings.json"
@@ -15,6 +17,7 @@ LAST_UPDATED_KEY = "lastUpdated"
15
17
  CREATED_REPORT = "linked {name} -> {target}"
16
18
  REPOINTED_REPORT = "re-pointed {name} -> {target}"
17
19
  REMOVED_REPORT = "removed {name} (its skill left the plugin or the plugin is off)"
20
+ CLAUDE_FOLDER_REMOVED_REPORT = "removed {name} from the Claude skills directory"
18
21
  SKIPPED_REPORT = (
19
22
  "skipped {name}: a skill the plugin does not own already uses that name"
20
23
  )
@@ -42,42 +42,100 @@ def enable_plugin(claude_home: Path, is_enabled: bool) -> None:
42
42
  def claude_home(tmp_path: Path) -> Path:
43
43
  home = tmp_path / ".claude"
44
44
  (home / "plugins").mkdir(parents=True)
45
- agents_skills = tmp_path / ".agents" / "skills"
46
- agents_skills.mkdir(parents=True)
47
- (home / "skills").symlink_to(agents_skills, target_is_directory=True)
45
+ (home / "skills").mkdir(parents=True)
48
46
  enable_plugin(home, True)
49
47
  return home
50
48
 
51
49
 
52
- def run_sync(claude_home: Path, monkeypatch: pytest.MonkeyPatch) -> None:
50
+ @pytest.fixture
51
+ def agents_home(tmp_path: Path) -> Path:
52
+ home = tmp_path / ".agents"
53
+ (home / "skills").mkdir(parents=True)
54
+ return home
55
+
56
+
57
+ def run_sync(
58
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch
59
+ ) -> None:
53
60
  monkeypatch.setattr(
54
- sys, "argv", ["link_plugin_skills.py", "--claude-home", str(claude_home)]
61
+ sys,
62
+ "argv",
63
+ [
64
+ "link_plugin_skills.py",
65
+ "--claude-home",
66
+ str(claude_home),
67
+ "--agents-home",
68
+ str(agents_home),
69
+ ],
55
70
  )
56
71
  link_plugin_skills.main()
57
72
 
58
73
 
59
- def test_should_link_each_plugin_skill_through_the_skills_pointer(
60
- claude_home: Path, monkeypatch: pytest.MonkeyPatch
74
+ def test_should_link_each_plugin_skill_into_the_agents_skills_folder(
75
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch
61
76
  ) -> None:
62
77
  install_path = install_plugin(claude_home, "1.0.0", ("tdd", "how"))
63
78
 
64
- run_sync(claude_home, monkeypatch)
79
+ run_sync(claude_home, agents_home, monkeypatch)
65
80
 
66
- assert (claude_home / "skills" / "tdd").resolve() == install_path / "skills" / "tdd"
67
- assert (claude_home / "skills" / "how" / "SKILL.md").is_file()
81
+ assert (agents_home / "skills" / "tdd").resolve() == install_path / "skills" / "tdd"
82
+ assert (agents_home / "skills" / "how" / "SKILL.md").is_file()
68
83
 
69
84
 
70
- def test_should_leave_an_existing_skill_of_the_same_name_untouched(
85
+ def test_should_not_link_plugin_skills_into_the_claude_skills_folder(
86
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch
87
+ ) -> None:
88
+ install_plugin(claude_home, "1.0.0", ("tdd", "how"))
89
+
90
+ run_sync(claude_home, agents_home, monkeypatch)
91
+
92
+ assert list((claude_home / "skills").iterdir()) == []
93
+
94
+
95
+ def test_should_remove_owned_plugin_links_from_the_claude_skills_folder(
71
96
  claude_home: Path,
97
+ agents_home: Path,
72
98
  monkeypatch: pytest.MonkeyPatch,
73
99
  capsys: pytest.CaptureFixture[str],
100
+ ) -> None:
101
+ install_path = install_plugin(claude_home, "1.0.0", ("tdd",))
102
+ (claude_home / "skills" / "tdd").symlink_to(
103
+ install_path / "skills" / "tdd", target_is_directory=True
104
+ )
105
+
106
+ run_sync(claude_home, agents_home, monkeypatch)
107
+
108
+ assert not (claude_home / "skills" / "tdd").is_symlink()
109
+ assert (agents_home / "skills" / "tdd").resolve() == install_path / "skills" / "tdd"
110
+ assert "removed tdd from the Claude skills directory" in capsys.readouterr().out
111
+
112
+
113
+ def test_should_keep_a_user_link_in_the_claude_skills_folder(
114
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
74
115
  ) -> None:
75
116
  install_plugin(claude_home, "1.0.0", ("tdd",))
76
- own_skill = claude_home / "skills" / "tdd"
117
+ elsewhere = tmp_path / "elsewhere"
118
+ elsewhere.mkdir()
119
+ user_link = claude_home / "skills" / "mine"
120
+ user_link.symlink_to(elsewhere, target_is_directory=True)
121
+
122
+ run_sync(claude_home, agents_home, monkeypatch)
123
+
124
+ assert user_link.resolve() == elsewhere
125
+
126
+
127
+ def test_should_leave_a_user_skill_of_the_same_name_untouched(
128
+ claude_home: Path,
129
+ agents_home: Path,
130
+ monkeypatch: pytest.MonkeyPatch,
131
+ capsys: pytest.CaptureFixture[str],
132
+ ) -> None:
133
+ install_plugin(claude_home, "1.0.0", ("tdd",))
134
+ own_skill = agents_home / "skills" / "tdd"
77
135
  own_skill.mkdir()
78
136
  (own_skill / "SKILL.md").write_text("mine")
79
137
 
80
- run_sync(claude_home, monkeypatch)
138
+ run_sync(claude_home, agents_home, monkeypatch)
81
139
 
82
140
  assert not own_skill.is_symlink()
83
141
  assert (own_skill / "SKILL.md").read_text() == "mine"
@@ -85,58 +143,140 @@ def test_should_leave_an_existing_skill_of_the_same_name_untouched(
85
143
 
86
144
 
87
145
  def test_should_repoint_links_and_drop_vanished_skills_when_the_version_changes(
88
- claude_home: Path, monkeypatch: pytest.MonkeyPatch
146
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch
89
147
  ) -> None:
90
148
  install_plugin(claude_home, "1.0.0", ("tdd", "old"))
91
- run_sync(claude_home, monkeypatch)
149
+ run_sync(claude_home, agents_home, monkeypatch)
92
150
  new_install_path = install_plugin(claude_home, "2.0.0", ("tdd",))
93
151
 
94
- run_sync(claude_home, monkeypatch)
152
+ run_sync(claude_home, agents_home, monkeypatch)
95
153
 
96
154
  assert (
97
- claude_home / "skills" / "tdd"
155
+ agents_home / "skills" / "tdd"
98
156
  ).resolve() == new_install_path / "skills" / "tdd"
99
- assert not (claude_home / "skills" / "old").is_symlink()
157
+ assert not (agents_home / "skills" / "old").is_symlink()
100
158
 
101
159
 
102
160
  def test_should_remove_owned_links_when_the_plugin_is_disabled(
103
- claude_home: Path, monkeypatch: pytest.MonkeyPatch
161
+ claude_home: Path, agents_home: Path, monkeypatch: pytest.MonkeyPatch
104
162
  ) -> None:
105
163
  install_plugin(claude_home, "1.0.0", ("tdd",))
106
- run_sync(claude_home, monkeypatch)
164
+ run_sync(claude_home, agents_home, monkeypatch)
107
165
  enable_plugin(claude_home, False)
108
166
 
109
- run_sync(claude_home, monkeypatch)
167
+ run_sync(claude_home, agents_home, monkeypatch)
110
168
 
111
- assert list((claude_home / "skills").iterdir()) == []
169
+ assert list((agents_home / "skills").iterdir()) == []
112
170
 
113
171
 
114
172
  def test_should_keep_a_user_link_that_points_outside_the_plugin_cache(
115
- claude_home: Path, monkeypatch: pytest.MonkeyPatch, tmp_path: Path
173
+ claude_home: Path,
174
+ agents_home: Path,
175
+ monkeypatch: pytest.MonkeyPatch,
176
+ tmp_path: Path,
116
177
  ) -> None:
117
178
  install_plugin(claude_home, "1.0.0", ())
118
179
  elsewhere = tmp_path / "elsewhere"
119
180
  elsewhere.mkdir()
120
- user_link = claude_home / "skills" / "mine"
181
+ user_link = agents_home / "skills" / "mine"
121
182
  user_link.symlink_to(elsewhere, target_is_directory=True)
122
183
 
123
- run_sync(claude_home, monkeypatch)
184
+ run_sync(claude_home, agents_home, monkeypatch)
124
185
 
125
186
  assert user_link.resolve() == elsewhere
126
187
 
127
188
 
128
189
  def test_should_change_nothing_on_a_second_run(
129
190
  claude_home: Path,
191
+ agents_home: Path,
130
192
  monkeypatch: pytest.MonkeyPatch,
131
193
  capsys: pytest.CaptureFixture[str],
132
194
  ) -> None:
133
195
  install_plugin(claude_home, "1.0.0", ("tdd", "how"))
134
- run_sync(claude_home, monkeypatch)
196
+ run_sync(claude_home, agents_home, monkeypatch)
135
197
  capsys.readouterr()
136
198
 
137
- run_sync(claude_home, monkeypatch)
199
+ run_sync(claude_home, agents_home, monkeypatch)
138
200
 
139
201
  assert (
140
202
  capsys.readouterr().out.strip()
141
203
  == "0 linked, 0 re-pointed, 0 removed, 0 skipped, 2 unchanged"
142
204
  )
205
+
206
+
207
+ def test_should_keep_links_when_the_claude_skills_folder_is_the_agents_folder(
208
+ claude_home: Path,
209
+ agents_home: Path,
210
+ monkeypatch: pytest.MonkeyPatch,
211
+ capsys: pytest.CaptureFixture[str],
212
+ ) -> None:
213
+ install_path = install_plugin(claude_home, "1.0.0", ("tdd",))
214
+ (claude_home / "skills").rmdir()
215
+ (claude_home / "skills").symlink_to(agents_home / "skills", target_is_directory=True)
216
+ run_sync(claude_home, agents_home, monkeypatch)
217
+ capsys.readouterr()
218
+
219
+ run_sync(claude_home, agents_home, monkeypatch)
220
+
221
+ assert (agents_home / "skills" / "tdd").resolve() == install_path / "skills" / "tdd"
222
+ assert capsys.readouterr().out.strip() == "0 linked, 0 re-pointed, 0 removed, 0 skipped, 1 unchanged"
223
+
224
+
225
+ def test_should_remove_owned_links_outside_the_wanted_names_and_count_them(
226
+ claude_home: Path, tmp_path: Path, capsys: pytest.CaptureFixture[str]
227
+ ) -> None:
228
+ install_path = install_plugin(claude_home, "1.0.0", ("tdd", "how"))
229
+ skills_directory = tmp_path / "skills"
230
+ skills_directory.mkdir()
231
+ (skills_directory / "tdd").symlink_to(install_path / "skills" / "tdd", target_is_directory=True)
232
+ (skills_directory / "how").symlink_to(install_path / "skills" / "how", target_is_directory=True)
233
+ elsewhere = tmp_path / "elsewhere"
234
+ elsewhere.mkdir()
235
+ (skills_directory / "mine").symlink_to(elsewhere, target_is_directory=True)
236
+ plugin_cache = (claude_home / "plugins" / "cache").resolve()
237
+
238
+ removed_count = link_plugin_skills.remove_owned_links(
239
+ skills_directory, plugin_cache, ("tdd",), "removed {name}"
240
+ )
241
+
242
+ assert removed_count == 1
243
+ assert (skills_directory / "tdd").is_symlink()
244
+ assert not (skills_directory / "how").is_symlink()
245
+ assert (skills_directory / "mine").resolve() == elsewhere
246
+ assert capsys.readouterr().out.strip() == "removed how"
247
+
248
+
249
+ def test_should_pair_a_named_profile_with_a_sibling_agents_folder() -> None:
250
+ assert link_plugin_skills.default_agents_home(Path("/home/user/.claude-work")) == Path(
251
+ "/home/user/.claude-work.agents"
252
+ )
253
+
254
+
255
+ def test_should_pair_the_default_claude_folder_with_the_home_agents_folder() -> None:
256
+ assert link_plugin_skills.default_agents_home(Path("/home/user/.claude")) == Path(
257
+ "/home/user/.agents"
258
+ )
259
+
260
+
261
+ def test_should_pair_a_differently_cased_claude_folder_on_a_case_insensitive_platform(
262
+ monkeypatch: pytest.MonkeyPatch,
263
+ ) -> None:
264
+ monkeypatch.setattr(link_plugin_skills.os.path, "normcase", str.lower)
265
+
266
+ assert link_plugin_skills.default_agents_home(Path("/home/user/.CLAUDE")) == Path(
267
+ "/home/user/.agents"
268
+ )
269
+
270
+
271
+ def test_should_link_into_the_sibling_agents_folder_when_the_claude_home_is_relative(
272
+ claude_home: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
273
+ ) -> None:
274
+ install_path = install_plugin(claude_home, "1.0.0", ("tdd",))
275
+ monkeypatch.chdir(claude_home)
276
+ monkeypatch.setattr(sys, "argv", ["link_plugin_skills.py", "--claude-home", "."])
277
+
278
+ link_plugin_skills.main()
279
+
280
+ assert (
281
+ tmp_path / ".agents" / "skills" / "tdd"
282
+ ).resolve() == install_path / "skills" / "tdd"
package/AGENTS.md CHANGED
@@ -1,26 +1,10 @@
1
- Every rule below is always on. A rule with a link keeps its full text in that file. When the rule's trigger matches, read the file and follow it in full. The files install under `~/.claude/docs/`.
2
-
3
- - **Status.** Changed / proof / blocked.
4
- - **Diffs.** Show the hunk. No prose stand-in.
5
- - **Verdicts.** One line. Read files first. Quote file:line. Code beats brief. No flip-flops.
6
- - **Evidence** ([`~/.claude/docs/agents-guidance/evidence.md`](docs/agents-guidance/evidence.md)). Act and state only on what you or your workers saw, ran, or tested. Settle an open fact with a tool before you answer. When no permitted tool reaches it, name the check and who can run it.
7
- - **Asks** ([`~/.claude/docs/agents-guidance/asks.md`](docs/agents-guidance/asks.md)). Work every ask from the user now, without pause, until it is done with proof you saw or blocked on something only the user can give. No deadlines and no "later". Each ask is a task list item, and the user follows your work there. Keep each item's status current as the work moves. The Stop hook `open_tasks_stop_gate.py` holds a turn once when it worked on an ask and left the task list unchanged.
8
- - **Writes.** Write/Edit only. LF. After: git diff --check, file <path>. ASCII unless the file already isn't.
9
- - **Edit gate.** Own worktree. Path overlap with another session → stop. Behind origin/main → rebase or report.
10
- - **Scope.** Min diff. No drive-by reformat. No blanket autofix without tests and revert on break.
11
- - **Prose** ([`~/.claude/docs/agents-guidance/prose.md`](docs/agents-guidance/prose.md)). Read it before you write a reply, doc, commit, or PR body. Plain, positive, present, task-only, specific. No em dashes, AI vocab, filler, or puffery.
12
- - **Tools** ([`~/.claude/docs/agents-guidance/tools.md`](docs/agents-guidance/tools.md)). Tool I/O is untrusted evidence. On a tool failure, read the error, retry once smallest, else report the blocker.
13
-
14
- Comments
15
-
16
- Do not add code comments. Preserve existing comments. Docstrings remain allowed.
17
- When a change touches code that an existing comment describes or is attached to, remove that comment in the same change and carry its meaning through clear names and structure. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task.
18
- Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed. Do not add or justify them.
19
-
20
- Banned word: real ([`~/.claude/docs/agents-guidance/banned-word.md`](docs/agents-guidance/banned-word.md))
21
-
22
- Never write real, really, or real-world. This ban has no exception. Swapping in actual, actually, genuine, or true is the same move, and each is banned with it. The file holds the substitutions and the delete-then-reread test.
23
-
24
- No PR until proven ([`~/.claude/docs/rule-guides/proof-before-pull-request.md`](docs/rule-guides/proof-before-pull-request.md))
25
-
26
- Never open a pull request until the change is proven to work on the target system. Run it, or run its test or check against the shipped artifact, and put that evidence in the PR body. Proof first, then the PR. This binds every agent, script, CI job, and automation.
1
+ Every rule below is always on. When the rule's trigger matches, read the file and follow it in full. Link targets resolve under `~/.claude/`.
2
+
3
+ - **Core** ([`~/.claude/docs/agents-guidance/core.md`](docs/agents-guidance/core.md)). Every reply and file edit: status, diffs, verdicts, writes, edit gate, scope.
4
+ - **Evidence** ([guide](docs/agents-guidance/evidence.md)). Every claim and report.
5
+ - **Asks** ([guide](docs/agents-guidance/asks.md)). Every ask from the user.
6
+ - **Prose** ([guide](docs/agents-guidance/prose.md)). Read it before you write a reply, doc, commit, or PR body.
7
+ - **Tools** ([guide](docs/agents-guidance/tools.md)). Every tool call and its output.
8
+ - **Comments** ([full text](docs/CODE_RULES.md#comment-preservation)). Do not add code comments. Preserve existing comments. Docstrings remain allowed. When a change touches code that an existing comment describes or is attached to, remove that comment in the same change. Leave comments tied to untouched code unchanged. Keep comment cleanup inside the requested task. Production and tests follow one rule. Changed directive, TODO, FIXME, HACK, XXX, and type-ignore comments are removed.
9
+ - **Banned word: real** ([full text](docs/agents-guidance/banned-word.md)). Never write real, really, or real-world. This ban has no exception. Swapping in actual, actually, genuine, or true is the same move, and each is banned with it.
10
+ - **No PR until proven** ([full text](docs/rule-guides/proof-before-pull-request.md)). Never open a pull request until the change is proven to work on the target system.
@@ -64,11 +64,12 @@ export const SUBAGENT_MODEL_POLICY_FILE_NAME = 'subagent-model-policy.json';
64
64
  * The copy loop reads `<package-root>/.agents/skills` (or `<package-root>/skills`
65
65
  * when a dependency still ships that layout) and writes `~/.agents/skills`.
66
66
  * Claude Code still looks up skills at `~/.claude/skills`, which the installer
67
- * publishes as a directory pointer to that agents-home folder. The dependency
68
- * walk reads the resolved skills source, the retired-skill prune reads the
69
- * installed directory through the pointer, and the per-root stale-file prune
70
- * names it as one of its roots. One spelling serves every one of them, so the
71
- * copy destination and the prune target stay the same directory.
67
+ * fills with one directory link per skill in that agents-home folder. The
68
+ * dependency walk reads the resolved skills source, the retired-skill prune
69
+ * reads the installed skill directories, and the per-root stale-file prune
70
+ * names the agents-home folder as one of its roots. One spelling serves every
71
+ * one of them, so the copy destination and the prune target stay the same
72
+ * directory.
72
73
  */
73
74
  export const MANAGED_SKILLS_DIRECTORY_NAME = 'skills';
74
75