feat: load AGENTS.md from local reference repositories

scripts/lib/references.py

@@ -1,10 +1,14 @@
 """Reference repository data models for 0.5.0 reference loading."""
 
 from dataclasses import dataclass, field
+from pathlib import Path
+
+from common.fs import read_text
 
 REFERENCE_KIND_LOCAL = "local"
 REFERENCE_KIND_REMOTE = "remote"
 SUPPORTED_REFERENCE_KINDS = {REFERENCE_KIND_LOCAL, REFERENCE_KIND_REMOTE}
+REFERENCE_AGENTS_FILENAME = "AGENTS.md"
 
 
 @dataclass(frozen=True)
@@ -94,3 +98,59 @@ def to_dict(self) -> dict:
             "agentskill_version": self.agentskill_version,
             "references": list(self.sources),
         }
+
+
+def load_local_reference(source: ReferenceSource) -> ReferenceLoadResult:
+    if source.kind != REFERENCE_KIND_LOCAL:
+        return ReferenceLoadResult(
+            source=source,
+            error=f"unsupported local reference source kind: {source.kind}",
+        )
+
+    root = Path(source.value)
+
+    if not root.exists():
+        return ReferenceLoadResult(
+            source=source,
+            error=f"reference path does not exist: {source.value}",
+        )
+
+    if not root.is_dir():
+        return ReferenceLoadResult(
+            source=source,
+            error=f"reference path is not a directory: {source.value}",
+        )
+
+    agents_path = root / REFERENCE_AGENTS_FILENAME
+
+    if not agents_path.exists():
+        return ReferenceLoadResult(
+            source=source,
+            error=f"AGENTS.md not found in reference repository: {source.value}",
+        )
+
+    content = read_text(agents_path)
+
+    if not content:
+        return ReferenceLoadResult(
+            source=source,
+            error=f"AGENTS.md is empty in reference repository: {source.value}",
+        )
+
+    if not content.strip():
+        return ReferenceLoadResult(
+            source=source,
+            error=f"AGENTS.md is empty in reference repository: {source.value}",
+        )
+
+    doc = ReferenceDocument(
+        source=source,
+        content=content,
+        source_path=REFERENCE_AGENTS_FILENAME,
+    )
+
+    return ReferenceLoadResult(source=source, document=doc)
+
+
+def load_local_references(sources: list[ReferenceSource]) -> list[ReferenceLoadResult]:
+    return [load_local_reference(s) for s in sources]

tests/test_references.py

@@ -3,6 +3,8 @@
     ReferenceLoadResult,
     ReferenceMetadata,
     ReferenceSource,
+    load_local_reference,
+    load_local_references,
 )
 
 
@@ -161,3 +163,115 @@ def test_reference_metadata_omits_absent_optional_fields():
     meta = ReferenceMetadata(agentskill_version="0.5.0")
     d = meta.to_dict()
     assert d["references"] == []
+
+
+def test_load_local_reference_success(tmp_path):
+    repo = tmp_path / "my-repo"
+    repo.mkdir()
+    (repo / "AGENTS.md").write_text("# Rules\n\nBe kind.")
+
+    src = ReferenceSource(kind="local", value=str(repo))
+    result = load_local_reference(src)
+
+    assert result.ok
+    assert result.document is not None
+    assert result.document.content == "# Rules\n\nBe kind."
+    assert result.document.source_path == "AGENTS.md"
+    assert result.document.source is src
+
+
+def test_load_local_reference_missing_path(tmp_path):
+    missing = tmp_path / "does-not-exist"
+    src = ReferenceSource(kind="local", value=str(missing))
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.document is None
+    assert result.error is not None
+    assert "does not exist" in result.error
+
+
+def test_load_local_reference_path_is_file(tmp_path):
+    file_path = tmp_path / "not-a-dir"
+    file_path.write_text("hello")
+
+    src = ReferenceSource(kind="local", value=str(file_path))
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.error is not None
+    assert "not a directory" in result.error
+
+
+def test_load_local_reference_missing_agents_md(tmp_path):
+    repo = tmp_path / "empty-repo"
+    repo.mkdir()
+
+    src = ReferenceSource(kind="local", value=str(repo))
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.error is not None
+    assert "AGENTS.md not found" in result.error
+
+
+def test_load_local_reference_empty_agents_md(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "AGENTS.md").write_text("")
+
+    src = ReferenceSource(kind="local", value=str(repo))
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.error is not None
+    assert "empty" in result.error
+
+
+def test_load_local_reference_whitespace_only_agents_md(tmp_path):
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    (repo / "AGENTS.md").write_text("   \n\n  ")
+
+    src = ReferenceSource(kind="local", value=str(repo))
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.error is not None
+    assert "empty" in result.error
+
+
+def test_load_local_reference_unsupported_kind():
+    src = ReferenceSource(kind="remote", value="https://github.com/org/repo.git")
+    result = load_local_reference(src)
+
+    assert not result.ok
+    assert result.error is not None
+    assert "unsupported local reference source kind" in result.error
+
+
+def test_load_local_references_batch_preserves_order(tmp_path):
+    repo_a = tmp_path / "repo-a"
+    repo_a.mkdir()
+    (repo_a / "AGENTS.md").write_text("# A\n")
+
+    repo_c = tmp_path / "repo-c"
+    repo_c.mkdir()
+    (repo_c / "AGENTS.md").write_text("# C\n")
+
+    sources = [
+        ReferenceSource(kind="local", value=str(repo_a)),
+        ReferenceSource(kind="local", value=str(tmp_path / "missing")),
+        ReferenceSource(kind="local", value=str(repo_c)),
+    ]
+
+    results = load_local_references(sources)
+
+    assert len(results) == 3
+    assert results[0].ok
+    assert not results[1].ok
+    assert results[2].ok
+    assert results[0].document is not None
+    assert results[2].document is not None
+    assert results[0].document.content == "# A\n"
+    assert results[2].document.content == "# C\n"