Skip to content

Context: Execution

Who is this for (2)

Context: Execution

Terms describing tool invocation and semantic safety gates during generation.

Tool

DefinitionConcrete runtime product used to execute commands (for example Claude Code, Codex, opencode).
ContextExecution
Statuscanonical
Applicable to1.x, 2.x
Related termsAgent, Slash Command

Tool Surface

DefinitionA 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.
ContextExecution
Statuscandidate
Applicable to3.x
Examplesslash command file, skill directory (“skill” has more than one meaning: see Pack skill), custom agent profile file, hook config, MCP config, plugin manifest
Use whenDescribing install/config/doctor/plugin ownership for Claude Code, Codex, Copilot, Cursor, Windsurf, Kiro, or another concrete tool.
Do NOT use whenDescribing 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 termsTool, Slash Command, Agent, Topology Surface

Tool-surface drift

DefinitionThe 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).
ContextExecution
Statuscandidate
Applicable to4.x
ExamplesAn edited .claude/commands/spec-kitty.plan.md; an edited file that upgrade wanted to remove.
Use whenExplaining why upgrade left a managed file alone, or what spec-kitty doctor tool-surfaces means by a drifted file.
Do NOT use whenThe 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 termsTool Surface, Slash Command, Pack skill

Pack skill

DefinitionA 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.
ContextExecution
Statuscanonical
Applicable to3.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 whenThe 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 termsTool Surface, Slash Command, Tool

Slash Command

DefinitionUser-facing command surface that triggers a lifecycle operation (for example specify, plan, tasks, review, consolidate).
ContextExecution
Statuscanonical
Applicable to1.x, 2.x

Semantic Check

DefinitionDeterministic validation step that compares extracted terms with active glossary scope(s) before generation proceeds.
ContextExecution
Statuscanonical
Applicable to1.x, 2.x
Related termsGlossary Scope, Strictness, Term Sense, Semantic Check Evaluation

Glossary Strictness

DefinitionPolicy mode controlling warning/block behavior for semantic conflicts.
ContextExecution
Statuscanonical
Applicable to1.x, 2.x
Modesoff, medium (default), max

Clarification Prompt

DefinitionTargeted question emitted when conflict severity/confidence requires human input before continuing generation.
ContextExecution
Statuscanonical
Applicable to1.x, 2.x
Burst policyNo cap is implemented today: the clarification step prompts for every unresolved conflict in turn (src/glossary/clarification.py).

Generation Boundary

DefinitionPoint where text/code generation would begin and semantic gate policy is enforced.
ContextExecution
Statuscanonical
Applicable to1.x, 2.x
Block conditionUnresolved high-severity semantic conflict

Middleware Pipeline

DefinitionAn 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsSemantic Check, Generation Boundary, Checkpoint/Resume

Checkpoint/Resume

DefinitionA 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsMiddleware Pipeline, Generation Boundary

Seed File

DefinitionAn 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsGlossary Scope, Term Sense

Collaboration Mode

DefinitionThe 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsHuman-in-Charge (HiC), Interactive Mode, Hands-off with Review Mode, Fully Delegated Mode

Interactive Mode

DefinitionThe 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsCollaboration Mode, Human-in-Charge (HiC)

Hands-off with Review Mode

DefinitionAgents 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.
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
Related termsCollaboration Mode, Human-in-Charge (HiC)

Fully Delegated Mode

DefinitionThe 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.”
ContextExecution
Statuscandidate
Applicable to1.x, 2.x
AliasAFK mode
Related termsCollaboration Mode, Human-in-Charge (HiC)

GovernanceContext

DefinitionA 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.
ContextExecution
Statuscandidate
Applicable to3.x
OwnerNone in code today.
Related termsMissionExecutionContext, InfraContext, Charter

MissionExecutionContext

DefinitionThe 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).
ContextExecution
Statuscanonical
Applicable to3.x
OwnerMission runtime (src/mission_runtime/context.py)
OHS entry pointresolve_action_context
Related termsGovernanceContext, InfraContext

InfraContext

DefinitionA 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.
ContextExecution
Statuscandidate
Applicable to3.x
OwnerNone in code today.
Related termsMissionExecutionContext, GovernanceContext

Effector

DefinitionThe 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.
ContextExecution
Statuscanonical
Applicable to3.x
Materialization triggerFirst concrete actor-kind-mismatch bug, or first feature requiring cross-log (status/retrospective/run) actor identity join
Placement when materializedsrc/kernel/ (Shared Kernel layer)
Related termscommunication artifact
ADRdocs/adr/3.x/2026-06-03-3-effector-actor-model.md

communication artifact

DefinitionA 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.
ContextExecution
Statuscanonical
Applicable to3.x
Aliascommunication artefact (UK spelling, legacy)
Examplesgit commit, pull request, PR comment, CI run result
Related termsEffector

repository root checkout

DefinitionThe 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.
ContextExecution
Statuscanonical
Applicable to3.x
Symbols unchanged this sliceThis 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 whenThe 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 termsBuild, MissionExecutionContext, Lane, primary branch, owned checkout

integrating worktree

DefinitionA 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).
ContextExecution
Statuscandidate
Applicable to4.x
Use whenDescribing which worktrees spec-kitty upgrade leaves alone, or why a lane still shows a pre-upgrade .kittify/metadata.yaml.
Do NOT use whenThe 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 termsrepository root checkout, owned checkout, Lane, Target-owned bookkeeping

owned checkout

DefinitionA 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).
ContextExecution
Statuscandidate
Applicable to3.x
Use whenDescribing where an owned Mission’s artifacts, status log and commits live; describing --owned-checkout behavior or its refusals (OWNED_* codes).
Do NOT use whenThe 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 termsrepository root checkout, MissionExecutionContext, Lane, target branch

Shadow Clone (Isolated Dev Environment)

DefinitionA 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.
ContextExecution
Statuscandidate
Applicable to3.x
ExamplesA 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 whenDescribing 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 whenThe 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 termsrepository root checkout, Lane, Build