---
type: "Context"
title: "Context: Execution"
description: "Glossary context for execution semantics: tool invocation and the semantic safety gates applied during generation within a Spec Kitty mission."
status: "stable"
generated:
  by: "process:dockitty-export"
  at: "2026-11-13T00:00:00Z"
---

## Context: Execution

Terms describing tool invocation and semantic safety gates during generation.

### Tool

| | |
|---|---|
| **Definition** | Concrete runtime product used to execute commands (for example Claude Code, Codex, opencode). |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Agent](/context/identity.md#agent), [Slash Command](#slash-command) |

---

### Tool Surface

| | |
|---|---|
| **Definition** | A tool-visible artifact or configuration entry that Spec Kitty installs, verifies, repairs, or packages for a concrete execution tool. This is `surface` **Sense 1** — the tool-facing sense, one of two unrelated domains that share the word. Realized in code by the `ToolSurfaceKind` enum in `src/specify_cli/tool_surface/enums.py` (members `COMMAND_SKILL`, `CHARTER_SKILL`, `CONTEXT_FILE`, `RULE`, `HOOK`, `AGENT_PROFILE`, `PLUGIN_MANIFEST`, `NATIVE_CONFIG`, `COMMAND_FILE`), renamed from the bare `SurfaceKind` per ADR [2026-07-23-1](/adr/3.x/2026-07-23-1-surface-vocabulary-two-domains-and-topology-surface-rename.md). |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `3.x` |
| **Examples** | slash command file, skill directory ("skill" has more than one meaning: see [Pack skill](#pack-skill)), custom agent profile file, hook config, MCP config, plugin manifest |
| **Use when** | Describing install/config/doctor/plugin ownership for Claude Code, Codex, Copilot, Cursor, Windsurf, Kiro, or another concrete tool. |
| **Do NOT use when** | Describing logical collaborator identity, assignment, handoff, or role; use [Agent](/context/identity.md#agent) or [Agent Profile](/context/identity.md#agent-profile) instead. The concept is the physical tree a mission artifact resolves to — use [Topology Surface](/context/orchestration.md#topology-surface) (`surface` **Sense 2**). Never write bare "surface" in governed prose; name the sense ("tool surface" / "topology surface"). |
| **Related terms** | [Tool](#tool), [Slash Command](#slash-command), [Agent](/context/identity.md#agent), [Topology Surface](/context/orchestration.md#topology-surface) |

---

### Tool-surface drift

| | |
|---|---|
| **Definition** | The state of a [tool surface](#tool-surface) file that Spec Kitty generated and still tracks as managed, whose content no longer matches anything Spec Kitty wrote, so Spec Kitty will not overwrite it without consent. In practice: someone edited a generated slash-command file, managed skill, agent profile or plugin-bundle component. `spec-kitty upgrade` keeps such a file, names it (`Not updated, your local edit was kept: <path>`) and exits non-zero with the outcome `drift_unresolved` and the failure reason `surface_drift` (ADR [2026-10-04-3](/adr/4.x/2026-10-04-3-upgrade-reports-one-outcome.md); whether that exit should be non-zero is open in [#5745](https://github.com/spec-kitty/spec-kitty/issues/5745)). |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Examples** | An edited `.claude/commands/spec-kitty.plan.md`; an edited file that upgrade wanted to remove. |
| **Use when** | Explaining why upgrade left a managed file alone, or what `spec-kitty doctor tool-surfaces` means by a drifted file. |
| **Do NOT use when** | The file is missing: upgrade recreates it, and that is not drift. The file matches an older generated version (stale): upgrade rewrites it, and that is not drift. The file was never generated by Spec Kitty: it is user-owned and untouched. The shared command-skill projection `.agents/skills/spec-kitty-<command>/SKILL.md` is git-ignored generated state: upgrade regenerates it even when edited, so it is never drift ([#702](https://github.com/spec-kitty/spec-kitty/issues/702), ADR 2026-10-04-3 amendment 2026-10-13). Do not use it for a difference between two branches' copies of `.kittify/metadata.yaml`. Never write bare "drift" in operator-facing text; say which file was kept and why. |
| **Related terms** | [Tool Surface](#tool-surface), [Slash Command](#slash-command), [Pack skill](#pack-skill) |

---

### Pack skill

| | |
|---|---|
| **Definition** | A thin, parameterized entry point that a team shares through a charter pack instead of through private per-user copies. It is a doctrine artifact of kind `skill` (`ArtifactKind.SKILL`, URN `skill:<id>`), declared as a `<id>.skill.yaml` record (plus a body file in the `prompt` form) in an org pack's `skills/` directory or in the project's `.kittify/charter-packs/skills/` directory. A maintainer switches it on with `spec-kitty charter activate skill <id>`. Spec Kitty then renders it as `<skill_namespace>-<id>/SKILL.md` into the project skill root of each configured tool, and records ownership in `.kittify/skills-manifest.json`. A pack skill carries no doctrine substance of its own: it `requires` the procedures and directives that do. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **The senses of "skill"** | The word "skill" names three different artifacts in this codebase. All three share one packaging format: a directory with a `SKILL.md` descriptor (the core glossary pack calls this a "skill package"). **Pack skill** — the charter-activatable artifact defined here. **Charter skill** — a skill shipped inside the product under `src/charter/offering/skills/` (for example `spk-*`); it teaches an agent how to operate Spec Kitty; realized as `ToolSurfaceKind.CHARTER_SKILL`. **Command skill** — a generated `spec-kitty-<command>` skill (for example under `.agents/skills/spec-kitty-<command>/`; named `spec-kitty.<command>` before 4.0.0rc8) that exposes a slash command to Agent Skills tools; realized as `ToolSurfaceKind.COMMAND_SKILL`. |
| **Do NOT use when** | The concept is a skill that ships with the product to teach an agent how to operate Spec Kitty (under `src/charter/offering/skills/`) — say "charter skill". The concept is a generated `spec-kitty-<command>` skill — say "command skill". The concept is the `ToolSurfaceKind` value — write the member name (`CHARTER_SKILL`, `COMMAND_SKILL`). The concept is only the rendered `SKILL.md` directory on disk — that is the *projection* of a pack skill (or of a charter skill); the pack skill is the declared artifact. Never write bare "skill" in governed prose when the sense is not obvious; name it. The `spk-`, `spec-kitty-` and `spec-kitty.` name prefixes are reserved for charter and command skills: a pack skill renders under its own `skill_namespace` prefix instead. |
| **Related terms** | [Tool Surface](#tool-surface), [Slash Command](#slash-command), [Tool](#tool) |

---

### Slash Command

| | |
|---|---|
| **Definition** | User-facing command surface that triggers a lifecycle operation (for example specify, plan, tasks, review, consolidate). |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |

---

### Semantic Check

| | |
|---|---|
| **Definition** | Deterministic validation step that compares extracted terms with active glossary scope(s) before generation proceeds. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Glossary Scope](/context/system-events.md#glossary-scope), [Strictness](#glossary-strictness), [Term Sense](/context/lexical.md#term-sense), [Semantic Check Evaluation](/context/system-events.md#semantic-check-evaluation) |

---

### Glossary Strictness

| | |
|---|---|
| **Definition** | Policy mode controlling warning/block behavior for semantic conflicts. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Modes** | `off`, `medium` (default), `max` |

---

### Clarification Prompt

| | |
|---|---|
| **Definition** | Targeted question emitted when conflict severity/confidence requires human input before continuing generation. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Burst policy** | No cap is implemented today: the clarification step prompts for every unresolved conflict in turn (`src/glossary/clarification.py`). |

---

### Generation Boundary

| | |
|---|---|
| **Definition** | Point where text/code generation would begin and semantic gate policy is enforced. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `1.x`, `2.x` |
| **Block condition** | Unresolved high-severity semantic conflict |

---

### Middleware Pipeline

| | |
|---|---|
| **Definition** | An ordered chain of processing steps that run before a mission step produces output. Each layer in the chain can extract terms, check for semantic conflicts, gate generation, prompt the Human-in-Charge for clarification, or resume from a checkpoint. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Semantic Check](#semantic-check), [Generation Boundary](#generation-boundary), [Checkpoint/Resume](#checkpointresume) |

---

### Checkpoint/Resume

| | |
|---|---|
| **Definition** | A mechanism that lets a glossary pipeline pause at a generation boundary and pick up where it left off in a later session. The pause point and its context are saved so no work is lost. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Middleware Pipeline](#middleware-pipeline), [Generation Boundary](#generation-boundary) |

---

### Seed File

| | |
|---|---|
| **Definition** | An optional YAML file (`.kittify/glossaries/{scope}.yaml`) that pre-loads domain glossary terms before the runtime starts extracting new ones. Gives teams a head start by defining known terminology upfront. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Glossary Scope](/context/system-events.md#glossary-scope), [Term Sense](/context/lexical.md#term-sense) |

---

### Collaboration Mode

| | |
|---|---|
| **Definition** | The level of Human-in-Charge involvement during a mission step or workflow. Determines how much real-time oversight the HiC provides versus delegating to agents. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic), [Interactive Mode](#interactive-mode), [Hands-off with Review Mode](#hands-off-with-review-mode), [Fully Delegated Mode](#fully-delegated-mode) |

---

### Interactive Mode

| | |
|---|---|
| **Definition** | The HiC works alongside agents in real time — conducting interviews, pair-developing, micro-prompting, or making decisions as they arise. The HiC is present and actively steering. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Collaboration Mode](#collaboration-mode), [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic) |

---

### Hands-off with Review Mode

| | |
|---|---|
| **Definition** | Agents operate independently during execution, but the HiC reviews results at defined checkpoints before work is accepted or advanced. The HiC is absent during execution but present for review. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Related terms** | [Collaboration Mode](#collaboration-mode), [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic) |

---

### Fully Delegated Mode

| | |
|---|---|
| **Definition** | The agentic stack operates asynchronously without the HiC present. Work proceeds until a final Accept/Decline decision point, where the HiC returns to approve or reject the outcome. Also known as "AFK mode." |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `1.x`, `2.x` |
| **Alias** | AFK mode |
| **Related terms** | [Collaboration Mode](#collaboration-mode), [Human-in-Charge (HiC)](/context/identity.md#human-in-charge-hic) |

---

### GovernanceContext

| | |
|---|---|
| **Definition** | A design concept, not a code type: the resolved set of Charter and Doctrine artifacts active for an operation, resolved once per operation and passed down, never re-derived mid-operation. No `GovernanceContext` type and no "Governance module" exist in `src/` today. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `3.x` |
| **Owner** | None in code today. |
| **Related terms** | [MissionExecutionContext](#missionexecutioncontext), [InfraContext](#infracontext), [Charter](/context/governance.md#charter) |

---

### MissionExecutionContext

| | |
|---|---|
| **Definition** | The resolved set of workspace root, branch name, Mission directory (code field `feature_dir`), and WP identity for an operation. Owned by `mission_runtime/context.py` (Open Host Service facade). Resolved once per operation via `resolve_action_context`; never re-derived from CWD by individual command surfaces. Renamed from `ExecutionContext` (FR-012) to match the ubiquitous language and disambiguate from the unrelated `core/context_validation.py::ExecutionContext(StrEnum)`. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Owner** | Mission runtime (`src/mission_runtime/context.py`) |
| **OHS entry point** | `resolve_action_context` |
| **Related terms** | [GovernanceContext](#governancecontext), [InfraContext](#infracontext) |

---

### InfraContext

| | |
|---|---|
| **Definition** | A design concept, not a code type: the resolved set of infrastructure credentials and endpoints for an operation, such as the git remote URL, a CI endpoint and external service tokens. No `InfraContext` type and no "Execution module" exist in `src/` today. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `3.x` |
| **Owner** | None in code today. |
| **Related terms** | [MissionExecutionContext](#missionexecutioncontext), [GovernanceContext](#governancecontext) |

---

### Effector

| | |
|---|---|
| **Definition** | The Actor realized inside the Execution domain — the execution-bound realization of an Actor that performs actions within a Mission, producing or consuming communication artifacts (commits, PRs, comments). Named concept in docs only; no code type until a concrete actor-kind-mismatch bug triggers materialization. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Materialization trigger** | First concrete actor-kind-mismatch bug, or first feature requiring cross-log (status/retrospective/run) actor identity join |
| **Placement when materialized** | `src/kernel/` (Shared Kernel layer) |
| **Related terms** | [communication artifact](#communication-artifact) |
| **ADR** | `docs/adr/3.x/2026-06-03-3-effector-actor-model.md` |

---

<a id="communication-artefact"></a>

### communication artifact

| | |
|---|---|
| **Definition** | A durable artifact produced or consumed by an Effector during a mission run (for example, a commit, a pull request, a review comment). Distinct from planning artifacts (spec, plan, tasks) which are produced before execution begins. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Alias** | `communication artefact` (UK spelling, legacy) |
| **Examples** | git commit, pull request, PR comment, CI run result |
| **Related terms** | [Effector](#effector) |

---

### repository root checkout

| | |
|---|---|
| **Definition** | The canonical repository-root working copy of a project — the single checkout from which planning commands run and against which lane worktrees are created. It is distinct from a lane worktree (an isolated per-work-package checkout under `.worktrees/`). This is `primary` **Sense C**; the charter §Branch-Intent Terminology Governance decrees "repository root checkout" as the canonical term for this sense. The retired alias phrases "primary surface" and "primary checkout" describe it. |
| **Context** | Execution |
| **Status** | canonical |
| **Applicable to** | `3.x` |
| **Symbols unchanged this slice** | This entry canonicalizes the prose term only. The underlying code symbols (`primary_feature_dir_*` and the rest of the Sense-C checkout cluster) are **not** renamed in this mission; the code rename is Track 2 (#2730). |
| **Do NOT use when** | The concept is the artifact-kind partition — use [PRIMARY partition](/context/orchestration.md#primary-partition). The concept is the repository's default integration branch — use [primary branch](/context/orchestration.md#primary-branch). The concept is the ref planning artifacts commit to — use [Target Ref / Commit Target](/context/orchestration.md#target-ref--commit-target). Avoid the retired aliases "primary surface" and "primary checkout". |
| **Related terms** | [Build](/context/orchestration.md#build), [MissionExecutionContext](#missionexecutioncontext), [Lane](/context/orchestration.md#lane), [primary branch](/context/orchestration.md#primary-branch), [owned checkout](#owned-checkout) |

---

### integrating worktree

| | |
|---|---|
| **Definition** | A linked git worktree whose checked-out branch is a `kitty/mission-…` mission, lane or coordination branch, as recognized by the branch-naming authority (`parse_mission_slug_from_branch`), or whose branch cannot be read (a detached HEAD counts, to fail safe). Its branch will later be integrated into another branch of the same Mission. `spec-kitty upgrade`, run from the repository root checkout, skips integrating worktrees: it writes, stamps and commits nothing in them. Since #7173 it also skips every other worktree under `.worktrees/` unless that worktree is named with `--include-worktree` or `--all-worktrees` (`is_integrating_worktree`, `src/specify_cli/upgrade/worktree_selection.py`; ADR [2026-10-04-4](/adr/4.x/2026-10-04-4-upgrade-writes-project-global-state-once.md)). |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `4.x` |
| **Use when** | Describing which worktrees `spec-kitty upgrade` leaves alone, or why a lane still shows a pre-upgrade `.kittify/metadata.yaml`. |
| **Do NOT use when** | The worktree is on an ordinary branch (a feature or landing branch): upgrade still upgrades and commits there. The concept is the repository-root working copy: use [repository root checkout](#repository-root-checkout), which is never an integrating worktree. The concept is a per-work-package execution checkout in general: use lane worktree, [Lane](/context/orchestration.md#lane). |
| **Related terms** | [repository root checkout](#repository-root-checkout), [owned checkout](#owned-checkout), [Lane](/context/orchestration.md#lane), [Target-owned bookkeeping](/context/orchestration.md#target-owned-bookkeeping) |

---

### owned checkout

| | |
|---|---|
| **Definition** | A linked git checkout of the repository that the canonical owned-mission validator has accepted, for one command invocation, as owning a given Mission. The operator names it with `--owned-checkout <path>`, or a flagless command adopts it after validation. Every lifecycle read and write of that Mission resolves inside it. The validator records the proof as the *validated ownership fact* (`mission_runtime.OwnedCheckout`: owned checkout, repository root checkout, stored topology, target branch). |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `3.x` |
| **Use when** | Describing where an owned Mission's artifacts, status log and commits live; describing `--owned-checkout` behavior or its refusals (`OWNED_*` codes). |
| **Do NOT use when** | The concept is the repository-root working copy — use [repository root checkout](#repository-root-checkout); the repository root checkout is never an owned checkout, and passing it is refused with `OWNED_CHECKOUT_IS_REPOSITORY_ROOT`. It is a per-work-package execution checkout — use lane worktree, [Lane](/context/orchestration.md#lane). It is the coordination worktree of a coordination topology. It is any linked worktree the validator has not accepted — say "linked checkout". It is the ref being committed to — use [Target Ref / Commit Target](/context/orchestration.md#target-ref--commit-target). Never write "primary" for either checkout. |
| **Related terms** | [repository root checkout](#repository-root-checkout), [MissionExecutionContext](#missionexecutioncontext), [Lane](/context/orchestration.md#lane), [target branch](/context/orchestration.md#target-branch) |

---

### Shadow Clone (Isolated Dev Environment)

| | |
|---|---|
| **Definition** | A contributor/maintainer practice for developing Spec Kitty itself: a standalone repository-root checkout of the Spec Kitty codebase whose CLI and runtime state are pinned to that checkout, so it does not interfere with a machine-global install or with sibling checkouts. Isolation has two axes — **code** (a clone-local `.venv` editable install placed first on `PATH`, so `spec-kitty` runs the checkout's live `src/`) and **state** (`SPEC_KITTY_HOME` pointed at a clone-local root so the offline queue, sync daemon, event journal, auth, gate-locks, and trackers do not land in the shared `~/.spec-kitty`). It is the non-containerised isolation option, chosen for speed over the stronger isolation of a container. |
| **Context** | Execution |
| **Status** | candidate |
| **Applicable to** | `3.x` |
| **Examples** | A stable checkout backing the machine-global `spec-kitty` (the maintainer's everyday repository root checkout), plus one or more *shadow* checkouts each activated per-session against its own `.venv` and `SPEC_KITTY_HOME`. |
| **Use when** | Describing how a maintainer runs several Spec Kitty checkouts on one machine without cross-mission pollution, or the `SPEC_KITTY_HOME` / clone-local `.venv` isolation levers that make that safe. |
| **Do NOT use when** | The concept is a per-work-package worktree under [`.worktrees/`](/context/configuration-project-structure.md#worktrees) inside a single checkout (that is intra-mission execution isolation, not a separate clone). The concept is the canonical [repository root checkout](#repository-root-checkout) of a *consumer* project rather than a maintainer's isolated development copy of Spec Kitty. |
| **Related terms** | [repository root checkout](#repository-root-checkout), [Lane](/context/orchestration.md#lane), [Build](/context/orchestration.md#build) |

## Related

- [Context: Governance](/context/governance.md)
- [Context: Identity](/context/identity.md)
- [Context: Lexical](/context/lexical.md)
- [Context: System Events](/context/system-events.md)

## Audience

- [Stakeholder Persona: AI Collaboration Agent](/context/audience/internal/ai-collaboration-agent.md) - Use these terms for tools, tool surfaces, checkouts and the glossary gates you run under; the repository root checkout entry is a footgun disambiguation.
- [Stakeholder Persona: Lead Developer](/context/audience/internal/lead-developer.md) - Use this when you work on tool surfaces, checkouts or the glossary pipeline.
