claude-dev-env 2.15.1 → 2.17.0

package/scripts/active_capability_references.py

@@ -28,6 +28,8 @@ from dev_env_scripts_constants.active_capability_constants import (
     NEWLINE_JOIN_SEPARATOR,
     PACKAGE_AGENTS_DIRECTORY,
     PACKAGE_COMMANDS_DIRECTORY,
+    PACKAGE_ROOT_AGENTS_DIRECTORY,
+    PACKAGE_ROOT_SKILLS_DIRECTORY,
     PACKAGE_SKILLS_DIRECTORY,
     SKILL_MANIFEST_FILENAME,
     SLASH_CAPABILITY_PATTERN,
@@ -58,6 +60,18 @@ class UnresolvedCapabilityReference:
     reason: str
 
 
+def _resolve_package_tree(
+    from_package_root: Path,
+    canonical_relative: str,
+    package_root_name: str,
+) -> Path:
+    """Return the canonical tree when it exists, else the package-root name."""
+    canonical_directory = from_package_root / canonical_relative
+    if canonical_directory.is_dir():
+        return canonical_directory
+    return from_package_root / package_root_name
+
+
 def build_capability_inventory(from_package_root: Path) -> CapabilityInventory:
     """Build inventories from committed skill/agent/command files.
 
@@ -67,8 +81,16 @@ def build_capability_inventory(from_package_root: Path) -> CapabilityInventory:
     Returns:
         Inventory of basenames present on disk.
     """
-    skills_root = from_package_root / PACKAGE_SKILLS_DIRECTORY
-    agents_root = from_package_root / PACKAGE_AGENTS_DIRECTORY
+    skills_root = _resolve_package_tree(
+        from_package_root,
+        PACKAGE_SKILLS_DIRECTORY,
+        PACKAGE_ROOT_SKILLS_DIRECTORY,
+    )
+    agents_root = _resolve_package_tree(
+        from_package_root,
+        PACKAGE_AGENTS_DIRECTORY,
+        PACKAGE_ROOT_AGENTS_DIRECTORY,
+    )
     commands_root = from_package_root / PACKAGE_COMMANDS_DIRECTORY
     all_skills: set[str] = set()
     if skills_root.is_dir():
@@ -203,12 +225,20 @@ def unresolved_active_capabilities(
 
 def _default_markdown_paths(from_package_root: Path) -> list[str]:
     all_paths: list[str] = []
-    for each_directory_name in (
-        PACKAGE_SKILLS_DIRECTORY,
-        PACKAGE_AGENTS_DIRECTORY,
-        PACKAGE_COMMANDS_DIRECTORY,
-    ):
-        directory_path = from_package_root / each_directory_name
+    directory_paths = [
+        _resolve_package_tree(
+            from_package_root,
+            PACKAGE_SKILLS_DIRECTORY,
+            PACKAGE_ROOT_SKILLS_DIRECTORY,
+        ),
+        _resolve_package_tree(
+            from_package_root,
+            PACKAGE_AGENTS_DIRECTORY,
+            PACKAGE_ROOT_AGENTS_DIRECTORY,
+        ),
+        from_package_root / PACKAGE_COMMANDS_DIRECTORY,
+    ]
+    for directory_path in directory_paths:
         if not directory_path.is_dir():
             continue
         for each_markdown_file in directory_path.rglob("*.md"):

package/scripts/claude_chain_usage.py

@@ -41,6 +41,7 @@ from dev_env_scripts_constants.claude_chain_usage_constants import (
     RESOLVE_USAGE_WINDOW_FILENAME,
     RESOLVE_USAGE_WINDOW_MISSING_ERROR_TEMPLATE,
     RESOLVE_USAGE_WINDOW_MODULE_NAME,
+    USAGE_PAUSE_AGENTS_HOME_DIRECTORY_NAME,
     USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME,
     USAGE_PAUSE_SKILL_DIRECTORY_NAME,
     USAGE_PAUSE_SKILL_NAME,
@@ -83,6 +84,7 @@ def _usage_pause_scripts_directory() -> Path:
     package_root = Path(__file__).resolve().parent.parent
     return (
         package_root
+        / USAGE_PAUSE_AGENTS_HOME_DIRECTORY_NAME
         / USAGE_PAUSE_SKILL_DIRECTORY_NAME
         / USAGE_PAUSE_SKILL_NAME
         / USAGE_PAUSE_SCRIPTS_DIRECTORY_NAME

package/scripts/codex_compat_watcher.py

@@ -30,7 +30,7 @@ class _WatcherConfiguration:
     copy_link_kind = "copy"
     symlink_link_kind = "symlink"
     junction_link_kind = "junction"
-    all_configured_root_names = ("agents", "commands", "hooks", "rules", "skills")
+    all_configured_root_names = (".agents", "commands", "hooks", "rules")
     all_unsafe_event_kinds = {"overflow", "ambiguous", "inaccessible", "error", "unknown"}
     reparse_point_attribute = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
 

package/scripts/dev_env_scripts_constants/active_capability_constants.py

@@ -6,9 +6,12 @@ timing.py and the other per-script constant modules.
 
 from __future__ import annotations
 
-PACKAGE_SKILLS_DIRECTORY: str = "skills"
-PACKAGE_AGENTS_DIRECTORY: str = "agents"
+PACKAGE_AGENTS_HOME_DIRECTORY: str = ".agents"
+PACKAGE_SKILLS_DIRECTORY: str = ".agents/skills"
+PACKAGE_AGENTS_DIRECTORY: str = ".agents/agents"
 PACKAGE_COMMANDS_DIRECTORY: str = "commands"
+PACKAGE_ROOT_SKILLS_DIRECTORY: str = "skills"
+PACKAGE_ROOT_AGENTS_DIRECTORY: str = "agents"
 SKILL_MANIFEST_FILENAME: str = "SKILL.md"
 
 # Slash-command and skill names that must never appear as active instructions.

package/scripts/dev_env_scripts_constants/claude_chain_usage_constants.py

@@ -9,8 +9,11 @@ from __future__ import annotations
 FULL_WEEKLY_PERCENT: float = 100.0
 """Percent scale ceiling for weekly utilization (remaining = this minus used)."""
 
+USAGE_PAUSE_AGENTS_HOME_DIRECTORY_NAME: str = ".agents"
+"""Package subdirectory that holds the canonical skill and agent source trees."""
+
 USAGE_PAUSE_SKILL_DIRECTORY_NAME: str = "skills"
-"""Package-root directory name that holds skill trees (sibling of ``scripts/``)."""
+"""Directory name under the agents home that holds skill trees."""
 
 USAGE_PAUSE_SKILL_NAME: str = "usage-pause"
 """Skill directory name under ``skills/`` that owns the OAuth usage probe."""

package/scripts/test_validate_instruction_pairs.py

@@ -100,21 +100,48 @@ def test_untracked_import_fails_tracking_check(tmp_path: Path) -> None:
     assert any("Git mode 100644" in each_error for each_error in all_errors)
 
 
-def test_pull_request_trigger_is_unconditional() -> None:
+def test_pull_request_target_trigger_is_unconditional() -> None:
     workflow_text = read_workflow("validate-instruction-pairs.yml")
 
-    assert "  pull_request:\n  push:\n" in workflow_text
+    assert "  pull_request:\n  pull_request_target:\n  push:\n" in workflow_text
 
 
 def test_instruction_pairs_status_context_stays_exact() -> None:
     workflow_text = read_workflow("validate-instruction-pairs.yml")
     reusable_workflow_text = read_workflow("instruction-pairs-reusable.yml")
+    caller_job_body = workflow_text.split("  instruction-pairs:\n", 1)[1]
+    caller_job_before_uses = caller_job_body.split("uses:", 1)[0]
 
     assert (
         "  instruction-pairs:\n"
         "    uses: ./.github/workflows/instruction-pairs-reusable.yml\n"
         "    with:\n"
-        "      validator-ref: ${{ github.event.pull_request.head.sha || github.sha }}\n"
         in workflow_text
     )
+    assert "      validator-ref: ${{ github.sha }}\n" in workflow_text
+    assert (
+        "      checkout-ref: ${{ github.event.pull_request.head.sha || github.sha }}\n"
+        in workflow_text
+    )
+    assert "if:" not in caller_job_before_uses
     assert "  instruction-pairs:\n    name: instruction-pairs\n" in reusable_workflow_text
+
+
+def test_release_please_short_circuit_exists_in_workflow() -> None:
+    workflow_text = read_workflow("validate-instruction-pairs.yml")
+    reusable_workflow_text = read_workflow("instruction-pairs-reusable.yml")
+
+    assert "skip-validation:" in reusable_workflow_text
+    assert "type: boolean" in reusable_workflow_text
+    assert "default: false" in reusable_workflow_text
+    assert "if: ${{ inputs.skip-validation }}" in reusable_workflow_text
+    assert "if: ${{ !inputs.skip-validation }}" in reusable_workflow_text
+    assert (
+        "Skipping instruction-pairs tree validation for a release-please pull request."
+        in reusable_workflow_text
+    )
+    assert "ref: ${{ inputs.checkout-ref }}" in reusable_workflow_text
+    assert "release-please--" in workflow_text
+    assert "chore(.*): release " in workflow_text
+    assert "autorelease: pending" in workflow_text
+    assert "skip-validation:" in workflow_text

package/scripts/test_verify_installable_package.py

@@ -31,8 +31,9 @@ def test_load_manifest_lists_hooks_and_claude_md() -> None:
     all_root_files = mod.required_root_file_names(manifest)
     assert "hooks" in all_directories
     assert "output-styles" in all_directories
+    assert ".agents" in all_directories
     assert "AGENTS.md" in all_root_files
-    assert "CLAUDE.md" in all_root_files
+    assert ".claude/CLAUDE.md" in all_root_files
     assert MANIFEST_FILENAME in all_root_files
 
 

package/scripts/tests/test_codex_compat_watcher.py

@@ -456,10 +456,10 @@ def test_debounced_reconciler_coalesces_and_suppresses_self_events() -> None:
     calls: list[str] = []
     reconciler = DebouncedReconciler(lambda: calls.append("run"), debounce_seconds=60.0)
 
-    reconciler.notify(WatchEvent("agents", is_self_event=True))
+    reconciler.notify(WatchEvent(".agents", is_self_event=True))
     assert reconciler.flush(should_force=True) is None
-    reconciler.notify(WatchEvent("agents"))
-    reconciler.notify(WatchEvent("skills"))
+    reconciler.notify(WatchEvent(".agents"))
+    reconciler.notify(WatchEvent("commands"))
     assert reconciler.flush(should_force=True) is None
     assert calls == ["run"]
 
@@ -468,7 +468,7 @@ def test_each_configured_root_triggers_reconciliation() -> None:
     calls: list[str] = []
     reconciler = DebouncedReconciler(lambda: calls.append("run") or "run")
 
-    for each_source_root in ("agents", "commands", "hooks", "rules", "skills"):
+    for each_source_root in (".agents", "commands", "hooks", "rules"):
         reconciler.notify(WatchEvent(each_source_root))
 
     assert reconciler.flush(should_force=True) == "run"
@@ -555,7 +555,7 @@ def test_out_of_scope_unsafe_events_are_ignored() -> None:
 def test_unsafe_event_details_are_sorted() -> None:
     reconciler = DebouncedReconciler(lambda: {"written": 1})
     reconciler.notify(WatchEvent("hooks", kind="unknown", path="z"))
-    reconciler.notify(WatchEvent("agents", kind="overflow", path="a"))
+    reconciler.notify(WatchEvent(".agents", kind="overflow", path="a"))
 
     assert reconciler.flush(should_force=True) == {
         "written": 1,

package/scripts/tests/test_engine.py

@@ -71,8 +71,8 @@ def test_explicit_roots_write_stem_named_mdc(
     cursor = tmp_path / "cursor-home"
     _write_minimal_curated_rules(claude / "rules")
     _write_minimal_docs(claude / "docs")
-    (claude / "rules" / "plain-language.md").write_text(
-        "# Plain language\n\nUse short sentences.\n",
+    (claude / "rules" / "asd-ste100-language.md").write_text(
+        "# ASD-STE100 Language Policy\n\nUse short sentences.\n",
         encoding="utf-8",
     )
     (claude / "rules" / "CLAUDE.md").write_text("# Inventory\n", encoding="utf-8")
@@ -90,8 +90,8 @@ def test_explicit_roots_write_stem_named_mdc(
         )
         == 0
     )
-    generated = (cursor / "rules" / "plain-language.mdc").read_text(encoding="utf-8")
-    assert 'description: "Plain language"' in generated
+    generated = (cursor / "rules" / "asd-ste100-language.mdc").read_text(encoding="utf-8")
+    assert 'description: "ASD-STE100 Language Policy"' in generated
     assert "alwaysApply: true" in generated
     assert "Use short sentences." in generated
     assert not (cursor / "rules" / "CLAUDE.mdc").is_file()

package/scripts/tests/test_rules.py

@@ -40,8 +40,8 @@ def test_build_mappings_emits_stem_mdc_for_remaining_claude_rules(
     claude = tmp_path / ".claude"
     _write_minimal_curated_rules(claude / "rules")
     (claude / "docs").mkdir(parents=True, exist_ok=True)
-    (claude / "rules" / "plain-language.md").write_text(
-        "# Plain language\n\nBe brief.\n",
+    (claude / "rules" / "asd-ste100-language.md").write_text(
+        "# ASD-STE100 Language Policy\n\nBe brief.\n",
         encoding="utf-8",
     )
     (claude / "rules" / "CLAUDE.md").write_text(
@@ -50,10 +50,10 @@ def test_build_mappings_emits_stem_mdc_for_remaining_claude_rules(
     (claude / "rules" / "AGENTS.md").write_text("# Agent inventory\n", encoding="utf-8")
     mappings = build_mappings(claude)
     output_by_key = {each_mapping.key: each_mapping for each_mapping in mappings}
-    discovered = output_by_key["plain-language"]
-    assert discovered.output_name == "plain-language.mdc"
+    discovered = output_by_key["asd-ste100-language"]
+    assert discovered.output_name == "asd-ste100-language.mdc"
     assert discovered.always_apply is True
-    assert discovered.description == "Plain language"
+    assert discovered.description == "ASD-STE100 Language Policy"
     assert "CLAUDE.md" not in {
         each_source.name
         for each_mapping in mappings

package/system-prompts/AGENTS.md

@@ -2,6 +2,14 @@
 
 System-prompt reference files installed into `~/.claude/system-prompts/` by `bin/install.mjs`. Rules and skills pull a file (or one of its sections) into context on demand by citing its installed path.
 
+Use `~/.claude/rules/asd-ste100-language.md` for user-facing word choice,
+sentence style, tone, punctuation, and prose form. Each prompt keeps its
+role-specific behavior contract.
+
+ELI5 owns the global beginner presentation envelope: large visuals, minimal
+text, one stable self-contained HTML artifact, update-in-place continuity, and
+sharing.
+
 ## Files
 
 | File | Purpose |

package/system-prompts/software-engineer.xml

@@ -7,6 +7,8 @@
 </role>
 
 <task_scope>
+  Apply rules/asd-ste100-language.md for user-facing word choice, sentence style, tone, punctuation,
+  and prose form. Keep the behavior contracts below within their named scope.
   Defer to the user's judgment when they indicate a task is too ambitious or complex to pursue.
   Match the scope of every action to what the user explicitly requested: a bug fix delivers the
   fix, a feature delivers the feature. Restrict scope statements to requirements, steps, and
@@ -20,11 +22,13 @@
 
   When a user asks a question, answer the question. When a user describes a problem, investigate
   and recommend. When the user says "do it", "go ahead", "make the change", or similarly
-  explicit language, proceed with action. When in doubt, ask: "Would you like me to make this
-  change, or just show you the approach?"
+  explicit language, proceed with action. Route user choices through AskUserQuestion.
 </task_scope>
 
 <output_style>
+  When a user-facing response needs beginner presentation, use ELI5: beginner framing, large
+  visuals, minimal text, one stable self-contained HTML artifact, update-in-place continuity,
+  and sharing. Apply rules/asd-ste100-language.md to sentence-level prose inside that artifact.
   Lead every response with the direct answer or result. Open with the substance — the
   conclusion, the fix, the decision — before any supporting context or explanation. Expand
   depth in proportion to the complexity of the ask: a direct question earns a sentence; a
@@ -387,7 +391,8 @@
   response begins with the outcome. When thinking is disabled, speak one brief
   natural-language sentence before a tool call that needs context, state when no
   fitting tool exists, and never emit internal-system XML in visible output.
-  Full contract: rules/opus5-communication-contract.md (opus5-communication-contract-v1).
+  Language policy: rules/asd-ste100-language.md. This section owns visible progress,
+  tool narration, and outcome-first final structure.
 </communication_contract>
 
 <help_and_feedback>

package/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/_shared/pr-loop/scripts/README.md

@@ -1,21 +0,0 @@
-# Shared PR-loop scripts
-
-Runnable helpers used by **bugteam**, **pr-converge**, and related skills. These files are **executed** from the repository (or a `~/.claude` install); they are not meant as primary model-reading context.
-
-## Inventory
-
-| File | Purpose |
-| --- | --- |
-| `preflight.py` | Local checks before a PR-loop run (pytest discovery, optional pre-commit, hooksPath sanity). |
-| `reviewer_availability.py` | Unified availability check for Copilot and Bugbot; reuses `copilot_quota.py` and `reviews_disabled.py` and exits 0 when the named `--reviewer` may be spawned. |
-| `reviews_disabled.py` | Opt-out and opt-in gate for reviewer tokens `bugteam`, `bugbot`, `copilot`, and `codex` via `CLAUDE_REVIEWS_DISABLED` / `CLAUDE_REVIEWS_ENABLED`. |
-| `code_rules_gate.py` | CODE_RULES gate over PR-scoped diffs (`--base`, staged-only, path filters). |
-| `fix_hookspath.py` | Repair `core.hooksPath` when it does not point at the packaged git-hooks tree. Single home for unexpected non-empty git stderr (hard-fail `RuntimeError`); skill wrappers may call it later. |
-| `grant_project_claude_permissions.py` / `revoke_project_claude_permissions.py` | Claude Code permission JSON helpers used during publish-style flows. |
-| `_claude_permissions_common.py` | Shared implementation for the permission scripts. |
-
-Configuration lives under `pr_loop_shared_constants/` next to these scripts (for example `preflight_constants.py`, `code_rules_gate_constants.py`, `fix_hookspath_constants.py`).
-
-## Gate semantics
-
-Merge-base selection, diff scoping, and exit codes for `code_rules_gate.py` are documented in [`../code-rules-gate.md`](../code-rules-gate.md).

package/agents/CLAUDE.md

@@ -1 +0,0 @@
-@AGENTS.md

package/docs/imagegen.md

@@ -1,22 +0,0 @@
-# Image generation
-
-The canonical image-generation entrypoint lives in the
-`python-automation` repository at `shared_utils.imagegen`.
-
-Resolve `python_automation_root` and `python_exe` from the repository's
-`run/tooling.json`, set `PYTHONPATH` to the resolved root, and run:
-
-```powershell
-$tooling = Get-Content '<REPO>\\run\\tooling.json' | ConvertFrom-Json
-$python_automation_root = $tooling.python_automation_root
-$python_executable = $tooling.python_exe
-$env:PYTHONPATH = $python_automation_root
-
-& $python_executable -m shared_utils.imagegen `
-  --prompt-file <PROMPT.txt> `
-  --size 2880x2880 `
-  --out <IMAGE.png>
-```
-
-Repeat `--reference-image <IMAGE.png>` for up to two visual references.
-The command verifies the decoded PNG dimensions before reporting success.