Handle empty promptinclude scans cleanly

Use the common rendering path when no promptinclude content is found so generic guidance stays visible. Exclude blank matching files from skipped counts while retaining budget-limit accounting, with focused scanner and zero-file regressions.

plugins/_promptinclude/AGENTS.md

@@ -16,6 +16,12 @@
 - Respect gitignore-style filtering, per-file budgets, and total token budgets.
 - Include only intended promptinclude files from configured workspaces.
 - Keep scan result status fields accurate for skipped, cropped, and included files.
+- Keep the generic promptinclude mechanism discoverable even when no matching
+  files exist; append file content only when the scan returns it.
+- Keep empty matching files out of included content and normal skipped counts
+  without reading beyond an exhausted count or token budget.
+- Keep the system fragment focused on prompt inclusion; optional capability
+  routing belongs in the corresponding policy-filtered tool prompts.
 
 ## Work Guidance
 

plugins/_promptinclude/extensions/python/system_prompt/_16_promptinclude.py

@@ -36,15 +36,6 @@ class PromptInclude(Extension):
             gitignore=config.get("gitignore", ""),
         )
 
-        if not result["files"] and result["skipped_count"] == 0:
-            prompt = self.agent.read_prompt(
-                "agent.system.promptinclude.md",
-                name_pattern=name_pattern,
-                includes="",
-            )
-            system_prompt.append(prompt)
-            return
-
         includes = _format_includes(self.agent, result)
         prompt = self.agent.read_prompt(
             "agent.system.promptinclude.md",

plugins/_promptinclude/helpers/scanner.py

@@ -109,11 +109,6 @@ def scan_promptinclude_files(
                 token_count=file_tokens, status="ok",
             ))
 
-    # remaining unprocessed files from matched list
-    remaining_unprocessed = len(matched) - len(result_files) - skipped_count
-    if remaining_unprocessed > 0:
-        skipped_count += remaining_unprocessed
-
     return ScanResult(files=result_files, skipped_count=skipped_count)
 
 

tests/test_promptinclude.py

@@ -0,0 +1,49 @@
+from types import SimpleNamespace
+
+import pytest
+
+from plugins._promptinclude.extensions.python.system_prompt import _16_promptinclude
+from plugins._promptinclude.helpers.scanner import scan_promptinclude_files
+
+
+def test_scanner_ignores_empty_matching_files(tmp_path) -> None:
+    (tmp_path / "empty.promptinclude.md").write_text(" \n", encoding="utf-8")
+
+    assert scan_promptinclude_files(str(tmp_path)) == {
+        "files": [],
+        "skipped_count": 0,
+    }
+
+
+@pytest.mark.asyncio
+async def test_promptinclude_stays_discoverable_without_matching_files(
+    monkeypatch, tmp_path
+) -> None:
+    class Agent:
+        context = SimpleNamespace()
+
+        def read_prompt(self, name, **kwargs):
+            assert name == "agent.system.promptinclude.md"
+            return f"{kwargs['name_pattern']}|{kwargs['includes']}"
+
+    async def call_direct(function, *args, **kwargs):
+        return function(*args, **kwargs)
+
+    monkeypatch.setattr(
+        _16_promptinclude.plugins,
+        "get_plugin_config",
+        lambda *_args, **_kwargs: {},
+    )
+    monkeypatch.setattr(
+        _16_promptinclude, "_resolve_workdir", lambda _agent: str(tmp_path)
+    )
+    monkeypatch.setattr(
+        _16_promptinclude.runtime, "call_development_function", call_direct
+    )
+
+    system_prompt: list[str] = []
+    await _16_promptinclude.PromptInclude(Agent()).execute(
+        system_prompt=system_prompt
+    )
+
+    assert system_prompt == ["*.promptinclude.md|"]