Skip to content

docs(platform-glossary): resolve "the operator" and the crew vocabulary clash - #59

Merged
ductiletoaster merged 1 commit into
mainfrom
docs/glossary-operator-and-crew
Aug 16, 2026
Merged

docs(platform-glossary): resolve "the operator" and the crew vocabulary clash#59
ductiletoaster merged 1 commit into
mainfrom
docs/glossary-operator-and-crew

Conversation

@ductiletoaster

Copy link
Copy Markdown
Member

Closes the glossary half of A0.4 in the PixelOven Agent Stack Program Plan (requirement G-7).

Why

PixelOven is standing up a component literally named operator — a soft fork of kunchenguid/firstmate, now at pixeloven/operator (private). That creates two vocabulary collisions the foundation should own rather than a consumer, because both appear in agent-facing instructions rather than in one project's docs.

1. "the operator" is a person, not a program

Escalation instructions across the fleet say "ask the operator", "the operator approves", "escalate to the operator". These always mean a human. An agent that resolves them to a program name does something plausible and wrong — the worst failure shape available.

The rule added:

  • Prose keeps "the operator" for the human, unqualified and unhedged, so the existing corpus stays correct by default.
  • A project named operator is always code-styled (operator) and never capitalized. Capitalization cannot carry the distinction, because it is invisible at the start of a sentence — exactly where "The operator should…" appears.
  • Kubernetes operators are noted as a third sense.

2. "crew" now means two different things

Vocabulary "crew" is the human is a worker is
this foundation the set of agent roles the operator a dispatched role
firstmate lineage the fleet of dispatched worker processes the captain a crewmate / secondmate

The load-bearing rule: do not translate between them silently. A firstmate crewmate is a running process in a git worktree; a foundation crew role is a declarative capability definition. They are not the same kind of thing, and one does not implement the other.

It also states explicitly that "the captain" and "the operator" denote the same human, so a third name for that person never gets invented.

Contribution rules honoured

  • .claude-plugin/plugin.json and package.json bumped 0.22.00.23.0 (additive skill content), per the version-bump CI gate.
  • docs/CATALOG.md regenerated for the updated frontmatter description.
  • Ran locally, all green: check_skills.py, render_roles.py --check, check_skill_refs.py, gen_catalog.py --check, and the templates YAML parse.

Scope

Additive only — one skill, no role definitions touched, no behavior changed.

…ry clash

Two additions to the shared vocabulary, both prompted by PixelOven adopting a
component literally named `operator` (a soft fork of kunchenguid/firstmate).

1. "the operator" is a person, not a program. Escalation instructions across
   the fleet say "ask the operator" / "escalate to the operator" and always
   mean a human. An agent reading that as a program name does something
   plausible and wrong. Rule: prose keeps "the operator" for the human,
   unqualified; a project named operator is always code-styled and never
   capitalized (capitalization is invisible at the start of a sentence, which
   is exactly where "The operator should…" appears). Kubernetes operators noted
   as a third sense.

2. "crew" now means two things in our working context. This foundation's crew
   = the set of agent ROLES, with the human as "the operator". The
   firstmate lineage's crew = the fleet of dispatched WORKER PROCESSES, with
   the human as "the captain" and workers as crewmates/secondmates. Added a
   comparison table and the rule not to translate between them silently — a
   crewmate is a running process, a crew role is a declarative definition.
   Also states that "the captain" and "the operator" are the same human.

Bumps plugin.json + package.json 0.22.0 -> 0.23.0 per the CI version-bump gate,
and regenerates docs/CATALOG.md for the updated description.

Task: A0.4 · Requirement: G-7

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01AWb1wJP3sD5oUbBrvSQ2UC
@ductiletoaster
ductiletoaster merged commit c424886 into main Aug 16, 2026
8 checks passed
@ductiletoaster
ductiletoaster deleted the docs/glossary-operator-and-crew branch August 16, 2026 17:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant