A tool-visible artifact or configuration entry that Spec Kitty installs, verifies, repairs, or packages for a concrete execution tool. This is surfaceSense 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 (surfaceSense 2). Never write bare "surface" in governed prose; name the sense ("tool surface" / "topology surface").
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.
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.
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.
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.
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.
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.
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.
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.
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."
The resolved set of Charter and Doctrine artifacts active for an operation. Owned by the Governance bounded module. Resolved once per operation and passed down; never re-derived mid-operation.
The resolved set of workspace root, branch name, feature directory, 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).
The resolved set of infrastructure credentials and endpoints for an operation, including git remote URL, CI endpoint, and any external service tokens. Owned by the Execution module.
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
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
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 primarySense 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".
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 (_is_integrating_worktree, src/specify_cli/upgrade/runner.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.
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.
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 primary checkout backing the machine-global spec-kitty, 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.