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.
HTML agent-marketplacechatgpt-pluginchatgpt-skillsclaude-codeclaude-code-pluginclaude-pluginclaude-skillsmcporganization
Build the vertical generator and the first vertical
Claudebc432c06182a
diff --git a/.claude/agents/verticals.md b/.claude/agents/verticals.mdnew file mode 100644index 0000000..245fb75--- /dev/null+++ b/.claude/agents/verticals.md@@ -0,0 +1,52 @@+---+name: verticals+description: Vertical packs. Owns verticals/** and nothing else — the per-vertical configs, the industry-only skills, and the context fragments that extend core skills. Gated: its diffs ship to a standalone repository, so they are surfaced before landing.+---++# Vertical packs++## Why this agent exists++The single owner of `verticals/**`. Each vertical is a config plus the content that makes the core+specific to one industry, and `scripts/build-vertical.py` emits a standalone repository from the+two. No other agent writes inside this surface.++It is separate from the departments because the content crosses them — an industrial vertical adds+to `operations`, `people` and `legal-risk` at once — and separate from `repo-meta` because writing+industry advice is not the same job as maintaining the generator that ships it.++## Authority: proposes++Diffs here are surfaced before they land. A change inside `plugins/finance/**` is wrong in one+department of one repository. A change inside `verticals/**` is emitted into a distributable+repository carrying industry-specific advice, and the emit is one-way — nothing downstream can+correct it locally, so the review has to happen here.++## Surface++Writes: `verticals/**`.+Reads: anything. Commits: nothing; the orchestrator is the sole committer.++## Standard++A vertical adds and extends. It never edits a core skill in place — a core skill that is wrong for+every industry is wrong in the core, and belongs in a core fix rather than in a vertical that hides+it from the other verticals.++- **New skills** go in `verticals/<slug>/skills/<department>/<skill>/SKILL.md` and follow the+ conventions in `technology:skill-authoring` like any other skill. A name that collides with a core+ skill fails the emit.+- **Extensions** go in `verticals/<slug>/context/<department>/<skill>.md` and are spliced into the+ core skill ahead of its `## Never` block. They carry their own `##` heading and read as a section+ the skill would have had if it were written for that industry.+- **Nothing is listed twice.** Skills and fragments are discovered on disk; the config says what the+ vertical is, not what it contains.++`verticals/README.md` holds the working details.++## Verification this surface implies++- `python3 scripts/build-vertical.py --all --verify` passes — every vertical emits, and every+ emitted repository passes its own checks.+- No change outside `verticals/**`. Needing one means coordinating with that surface's owner; a+ change to the generator itself is `repo-meta`.diff --git a/.gitignore b/.gitignoreindex ca80f25..09a6e5a 100644--- a/.gitignore+++ b/.gitignore@@ -2,3 +2,8 @@# untracked __pycache__ is enough to make a clean tree look dirty.__pycache__/*.pyc++# Emitted vertical repositories. Generation is one-way (D8) and the output is never hand-edited, so+# committing it would put a hand-editable copy in front of every contributor. `build-vertical.py+# --verify` proves the emit is sound without keeping a copy (D36).+dist/diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 854bbf3..e411729 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -61,6 +61,7 @@ Every check CI runs, in one script — the workflow calls this same file, so the| Skill references | Every `department:skill` mentioned in the docs or in a skill body resolves || US English spelling | No British spellings, by exact word form || `## Never` blocks | Bullets inside one block agree on terminal punctuation |+| Verticals | Every vertical emits, and the emitted repository passes its own checks || Manifests | The marketplace file and every `plugin.json` parse |**Stage your files first.** The surface guard reads `git ls-files`, so an unstaged file is invisible@@ -113,6 +114,19 @@ department cannot end up missing from the README and the org chart while the cheGive it a chief before any specialists — the department's remit should exist before things are addedto it.+## Adding to a vertical++A vertical is the core made specific to one industry. `scripts/build-vertical.py` emits a standalone+repository from the core plus a config under `verticals/<slug>/`.++Generation is one-way and **generated output is never hand-edited** (D8). `dist/` is gitignored for+that reason; what replaces a committed copy is `--verify`, which emits to a temporary directory and+runs the emitted repository's own checks against it. CI does that on every push.++A vertical adds skills and extends core skills. It never edits a core skill in place — a core skill+that is wrong for every industry is wrong in the core, and fixing it there is what reaches every+vertical on its next emit. `verticals/README.md` has the working details.+## Adding a file outside `plugins/`It needs an owner in `docs/AGENT-SURFACES.md`, or the surface check fails. Most such files belong todiff --git a/docs/AGENT-SURFACES.md b/docs/AGENT-SURFACES.mdindex d39bdfc..439c3b1 100644--- a/docs/AGENT-SURFACES.md+++ b/docs/AGENT-SURFACES.md@@ -53,6 +53,7 @@ corporate-strategy builder installed autonomoussecurity builder installed autonomousit-operations builder installed autonomouspmo builder installed autonomous+verticals builder installed proposesrepo-meta builder installed proposeslegal-risk-review reviewer installed autonomoussecurity-review reviewer installed autonomous@@ -63,6 +64,13 @@ generators every document is built from, and this map. A change inside `plugins/wrong in one department. A change to `scripts/check-all.sh` can make every other check stopreporting, and nothing downstream would fail to say so.+`verticals` is the second, for the same reason in a different direction. It owns the per-vertical+configs and content that `scripts/build-vertical.py` emits standalone repositories from, so a change+inside `verticals/**` does not land in this repository — it lands in a distributable artifact+carrying somebody's industry advice, and the emit is one-way, so nothing downstream can correct it+locally. It owns the input rather than the generator; the generator is a script and belongs to+`repo-meta` with the others.+Charters live in `.claude/agents/`, one per installed row. A row marked `installed` without acharter, or a charter without a row, fails the check — the two cannot drift apart silently.@@ -135,6 +143,10 @@ plugins/pmo/**plugins/security/**```+```surface:verticals+verticals/**+```+```surface:repo-metaLICENSE.gitignorediff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.mdindex d54d3e5..78c1b4c 100644--- a/docs/DECISION-LOG.md+++ b/docs/DECISION-LOG.md@@ -47,6 +47,7 @@ recorded rather than being deleted.| D33 | US English check rejects the plural of "analysis" | ✅ Resolved || D34 | Two skills claim social graphics | ✅ Resolved || D35 | Whether description shape is a checkable convention | ✅ Resolved |+| D36 | Where emitted vertical repositories live | ✅ Resolved |---@@ -409,7 +410,7 @@ of decisions.| 7 | Deepen `operations`, then `finance`, then `people` | D10 | — | ✅ done || 8 | Catalog the other organizations' public repos — no import | D11 | — | ✂️ dropped, D30 || 9 | ~~Separate session for the private sweep~~ | D11 | — | ✂️ dropped, D30 |-| 10 | Build the vertical generator: core, per-vertical config, one-way emit | D8 | — | |+| 10 | Build the vertical generator: core, per-vertical config, one-way emit | D8 | — | ✅ done, D36 || 11 | Revisit repo visibility | D16 | after 1 | ✅ done |Items 1–4 can proceed in parallel; all four land before item 5. Items 8 and 9 were dropped in D30.@@ -1207,3 +1208,44 @@ it.** The figure "~24 agents over a 1,500-file monorepo" in `executive:agent-hiea claim about this roster, which currently runs 17 builders and 2 reviewers. It is not: bothinstances say the method was *extracted from* a working implementation of that size. The sentencedescribes the source the method came from, and changing the number would make it wrong.++---++## D36. Where emitted vertical repositories live — ✅ Resolved++D8 resolved the vertical architecture to template-plus-generator with one-way emit, and roadmap item+10 was to build it. Building it raised a question D8 did not answer: what happens to the output.++Every other generated artifact in this repository — the README, the org chart, the social card — is+committed, and a `--check` mode fails the build when the committed copy drifts from what the+generator produces. Applying that pattern here would mean committing an entire second copy of the+tree per vertical.++- **(a) Emit to a gitignored `dist/`, and verify by emitting to a temporary directory and running+ the emitted repository's own checks against it.** ← **chosen**+- (b) Commit the emitted tree and `--check` it like the other generated documents. Consistent with+ the existing pattern, and reviewable in a diff. It also roughly doubles the repository per+ vertical, and — decisively — puts a hand-editable copy of the output in front of every+ contributor, which is the one thing D8's rule forbids. A `--check` failure would read as "the+ generated copy is stale" long after someone had already edited it.+- (c) Emit straight to the downstream repository from CI. Removes the local copy entirely, at the+ cost of making every push to this repository a publish. Publishing should be a deliberate act.++**Resolution: (a).** The invariant worth holding is not "a stored copy matches the generator" but+"the generator produces a repository that is sound." `--verify` states that directly: it emits into+a temporary directory, initializes it the way a consumer's clone would be, runs the emitted+repository's checks, and keeps nothing. CI runs it on every push, so the emit cannot rot unnoticed.++**Two consequences worth recording.**++The emitted repository does not carry the three document generators or their checks. Its README is+written by `build-vertical.py`, so a "README is current" check downstream would be verifying the+wrong generator; freshness is guaranteed upstream instead. It carries the other seven checks, which+still mean what they say about a tree of skills.++`verticals/**` is a new surface with its own owner, and it is the second row marked `proposes`. A+change inside a department is wrong in one department of one repository. A change inside a vertical+is emitted into a distributable repository carrying industry-specific advice, and because the emit+is one-way, nothing downstream can correct it locally. The generator itself stays with `repo-meta`+alongside the other scripts — writing industry advice and maintaining the tool that ships it are+different jobs.diff --git a/plugins/operations/skills/quality-management/SKILL.md b/plugins/operations/skills/quality-management/SKILL.mdindex cc8f80b..7b2ad15 100644--- a/plugins/operations/skills/quality-management/SKILL.md+++ b/plugins/operations/skills/quality-management/SKILL.md@@ -10,7 +10,7 @@ process that produced the work, so that is where the effort belongs.## Define quality as the customer experiences it-A standard nobody outside the team recognises is a preference. State quality in terms a customer+A standard nobody outside the team recognizes is a preference. State quality in terms a customerwould agree with: correct, on time, complete, usable — with a threshold, so conformance is a factrather than an opinion.diff --git a/scripts/build-vertical.py b/scripts/build-vertical.pynew file mode 100755index 0000000..b629616--- /dev/null+++ b/scripts/build-vertical.py@@ -0,0 +1,410 @@+#!/usr/bin/env python3+"""Emit a standalone vertical repository from the core tree plus a per-vertical config.++D8 resolved the vertical architecture to template-plus-generator rather than overlays, because+productization is planned (D7c) and migrating from overlays to a generator later is worse than+paying for the generator now. What that commits to is one rule, and the rule is the whole cost:++ Generation is one-way. Generated output is never hand-edited.++An edit made downstream is lost on the next emit, silently, which is worse than a fork because the+divergence is invisible. Everything a vertical changes lives in `verticals/<slug>/` or in the core.++Output goes to `dist/headcount-<slug>/`, which is gitignored. Committing the emitted tree would+put a hand-editable copy of it in front of every contributor, which is the one thing the rule above+forbids; the guarantee that the output is sound comes from `--verify`, which emits into a temporary+directory and runs the emitted repository's own checks against it (D36).++What a vertical config may do:++ * add skills `verticals/<slug>/skills/<dept>/<skill>/SKILL.md`, discovered on disk+ * extend a core skill `verticals/<slug>/context/<dept>/<skill>.md`, spliced in ahead of `## Never`+ * drop a department `[emit] exclude_departments`++It may not edit a core skill in place. A core skill that is wrong for every vertical is wrong in the+core, and belongs in a core fix.++Usage:+ build-vertical.py industrial emit to dist/headcount-industrial/+ build-vertical.py industrial --verify emit to a temp dir and run its checks; emit nothing+ build-vertical.py --all --verify the same for every configured vertical+"""+import argparse+import glob+import json+import os+import re+import shutil+import subprocess+import sys+import tempfile+import tomllib++ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))+VERTICALS = os.path.join(ROOT, "verticals")++# Copied into the emitted repository verbatim. The three document generators are deliberately not+# among them: the emitted README is written by this script, so a "README is current" check+# downstream would be verifying the wrong generator. Freshness is guaranteed here instead.+EMIT_SCRIPTS = [+ "validate-skills.py",+ "check-provenance.py",+ "check-skill-refs.py",+ "check-us-english.py",+ "check-never-blocks.py",+]++CHECK_ALL = """#!/usr/bin/env bash+# Generated by headcount's build-vertical.py. Do not edit — see README.+# The checks that still mean something in a generated repository. The three that verify generated+# documents are upstream, where the generator that writes them lives.+set -uo pipefail+cd "$(dirname "$0")/.."++fail=0+run() {+ printf '\\n\\033[1m%s\\033[0m\\n' "$1"; shift+ if "$@"; then :; else fail=1; printf ' FAILED\\n'; fi+}++run "Surface map is coherent" \\+ node plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs check+run "Skill frontmatter is valid" \\+ python3 scripts/validate-skills.py+run "No third-party license text" \\+ python3 scripts/check-provenance.py+run "Skill references resolve" \\+ python3 scripts/check-skill-refs.py+run "US English spelling" \\+ python3 scripts/check-us-english.py+run "Never blocks are internally consistent" \\+ python3 scripts/check-never-blocks.py+run "Manifests parse" \\+ python3 -c "+import json,glob,sys+bad=[]+for f in ['.claude-plugin/marketplace.json']+glob.glob('plugins/*/.claude-plugin/plugin.json'):+ try: json.load(open(f))+ except Exception as e: bad.append(f'{f}: {e}')+for b in bad: print(' ',b)+print(f'manifests: {len(bad)} problems')+sys.exit(1 if bad else 0)+"++printf '\\n'+if [ "$fail" -eq 0 ]; then printf '\\033[32mAll checks passed.\\033[0m\\n'; else printf '\\033[31mChecks failed.\\033[0m\\n'; fi+exit "$fail"+"""++BANNER = (+ "> **This repository is generated.** It is emitted from "+ "[`{upstream_slug}`]({upstream}) by `scripts/build-vertical.py {slug}`, and every file in it "+ "is overwritten on the next emit. Edits made here are lost silently. Fix the core upstream, or "+ "the vertical's own content under `verticals/{slug}/` upstream, and re-emit."+)++CONTRIBUTING = """# Contributing++{banner}++Nothing is merged into this repository directly. Where a change belongs depends on what is wrong:++| What you found | Where it is fixed |+|---|---|+| A skill that is wrong for every industry | The core, in [`{upstream_slug}`]({upstream}) |+| A skill that is wrong only for {title} | `verticals/{slug}/` upstream |+| A missing {title} capability | A new skill under `verticals/{slug}/skills/` upstream |+| Anything about the generator itself | `scripts/build-vertical.py` upstream |++Open the issue or pull request against the upstream repository. A pull request here cannot be+merged — the next emit would erase it.++## Running the checks++```+./scripts/check-all.sh+```++These are the upstream checks that still mean something downstream. The three that verify generated+documents run upstream, where the generator that writes them lives.+"""+++def die(message):+ sys.exit(f"build-vertical: {message}")+++def load_config(slug):+ path = os.path.join(VERTICALS, slug, "vertical.toml")+ if not os.path.exists(path):+ die(f"no config at verticals/{slug}/vertical.toml")+ with open(path, "rb") as handle:+ config = tomllib.load(handle)+ for section, key in (("vertical", "slug"), ("vertical", "title"), ("repo", "url")):+ if key not in config.get(section, {}):+ die(f"verticals/{slug}/vertical.toml is missing [{section}] {key}")+ if config["vertical"]["slug"] != slug:+ die(f"verticals/{slug}/vertical.toml declares slug "+ f"{config['vertical']['slug']!r}, which is not its directory name")+ return config+++def configured_verticals():+ return sorted(+ os.path.basename(os.path.dirname(p))+ for p in glob.glob(os.path.join(VERTICALS, "*", "vertical.toml"))+ )+++def core_departments():+ """Departments on disk, in the marketplace manifest's order.++ The manifest already lists them in reporting order — the chief executive first, then the+ functions beneath — so ordering by it keeps the emitted README reading like the core's without+ a second copy of that order for someone to forget to update. A department on disk but absent+ from the manifest sorts last rather than disappearing.+ """+ found = sorted(+ os.path.basename(os.path.dirname(os.path.dirname(m)))+ for m in glob.glob(os.path.join(ROOT, "plugins", "*", ".claude-plugin", "plugin.json"))+ )+ manifest = json.load(open(os.path.join(ROOT, ".claude-plugin", "marketplace.json"), encoding="utf-8"))+ order = {p["name"]: n for n, p in enumerate(manifest["plugins"])}+ return sorted(found, key=lambda d: (order.get(d, len(order)), d))+++def splice(core_text, fragment):+ """Put a vertical's extra material into a core skill ahead of its `## Never` block.++ Appending at the end would land it after the Never list, which every skill closes with, and the+ result reads as though the rules were followed by an afterthought. Ahead of the rules is where+ a section of the same kind would have been written by hand.+ """+ fragment = fragment.strip() + "\n"+ marker = "\n## Never\n"+ at = core_text.find(marker)+ if at == -1:+ return core_text.rstrip("\n") + "\n\n" + fragment+ return core_text[:at] + "\n" + fragment + core_text[at:]+++def collect(slug):+ """What the vertical adds, discovered on disk rather than listed in the config.++ Listing them would be a second place to forget: a skill added to the directory and not to the+ list would be silently dropped from every emit, which is the failure `build-readme.py` already+ guards against for departments.+ """+ base = os.path.join(VERTICALS, slug)+ skills = {}+ for path in sorted(glob.glob(os.path.join(base, "skills", "*", "*", "SKILL.md"))):+ skill = os.path.basename(os.path.dirname(path))+ dept = os.path.basename(os.path.dirname(os.path.dirname(path)))+ skills[(dept, skill)] = path+ context = {}+ for path in sorted(glob.glob(os.path.join(base, "context", "*", "*.md"))):+ skill = os.path.basename(path)[: -len(".md")]+ dept = os.path.basename(os.path.dirname(path))+ context[(dept, skill)] = path+ return skills, context+++def emit(slug, config, out):+ vertical, repo = config["vertical"], config["repo"]+ title = vertical["title"]+ name = vertical.get("name", f"headcount-{slug}")+ excluded = set(config.get("emit", {}).get("exclude_departments", []))+ departments = [d for d in core_departments() if d not in excluded]+ unknown = excluded - set(core_departments())+ if unknown:+ die("exclude_departments names department(s) that are not on disk: " + ", ".join(sorted(unknown)))++ skills, context = collect(slug)+ for (dept, skill) in list(skills) + list(context):+ if dept not in departments:+ die(f"verticals/{slug} targets department {dept!r}, which is not emitted")+ for (dept, skill) in skills:+ if os.path.exists(os.path.join(ROOT, "plugins", dept, "skills", skill, "SKILL.md")):+ die(f"verticals/{slug}/skills/{dept}/{skill} would shadow a core skill of the same "+ f"name — a vertical adds skills, it does not replace them")+ for (dept, skill) in context:+ if not os.path.exists(os.path.join(ROOT, "plugins", dept, "skills", skill, "SKILL.md")):+ die(f"verticals/{slug}/context/{dept}/{skill}.md extends a skill that does not exist")++ shutil.rmtree(out, ignore_errors=True)+ os.makedirs(out)++ banner = BANNER.format(+ slug=slug, upstream=repo["upstream"],+ upstream_slug=repo["upstream"].rstrip("/").split("github.com/")[-1],+ )++ # Departments, with the vertical's material folded in.+ counts = {}+ for dept in departments:+ src = os.path.join(ROOT, "plugins", dept)+ dst = os.path.join(out, "plugins", dept)+ shutil.copytree(src, dst)+ for path in glob.glob(os.path.join(dst, "skills", "*", "SKILL.md")):+ skill = os.path.basename(os.path.dirname(path))+ fragment = context.get((dept, skill))+ if fragment:+ text = open(path, encoding="utf-8").read()+ with open(path, "w", encoding="utf-8") as handle:+ handle.write(splice(text, open(fragment, encoding="utf-8").read()))+ for (d, skill), path in skills.items():+ if d != dept:+ continue+ target = os.path.join(dst, "skills", skill)+ os.makedirs(target, exist_ok=True)+ shutil.copy2(path, os.path.join(target, "SKILL.md"))+ manifest_path = os.path.join(dst, ".claude-plugin", "plugin.json")+ manifest = json.load(open(manifest_path, encoding="utf-8"))+ manifest["repository"] = repo["url"]+ manifest["keywords"] = sorted(set(manifest.get("keywords", [])) | set(vertical.get("keywords", [])))+ json.dump(manifest, open(manifest_path, "w", encoding="utf-8"), indent=2)+ open(manifest_path, "a", encoding="utf-8").write("\n")+ counts[dept] = len(glob.glob(os.path.join(dst, "skills", "*", "SKILL.md")))++ # Marketplace manifest, renamed and re-sourced.+ marketplace = json.load(open(os.path.join(ROOT, ".claude-plugin", "marketplace.json"), encoding="utf-8"))+ marketplace["name"] = name+ marketplace["metadata"]["description"] = vertical.get("description", marketplace["metadata"]["description"])+ marketplace["plugins"] = [p for p in marketplace["plugins"] if p["name"] in departments]+ os.makedirs(os.path.join(out, ".claude-plugin"))+ with open(os.path.join(out, ".claude-plugin", "marketplace.json"), "w", encoding="utf-8") as handle:+ json.dump(marketplace, handle, indent=2)+ handle.write("\n")++ # The surface map, charters, and the checks that still apply downstream.+ os.makedirs(os.path.join(out, "docs"))+ shutil.copy2(os.path.join(ROOT, "docs", "AGENT-SURFACES.md"), os.path.join(out, "docs"))+ shutil.copytree(os.path.join(ROOT, ".claude"), os.path.join(out, ".claude"))+ os.makedirs(os.path.join(out, "scripts"))+ for script in EMIT_SCRIPTS:+ shutil.copy2(os.path.join(ROOT, "scripts", script), os.path.join(out, "scripts"))+ check_all = os.path.join(out, "scripts", "check-all.sh")+ open(check_all, "w", encoding="utf-8").write(CHECK_ALL)+ os.chmod(check_all, 0o755)+ shutil.copytree(os.path.join(ROOT, ".github"), os.path.join(out, ".github"))+ for name_ in ("LICENSE", ".gitattributes", ".gitignore"):+ shutil.copy2(os.path.join(ROOT, name_), os.path.join(out, name_))++ open(os.path.join(out, "CONTRIBUTING.md"), "w", encoding="utf-8").write(+ CONTRIBUTING.format(+ banner=banner, slug=slug, title=title,+ upstream=repo["upstream"],+ upstream_slug=repo["upstream"].rstrip("/").split("github.com/")[-1],+ )+ )+ open(os.path.join(out, "README.md"), "w", encoding="utf-8").write(+ readme(config, departments, counts, banner, name)+ )+ return sum(counts.values()), len(departments)+++def readme(config, departments, counts, banner, name):+ vertical, repo = config["vertical"], config["repo"]+ total = sum(counts.values())+ added = config.get("_added", [])+ lines = [+ f"# {name}",+ "",+ vertical.get("tagline", ""),+ "",+ banner,+ "",+ f"{len(departments)} departments, {total} skills. Every department installs on its own, so "+ "only the function you are asking about loads.",+ "",+ "```",+ f"/plugin marketplace add {repo['url'].rstrip('/').split('github.com/')[-1]}",+ f"/plugin install operations@{name}",+ "```",+ "",+ "## What this adds over the core",+ "",+ vertical.get("rationale", "").strip(),+ "",+ ]+ if added:+ lines += ["| Skill | What it covers |", "|---|---|"]+ lines += [f"| `{dept}:{skill}` | {summary} |" for dept, skill, summary in added]+ lines += [""]+ lines += [+ "## Departments",+ "",+ "| Department | Skills |",+ "|---|---|",+ ]+ lines += [f"| `{d}` | {counts[d]} |" for d in departments]+ lines += [+ "",+ "## License",+ "",+ "MIT, the same as the core. See `LICENSE`.",+ "",+ ]+ return "\n".join(lines)+++def describe(path):+ front = re.match(r"^---\s*\n(.*?)\n---", open(path, encoding="utf-8").read(), re.S)+ desc = re.search(r"^description:\s*(.*)$", front.group(1), re.M).group(1).strip()+ cut = re.split(r"(?:\.\s+)(?:Also )?[Uu]se (?:this|it)\b", desc)[0].rstrip(" .,—-")+ return cut+++def build(slug, verify):+ config = load_config(slug)+ skills, _ = collect(slug)+ config["_added"] = sorted(+ (dept, skill, describe(path)) for (dept, skill), path in skills.items()+ )+ name = config["vertical"].get("name", f"headcount-{slug}")+ out = tempfile.mkdtemp(prefix=f"{name}-") if verify else os.path.join(ROOT, "dist", name)+ try:+ total, departments = emit(slug, config, out)+ if not verify:+ print(f"{name}: {departments} departments, {total} skills → dist/{name}/")+ return 0+ # The emitted surface map governs the emitted tree, and `agent-guard check` reads+ # `git ls-files` to know what that tree contains. A consumer gets this repository by+ # cloning it, so verify it the same way: initialize and stage, or the check either errors+ # out (no repository) or passes vacuously against zero tracked files.+ for command in (["git", "init", "-q", "."], ["git", "add", "-A"]):+ subprocess.run(command, cwd=out, check=True, capture_output=True)+ result = subprocess.run(["./scripts/check-all.sh"], cwd=out, capture_output=True, text=True)+ if result.returncode != 0:+ print(f" {name}: emitted repository fails its own checks")+ for line in (result.stdout + result.stderr).splitlines():+ if line.strip():+ print(f" {line}")+ return 1+ print(f" {name}: {departments} departments, {total} skills, emitted repository passes its own checks")+ return 0+ finally:+ if verify:+ shutil.rmtree(out, ignore_errors=True)+++def main():+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("slug", nargs="?", help="vertical to emit")+ parser.add_argument("--all", action="store_true", help="every configured vertical")+ parser.add_argument("--verify", action="store_true",+ help="emit to a temporary directory and run the emitted checks; write nothing")+ args = parser.parse_args()++ slugs = configured_verticals() if args.all else ([args.slug] if args.slug else [])+ if not slugs:+ die("name a vertical, or pass --all. Configured: " + ", ".join(configured_verticals()))++ failures = sum(build(slug, args.verify) for slug in slugs)+ if args.verify:+ print(f"verticals: {len(slugs)} checked, {failures} problems")+ return 1 if failures else 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/scripts/check-all.sh b/scripts/check-all.shindex 7204282..7c3db2d 100755--- a/scripts/check-all.sh+++ b/scripts/check-all.sh@@ -35,6 +35,8 @@ run "US English spelling" \python3 scripts/check-us-english.pyrun "Never blocks are internally consistent" \python3 scripts/check-never-blocks.py+run "Verticals emit and pass their own checks" \+ python3 scripts/build-vertical.py --all --verifyrun "Manifests parse" \python3 -c "import json,glob,sysdiff --git a/scripts/check-provenance.py b/scripts/check-provenance.pyindex 3f76f57..81bb25a 100755--- a/scripts/check-provenance.py+++ b/scripts/check-provenance.py@@ -41,7 +41,9 @@ OWN_LICENSE = "LICENSE" # ours, and the only one expectedOWN_LICENSE_MENTION = {"CONTRIBUTING.md", "README.md", "docs/DECISION-LOG.md"}OWN_LICENSE_PATTERN = r"\bMIT License\b"-SKIP_DIRS = (".git/",)+# Generated output and build byproducts are not this repository's content. `dist/` in particular+# is a copy of the tree already being checked, so scanning it doubles every finding.+SKIP_DIRS = (".git/", "dist/", "__pycache__/")def is_probably_text(path, sniff=4096):diff --git a/scripts/check-us-english.py b/scripts/check-us-english.pyindex 09ca6e5..65e98b6 100755--- a/scripts/check-us-english.py+++ b/scripts/check-us-english.py@@ -40,7 +40,8 @@ PAIRS = {"prioritising": "prioritizing", "prioritisation": "prioritization","optimise": "optimize", "optimised": "optimized", "optimising": "optimizing","optimisation": "optimization",- "recognise": "recognize", "recognised": "recognized", "recognising": "recognizing",+ "recognise": "recognize", "recognises": "recognizes",+ "recognised": "recognized", "recognising": "recognizing","recognisable": "recognizable","realise": "realize", "realised": "realized", "realising": "realizing","realisation": "realization",@@ -84,7 +85,10 @@ PAIRS = {}WORD = re.compile(r"\b(" + "|".join(sorted(PAIRS, key=len, reverse=True)) + r")\b", re.I)-SKIP_DIRS = {".git", "node_modules", "__pycache__"}+# `dist` holds emitted vertical repositories, which are generated output rather than content of+# this repository — checking them here reports the same finding twice and reports it against a+# path nobody can fix. The emitted tree runs this check itself, where a finding is actionable.+SKIP_DIRS = {".git", "node_modules", "__pycache__", "dist"}# LICENSE is the canonical MIT text and is never rewritten. This file lists British spellings by# definition, so it excludes itself the way check-provenance.py does.SKIP_FILES = {"LICENSE", os.path.basename(__file__)}diff --git a/verticals/README.md b/verticals/README.mdnew file mode 100644index 0000000..7de87c6--- /dev/null+++ b/verticals/README.md@@ -0,0 +1,77 @@+# Verticals++A vertical is the core made specific to one industry. `scripts/build-vertical.py` reads a vertical's+config and emits a standalone repository from it — the whole core, plus what that industry adds.++```+python3 scripts/build-vertical.py industrial → dist/headcount-industrial/+python3 scripts/build-vertical.py industrial --verify emit to a temp dir, run its checks, keep nothing+python3 scripts/build-vertical.py --all --verify the same for every vertical; this is what CI runs+```++## The rule++**Generation is one-way. Generated output is never hand-edited.** D8 chose a generator over overlays+because productization is planned, and this rule is the entire cost of that choice. An edit made+downstream is lost on the next emit, silently — which is worse than a fork, because the divergence+is invisible.++`dist/` is gitignored for the same reason. A committed copy of the output is a hand-editable copy in+front of every contributor. What replaces it is `--verify`, which emits into a temporary directory,+initializes it the way a consumer's clone would be, and runs the emitted repository's own checks+against it. CI runs that on every push, so the emit cannot rot unnoticed without anything being+stored (D36).++## Layout++```+verticals/<slug>/+ vertical.toml what the vertical is+ skills/<department>/<skill>/SKILL.md industry-only skills, added to that department+ context/<department>/<skill>.md extends a core skill of that name+```++Skills and fragments are **discovered on disk, never listed** in the config. A list is a second place+to forget, and a skill added to the directory but not the list would be silently dropped from every+emit — the failure `build-readme.py` already guards against for departments.++## What a vertical may do++| | |+|---|---|+| Add a skill | `skills/<department>/<skill>/SKILL.md`. Colliding with a core skill's name fails the emit. |+| Extend a core skill | `context/<department>/<skill>.md`, spliced in ahead of the skill's `## Never` block. |+| Drop a department | `[emit] exclude_departments` in the config. |++It may **not** edit a core skill in place. A core skill that is wrong for every industry is wrong in+the core; fixing it there means every vertical gets the fix on its next emit, which is the whole+reason for generating rather than forking.++Fragments carry their own `##` heading and are spliced ahead of `## Never` rather than appended,+because every skill closes with its rules and material after them reads as an afterthought.++## Adding a vertical++1. `verticals/<slug>/vertical.toml` — `[vertical]` slug, title, tagline, description, rationale;+ `[repo]` url and upstream. The slug must equal the directory name.+2. Write the skills and fragments.+3. `python3 scripts/build-vertical.py <slug> --verify` until it passes.+4. `./scripts/check-all.sh` — the vertical check runs `--all --verify`, so a broken vertical fails+ the build for everything.++**Vertical content is checked through the emit, not directly.** The core checkers glob `plugins/**`,+which this directory is not, so a thin description, a British spelling, a mixed `## Never` block or+a dangling `department:skill` reference in a vertical skill surfaces when the emitted repository+runs those same checks against itself. It is caught before anything ships, and the failure names+the emitted path rather than the source — look for the same file under `verticals/<slug>/`.++Naming follows D22: each vertical is `headcount-<slug>`, which is what the emitted marketplace and+install strings use.++## Publishing++The emitted tree is a complete repository. Publishing it is a deliberate act rather than part of the+build: emit without `--verify`, then push `dist/headcount-<slug>/` to its own repository. It carries+its own README, its own `CONTRIBUTING.md` pointing contributions back here, and the checks that+still mean something downstream — the three that verify generated documents stay upstream, where the+generators that write them live.diff --git a/verticals/industrial/context/legal-risk/regulatory-compliance.md b/verticals/industrial/context/legal-risk/regulatory-compliance.mdnew file mode 100644index 0000000..90f8532--- /dev/null+++ b/verticals/industrial/context/legal-risk/regulatory-compliance.md@@ -0,0 +1,29 @@+## Regulators that arrive at the site++A cross-industry compliance program is built around obligations that arrive as filings. An operating+site adds regulators who arrive in person, inspect equipment and interview employees, and whose+obligations run on clocks measured in hours.++The categories worth tracking separately, because each has its own trigger and its own owner:++- **Occupational safety.** Recordkeeping is continuous and the log is posted annually; serious+ events carry a short notification window. The inspection is unannounced and the walkthrough is+ itself evidence. `operations:ehs-and-workplace-safety` holds the operational side.+- **Environmental permits.** Air, wastewater, stormwater and waste each carry conditions, monitoring+ and periodic reporting. A permit condition breached is a violation whether or not anything was+ released, and permits expire on their own schedule rather than the company's.+- **Release reporting.** Spills and releases above a reportable quantity trigger notification within+ hours. Knowing the quantities for what is on site is preparation, not response — nobody derives+ them correctly at the time.+- **Product and material regulation.** Hazard communication and safety data sheets, restricted+ substances, labeling, and anything specific to what the site makes or handles.+- **Equipment certification.** Pressure vessels, lifting equipment, forklifts and their operators+ carry inspection and certification intervals with their own dates.++**A site has a finite, enumerable obligation list, and most sites have never written it down.**+Producing it once — obligation, regulator, trigger, frequency, named owner, evidence location — is+the highest-value compliance work an operating site can do, and it is usually assembled in a week+from permits already in the file.++Contractors and temporary workers on the site are inside most of these obligations and outside most+companies' tracking of them.diff --git a/verticals/industrial/context/operations/capacity-and-demand-planning.md b/verticals/industrial/context/operations/capacity-and-demand-planning.mdnew file mode 100644index 0000000..b8f7e28--- /dev/null+++ b/verticals/industrial/context/operations/capacity-and-demand-planning.md@@ -0,0 +1,28 @@+## On a plant floor, capacity is one resource++Everything above describes a system's capacity in aggregate. A plant does not have one. It has a+sequence of resources, and its output is set by the slowest one in the current product mix — which+moves when the mix moves.++Three consequences that do not follow from the aggregate view:++- **The utilization threshold applies per resource, not per plant.** A plant at 70% overall with the+ press at 95% behaves like a plant at 95%. Aggregate utilization is the number most likely to be+ quoted and least likely to explain the queue.+- **Capacity added anywhere else produces inventory.** Speeding up a feeding operation puts more+ work in front of the constraint. The line looks busier and ships the same.+- **The constraint is worth protecting, not optimizing.** Time lost at the constraint is lost for the+ whole plant and cannot be recovered elsewhere. Keeping a deliberate buffer of work in front of it,+ and scheduling maintenance and changeovers around it, is worth more than a percentage point of+ its own efficiency.++**Changeover time is capacity that looks like demand.** A resource whose nominal rate covers the+order book can still be short, because a third of its hours go to setups the schedule implies. When+capacity looks adequate on paper and is not in practice, count the changeovers the sequence requires+before adding a shift. `operations:production-management` covers the sequencing decision that sets+that number.++**Labor availability is a separate constraint from machine availability**, and on most sites the+binding one. Certified operators, shift coverage, and absence run on different arithmetic from+equipment, and a plan built on machine hours alone will be wrong every time a qualified operator is+out.diff --git a/verticals/industrial/context/operations/quality-management.md b/verticals/industrial/context/operations/quality-management.mdnew file mode 100644index 0000000..3b7d9ea--- /dev/null+++ b/verticals/industrial/context/operations/quality-management.md@@ -0,0 +1,30 @@+## Inside a certified quality system++Where the plant holds a certification — ISO 9001, IATF 16949, AS9100 or a customer-specific scheme —+the quality system stops being purely internal. It carries obligations that are audited, and the+audit tests the system rather than the product.++What that changes in practice:++- **Nonconformance has to be dispositioned and recorded**, not just fixed. Use as-is, rework, repair,+ scrap, return — each with an authority level that says who may decide, and the reasoning attached.+ An undocumented "we sorted it" is the finding.+- **Corrective action is a defined loop with evidence at the end.** Containment first, so nothing+ further escapes while the cause is being found; then cause; then the action; then verification that+ the rate actually moved; then closure. Auditors open closed actions and look for the last step,+ because it is the one most often missing.+- **Document and change control is part of the product.** Which revision of the drawing, the work+ instruction and the inspection plan was in force when the part was made is a question that will be+ asked, sometimes years later.+- **Traceability runs backwards from the customer.** Given a complaint, the system has to identify+ the lot, the material, the machine, the shift and everything else made under the same conditions.+ That defines the recall boundary, and a system that cannot draw it makes the boundary everything.++**Certification is evidence of a system, not of quality.** A plant can hold a clean certificate and+ship defects; the certificate says the process is documented and followed. Treat an audit finding as+information about the system and the escaped-defect rate as information about the product, and do+not let a clean audit answer a customer complaint.++Customer-specific requirements sit on top of the standard and usually carry the sharper teeth —+production part approval, annual revalidation, mandated containment on escape. Know which customer+imposes what before the escape, not after.diff --git a/verticals/industrial/context/operations/supply-chain-and-logistics.md b/verticals/industrial/context/operations/supply-chain-and-logistics.mdnew file mode 100644index 0000000..6e8fc2b--- /dev/null+++ b/verticals/industrial/context/operations/supply-chain-and-logistics.md@@ -0,0 +1,26 @@+## Inbound materials behave differently from inbound goods++Everything above holds for a supply chain that moves finished goods. A plant's inbound side has+properties that change the answers.++**Lead time variability costs more than lead time.** A material that reliably takes six weeks can be+planned. One that takes two to six weeks cannot, and the difference is absorbed as either safety+stock or missed production. When pressing a supplier, press on the variance before the average.++**A shortage of any one input is a shortage of the finished item.** Ninety-nine of a hundred+components in stock is zero units buildable. This is why component-level availability, not aggregate+inventory value, is the number that predicts whether the schedule holds — and why inventory+reduction programs measured in dollars reliably delete the cheap part that stops the line.++**Qualification makes second-sourcing slow.** Where material is specified, certified, or bound to a+customer approval, an alternate supplier is a qualification project measured in months, not a+purchase order. The time to start is before the single source is a problem. Rank single-sourced+inputs by what stopping costs per day and qualify downward from the top.++**Minimum order quantities and batch sizes propagate.** A supplier minimum that exceeds a run's+requirement pushes the excess into inventory or forces a longer run than the schedule wanted. That+is a supply decision reshaping the production schedule, and it should be visible as one rather than+absorbed at the plant.++Scrap and yield sit between the two sides: material consumed is what was issued, not what shipped,+and a plan built on finished quantity under-orders by the yield gap every time.diff --git a/verticals/industrial/context/people/employment-compliance.md b/verticals/industrial/context/people/employment-compliance.mdnew file mode 100644index 0000000..6d72c84--- /dev/null+++ b/verticals/industrial/context/people/employment-compliance.md@@ -0,0 +1,31 @@+## Hourly, shift and plant-floor employment++The obligations above apply everywhere. An hourly, shift-based workforce concentrates the exposure+in a few mechanisms, and they are mechanical rather than judgmental — which means errors are+systematic, apply to everyone at once, and accumulate quietly until they are found in aggregate.++**Time worked is not time on the clock, and not time scheduled.** Compensable time typically starts+before the workstation: donning required protective equipment, walking to a post where that+equipment is required, pre-shift handover, and mandatory briefings. Rounding rules that are neutral+in design are frequently not neutral in practice, and the test is whether they favor the employer+over a period.++**Overtime is calculated on a regular rate that is wider than the base rate.** Shift differentials,+non-discretionary production or attendance bonuses and similar payments generally have to be folded+in before the premium is computed. Paying the premium on base pay alone is the most common+underpayment in a plant, and because it is arithmetic it applies to every affected employee for the+whole look-back period.++**Breaks, meal periods and rest are jurisdictional and specific.** Duration, timing, whether they are+paid, and whether an interrupted meal period becomes compensable vary by state and country. A single+national policy will be wrong somewhere, and usually in the direction that costs.++**Temporary and agency workers can create joint employment.** Where the site controls the work,+schedules the hours and supervises directly, obligations can attach to the site regardless of who+issues the paycheck. Assume exposure and confirm the agency's compliance rather than the reverse.++Classification of production supervisors is the recurring judgment call: a working supervisor who+spends most of a shift on the line may not meet the exemption tests whatever the title says.++Attendance and scheduling systems encode all of this. When the policy is right and the configuration+is old, the configuration wins — and it is the configuration that will be produced in discovery.diff --git a/verticals/industrial/skills/operations/ehs-and-workplace-safety/SKILL.md b/verticals/industrial/skills/operations/ehs-and-workplace-safety/SKILL.mdnew file mode 100644index 0000000..0ede7b3--- /dev/null+++ b/verticals/industrial/skills/operations/ehs-and-workplace-safety/SKILL.md@@ -0,0 +1,102 @@+---+name: ehs-and-workplace-safety+description: Runs environment, health and safety on an operating site — hazard controls in order of effectiveness, incident recording and reporting obligations, and safety measurement that does not reward silence. Use this to build or audit a safety program, decide what controls a hazard actually needs, work out whether an injury is recordable or reportable, investigate an incident, or fix safety metrics that have stopped producing reports.+---++# Environment, health and safety++Safety on an operating site is a legal obligation with clocks attached, not a value statement. The+difference matters at the moment something happens, because the obligations start running whether or+not anyone has decided what to do.++## Controls in order of effectiveness++The hierarchy is not advice about preference. It is a ranking by how much the control depends on a+person behaving correctly under pressure, and everything below the third rung does.++1. **Elimination** — the hazard is not there. The task is designed out, or done elsewhere.+2. **Substitution** — a less hazardous material, process or energy source.+3. **Engineering** — guards, interlocks, ventilation, barriers. The hazard remains; reaching it does+ not depend on judgment.+4. **Administrative** — procedure, training, signage, permits, rotation.+5. **Personal protective equipment** — the last line, worn by the person the hazard is nearest to.++Most programs that look thorough are stacked at rungs 4 and 5, because those are cheap to add and+produce documents. A new procedure and a toolbox talk in response to an injury is the default+answer, and it leaves the hazard exactly where it was.++The test for a proposed control: if the most rushed person on the worst shift skips a step, does the+hazard reach them? If yes, the control is at rung 4 or below whatever it is called.++## Energy control is the one to get right first++Most severe injuries on production equipment happen during maintenance, cleaning or clearing a jam —+work done with guards removed, by someone who has done it a hundred times, on a machine that was+believed to be off.++Isolation of hazardous energy has to be procedural per machine rather than generic per plant, and+must account for stored energy — pressure, springs, gravity, capacitance — which is what "off" fails+to address. Verification is the step that gets dropped: attempting the start after isolating is what+turns a belief into a fact.++Where an outside contractor works on the site, the isolation procedure is theirs to follow and yours+to specify. Coordination is the usual gap.++## Recordable, reportable and the clocks++These are three different thresholds and they are routinely conflated:++- **First aid** — treated and logged, not recorded.+- **Recordable** — medical treatment beyond first aid, restricted duty, days away, loss of+ consciousness, or a significant diagnosed condition. It goes on the log.+- **Reportable** — the serious subset that must be told to the regulator within a fixed window,+ measured in hours for a fatality and in a small number of days for an in-patient hospitalization,+ amputation or eye loss.++The failure is almost never refusal. It is that nobody knew the clock had started, because the event+was being managed as a medical matter while the reporting window ran. Name in advance who decides+recordability, who notifies, and what happens when that person is unreachable at 2am — which is when+it will happen. `legal-risk:regulatory-compliance` holds the wider obligation-tracking method.++Environmental releases carry their own thresholds and their own clocks, usually shorter. A site with+permits should know its reportable quantities before it needs them.++## Measure what precedes the injury++A recordable injury rate is a lagging measure on a small denominator. A site can go a year without a+recordable and still be one guard away from a serious event, and a site can record two minor injuries+in a strong year and look worse.++Worse, attaching the rate to bonuses or site rankings reliably suppresses reporting rather than+injuries. The first thing lost is the near-miss, which is the only free information the system+produces.++Measure ahead of the event instead: near-misses reported per period, with a rising count read as the+program working; hazards identified and closed, with age; time to close a corrective action; and+audit findings on the controls that matter, weighted toward rungs 1 to 3. Pair any lagging rate with+a severity-potential measure, because frequency and severity move independently and a program tuned+on frequency alone optimizes for paper cuts.++## Tooling++EHS management systems — Intelex, Cority, VelocityEHS, Enablon, Benchmark Gensuite and similar —+carry the incident log, corrective actions, training records and regulator-facing reports in one+auditable place, which is what an inspection asks for. The determining factor is whether reporting+is easy enough on the floor that near-misses actually arrive; a system only supervisors can reach+records incidents and nothing that precedes them.++Regulatory recordkeeping has a required form and a required posting period. Whatever the system,+confirm it produces the log in the form the regulator expects rather than an export someone+reformats each year.++Below that scale, a shared log with a fixed set of fields and a named owner per open item covers+most of the value. What cannot be substituted is the review — an incident system nobody reads is a+liability record rather than a safety program.++## Never++- Answer an incident with a procedure and a briefing while the hazard stays reachable.+- Let the recordability decision wait on the medical outcome while a reporting clock runs.+- Tie a site bonus to an injury rate, which buys silence rather than safety.+- Isolate a machine without verifying the isolation by attempting a start.+- Treat a near-miss report as a problem with the reporter.diff --git a/verticals/industrial/skills/operations/maintenance-and-reliability/SKILL.md b/verticals/industrial/skills/operations/maintenance-and-reliability/SKILL.mdnew file mode 100644index 0000000..665ec7f--- /dev/null+++ b/verticals/industrial/skills/operations/maintenance-and-reliability/SKILL.md@@ -0,0 +1,100 @@+---+name: maintenance-and-reliability+description: Keeps production assets available — ranking equipment by consequence of failure, setting preventive and predictive intervals, sizing spares, and moving a plant off reactive maintenance. Use this to build or fix a maintenance program, decide what to put on a PM schedule, diagnose repeat failures on one asset, justify spares inventory, or work out why a plant that maintains everything still has unplanned downtime.+---++# Maintenance and reliability++A plant that maintains everything equally maintains the wrong things. Maintenance effort is finite,+and spending it evenly across assets means the machine whose failure stops the line gets the same+attention as the one with three spares in the cabinet.++## Rank by consequence, not by age or cost++The question is not how likely a machine is to fail. It is what happens when it does.++Rank every asset on what its failure costs: production stopped, product scrapped, a safety event, a+regulatory exposure, or nothing anyone notices before the next shift. That ranking, not the capital+value, decides where preventive effort goes.++Two things this exposes immediately in most plants:++- **Assets with no redundancy and no spare** — the ones that will stop the plant and keep it stopped+ while a part ships. These are the whole list worth arguing about.+- **Assets on a PM schedule for no reason** — inherited from a manual, consuming hours, preventing+ nothing that would have mattered.++## Not everything wears out++The intuition behind interval-based maintenance is that failure probability rises with age, so+replacing on a schedule beats waiting. That holds for things that genuinely wear — belts, bearings,+seals, tooling, anything in contact.++It does not hold for most electronics, instrumentation and control systems, where failure rate is+roughly flat with age and intervention is itself a source of failure. Scheduled replacement of a+component that does not wear out converts a stable asset into one that gets disturbed on a cycle,+and introduces the installation errors that follow every disturbance.++So the interval has to be chosen by failure mode:++1. **Wears predictably** → interval-based replacement, set from observed life rather than the+ manual's default.+2. **Degrades observably** → condition-based. Vibration, thermal, oil analysis, current draw. Replace+ on the signal rather than the calendar.+3. **Fails randomly, consequence low** → run to failure, deliberately, with the decision recorded so+ it does not read as neglect.+4. **Fails randomly, consequence high** → redundancy or detection, because no interval helps.++Option 3 is a legitimate strategy and it is the one nobody writes down, which is why it gets+mistaken for the program failing.++## The backlog is the leading indicator++Downtime is a lagging measure. By the time it moves, the condition that produced it has been present+for months.++The honest leading indicator is the state of the planned-work backlog: how much identified work is+waiting, how old the oldest item is, and what fraction of the week's hours went to work that was+planned before the week started. A plant doing 80% planned work is in a different regime from one+doing 30%, and the second cannot schedule production reliably no matter how good its scheduler is.++The reactive trap is self-sustaining. Unplanned failures consume the hours that would have prevented+the next ones, so the ratio degrades on its own. Breaking it costs a deliberate, temporary+over-allocation to planned work while the backlog is worked down, and that is a decision someone has+to fund rather than a habit the team can adopt.++## Spares are an availability decision priced as inventory++A spare is bought against a downtime cost, not against a usage rate, which is why usage-based+reorder logic gets critical spares wrong in both directions. The part used twice a year sits at zero+and the plant waits six weeks for it.++Size the critical few on lead time and consequence: what it costs per day stopped, multiplied by the+realistic days to obtain. Everything else can run on consumption. Say which list each part is on,+because the finance conversation about slow-moving inventory will otherwise delete the critical+ones first — they are, by design, the parts that never move.++## Tooling++A computerized maintenance management system is the asset register, the work order history and the+PM schedule in one place. Fiix, Limble, UpKeep, eMaint, IBM Maximo and similar differ mostly in how+much configuration they demand; the failure mode is identical across all of them, which is a system+populated with assets and never with completed work orders. History is the entire value — without it+there is no observed failure interval and every PM stays at the manual's default.++Condition monitoring is a sensor and analysis decision before it is a software one. Portable+vibration and thermal instruments on a route cover most plants. Permanently installed monitoring on+a machine ranked at the top of the consequence list pays; installed everywhere it becomes a data+stream nobody reads.++Where the ERP holds the asset master — SAP PM, Oracle, Infor and similar — keep one register rather+than two. A maintenance system with its own asset list diverges from the financial one within a+year, and then neither is trusted.++## Never++- Put an asset on a preventive schedule without naming the failure mode it prevents.+- Treat repeat failures on one asset as bad luck rather than as an unfixed cause.+- Let unplanned work consume the hours allocated to planned work and call the ratio a result.+- Judge a maintenance program on downtime alone, which moves months after the cause does.+- Cut a critical spare because it has not moved.diff --git a/verticals/industrial/skills/operations/production-management/SKILL.md b/verticals/industrial/skills/operations/production-management/SKILL.mdnew file mode 100644index 0000000..8888fe5--- /dev/null+++ b/verticals/industrial/skills/operations/production-management/SKILL.md@@ -0,0 +1,105 @@+---+name: production-management+description: Runs the production schedule — sequencing and releasing work, managing work in process and changeovers, and holding the promised date when the floor and the order book disagree. Use this to build or fix a production schedule, decide what to run next, diagnose why lead times are growing while machines look busy, set up OEE or throughput measurement, or choose between make-to-stock and make-to-order for a product line.+---++# Production management++The schedule is a promise made to a customer using capacity you do not fully control. Most plants+that miss dates are not short of machine hours. They are running a sequence that maximizes+utilization on each machine and no one is accountable for the order.++## Sequence is the decision, not the loading++Loading answers how much work a resource has. Sequence answers what the customer gets and when, and+it is the part usually left to whoever is standing at the machine.++Two sequences with identical total hours produce very different outcomes:++- **Grouped by setup** — run everything in the same color, material or die together. Maximizes+ machine output, and pushes any order that does not fit the current group to the back.+- **Grouped by due date** — run what is owed soonest. Protects dates, and pays for it in changeovers.++Neither is correct in general. What is not acceptable is the choice being made implicitly, shift by+shift, by someone with no view of the order book. Decide the rule, write it down, and state what+overrides it — because something always will, and an unstated override is how a schedule quietly+stops meaning anything.++## Work in process is the lead time++Little's Law is the whole of it: lead time equals work in process divided by throughput. Releasing+more work into a plant that is already full does not make anything come out sooner. It lengthens+every job on the floor, including the one that was on time.++The practical consequence is that **release is a control and most plants do not use it as one**.+Work is released when the order arrives or when the paperwork clears, and the floor absorbs it.+Capping releases against a work-in-process target feels like doing less and shortens quoted lead+times measurably.++The tell that release is uncontrolled: expediting works. If pushing a job to the front reliably+gets it out, there is enough queue on the floor to hide the cost, and someone else's date moved.++## Changeover is capacity you can buy back++Setup time is usually treated as fixed, so the response to losing capacity to it is longer runs,+which raises inventory and lengthens lead times for everything else.++Attack the setup instead. Separate the work that can be done while the machine is still running —+staging material, pre-setting tooling, moving the next die to the press — from the work that+genuinely requires it stopped. Most first attempts find that a third or more of the setup did not+need the machine idle. That recovered time is real capacity, and it costs nothing.++The second-order effect matters more than the recovered hours: cheaper changeovers make small runs+viable, which makes due-date sequencing affordable, which is what protects the promise.++## OEE tells you where, not whether++Overall equipment effectiveness multiplies availability, performance and quality. Its value is the+decomposition — a line at 60% for three different reasons needs three different fixes.++Two ways it misleads:++- **On a non-bottleneck it is noise.** Improving OEE on a resource that is not constraining output+ produces inventory, not throughput. Measure it where the constraint is.+- **It rewards running.** A line kept running to protect the number, making parts nobody ordered,+ scores well. Pair it with schedule adherence or it will quietly optimize for the wrong thing.++Throughput at the constraint, plus on-time delivery, answers the business question. OEE answers the+engineering question underneath it.++## Make-to-stock and make-to-order are a lead-time decision++The choice is between holding inventory and holding the customer waiting, and it is made per product+family rather than per plant.++Make-to-stock where demand is predictable, the item is standard, and the customer's tolerance for+waiting is shorter than the production lead time. Make-to-order where variety is high, the item+carries customer-specific content, or obsolescence risk is real.++The hybrid is usually the right answer and rarely stated: hold the common part as stock, finish to+order. That moves the decoupling point as late as possible, which is where inventory is cheapest and+most flexible. `operations:capacity-and-demand-planning` holds the demand side of this decision.++## Tooling++Scheduling and shop-floor execution is where an ERP is either doing the work or being worked around.+SAP, Oracle NetSuite, Epicor Kinetic, Infor CloudSuite Industrial, Odoo and similar carry the order+book, routings and material availability, and the schedule should come from the same system that+knows whether the material is there.++Finite-capacity scheduling — PlanetTogether, Preactor, Opcenter APS and similar — earns its place+where sequence-dependent setups, shared tooling or constrained labor make the ERP's infinite-capacity+plan fiction. Below that complexity a well-maintained spreadsheet with a stated sequencing rule beats+a scheduler nobody trusts.++Machine-level data collection sits underneath OEE. At scale, a manufacturing execution system;+below it, a tablet at the line and an honest downtime reason code list are enough to find the top+three causes, which is all the first year needs.++## Never++- Release work into a full plant because the order arrived.+- Let sequence be decided at the machine by whoever is standing there.+- Improve utilization on a resource that is not the constraint and call it capacity.+- Quote a lead time from routed hours rather than from observed work in process.+- Report a schedule as met after the dates were moved to match what shipped.diff --git a/verticals/industrial/skills/people/labor-and-union-relations/SKILL.md b/verticals/industrial/skills/people/labor-and-union-relations/SKILL.mdnew file mode 100644index 0000000..623e12d--- /dev/null+++ b/verticals/industrial/skills/people/labor-and-union-relations/SKILL.md@@ -0,0 +1,100 @@+---+name: labor-and-union-relations+description: Manages the relationship with a represented workforce — administering a collective agreement, handling grievances, understanding what supervisors may and may not say, and preparing for bargaining. Use this for a grievance or arbitration question, a work rule change in a represented unit, supervisor guidance during organizing, contract interpretation and past practice, or preparation for negotiations.+---++# Labor and union relations++A collective agreement is a contract that constrains management rights for its term. Most disputes+are not about its words. They are about something a supervisor did that the words did not obviously+cover, and about what the plant has done for the last five years.++This is jurisdiction-specific law with real consequences. Treat what follows as the structure of the+problem and the vocabulary for the conversation, and involve qualified labor counsel before acting+on anything contested.++## Past practice is part of the agreement++The written agreement is not the whole of it. A practice that is consistent, known to both sides,+repeated over time and unchallenged becomes enforceable, and changing it unilaterally is a common+route to a grievance the employer loses despite the contract language being on its side.++This cuts both ways and is worth auditing before it matters. Informal accommodations — the early+finish before a holiday, the overtime that always goes to the same crew, the break taken at the+machine — are being accrued as practice whether or not anyone intended it.++When you want to end one, end it explicitly and at the bargaining table or through the notice the+agreement requires. Ending it quietly is the version that costs.++## The grievance procedure is a pressure valve, and it works++Grievances escalate through fixed steps with fixed clocks, ending in arbitration. Two habits+determine whether the system absorbs disputes or accumulates them:++- **Answer at the earliest step you can.** A grievance settled by the supervisor who caused it costs+ a conversation. The same grievance at step three costs two managers, a business agent and a+ written record that becomes precedent.+- **Answer in writing, on the merits, within the clock.** Missing a time limit can decide the case+ without the merits being reached, and a vague answer preserves nothing for later.++Settle explicitly as non-precedential when that is what you mean, in writing. A settlement that does+not say so is the past practice of the next dispute.++Read arbitration honestly before filing or resisting: the question an arbitrator answers is narrow,+and "we were within our rights" loses regularly to "that is not how this plant has operated."++## What a supervisor says is the employer speaking++During an organizing campaign, and generally, a front-line supervisor's offhand remark is attributed+to the employer and is the most common source of unfair labor practice exposure. The exposure comes+from four categories, and they are worth teaching as four:++- **Threats** — any suggestion of a consequence tied to union activity. Including "we'd probably+ have to look at the shift premium."+- **Interrogation** — asking who signed, who attended, or how someone will vote.+- **Promises** — a new benefit offered or hinted at during a campaign, which is unlawful even when+ it was already planned.+- **Surveillance** — watching or appearing to watch meetings, or monitoring who talks to whom.++The protection of concerted activity is broader than union membership: two unrepresented employees+discussing pay are engaged in it, and a policy forbidding discussion of wages is a problem+independent of any union. `people:employee-relations` covers the individual-employee side of this.++## Bargaining obligations do not wait for negotiations++Where a mandatory subject is involved — pay, hours, and terms and conditions of employment — the+obligation to bargain applies to changes during the term, not only at renewal. Scheduling systems,+attendance policies, subcontracting bargaining-unit work, plant relocations and new monitoring+technology land here more often than managers expect.++The sequence that keeps this clean is notice, an opportunity to bargain, and then implementation —+in that order, with the notice documented. Implementing first and negotiating the complaint+afterwards is the path that produces a make-whole remedy.++In preparation for a renewal, cost every proposal over the full term with the compounding stated,+and know the two or three items the other side cannot return without. Those are what the agreement+will be settled on, and everything else is trading stock.++## Tooling++Labor relations runs on records, and the records are the case. A grievance log with dates, steps,+clocks, outcomes and whether each settlement was precedential is the single highest-value artifact,+and a spreadsheet maintained without fail beats a module maintained occasionally. Case management in+UKG, Dayforce, HR Acuity and similar earns its place where volume makes the clocks unmanageable by+hand.++Seniority, bidding, shift assignment and overtime distribution are where a represented unit and a+generic HRIS collide, because the rules are contractual rather than configurable. Confirm the system+can express the agreement before it becomes the system of record, or the plant will run the real+rules in a parallel spreadsheet and the two will disagree in front of an arbitrator.++Keep the current agreement, every memorandum of understanding and every side letter in one indexed+place. The document that decides a grievance is usually not the one in the binder.++## Never++- Change a long-standing practice quietly and expect the contract language to carry it.+- Let a grievance time limit pass without a written answer on the merits.+- Let a supervisor answer questions about union activity without guidance in advance.+- Implement a change to a mandatory subject and offer to discuss it afterwards.+- Settle a grievance without stating in writing whether it sets precedent.diff --git a/verticals/industrial/vertical.toml b/verticals/industrial/vertical.tomlnew file mode 100644index 0000000..97197bc--- /dev/null+++ b/verticals/industrial/vertical.toml@@ -0,0 +1,38 @@+# The industrial vertical: manufacturing, production, print and fulfillment operations.+#+# Chosen as the first vertical because it is the one that can be checked against reality — D10+# records the operating businesses behind this repository as print, fulfillment and production+# work, and D7 resolved that verticals are built for own use before they are productized. A+# vertical nobody in the room can judge is a vertical whose quality nobody can judge.+#+# This file says what the vertical *is*. What it *adds* is discovered on disk: skills under+# skills/<department>/<skill>/SKILL.md, and extensions to core skills under+# context/<department>/<skill>.md. Nothing is listed twice.++[vertical]+slug = "industrial"+name = "headcount-industrial"+title = "Industrial"+tagline = "An agent organization for companies that make and ship physical things — the full cross-industry core, plus the plant floor."+description = "An agent organization for manufacturing, production, print and fulfillment operations. Each department installs independently so only the relevant function loads."+keywords = ["manufacturing", "production", "industrial", "plant-operations"]+rationale = """+The core is deliberately cross-industry: it covers the company, not the factory. That is the right+default, and it is also why a plant manager asking a core skill about capacity gets an answer about+service queues.++This vertical keeps every core skill and adds the part the core leaves out on purpose — production+scheduling, maintenance and reliability, safety as a regulated obligation rather than a value, and+the employment relationship as it exists on a shop floor. Where a core skill is right in shape but+thin on the plant floor, the vertical extends it in place rather than forking it, so an improvement+to the core still reaches this repository on the next emit.+"""++[repo]+url = "https://github.com/cbrock84/headcount-industrial"+upstream = "https://github.com/cbrock84/headcount"++[emit]+# Every core department ships. Nothing about demand generation or product stops applying to a+# manufacturer, and D8's rule against removing a surface because it looks unused applies here too.+exclude_departments = []