Skip to content

Business operating system for Claude Code — 57 skills, 21 agents, smart daemon. Unified inbox (WhatsApp/Email/Slack/Telegram), autonomous PR merge, full-AWS monitoring, revenue (Stripe+RevenueCat), e-commerce (Shopify), marketing (Klaviyo/Meta/GA4), voice (Bland/ElevenLabs), APM (Datadog/NewRelic/OTEL), YOLO mode.

feat: add portable config contract and public-content sanitizer (#769)

Aurora Capital48cdcebca568
diff --git a/claude-ops/docs/public-template-contract.md b/claude-ops/docs/public-template-contract.md
new file mode 100644
index 00000000..cfbc8de5
--- /dev/null
+++ b/claude-ops/docs/public-template-contract.md
@@ -0,0 +1,62 @@
+# Public template/config contract
+
+Claude Ops upstream docs, templates, and tests must stay portable. Any machine-, organization-, person-, channel-, or runtime-specific value belongs in user config or a runtime adapter, not in public plugin content.
+
+## Configuration keys
+
+| Key | Type | Default | Purpose |
+| --- | --- | --- | --- |
+| `OPS_PLUGIN_ROOT` | path | discovered package/plugin root | Root of the installed Claude Ops plugin. |
+| `OPS_DATA_DIR` | path | `${XDG_STATE_HOME:-$HOME/.local/state}/claude-ops` | Writable state and generated data. |
+| `OPS_CONFIG_PATH` | path | `${XDG_CONFIG_HOME:-$HOME/.config}/claude-ops/config.yaml` | User-owned configuration file. |
+| `OPS_CACHE_DIR` | path | `${XDG_CACHE_HOME:-$HOME/.cache}/claude-ops` | Cache files safe to delete. |
+| `OPS_RUNTIME_ADAPTER` | string | `claude-code` | Runtime integration layer. |
+| `ORG_NAME` | string | none | User-supplied display label for organization workflows. |
+| `PROJECT_ROOTS` | list[path] | none | User-supplied repository roots. |
+| `ISSUE_TRACKER_PROVIDER` | string | none | Issue tracker adapter, for example Linear, GitHub, or Jira. |
+| `LINEAR_TEAM_KEY` | string | none | Optional team key when the issue tracker adapter is Linear. |
+| `APPROVAL_CHAIN` | list | none | User-configured approval roles. |
+| `COMM_CHANNELS` | map | none | User-configured communication destinations. |
+| `SERVICE_REGISTRY_PATH` | path | none | Optional user-owned service registry file. |
+| `MCP_CAPABILITIES` | map | runtime-discovered | Capability-to-tool mapping. |
+| `SECRET_PROVIDER` | string | `env` | Secret backend, for example environment, 1Password, or Doppler. |
+
+## Placeholder rules
+
+| Local/private value | Public replacement |
+| --- | --- |
+| Absolute local path | `$HOME`, XDG dirs, package-relative paths, `{{PLUGIN_ROOT}}`, `{{OPS_DATA_DIR}}` |
+| Organization, project, or company name | `{{ORG_NAME}}`, `{{PROJECT_NAME}}` |
+| Person, username, or approval identity | `{{USER_NAME}}`, `{{APPROVER}}`, `{{ASSIGNEE}}` |
+| Email address | `{{CONTACT_EMAIL}}` or a reserved `example.com` address |
+| Chat or channel ID | `{{APPROVAL_CHANNEL}}`, `{{COMM_CHANNELS.review}}` |
+| Repository path | `{{ORG}}/{{REPO}}` or `{{PROJECT_ROOT}}` |
+| Legacy task system name | `legacy task system` |
+| Runtime-specific primitive | runtime adapter or capability name |
+| Concrete MCP tool function | capability name, for example `issue_tracker.search` |
+
+## Runtime adapter wording
+
+Describe behavior as a capability first, then map it in runtime-specific docs.
+
+| Capability | Claude Code adapter wording | Generic wording |
+| --- | --- | --- |
+| Shell command | Bash/Shell | host shell command capability |
+| Read file | Read | file read capability |
+| Write or edit file | Write/Edit | file write/edit capability |
+| Search files | Grep/Glob | file search capability |
+| Spawn worker | Task adapter | runtime task adapter |
+| Ask user | Ask user adapter | user decision adapter |
+| Fetch web content | Web fetch/search | web research capability |
+| Issue tracker | configured MCP/API | issue tracker capability |
+
+## Public PR gate
+
+A public PR is not ready unless:
+
+1. The diff contains no hardcoded local absolute paths.
+2. The diff contains no private organization, project, person, email, or channel values.
+3. The diff contains no real chat IDs, private service URLs, or internal repo names.
+4. Runtime-specific primitives are behind an adapter or clearly isolated in runtime docs.
+5. Example config uses placeholders and neutral examples only.
+6. The public-content sanitizer passes on changed docs, templates, and tests.
diff --git a/claude-ops/scripts/sanitize-public-content.py b/claude-ops/scripts/sanitize-public-content.py
new file mode 100644
index 00000000..2ec36341
--- /dev/null
+++ b/claude-ops/scripts/sanitize-public-content.py
@@ -0,0 +1,159 @@
+#!/usr/bin/env python3
+"""Scan public Claude Ops docs/templates for non-portable content.
+
+This is a read-only guard. It is intended for changed public files, not for
+rewriting historical content automatically.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import asdict, dataclass
+from pathlib import Path
+
+EXCLUDE_PARTS = {".git", "node_modules", "__pycache__", ".pytest_cache", "dist", "build", "coverage"}
+EXCLUDE_NAMES = {"package-lock.json", "pnpm-lock.yaml", "yarn.lock", "bun.lockb", "CHANGELOG.md"}
+EXTS = {".md", ".txt", ".json", ".yaml", ".yml", ".toml", ".sh", ".bash", ".py", ".js", ".mjs", ".ts", ".tsx"}
+PLACEHOLDER_RE = re.compile(r"\{\{[A-Z0-9_\.:-]+\}\}|\$\{?[A-Z0-9_]+\}?|example\.(com|org|net)", re.I)
+
+RUNTIME_PRIMITIVE_RE = re.compile(
+ r"\b(?:"
+ + "|".join(
+ [
+ "Task" + "Create",
+ "add" + "BlockedBy",
+ "CLAUDE_CODE" + "_EXPERIMENTAL_AGENT_TEAMS",
+ r"mcp" + r"__[A-Za-z0-9_]+" + r"__[A-Za-z0-9_]+",
+ r"gh\s+[^\n]*" + r"--admin",
+ ]
+ )
+ + r")\b"
+)
+
+CHECKS = [
+ (
+ "absolute_local_path",
+ re.compile(r"(?<![A-Za-z0-9_])(/home/[A-Za-z0-9._-]+|/Users/[A-Za-z0-9._-]+|/mnt/[A-Za-z0-9._/-]+)"),
+ "Use $HOME, XDG dirs, package-relative paths, or {{PLUGIN_ROOT}}/{{OPS_DATA_DIR}}.",
+ ),
+ (
+ "real_email",
+ re.compile(r"\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b", re.I),
+ "Use {{CONTACT_EMAIL}} or a reserved example.com/org/net address.",
+ ),
+ (
+ "chat_or_channel_id",
+ re.compile(r"\b(?:chat_id|thread_id|message_thread_id|jid|channel_id)\s*[:=]\s*['\"]?[[email protected]]{6,}|\b-?100\d{8,}\b|\b\d{10,}@g\.us\b", re.I),
+ "Use {{APPROVAL_CHANNEL}}/{{COMM_CHANNELS.*}} and keep real IDs in user config.",
+ ),
+ (
+ "private_service_url",
+ re.compile(
+ r"https?://(?:localhost|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|"
+ r"100\.(?:6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d+\.\d+|"
+ r"172\.(?:1[6-9]|2\d|3[0-1])\.\d+\.\d+|192\.168\.\d+\.\d+|"
+ r"[A-Za-z0-9.-]*\.internal)\S*",
+ re.I,
+ ),
+ "Use {{SERVICE_URL}} or SERVICE_REGISTRY_PATH, not private URLs.",
+ ),
+ (
+ "unadapted_runtime_primitive",
+ RUNTIME_PRIMITIVE_RE,
+ "Put runtime-specific primitives behind an adapter/capability name.",
+ ),
+]
+
+@dataclass
+class Finding:
+ path: str
+ line: int
+ kind: str
+ message: str
+ snippet: str
+
+
+def allowed(_line: str, match_text: str) -> bool:
+ if PLACEHOLDER_RE.search(match_text):
+ return True
+ if re.search(r"@(example\.com|example\.org|example\.net)$", match_text, re.I):
+ return True
+ return False
+
+
+def iter_files(paths: list[str]) -> list[Path]:
+ out: list[Path] = []
+ for raw in paths:
+ p = Path(raw)
+ if p.is_file():
+ out.append(p)
+ continue
+ for child in p.rglob("*"):
+ if not child.is_file():
+ continue
+ if child.suffix not in EXTS:
+ continue
+ if child.name in EXCLUDE_NAMES:
+ continue
+ if any(part in EXCLUDE_PARTS for part in child.parts):
+ continue
+ out.append(child)
+ return sorted(set(out))
+
+
+def scan_file(path: Path) -> list[Finding]:
+ try:
+ text = path.read_text(errors="ignore")
+ except Exception as exc:
+ return [Finding(str(path), 0, "read_error", str(exc), "")]
+ findings: list[Finding] = []
+ for no, line in enumerate(text.splitlines(), 1):
+ for kind, rx, msg in CHECKS:
+ match = rx.search(line)
+ if not match or allowed(line, match.group(0)):
+ continue
+ snippet = line.strip()
+ if len(snippet) > 180:
+ snippet = snippet[:177] + "..."
+ findings.append(Finding(str(path), no, kind, msg, snippet))
+ break
+ return findings
+
+
+def run(paths: list[str]) -> dict:
+ files = iter_files(paths)
+ findings: list[Finding] = []
+ for path in files:
+ findings.extend(scan_file(path))
+ by_kind: dict[str, int] = {}
+ for finding in findings:
+ by_kind[finding.kind] = by_kind.get(finding.kind, 0) + 1
+ return {
+ "files_scanned": len(files),
+ "findings": len(findings),
+ "by_kind": dict(sorted(by_kind.items())),
+ "sample": [asdict(f) for f in findings[:200]],
+ }
+
+
+def main(argv: list[str] | None = None) -> int:
+ parser = argparse.ArgumentParser()
+ parser.add_argument("paths", nargs="+", help="Files or directories to scan")
+ parser.add_argument("--json", action="store_true", help="Emit JSON report")
+ args = parser.parse_args(argv)
+ report = run(args.paths)
+ if args.json:
+ print(json.dumps(report, indent=2))
+ else:
+ print(f"files_scanned={report['files_scanned']} findings={report['findings']}")
+ for kind, count in report["by_kind"].items():
+ print(f"{kind}: {count}")
+ for finding in report["sample"]:
+ print(f"{finding['path']}:{finding['line']}: {finding['kind']}: {finding['snippet']}")
+ return 1 if report["findings"] else 0
+
+
+if __name__ == "__main__":
+ raise SystemExit(main())
diff --git a/claude-ops/templates/claude-ops.example.config.yaml b/claude-ops/templates/claude-ops.example.config.yaml
new file mode 100644
index 00000000..60af21e7
--- /dev/null
+++ b/claude-ops/templates/claude-ops.example.config.yaml
@@ -0,0 +1,42 @@
+# Claude Ops neutral example config. Placeholder-only and safe for public docs.
+ops:
+ plugin_root: "${OPS_PLUGIN_ROOT:-{{PLUGIN_ROOT}}}"
+ data_dir: "${OPS_DATA_DIR:-${XDG_STATE_HOME:-$HOME/.local/state}/claude-ops}"
+ config_path: "${OPS_CONFIG_PATH:-${XDG_CONFIG_HOME:-$HOME/.config}/claude-ops/config.yaml}"
+ cache_dir: "${OPS_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/claude-ops}"
+ runtime_adapter: "${OPS_RUNTIME_ADAPTER:-claude-code}"
+
+organization:
+ name: "{{ORG_NAME}}"
+ project_roots:
+ - "{{PROJECT_ROOT}}"
+
+issue_tracker:
+ provider: "{{ISSUE_TRACKER_PROVIDER}}"
+ linear_team_key: "{{LINEAR_TEAM_KEY}}"
+
+approvals:
+ chain:
+ - role: "{{REQUESTING_AGENT}}"
+ - role: "{{BUSINESS_OWNER}}"
+ - role: "{{FINAL_APPROVER}}"
+
+communications:
+ channels:
+ review: "{{APPROVAL_CHANNEL}}"
+ incidents: "{{INCIDENT_CHANNEL}}"
+ releases: "{{RELEASE_CHANNEL}}"
+
+services:
+ registry_path: "{{SERVICE_REGISTRY_PATH}}"
+
+mcp_capabilities:
+ issue_tracker.search: "{{ISSUE_TRACKER_SEARCH_CAPABILITY}}"
+ observability.search: "{{OBSERVABILITY_SEARCH_CAPABILITY}}"
+ docs.read: "{{DOCS_READ_CAPABILITY}}"
+
+secrets:
+ provider: "{{SECRET_PROVIDER}}"
+ required_env:
+ - "{{ISSUE_TRACKER_TOKEN_ENV}}"
+ - "{{OBSERVABILITY_TOKEN_ENV}}"
diff --git a/claude-ops/tests/fixtures/public-sanitizer/good.md b/claude-ops/tests/fixtures/public-sanitizer/good.md
new file mode 100644
index 00000000..bc925756
--- /dev/null
+++ b/claude-ops/tests/fixtures/public-sanitizer/good.md
@@ -0,0 +1,11 @@
+# Good public sanitizer fixture
+
+Use placeholders in public docs:
+
+- `{{ORG_NAME}}`
+- `{{CONTACT_EMAIL}}`
+- `{{APPROVAL_CHANNEL}}`
+- `{{PLUGIN_ROOT}}`
+- `${XDG_STATE_HOME:-$HOME/.local/state}/claude-ops`
+
+Runtime-specific behavior should be described as a capability or adapter.
diff --git a/claude-ops/tests/test-public-sanitizer.py b/claude-ops/tests/test-public-sanitizer.py
new file mode 100644
index 00000000..2cd3c45b
--- /dev/null
+++ b/claude-ops/tests/test-public-sanitizer.py
@@ -0,0 +1,92 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import importlib.util
+import sys
+import tempfile
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+SCRIPT = ROOT / "scripts" / "sanitize-public-content.py"
+FIXTURES = ROOT / "tests" / "fixtures" / "public-sanitizer"
+
+spec = importlib.util.spec_from_file_location("sanitize_public_content", SCRIPT)
+assert spec and spec.loader
+module = importlib.util.module_from_spec(spec)
+sys.modules[spec.name] = module
+spec.loader.exec_module(module)
+
+
+def test_good_fixture_passes():
+ report = module.run([str(FIXTURES / "good.md")])
+ assert report["findings"] == 0, report
+
+
+def test_bad_fixture_fails_by_category():
+ # Build unsafe values at runtime so repository PII/secret guards do not
+ # mistake intentional test data for leaked operator data.
+ content = "\n".join(
+ [
+ "Do not ship absolute paths like " + "/" + "home" + "/" + "alice" + "/private-plugin.",
+ "Do not ship real emails like " + "owner" + "@" + "private.invalid" + " even beside {{ORG_NAME}}.",
+ "Do not ship chat IDs like chat_id=" + "12345" + "67890.",
+ "Do not ship private URLs like https://" + "192.168.1.10" + "/admin.",
+ "Do not ship unadapted runtime primitives like " + "Task" + "Create.",
+ ]
+ )
+ with tempfile.TemporaryDirectory() as tmp:
+ bad = Path(tmp) / "bad.md"
+ bad.write_text(content)
+ report = module.run([str(bad)])
+ assert report["findings"] >= 5, report
+ for kind in [
+ "absolute_local_path",
+ "real_email",
+ "chat_or_channel_id",
+ "private_service_url",
+ "unadapted_runtime_primitive",
+ ]:
+ assert report["by_kind"].get(kind, 0) >= 1, report
+
+
+def test_private_url_ranges_are_scoped():
+ private_urls = "\n".join(
+ [
+ "http://" + "localhost" + ":3000/health",
+ "http://" + "127.0.0.1" + "/health",
+ "https://" + "100.64.0.1" + "/admin",
+ "https://" + "100.127.255.255" + "/admin",
+ ]
+ )
+ public_url = "https://" + "100.128.0.1" + "/status"
+ with tempfile.TemporaryDirectory() as tmp:
+ private = Path(tmp) / "private.md"
+ public = Path(tmp) / "public.md"
+ private.write_text(private_urls)
+ public.write_text(public_url)
+ private_report = module.run([str(private)])
+ public_report = module.run([str(public)])
+ assert private_report["by_kind"].get("private_service_url") == 4, private_report
+ assert public_report["findings"] == 0, public_report
+
+
+def test_sanitizer_source_passes():
+ report = module.run([str(SCRIPT)])
+ assert report["findings"] == 0, report
+
+
+def test_public_contract_and_example_pass():
+ report = module.run([
+ str(ROOT / "docs" / "public-template-contract.md"),
+ str(ROOT / "templates" / "claude-ops.example.config.yaml"),
+ ])
+ assert report["findings"] == 0, report
+
+
+if __name__ == "__main__":
+ test_good_fixture_passes()
+ test_bad_fixture_fails_by_category()
+ test_private_url_ranges_are_scoped()
+ test_sanitizer_source_passes()
+ test_public_contract_and_example_pass()
+ print("public sanitizer tests passed")