Glossary

The terms below are the ones that recur across every other methodology doc. Definitions are curated from ai-engineering-strategy.md Appendix A, updated to reflect implementation reality where it has diverged from v0.4.

A

Actor. A specific AI session running on a specific machine for a specific user. Example: cc-ariel-laptop (Claude Code on Ariel's laptop). Different actors must coordinate via the state-management protocol; same-actor handoffs (laptop ↔ phone) are reconciled without conflict (see state-management.md step 3).

Agent. A detailed expert-knowledge file in .claude/agents/<name>.md, sized 15–25KB, written in the BeWith canonical template (Role → When invoked → Checklist → Output format → Handoff points → Cross-references → optional Anti-patterns) with Anthropic-compliant frontmatter (name, description, tools, model: inherit). 15 agents are planned; the first one (process-guardian) is live. Loaded lazily by the Policy Engine at step 5 of /continue.

AI Context block. A structured markdown block in a GitHub Issue body that holds the authoritative state of an in-progress task (active actor, phase, plan, files touched, decisions, blockers, next step). The local cache and the ClickUp custom field mirror it; the block itself wins all ties. See state-management.md.

Always-autonomous (autonomy category). Actions the AI never pauses for, regardless of any configuration: branch creation, commits to feature branches, push to feature branches, test execution, lint autofix, type check, ClickUp status changes to "In Progress", state-sync updates. See autonomy-model.md.

Autonomy mode. One of three categories the platform assigns to every mutating action: always_require_approval (Hard Floor), configurable_gates (per-user opt-in), or never_ask.

B

Blast radius. The set of users, systems, or developers affected by an action. One of the four criteria for the Hard Floor. An action with blast radius beyond the current actor (e.g. force-push to a shared branch) is a Hard Floor candidate; an action whose blast radius is contained (e.g. reformatting local files) is not.

C

Configurable gate. An action class where the platform default is autonomous but each developer may opt into requiring approval via ~/.claude/user-overrides.yaml. Six gates exist: ClickUp comments, ClickUp status-to-Done, cross-repo PR creation, schema migration, breaking API contract change, large refactor. See autonomy-model.md.

Consumer repository. Any of bewith-dev's 44 active repositories that consumes the bewith-docs platform via the bewith Claude Code plugin. The consumer holds a thin local presence — CLAUDE.md + .github/copilot-instructions.md + a wrapper workflow pinned via uses: …@vN.N.N — and reads the platform's agents/skills/commands/hooks from ~/.claude/plugins/cache/bewith/ (no per-repo copy, no lock file).

CU-id. A ClickUp task identifier matching the pattern CU- followed by ≥6 alphanumeric characters with at least one digit AND one letter. Validated by scripts/checks/check-cu-id.sh (shared by branch-name-check.sh, commit-cu-check.sh, and clickup-commit-check.yml). Placeholders like CU-pending / CU-tbd / CU-xxx / CU-000000 are rejected by design — see [[feedback-no-placeholder-workarounds]].

D

Deterministic AI Engineering. The methodology — the portable philosophy underlying the platform. See deterministic-ai.md. Not the same thing as the platform implementation, which is BeWith-specific.

E

Effective directory (legacy v0.4 term). <consumer>/.claude/effective/ — a per-repo materialised copy of the platform, generated by governance-build.sh at session start. Not used in the current implementation. Replaced by the shared-clone model — see consumption-model.md and Implementation notes in ai-engineering-strategy.md.

Engineering-standards. The platform repo's product name. Materialised inside bewith-dev/bewith-docs today, which holds both the platform (.claude/, policies/, autonomy/, etc.) and the knowledge base (docs/).

Event vocabulary. A markdown document at events/vocabulary.md listing the named events a policy's triggered_by clause can reference (schema.modified, endpoint.added, auth.touched, etc.). It is not an event bus — just a shared vocabulary that keeps policies coherent.

F

Federation. The model where every consumer repo adopts a specific version of the platform — via the bewith plugin's version field installed per developer, plus each repo's wrapper-workflow uses: …@vN.N.N ref pinning the CI logic. Upgrades are explicit; drift is detectable in CI; rollback is one PR. See deterministic-ai.md principle 7.

G

governance.lock.json. (Removed in v0.5.) v0.4 specified a per-consumer pin file with a single key and value. Dropped 2026-05-27 when the platform moved to the plugin model — the plugin's version field + each consumer's wrapper-workflow @ref together cover the same pinning intent without an extra file. The validator workflow and script that consulted it were deleted. See ai-engineering-strategy.md §6.4.

H

Hard Floor. The autonomy category whose items always require explicit human approval, regardless of any developer's per-user override. Seven items, defined by the four criteria (irreversibility, blast radius, no tooling recovery, no reasonable disagreement). Adding to the list requires an ADR. See autonomy-model.md.

Hook. A script that runs at a specific lifecycle event — git events (pre-commit, commit-msg, pre-push) or Claude Code events (PreToolUse, SessionStart, etc.). Git hooks are wired per-repo via scripts/install-git-hooks.sh; Claude Code hooks are declared in settings.json, not auto-discovered. See consumption-model.md for how the platform's hooks reach user-level Claude Code.

L

Lazy loading. Loading only the agents, skills, and knowledge documents the current task requires, instead of the full platform body at session start. Keeps per-session context cost flat (~50KB) even as the platform grows. See deterministic-ai.md principle 2.

Lease. A planned (not yet implemented) mechanism for declaring "I am actively working on this task right now" — distinct from ClickUp ownership which is a static assignment. Designed as a GitHub Issue with label ai-lease, a JSON body describing actor and target, a 30-minute lifetime, and a 10-minute heartbeat. Currently deferred — see ai-engineering-strategy.md §15 note.

N

Never-ask. The autonomy category for actions the AI never pauses for. Eight items, all reversible and low-risk. Lives in autonomy/defaults.yaml.

O

Overlay. The mechanism by which a consumer repo adds or overrides platform content for its own scope. Implemented via Claude Code's native scope priority — project-level files (<consumer>/.claude/...) shadow user-level (~/.claude/...) by name. No custom merge logic. See consumption-model.md.

P

Platform. Shorthand for bewith-dev/bewith-docs, the repo that holds the agents, skills, commands, policies, hooks, configs, and templates that consumer repos rely on. Published as the bewith Claude Code plugin.

Plugin (bewith). The Claude Code plugin manifest at .claude-plugin/plugin.json + the marketplace catalog at .claude-plugin/marketplace.json that publishes bewith-docs for installation. Developers install once via the sandbox CLI; the cache lives at ~/.claude/plugins/cache/bewith/. Lazy loading keeps per-session context small. See consumption-model.md.

Policy. A YAML file in policies/ that maps a trigger (file change, named event, diff size) to required agents, required gates, risk score, auto-workflows, and approval conditions. Validated against policies/schema.json. See policy-engine.md.

Policy Engine. The layer that evaluates all policies against the current task and aggregates the result. The policies live in this repo; the runtime that evaluates them at step 4 of /continue lives downstream (probably in a Claude skill or CLI). See policy-engine.md and Implementation notes in ai-engineering-strategy.md.

R

Risk score. An integer 1–10 each policy returns to indicate the blast radius and reversibility of a change. Aggregated by max across all matched policies. Drives human_approval_required conditions like risk.score >= 7.

S

Shared clone. (Superseded by the plugin model 2026-05-27.) An interim 2026-05-26 design had each developer keep a local clone of bewith-docs and symlink its content into ~/.claude/. The plugin model replaces this — the cache lives at ~/.claude/plugins/cache/bewith/ and is managed by Claude Code itself. See consumption-model.md.

Single Source of Truth (SoT). The one place a given piece of information lives. For task state, the GitHub Issue body. For ClickUp ownership, the ClickUp assignee. For governance rules, the platform repo (bewith-docs). For the platform version a consumer's CI runs against, the wrapper workflow's uses: …@vN.N.N ref. See deterministic-ai.md principle 2.

Skill. A reusable AI capability packaged as a SKILL.md file in its own directory under .claude/skills/<name>/. Skills typically wrap a tool, an MCP call, or a procedure. ~25 skills are planned.

W

Workflow. Two unrelated senses: (1) a procedural markdown document in docs/workflows/ describing a multi-step process (~18 planned); (2) a GitHub Actions workflow in .github/workflows/. Context disambiguates; when both are in scope, the second is called CI workflow.

Y

Yank / yanked release. (Removed in v0.5.) v0.4 specified a HEAD-level .yanked.json manifest at the platform root, consulted by the lock validator to fail consumer CI for yanked versions. Dropped 2026-05-27 with the lock contract. Withdrawing a platform release now happens through the standard plugin-marketplace flow — pull the catalog entry or bump the plugin to a fix release.

See also

• ai-engineering-strategy.md Appendix A — the original v0.4 glossary this curated version is built on.
• deterministic-ai.md — the eight principles that frame how many of these terms are used.