Skip to content

An agent organization structured as a company — 15+ departments, 125+ skills, each independently installable, citing the standards and regulators that settle the question. Runs in Claude Code and ChatGPT.

Address Codex review on #6: provenance coverage and department drift

Claude2548acc17b01
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2317374..b5ac8ac 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,8 +10,13 @@ terms as the rest of this repository.**
Contribute only work you have the right to license this way. In particular, do not paste in skills,
prose, or reference material from another project unless you wrote it or its licence permits
relocation — and if it does, say so in the pull request. Every line in this repository is original
-to it, and `scripts/check-provenance.py` fails the build if third-party licence text, copyright
-notices, or font assets appear.
+to it.
+
+`scripts/check-provenance.py` is a backstop, not a proof. It scans every text file in the tree for
+licence headers, copyright notices, and SPDX identifiers, flags files named like licences
+(`LICENSE`, `COPYING`, `NOTICE`, `PATENTS`, `AUTHORS`), and rejects bundled font assets. It cannot
+detect prose lifted without a notice attached — which is the case that matters most. Review is what
+catches that; the check only catches the obvious.
## What makes a good skill
@@ -51,7 +56,7 @@ Four checks, the same ones CI runs:
|---|---|
| Surface map | Every tracked path has exactly one owner |
| Skill frontmatter | `name` equals the directory name, lowercase-hyphenated, unique, description substantial |
-| Provenance | No third-party licence text, copyright notices, or font assets |
+| Provenance | No licence headers, copyright notices, licence-named files, or font assets |
| Generated docs | README and org-chart tables match the tree |
**Stage your files first.** The surface guard reads `git ls-files`, so an unstaged file is invisible
@@ -68,12 +73,17 @@ present.
## Adding a department
-All four, in the same change, or the check fails:
+All five, in the same change, or the check fails:
1. `plugins/<name>/skills/` and `plugins/<name>/.claude-plugin/plugin.json`
2. A roster row and a `surface:` block in `docs/AGENT-SURFACES.md`
3. A charter at `.claude/agents/<name>.md`
4. An entry in `.claude-plugin/marketplace.json`
+5. A `(rank, title, executive)` entry in `META` in `scripts/build-readme.py`, then regenerate with
+ `python3 scripts/build-readme.py`
+
+The generator reads the department list off disk and refuses to run until step 5 is done, so a new
+department cannot end up missing from the README and the org chart while the checks still pass.
Give it a chief before any specialists — the department's remit should exist before things are added
to it.
diff --git a/scripts/build-readme.py b/scripts/build-readme.py
index 2a5b80c..c0d6314 100755
--- a/scripts/build-readme.py
+++ b/scripts/build-readme.py
@@ -3,25 +3,50 @@
and verified in CI so the README can never drift from what the repo actually contains."""
import glob, os, re, json, sys
-ORDER = [
- ("executive", "Office of the CEO", "Chief Executive"),
- ("technology", "Technology", "CTO / CIO"),
- ("security", "Security", "CISO"),
- ("product", "Product", "CPO"),
- ("marketing", "Marketing", "CMO"),
- ("demand-generation", "Demand Generation", "CMO"),
- ("revenue", "Revenue", "CRO"),
- ("finance", "Finance", "CFO"),
- ("operations", "Operations", "COO"),
- ("customer-experience","Customer Experience","CCO"),
- ("data-analytics", "Data & Analytics", "CDO"),
- ("corporate-strategy","Corporate Strategy", "CSO"),
- ("people", "People", "CHRO"),
- ("legal-risk", "Legal & Risk", "CLO / CCO"),
-]
+# Display metadata per department. The department list itself comes from the plugin tree — see
+# load_departments() — so a department cannot be added to disk and silently omitted from the docs.
+# The rank fixes reporting order: the chief executive first, then the functions beneath.
+META = {
+ "executive": (10, "Office of the CEO", "Chief Executive"),
+ "technology": (20, "Technology", "CTO / CIO"),
+ "security": (30, "Security", "CISO"),
+ "product": (40, "Product", "CPO"),
+ "marketing": (50, "Marketing", "CMO"),
+ "demand-generation": (60, "Demand Generation", "CMO"),
+ "revenue": (70, "Revenue", "CRO"),
+ "finance": (80, "Finance", "CFO"),
+ "operations": (90, "Operations", "COO"),
+ "customer-experience": (100, "Customer Experience", "CCO"),
+ "data-analytics": (110, "Data & Analytics", "CDO"),
+ "corporate-strategy": (120, "Corporate Strategy", "CSO"),
+ "people": (130, "People", "CHRO"),
+ "legal-risk": (140, "Legal & Risk", "CLO / CCO"),
+}
REVIEWER = {"security", "legal-risk"}
+def load_departments():
+ """Departments come from disk, not from a list someone has to remember to update. A department
+ present on disk but missing from META is a hard error rather than a silent omission — the same
+ mistake used to drop a department out of both generated docs while --check still passed."""
+ found = {os.path.basename(os.path.dirname(os.path.dirname(m)))
+ for m in glob.glob("plugins/*/.claude-plugin/plugin.json")}
+ missing = sorted(found - set(META))
+ if missing:
+ sys.exit("build-readme: no display metadata for department(s) "
+ + ", ".join(missing)
+ + "\n add a (rank, title, executive) entry to META in scripts/build-readme.py")
+ stale = sorted(set(META) - found)
+ if stale:
+ sys.exit("build-readme: META names department(s) that are not on disk: "
+ + ", ".join(stale)
+ + "\n remove them from META in scripts/build-readme.py")
+ return [(d, META[d][1], META[d][2]) for d in sorted(found, key=lambda d: META[d][0])]
+
+
+ORDER = load_departments()
+
+
def summarize(path, limit=165):
text = open(path, encoding="utf-8").read()
front = re.match(r"^---\s*\n(.*?)\n---", text, re.S).group(1)
diff --git a/scripts/check-provenance.py b/scripts/check-provenance.py
index 7f3cb58..c443f4b 100755
--- a/scripts/check-provenance.py
+++ b/scripts/check-provenance.py
@@ -1,35 +1,76 @@
#!/usr/bin/env python3
-"""All content here is original. Fail if third-party licence text or upstream names reappear."""
+"""All content here is original. This is a heuristic backstop, not proof: it catches the common
+shapes of third-party licence text and vendored assets. It cannot detect prose copied without a
+notice, so it supplements review rather than replacing it."""
import glob, os, re, sys
+# Markers for the licences most likely to arrive with vendored material.
PATTERNS = [
r"\bMIT License\b",
+ r"\bApache License\b",
+ r"\bGNU (?:GENERAL|LESSER|AFFERO)\b",
+ r"\bBSD \d-Clause\b",
+ r"\bMozilla Public License\b",
+ r"\bSIL Open Font License\b",
+ r"\bCreative Commons Attribution\b",
r"Permission is hereby granted",
- r"Copyright \(c\)",
+ r"Redistribution and use in source and binary forms",
+ r"Copyright\s*(?:\(c\)|©)",
r"\bSPDX-License-Identifier\b",
- r"\bSIL Open Font License\b",
+ r"\bAll rights reserved\b",
]
-# Our own MIT LICENSE at the repo root is expected; any other licence file is not.
-OWN_LICENSE = "LICENSE"
-BANNED_FILES = ("licence", "license", "ofl", ".ttf", ".otf", ".woff")
+
+# Filenames that carry someone else's terms, whatever their extension.
+LICENCE_NAMES = re.compile(
+ r"^(licen[cs]e|copying|notice|patents|authors|ofl)(\..*)?$|licen[cs]e", re.I
+)
+# Binary assets that are always third-party when present.
+ASSET_EXTS = (".ttf", ".otf", ".woff", ".woff2", ".eot")
+
+OWN_LICENCE = "LICENSE" # ours, and the only one expected
+SKIP_DIRS = (".git/",)
+
+
+def is_probably_text(path, sniff=4096):
+ try:
+ with open(path, "rb") as handle:
+ chunk = handle.read(sniff)
+ except OSError:
+ return False
+ if b"\0" in chunk:
+ return False
+ try:
+ chunk.decode("utf-8")
+ except UnicodeDecodeError:
+ return False
+ return True
+
problems = []
for path in glob.glob("**/*", recursive=True):
- if not os.path.isfile(path) or path.startswith(".git/"):
+ if not os.path.isfile(path) or path.startswith(SKIP_DIRS):
continue
if os.path.abspath(path) == os.path.abspath(__file__):
continue # this file necessarily contains the patterns it searches for
- if path == OWN_LICENSE:
+ if path == OWN_LICENCE:
continue
- if any(token in os.path.basename(path).lower() for token in BANNED_FILES):
- problems.append(f"{path}: third-party licence or font asset")
+
+ name = os.path.basename(path)
+ if name.lower().endswith(ASSET_EXTS):
+ problems.append(f"{path}: third-party font asset")
continue
- if os.path.splitext(path)[1] not in (".md", ".json", ".mjs", ".py", ".yml"):
+ if LICENCE_NAMES.match(name):
+ problems.append(f"{path}: third-party licence or notice file")
+ continue
+
+ # Every text file, whatever its extension — an extension allowlist is how a .txt slips past.
+ if not is_probably_text(path):
continue
text = open(path, encoding="utf-8", errors="replace").read()
for pattern in PATTERNS:
if re.search(pattern, text):
problems.append(f"{path}: matches {pattern!r}")
+ break
for problem in problems:
print(f" {problem}")