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
Add an authority axis to the surface map
Claude9f3436ca70a8
diff --git a/docs/AGENT-SURFACES.md b/docs/AGENT-SURFACES.mdindex 507518c..d39bdfc 100644--- a/docs/AGENT-SURFACES.md+++ b/docs/AGENT-SURFACES.md@@ -14,34 +14,62 @@ and "UI" both end up in the same token file, and neither is wrong.The orchestrator is neither: it owns no surface and is the sole committer.+## Authority++The class and the surface together answer *where* an agent may write. They have never answered+whether that write may land without a decision, so in practice that was settled per dispatch, from+memory, by whoever was driving. Authority states it once, in the same row, and `check` verifies it.++- **autonomous** — dispatch it and take the result. The surface is the only gate needed.+- **proposes** — it may do the work; the orchestrator surfaces the diff before landing it.+- **escalates** — do not dispatch it unasked. The work itself is the decision.++Two things the check enforces, both because the row would otherwise read as governed while+governing nothing: a reviewer may not be gated, because it holds no write surface to gate; and a+gated builder must actually own a surface.++Almost every row here is `autonomous`, and that is the honest answer rather than a placeholder — a+department writes only inside its own plugin directory, where the worst case is a bad skill in one+department. The column exists because the one exception is real, and because a repository adopting+this map will have more of them than this one does.+## Roster```roster-# id class status-executive builder installed-technology builder installed-product builder installed-marketing builder installed-demand-generation builder installed-revenue builder installed-finance builder installed-operations builder installed-people builder installed-legal-risk builder installed-customer-experience builder installed-data-analytics builder installed-corporate-strategy builder installed-security builder installed-it-operations builder installed-pmo builder installed-repo-meta builder installed-legal-risk-review reviewer installed-security-review reviewer installed-```+# id class status authority+executive builder installed autonomous+technology builder installed autonomous+product builder installed autonomous+marketing builder installed autonomous+demand-generation builder installed autonomous+revenue builder installed autonomous+finance builder installed autonomous+operations builder installed autonomous+people builder installed autonomous+legal-risk builder installed autonomous+customer-experience builder installed autonomous+data-analytics builder installed autonomous+corporate-strategy builder installed autonomous+security builder installed autonomous+it-operations builder installed autonomous+pmo builder installed autonomous+repo-meta builder installed proposes+legal-risk-review reviewer installed autonomous+security-review reviewer installed autonomous+```++`repo-meta` is the exception because of what it owns: the CI workflows, the check scripts, the+generators every document is built from, and this map. A change inside `plugins/finance/**` is+wrong in one department. A change to `scripts/check-all.sh` can make every other check stop+reporting, and nothing downstream would fail to say so.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.+The column may be omitted; an omitted authority means `autonomous`, and `check` reports which rows+defaulted so that a map which never considered the question is distinguishable from one that+answered it.+## Surfaces```surface:executivediff --git a/docs/DECISION-LOG.md b/docs/DECISION-LOG.mdindex 61dc2a5..f328487 100644--- a/docs/DECISION-LOG.md+++ b/docs/DECISION-LOG.md@@ -952,3 +952,45 @@ toward manufacturing, logistics and retail, so they go to the verticals too.**Remaining Tier 1**, recorded in the org chart's gaps section: customer experience depth, legaldepth, corporate strategy depth, and product discovery and prioritization. None is a missingfunction; all are thin coverage of a function already present.++---++## D31. Authority as a second axis on the surface map — ✅ Resolved++The surface map answers where an agent may write. It has never answered whether that write may+land without a decision, and the two are not the same question. In practice the second one was+settled per dispatch, from memory, by whoever happened to be driving — which is the condition the+surface map itself exists to eliminate.++- **(a) A fourth roster column, checked by the guard.** ← **chosen**+- (b) State it in each charter. Prose inside the agent being governed; nothing checks it, and it is+ invisible at the moment it matters, which is the dispatch.+- (c) Infer it from class. Conflates "cannot write" with "may not land unreviewed" — a reviewer is+ ungated precisely because it cannot write, and a builder's blast radius has nothing to do with+ its class.+- (d) Leave it implicit. The status quo, and the reason this was raised.++**Resolution:** (a). Three values — `autonomous` (dispatch it and take the result), `proposes` (the+orchestrator surfaces the diff before landing it), `escalates` (do not dispatch it unasked; the+work itself is the decision).++**Eighteen of nineteen rows are `autonomous`, and that is the honest answer rather than a+placeholder.** A department writes only inside its own plugin directory, where the worst outcome is+a bad skill in one department. Marking rows gated to make the column look load-bearing would be the+decoration this repository rejects everywhere else.++**The one exception is `repo-meta`, and it is a real one.** It owns the CI workflows, the check+scripts, every generator the documents are built from, and the surface map itself. A wrong change+under `plugins/finance/**` is wrong in one department. A wrong change to `scripts/check-all.sh` can+make every other check stop reporting, and nothing downstream would fail to say so. That is the+shape of thing worth a checkpoint.++**Two invariants are enforced rather than described**, both catching a row that reads as governed+while governing nothing: a reviewer may not be gated, because it holds no write surface to gate;+and a gated builder must own a surface. Both were verified against deliberately broken maps rather+than assumed — an unproven guard is a comment claiming to be a guard.++**Existing maps keep working.** The column is optional and omission means `autonomous`, but `check`+reports which rows defaulted, so a map that never considered the question stays distinguishable+from one that answered it. The value here is not the single gated row; it is that the axis is now+expressible and checked instead of remembered — the same argument that justified the surface map.diff --git a/plugins/executive/skills/agent-hierarchy/SKILL.md b/plugins/executive/skills/agent-hierarchy/SKILL.mdindex 14eefd4..561eaed 100644--- a/plugins/executive/skills/agent-hierarchy/SKILL.md+++ b/plugins/executive/skills/agent-hierarchy/SKILL.md@@ -14,7 +14,10 @@ Split agents by **write surface, not by topic**. Two classes only: **builders**,inside exactly one exclusive surface and never commit, and **reviewers**, which are permanentlyread-only and can always run in parallel. The orchestrator — the main chat — is the solecommitter. Write the surface map **before** any charters, keep it in one Markdown file, and-enforce it with a script that runs in CI. Producer and auditor are never the same agent. For+enforce it with a script that runs in CI. Each row also carries an **authority** — `autonomous`,+`proposes`, or `escalates` — which answers the separate question of whether that agent's work may+land without a decision; most rows are `autonomous`, and gating everything makes the gate+meaningless. Producer and auditor are never the same agent. Foreach class of fact, exactly one file owns it and everyone else derives.## Why topic splits faildiff --git a/plugins/executive/skills/agent-hierarchy/references/playbook.md b/plugins/executive/skills/agent-hierarchy/references/playbook.mdindex 735de5e..5225c71 100644--- a/plugins/executive/skills/agent-hierarchy/references/playbook.md+++ b/plugins/executive/skills/agent-hierarchy/references/playbook.md@@ -73,11 +73,11 @@ trying to prevent.````markdown```roster-# id class status-core-owner builder installed-ios-builder builder installed-store-compliance reviewer installed-telemetry reviewer planned+# id class status authority+core-owner builder installed proposes+ios-builder builder installed autonomous+store-compliance reviewer installed autonomous+telemetry reviewer planned autonomous``````surface:ios-builder@@ -94,6 +94,24 @@ apps/ios/****Semantics.** One glob per line. Leading `!` excludes. **Later lines win over earlierones.** A path may be claimed by exactly one owner.+**The fourth roster column is authority**, and it answers the question the surface cannot:+not *where* the agent may write, but whether that write may land without a decision.++| Authority | Meaning |+|---|---|+| `autonomous` | Dispatch it and take the result. The surface is the only gate needed. |+| `proposes` | It may do the work; the orchestrator surfaces the diff before landing it. |+| `escalates` | Do not dispatch it unasked. The work itself is the decision. |++Most rows are `autonomous` and should be — gate everything and the gate stops meaning+anything. Reserve it for surfaces where the blast radius escapes the surface: the build and+release path, dependency manifests, anything the other agents' checks run through. In the+example above `core-owner` is gated because every consumer compiles against what it changes.++Omitting the column means `autonomous`, so existing maps keep working; `check` reports which+rows defaulted, because a map that never asked the question should be distinguishable from+one that answered it.+| Pattern | Matches ||---|---|| `**/` | any number of leading segments, including none |@@ -135,7 +153,10 @@ So: every claim in the map is checked against `git ls-files` on every PR.write anywhere; a row still marked `planned` whose charter has landed is a lie aboutwhat is dispatchable.4. **A reviewer declares no write surface.**-5. **Decision numbers are unique.** Two concurrent sessions both claiming `D14` merges+5. **Authority matches the surface the row holds.** A gated reviewer reads as governed while+ being the one row that never needed governing — it cannot write at all. A gated builder+ owning no surface has a checkpoint on an empty set. Both fail.+6. **Decision numbers are unique.** Two concurrent sessions both claiming `D14` mergescleanly in git and fails nothing — which is precisely why it needs a guard and not aconvention. *(Tune this assertion's regex to your own log format; the shipped onematches `### D<number>` headings.)*diff --git a/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs b/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjsindex c76afd6..d88a4d0 100644--- a/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs+++ b/plugins/executive/skills/agent-hierarchy/scripts/agent-guard.mjs@@ -28,6 +28,26 @@ const DECISION_LOG = process.env.AGENT_DECISIONS ?? 'docs/DECISION-LOG.md';/** The orchestrator is not an agent. It owns the context artifacts and commits everything. */const ORCHESTRATOR = 'orchestrator';+/* ── Authority ────────────────────────────────────────────────────────────────+ * The surface map answers *where* an agent may write. It has never answered whether+ * that write may land without a human seeing it, so in practice that was decided per+ * dispatch, from memory, by whoever was driving. Authority is the second axis, stated+ * once in the map and checked like everything else.+ *+ * autonomous dispatch it and take the result; the surface is the only gate needed+ * proposes it may do the work, but the orchestrator surfaces the diff before landing+ * escalates do not dispatch it without being asked to; the work itself is the decision+ *+ * Rows may omit the column. Omission means `autonomous` — the behavior every existing map+ * already had — and is reported as a note so a map that never considered the question is+ * distinguishable from one that answered it.+ */+const AUTHORITY = ['autonomous', 'proposes', 'escalates'];+const DEFAULT_AUTHORITY = 'autonomous';++/** Gated rows are the ones whose output the orchestrator may not simply take. */+const isGated = (row) => row.authority !== 'autonomous';+/* ── Glob → RegExp ────────────────────────────────────────────────────────────* Hand-rolled on purpose. A matcher dependency here buys four metacharacters and* costs you a supply-chain review on the one file whose job is enforcing rules.@@ -82,7 +102,7 @@ const ownersOf = (owners, file) => owners.filter((o) => claims(o, file)).map((o)* Two fenced-block kinds inside an ordinary Markdown file, so the map stays readable* as documentation and parseable as config. One file, not two that can disagree.*- * ```roster <id> <builder|reviewer> <installed|planned>+ * ```roster <id> <builder|reviewer> <installed|planned> [authority]* ```surface:<id> one glob per line; `!` prefix excludes*/function fencedBlocks(src) {@@ -105,12 +125,24 @@ export function parseSurfaceMap(src) {for (const { info, body } of fencedBlocks(src)) {if (info === 'roster') {for (const line of significant(body)) {- const [id, klass, status] = line.split(/\s+/);+ const cols = line.split(/\s+/);+ const [id, klass, status, authority] = cols;if (!id || !klass || !status) { errors.push(`roster: cannot parse "${line}"`); continue; }+ if (cols.length > 4) { errors.push(`roster: ${id} has ${cols.length} columns, expected at most 4 (id, class, status, authority)`); continue; }if (klass !== 'builder' && klass !== 'reviewer') { errors.push(`roster: ${id} has unknown class "${klass}"`); continue; }if (status !== 'installed' && status !== 'planned') { errors.push(`roster: ${id} has unknown status "${status}"`); continue; }+ if (authority !== undefined && !AUTHORITY.includes(authority)) {+ errors.push(`roster: ${id} has unknown authority "${authority}" — one of ${AUTHORITY.join(', ')}`);+ continue;+ }if (roster.some((r) => r.id === id)) { errors.push(`roster: ${id} listed twice`); continue; }- roster.push({ id, klass, status });+ roster.push({+ id,+ klass,+ status,+ authority: authority ?? DEFAULT_AUTHORITY,+ authorityStated: authority !== undefined,+ });}} else if (info.startsWith('surface:')) {const id = info.slice('surface:'.length).trim();@@ -197,7 +229,30 @@ function check() {}}- // 4. Decision numbers are unique. Two concurrent sessions both claiming D14 merges+ // 4. Authority is coherent with the surface the row actually holds.+ // A reviewer holds no write surface, so gating its writes gates nothing — and a row+ // reading `security-review reviewer installed proposes` looks governed while being+ // the one row that never needed governing. Same failure in the other direction: a+ // builder marked `proposes` that owns no surface has a checkpoint on an empty set.+ for (const r of roster) {+ const owned = owners.find((x) => x.id === r.id);+ const writes = owned ? owned.patterns.some((p) => !p.negated) : false;+ if (r.klass === 'reviewer' && isGated(r)) {+ problems.push(`reviewer ${r.id} declares authority "${r.authority}" — reviewers hold no write surface, so there is nothing to gate`);+ }+ if (r.klass === 'builder' && isGated(r) && !writes) {+ problems.push(`${r.id} declares authority "${r.authority}" but holds no write surface — the gate governs nothing`);+ }+ }++ // A row that never stated an authority is not wrong, but it did not answer the question+ // either. Say so once, the same way a stale glob is said.+ const unstated = roster.filter((r) => !r.authorityStated).map((r) => r.id);+ if (unstated.length) {+ notes.push(`authority not stated on ${unstated.length} row(s), defaulting to ${DEFAULT_AUTHORITY}: ${unstated.join(', ')}`);+ }++ // 5. Decision numbers are unique. Two concurrent sessions both claiming D14 merges// cleanly in git and fails nothing, which is exactly why it needs a guard and not// a convention.if (existsSync(DECISION_LOG)) {@@ -217,8 +272,12 @@ function check() {const builders = roster.filter((r) => r.klass === 'builder').length;const reviewers = roster.filter((r) => r.klass === 'reviewer').length;+ const gated = roster.filter(isGated);for (const n of notes) console.log(` ok ${n}`);console.log(` ok Roster: ${builders} builder(s), ${reviewers} reviewer(s), ${charters.length} charter file(s).`);+ console.log(gated.length+ ? ` ok Authority: ${roster.length - gated.length} autonomous, ${gated.length} gated — ${gated.map((r) => `${r.id} (${r.authority})`).join(', ')}.`+ : ` ok Authority: all ${roster.length} row(s) autonomous.`);if (problems.length) {console.error(`\nAgent surfaces FAILED — ${problems.length} problem(s):`);@@ -268,6 +327,11 @@ function diff(agentId, base) {if (violations.size === 0) {console.log(` ok ${files.length} changed path(s), all inside ${agentId}'s surface.`);+ // Clean is not the same as landable. This is the only moment the distinction is+ // actionable, so it is said here rather than left to whoever remembers the map.+ if (isGated(row)) {+ console.log(` !! ${agentId} authority is "${row.authority}" — surface this diff for a decision before committing it.`);+ }return;}console.error(`\nagents:diff FAILED — ${agentId} changed path(s) outside its surface:`);