Skip to content

Terminology Reference

This document defines the target-state canonical terminology for Spec Kitty’s three-tier domain model and identity layer. All new code, CLI surfaces, documentation, and API contracts should converge on these terms.

Not yet implemented. This reference describes the canonical model defined by mission 081. The current codebase still uses the pre-081 names (project_uuid for the locally minted identity, project_slug for the display label, ProjectIdentity for the identity class, etc.). Follow-up implementation missions will rename code, config keys, and wire protocol fields to match these definitions. Until then, treat this document as the authoritative target — not a description of current behavior.

Canonical source: Mission 081 — Canonical Baseline and Repository Boundary


The Three Domain Terms

TermDefinitionIdentity FieldExample Usage
ProjectSaaS collaboration surface that groups one or more repositories under a shared identity for collaboration, visibility, and governance. A project may span multiple repositories and exists independent of any single Git checkout.project_uuid (optional, SaaS-assigned)“Bind this repository to a project”
RepositoryLocal Git resource (one .git directory) that holds mission artifacts, source code, and .kittify/ configuration. Multiple checkouts (worktrees) of the same repository share one repository identity.repository_uuid (stable, locally minted)“Initialize a new repository”
BuildOne checkout or worktree of one repository. Each build has its own working tree, .kittify/ state snapshot, and execution context. Builds are ephemeral relative to the repository they belong to.build_id (per worktree)“This build is running lane-a”

Identity Fields

FieldScopeDescriptionStabilityMigration Note
repository_uuidRepositoryStable local repository identity, minted once per repository. Required namespace key for body sync and deduplication.Immutable once mintedWas mislabeled as project_uuid before mission 081
repository_labelRepositoryHuman-readable display name derived from git remote or directory name.Mutable; display onlyWas called project_slug before mission 081
repo_slugRepositoryOptional owner/repo Git provider reference (e.g. spec-kitty/spec-kitty).Unchanged from current; optionalNo change — retains pre-081 meaning
project_uuidCollaborationSaaS-assigned project binding. Absent until a repository is bound to a SaaS project. Never locally minted.Absent until bindingWas incorrectly used for locally minted repository identity
mission_idMissionCanonical mission machine identity. ULID (26 chars), minted at agent mission create. Aggregate key for events and selectors.Immutable once mintedReplaces mission_number as canonical identity as of mission 083
mid8MissionFirst 8 characters of mission_id. Short disambiguator used in branch and worktree names.Derived from mission_idNew in mission 083
mission_slugMissionHuman-readable kebab slug (e.g. auth-system). Used in directory names and as a convenience selector.Mutable in principle; stable in practicePre-083 slugs embedded a NNN- numeric prefix; that prefix is display-only as of mission 083
mission_numberMissionDisplay-only numeric prefix (int | None). null pre-merge, assigned at merge time via max(existing)+1 inside the merge-state lock. Never used for identity, routing, or locking.Assigned once at merge timeWas canonical identity pre-mission-083
build_idBuildPer-checkout/worktree identity, unique per working tree.Stable per worktreeNo change — already correctly scoped
node_idMachineStable machine fingerprint (12-char hex).Stable per hostNo change — already correctly scoped

See the mission identity migration runbook for the operator upgrade path and ADR 2026-04-09-1 for the design rationale.


Quick Rules

  1. If you mean the local Git directory, say repository.
  2. If you mean the SaaS collaboration group, say project.
  3. If you mean one specific checkout or worktree, say build.
  4. If you mean the Jira/Linear/GitHub workspace, say tracker project (qualified).
  5. repository_label is a mutable display name — never use it as a primary key.
  6. repo_slug means owner/repo from the Git provider — do not repurpose it for display names.
  7. repository_uuid is the required namespace key for local operations — not project_uuid.
  8. repository root checkout is a location, not a branch name.
  9. Use current branch, primary branch, feature branch, start branch, target branch, base_branch, planning_base_branch, and merge_target_branch when you mean branch intent.
  10. Do not use main repository, main repo, or main repository root in new docs or prompts.

Checkout and Branch Terms

TermMeaningDo Not Use It To Mean
repository root checkoutThe non-worktree checkout where planning commands runThe branch name
current branchThe branch checked out when planning startsThe mission’s intended landing branch if it was explicitly overridden
primary branchThe repository’s default integration branch, usually resolved from origin/HEADThe mission’s intended landing branch after target_branch is persisted
feature branchA dedicated branch for pr-bound mission planning and implementation workThe protected/default branch or every lane worktree branch
start branchThe branch agent mission create <mission_slug> --start-branch <topic-branch> creates or switches to before writing mission scaffoldingA later merge override or a separate branch from --target-branch
target branchThe branch the mission records planning and merge intent against“Whatever branch happens to be checked out later”
base_branchAt mission level, alias for target_branch; at WP level, the immediate parent branch for a lane worktreeA universal synonym for main
planning_base_branchCanonical helper alias for the intended planning branchA second repository or a worktree
merge_target_branchCanonical helper alias for the intended final merge branchProof that the branch must be main

When location and branch both matter, name both explicitly. Example: “Run /spec-kitty.plan from the repository root checkout on develop.”


Naming Conventions

Variables and parameters

CorrectIncorrectWhy
repo_rootproject_rootIt is a repository root, not a project root
repository_uuidproject_uuid (for local identity)The locally minted UUID is repository-scoped
repository_labelproject_slug (for the display name)It is a repository label, not a project slug
repo_slug(no change needed)Already correct for owner/repo Git provider reference

Functions

CorrectIncorrect
locate_repository_root()locate_project_root()
get_repository_root_or_exit()get_project_root_or_exit()
generate_repository_uuid()generate_project_uuid()
derive_repository_label()derive_project_slug()

Config keys

CorrectIncorrect
repository.repository_uuidproject.uuid
repository.repository_labelproject.slug
repository.repo_slugproject.repo_slug
project.project_uuid (SaaS binding only)project.uuid (for local identity)

Wire protocol fields

CorrectIncorrect
repository_uuidproject_uuid (for locally minted identity)
repository_labelproject_slug (for display name)
repo_slug (unchanged)Repurposing repo_slug for display names
project_uuid (only when SaaS binding exists)project_uuid (for local identity)

CLI help text

CorrectIncorrect
“Path to repository to repair”“Path to project to repair”
“Name for your new repository directory”“Name for your new project directory”
“Initialize a new spec-kitty repository”“Setup tool for spec-driven development projects”

Decision Tree

Use this tree to resolve ambiguous naming cases:

Is the thing you're naming...
+-- The local .git directory?
| +-- Use "repository" / repo_root / repository_uuid
+-- A specific checkout or worktree?
| +-- Use "build" / build_id
+-- The SaaS collaboration group?
| +-- Use "project" / project_uuid
+-- A Jira/Linear/GitHub workspace?
| +-- Use "tracker project" / tracker_project_slug
+-- A human-readable label for the repo?
| +-- Use repository_label (and note it's display-only, not an identity)
+-- The owner/repo Git provider reference?
| +-- Use repo_slug (and note it's optional, unchanged from current)
+-- A namespace key for body sync or dedup?
+-- Use repository_uuid (never project_uuid, which is optional)

What Changed (Migration Summary)

Mission 081 established canonical definitions and identified naming drift. The renames below are the target state for follow-up implementation missions. No existing identity values are lost — only names and labels change.

Old NameNew NameReason
project_uuid (locally minted)repository_uuidThe locally minted UUID is repository-scoped, not project-scoped
project_slugrepository_labelIt is a repository display name, not a project slug
project_rootrepo_rootThe path refers to the repository root directory
locate_project_root()locate_repository_root()Resolves the repository, not a project
get_project_root_or_exit()get_repository_root_or_exit()Resolves the repository, not a project
ProjectIdentityRepositoryIdentityThe identity class represents a repository
“project” (meaning local Git resource)“repository”Reserved “project” for SaaS collaboration surface

Fields that are unchanged: repo_slug, build_id, node_id, project_uuid (when used for actual SaaS binding).