add: portability CI gate, refactor Hermes-specific reference in safe-editing

what:
- .github/scripts/check-portability.py — portability gate scanning shipped
  SKILL.md and reference files for agent-specific references. Includes
  inline exemption mechanism (# portability: allow-platform-ref) for
  documentation-only platform path mentions.
- .github/workflows/ci.yml — added .github/scripts/** to trigger paths
  and portability check as a CI step
- references/safe-editing.md — replaced Hermes-specific import
  (from hermes_tools import terminal, write_file) with portable Python
  stdlib open/read/write; updated section title and lead-in text
- references/project-orientation.md — marked .cursor/rules/* mention as
  documentation-only with exemption comment

why:
- safe-editing.md had a Hermes-specific Python import in the shipped
  reference surface that would break non-Hermes agents
- No portability gate existed to prevent future drift
- project-orientation.md's agent file listing included .cursor/ as a
  documentation reference, not an instruction — needed exemption

Author: CodeSigils

.github/scripts/check-portability.py

@@ -0,0 +1,69 @@
+#!/usr/bin/env python3
+"""Check for agent-specific references in portable skill files.
+
+Ensures python-project-workflow's runtime surface remains cross-agent
+compatible. Scans both SKILL.md and references/*.md under skills/.
+
+"""
+from __future__ import annotations
+
+import re
+import sys
+from pathlib import Path
+
+SKILLS_DIR = Path("skills")
+
+FORBIDDEN_PATTERNS = (
+    ("Hermes tool name", re.compile(r"\bskill_(?:view|manage)\b", re.IGNORECASE)),
+    ("Hermes config path", re.compile(r"~/\.hermes(?:/|\b)", re.IGNORECASE)),
+    (
+        "Hermes CLI command",
+        re.compile(
+            r"\bhermes\s+(?:skills?|config|tools?|setup|help|doctor|gateway|run|serve|cron)\b",
+            re.IGNORECASE,
+        ),
+    ),
+    ("Hermes Python import", re.compile(r"from hermes_tools\b", re.IGNORECASE)),
+    ("Claude Code agent reference", re.compile(r"\bClaude\(\)", re.IGNORECASE)),
+    ("Gemini CLI command", re.compile(r"\bgemini\s+skills?\b", re.IGNORECASE)),
+    (
+        "Platform-specific path",
+        re.compile(r"\.(?:claude|cursor|codex|opencode|gemini)/"),
+    ),
+)
+
+
+def scan_file(path: Path) -> list[tuple[Path, int, str, str]]:
+    violations: list[tuple[Path, int, str, str]] = []
+    text = path.read_text(encoding="utf-8")
+    for line_no, line in enumerate(text.splitlines(), start=1):
+        # Exemption: lines with this comment are documentation references, not instructions
+        if "# portability: allow-platform-ref" in line:
+            continue
+        for label, pattern in FORBIDDEN_PATTERNS:
+            if pattern.search(line):
+                violations.append((path, line_no, label, line.rstrip()))
+    return violations
+
+
+def main() -> int:
+    violations: list[tuple[Path, int, str, str]] = []
+    for path in sorted(SKILLS_DIR.rglob("*.md")):
+        try:
+            violations.extend(scan_file(path))
+        except OSError as exc:
+            print(f"FAIL: could not read {path}: {exc}", file=sys.stderr)
+            return 1
+
+    if violations:
+        print("FAIL: agent-specific references found in skills/ — will break non-Hermes agents:")
+        for path, line_no, label, line in violations:
+            print(f"  {path}:{line_no}: {label}: {line}")
+        return 1
+
+    print("PASS: no agent-specific references in skills/")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

.github/workflows/ci.yml

@@ -5,6 +5,7 @@ on:
     branches: [main]
     paths:
       - ".github/workflows/ci.yml"
+      - ".github/scripts/**"
       - "README.md"
       - "CITATION.cff"
       - "scripts/**"
@@ -13,6 +14,7 @@ on:
     branches: [main]
     paths:
       - ".github/workflows/ci.yml"
+      - ".github/scripts/**"
       - "README.md"
       - "CITATION.cff"
       - "scripts/**"
@@ -40,6 +42,9 @@ jobs:
           python -m pip install --upgrade pip
           python -m pip install ruff
 
+      - name: Check cross-agent portability
+        run: python3 .github/scripts/check-portability.py
+
       - name: Run skill source checks
         run: python3 scripts/validate.py
 

skills/python-project-workflow/references/project-orientation.md

@@ -52,7 +52,7 @@ Before giving advice, inspect the repository to understand its current state and
 
 ### Agent and Developer Documentation
 
-- `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, `.continue/rules/*`, `.github/copilot-instructions.md`, `CONVENTIONS.md`,
+- `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*` # portability: allow-platform-ref, `.continue/rules/*`, `.github/copilot-instructions.md`, `CONVENTIONS.md`,
   `.aider*`
 - `README.md`, `CONTRIBUTING.md`, `DEVELOPMENT.md`
 - Documentation directories: `docs/`, `doc/`, `documentation/`

skills/python-project-workflow/references/safe-editing.md

@@ -12,25 +12,24 @@ Editing files with dense backslash patterns (e.g. sed BRE capture groups `\(...\
 
 ## Safe Workflow (Ranked by Reliability)
 
-### 1. First Resort: `write_file` with `terminal("cat")` input
+### 1. First Resort: Python stdlib read/write
 
-Use `execute_code` with `terminal("cat")` to read raw bytes, then `write_file` — zero escaping layers:
+Use Python stdlib — open the file, read, replace, write — zero escaping layers:
 
 ```python
-from hermes_tools import terminal, write_file
-
 # Read raw file (no escaping, no format wrapping)
-r = terminal(["cat", "/path/to/file"])
-content = r["output"]
+with open("/path/to/file") as f:
+    content = f.read()
 
 # Python string replacement — backslashes in your replacement are literal
 content = content.replace(
     'old_backslash_pattern',   # literal bytes from the file
     'new_backslash_pattern'    # literal bytes you want
 )
 
-# Write_file accepts raw content with no escaping
-write_file("/path/to/file", content)
+# Write back
+with open("/path/to/file", "w") as f:
+    f.write(content)
 ```
 
 Use raw strings `r'...'` so Python doesn't process the backslashes. Verify the result with `od -A x -t x1z | grep '5c'` (see Diagnostic below).