Context: Execution
Terms describing tool invocation and semantic safety gates during generation.
| |
|---|
| 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, Slash Command |
| |
|---|
| 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. |
| Context | Execution |
| Status | candidate |
| Applicable to | 3.x |
| Examples | slash command file, skill directory (“skill” has more than one meaning: see 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 or Agent Profile instead. The concept is the physical tree a mission artifact resolves to — use Topology Surface (surface Sense 2). Never write bare “surface” in governed prose; name the sense (“tool surface” / “topology surface”). |
| Related terms | Tool, Slash Command, Agent, Topology Surface |
| |
|---|
| Definition | The state of a 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; whether that exit should be non-zero is open in #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, 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, Slash Command, 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, Slash Command, 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
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, Generation Boundary, Checkpoint/Resume |
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, 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, Term Sense |
Collaboration 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, 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, 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, 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, InfraContext, 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, 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, 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 |
| ADR | docs/adr/3.x/2026-06-03-3-effector-actor-model.md |
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 |
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. The concept is the repository’s default integration branch — use primary branch. The concept is the ref planning artifacts commit to — use Target Ref / Commit Target. Avoid the retired aliases “primary surface” and “primary checkout”. |
| Related terms | Build, MissionExecutionContext, Lane, primary branch, 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). |
| 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, which is never an integrating worktree. The concept is a per-work-package execution checkout in general: use lane worktree, Lane. |
| Related terms | repository root checkout, owned checkout, Lane, 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; 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. 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. Never write “primary” for either checkout. |
| Related terms | repository root checkout, MissionExecutionContext, Lane, 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/ inside a single checkout (that is intra-mission execution isolation, not a separate clone). The concept is the canonical repository root checkout of a consumer project rather than a maintainer’s isolated development copy of Spec Kitty. |
| Related terms | repository root checkout, Lane, Build |