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.

Add CONTRIBUTING.md and record D21: staying MIT

Chris Brock492101ff3e9c
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..2317374
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,90 @@
+# Contributing
+
+Contributions are welcome. This document covers the licence, the bar for a skill, and the checks.
+
+## Licence
+
+**By submitting a contribution you agree it is licensed under the [MIT Licence](LICENSE), the same
+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.
+
+## What makes a good skill
+
+A skill is judged twice: whether it loads at the right moment, and whether it helps once loaded.
+
+**The description does the triggering.** It is the only part read when deciding whether to load. Lead
+with what the skill does, then when to reach for it — in the words someone would actually use,
+including the oblique ones. Vague descriptions fail twice over: they miss cases they should catch
+and fire on cases they cannot help.
+
+**The body does the work.** Write for someone competent who has not thought about this problem
+today:
+
+- **Method over exhortation.** "Be thorough" is noise; an ordered procedure is instruction.
+- **State the failure behind each rule.** A rule with no failure attached gets optimized away by the
+ next reader.
+- **Be specific enough to be wrong.** Guidance too hedged to contradict is too vague to follow.
+- **Long material goes in `references/`**, with the body saying when to read it.
+
+**Where a skill touches regulated ground** — law, privacy, compensation, medical, financial, or
+safety advice — say plainly what it structures and what needs qualified professional input. Skills
+that sound authoritative and are subtly wrong in these areas cause real harm, because they get
+trusted.
+
+Read `technology:skill-authoring` for the full treatment, and `executive:agent-hierarchy` for why
+departments are split by exclusive write surface rather than by topic.
+
+## Before opening a pull request
+
+```
+./scripts/check-all.sh
+```
+
+Four checks, the same ones CI runs:
+
+| Check | What it enforces |
+|---|---|
+| 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 |
+| 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
+to it — the check will pass and then fail once committed. The script warns when untracked files are
+present.
+
+## Adding a skill
+
+1. `plugins/<department>/skills/<skill-name>/SKILL.md`
+2. Frontmatter `name` must equal the directory name.
+3. Check nothing already covers the ground. Two skills whose descriptions both match a request means
+ neither reliably wins — prefer extending an existing skill, or folding a family into one skill
+ with references, over adding a near-neighbour.
+
+## Adding a department
+
+All four, 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`
+
+Give it a chief before any specialists — the department's remit should exist before things are added
+to it.
+
+## Adding a file outside `plugins/`
+
+It needs an owner in `docs/AGENT-SURFACES.md`, or the surface check fails. Most such files belong to
+`repo-meta`.
+
+## Decisions
+
+Choices with more than one defensible answer go in `docs/DECISION-LOG.md`, numbered. A number is
+assigned when the question is raised, not when it is answered, and is never reused. Every entry
+carries lettered options and an explicit recommendation.
diff --git a/docs/AGENT-SURFACES.md b/docs/AGENT-SURFACES.md
index 7bc75b6..9895a50 100644
--- a/docs/AGENT-SURFACES.md
+++ b/docs/AGENT-SURFACES.md
@@ -99,6 +99,7 @@ plugins/security/**
```surface:repo-meta
LICENSE
+CONTRIBUTING.md
docs/**
scripts/**
.github/**
diff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.md
index 632b89e..09fc89e 100644
--- a/docs/DECISION-LOG.md
+++ b/docs/DECISION-LOG.md
@@ -477,3 +477,50 @@ The list, in order of value:
**Recommendation: (b).** 1–3 matter; 4 is preference; 5 is worth doing only if you want the profile
to lead with this.
+
+## D21. MIT or Apache-2.0 for the long term — ✅ Resolved
+
+Raised while preparing to publish. Apache-2.0 is the usual alternative to MIT for a project intended
+for wide reuse.
+
+**What Apache-2.0 adds over MIT:** an explicit patent grant with a retaliation clause, an explicit
+trademark carve-out, a requirement that modified files carry a notice of change, and automatic terms
+for inbound contributions.
+
+- **(a) MIT.** ← **chosen**
+- (b) Apache-2.0.
+- (c) A content licence such as CC-BY-4.0.
+- (d) Dual — CC-BY for the prose, MIT for the scripts.
+
+**Resolution: (a).** The reasoning, recorded so it is not re-litigated:
+
+- **The patent grant is Apache's headline feature and is near-irrelevant here.** This repository is
+ markdown. Instructions for running a threat model or a CRO audit are not patentable subject matter
+ in any practical sense, so the protection Apache exists to provide has almost nothing to attach to.
+- **Apache §4(b) is active friction for the intended use.** It requires modified files to carry
+ prominent change notices. The whole design is people installing a department and adapting it; MIT
+ lets them, Apache asks them to annotate every file they touch.
+- **MIT is the ecosystem norm.** Every collection this repository originally drew from was MIT, and
+ the Claude skills and plugins ecosystem is MIT by convention. Lower friction, fewer legal reviews.
+- **Short licences get complied with.** Two hundred lines of licence on a prose repository invites
+ the question of whether anyone read it.
+- **(c) and (d) rejected:** Creative Commons explicitly advises against using CC for software, this
+ repository contains executable scripts alongside the prose, and a split licence confuses tooling
+ and adopters for no practical gain.
+
+**The one real gap MIT leaves** — what licence inbound contributions carry — is closed by
+`CONTRIBUTING.md` stating that contributions are accepted under MIT, rather than by changing the
+licence.
+
+**Timing note, which is the part that matters later.** Relicensing is clean only while there is a
+single copyright holder. Once outside contributions land under MIT, you cannot retroactively un-MIT
+what has been published; you would be layering Apache over MIT-licensed parts, which is lawful but
+messy. So this decision is cheap to reverse **today** and expensive to reverse after the first
+external pull request.
+
+**Revisit if** the repository grows substantial executable code — the vertical generator in D8 is the
+plausible candidate — or if a corporate adopter's legal team specifically asks for the patent grant.
+Neither is true now.
+
+**Not legal advice.** For the productized vertical variants contemplated in D8, where money and
+third-party distribution are involved, this is worth qualified counsel rather than a decision log.