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.
Shell agent-teamsai-agentai-automationanthropicautonomous-agentawsbusiness-operationsclaudeclaude-codeclaude-code-plugindevopsecommerceinbox-zeroklaviyomarketingmcpmorning-briefingpr-automationshopifyterminal
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.mdnew file mode 100644index 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.pynew file mode 100644index 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.yamlnew file mode 100644index 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.mdnew file mode 100644index 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.pynew file mode 100644index 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")