New: 97,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Agent skill

Spec Kitty Git Workflow

by spec-kitty in spec-kitty/spec-kitty

Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit…

MITAuto-check passedDevelopment

Install Spec Kitty Git Workflow

skills CLI
$ npx skills add spec-kitty/spec-kitty --skill spec-kitty-git-workflow -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install spec-kitty/spec-kitty spec-kitty-git-workflow --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/spec-kitty/spec-kitty.git skills-src && mkdir -p .claude/skills && cp -r skills-src/src/charter/offering/skills/spec-kitty-git-workflow .claude/skills/spec-kitty-git-workflow && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
spec-kitty-git-workflow
GitHub stars
1.7k
Token cost
~2.3k tokens
SKILL.md length
944 words
Files
2 (incl. references)
Skills in repo
50
Repo updated
First seen
Licence
MIT

At a glance

Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit…

  • Works in 11 steps: Worktree Creation → Planning Artifact Auto-Commits → Lane Transition Auto-Commits → …
  • Tasks that involve Git workflow
  • SKILL.md covers The Core Boundary, What Python Does Automatically, What Agents Must Do and Auto-Commit Configuration, plus 4 more sections
  • Calls git

What it does

Spec Kitty Git Workflow is an agent skill from spec-kitty/spec-kitty. Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit pattern. Triggers: "how does spec-kitty use git", "worktree management", "auto-commit", "who commits what", "git workflow", "merge workflow", "rebase WPs", "worktree cleanup", "safe commit". Does NOT handle: runtime loop advancement (use runtime-next), setup or repair (use setup-doctor), mission selection (use…

Its SKILL.md is about 2.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 2 other files, including reference files (for example `references/git-operations-matrix.md`).

It sits in Development, covering Git workflow and Git worktrees. It works with Git and Python. The repository describes itself as: Spec-Driven Development with organizational governance. Specs tell AI agents what to build; Charter governs how they build it. Git-native missions, enforceable workflows, and… The licence is MIT.

When your agent uses it

  • Tasks that involve Git workflow
  • Tasks that involve Git worktrees

Example prompts

  • “how does spec-kitty use git”
  • “worktree management”
  • “auto-commit”
  • “/spec-kitty-git-workflow”

Requirements

  • Python 3

Workflow steps

11 steps, taken from the step headings in SKILL.md.

  1. Worktree Creation
  2. Planning Artifact Auto-Commits
  3. Lane Transition Auto-Commits
  4. Status Event Log (No Auto-Commit)
  5. Merge Execution
  6. Pre-flight Validation (Read-Only)
  7. Implementation Commits
  8. Refreshing a Stale Lane Workspace
  9. Multi-Dependency Work
  10. Pushing
  11. Conflict Resolution

What it can do on your machine

Read from SKILL.md and the folder at commit 2fe1172. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • git

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use git, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Spec Kitty Git Workflow loads about 2.3k tokens when it runs, and up to ~3.3k if it reads all its reference files. Until then it costs about 138 tokens; SKILL.md has 944 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~138
When it runs · the whole SKILL.md, loaded when a task matches
~2.3k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from spec-kitty/spec-kitty at commit 2fe1172, republished under its MIT licence (© spec-kitty). 944 words, ~2,317 tokens.

Download SKILL.mdSave it as .claude/skills/spec-kitty-git-workflow/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.
name
spec-kitty-git-workflow
description
Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit pattern. Triggers: "how does spec-kitty use git", "worktree management", "auto-commit", "who commits what", "git workflow", "merge workflow", "rebase WPs", "worktree cleanup", "safe commit". Does NOT handle: runtime loop advancement (use runtime-next), setup or repair (use setup-doctor), mission selection (use mission-system).

spec-kitty-git-workflow

Understand the boundary between what spec-kitty's Python code does with git and what LLM agents are expected to do. This boundary is critical — agents that try to create worktrees manually or skip implementation commits will break the workflow.

The Core Boundary

Python handles infrastructure git — worktrees, lane commits, merges, cleanup. Agents handle content git — implementation commits, rebases, conflict resolution.

Git OperationWho Does ItWhen
git worktree addPythonspec-kitty implement WP##
git commit (planning artifacts)PythonBefore worktree creation
git commit (lane transitions)PythonWP moves through claimed/in_progress/for_review/in_review
git commit (implementation code)AgentAfter writing code in worktree
git merge/auto-rebase (stale lane sync)Python or AgentWhen stale checks classify the lane as recoverable
git merge (lane → mission → target)Pythonspec-kitty merge
git pushPython (opt-in)spec-kitty merge --push only
git pushAgentAny other push scenario
Conflict resolutionAgentDuring rebase or manual merge
git worktree removePythonAfter successful merge
git branch -d (cleanup)PythonAfter successful merge

What Python Does Automatically

1. Worktree Creation

When you run spec-kitty implement WP01, Python:

git worktree add -b kitty/mission-042-mission-lane-a .worktrees/042-mission-lane-a kitty/mission-042-mission

It also records the lane workspace context in .kittify/workspaces/<feature>-<lane>.json so later commands resolve the same lane worktree deterministically.

The agent never creates worktrees. Always use spec-kitty implement.

For dependent WPs in the same execution lane:

spec-kitty implement WP02

This reuses the lane worktree instead of creating a second workspace:

# WP02 reuses .worktrees/042-mission-lane-a
2. Planning Artifact Auto-Commits

Before creating a worktree, Python checks if kitty-specs/042-mission/ has uncommitted changes on the primary branch. If so, it commits through BookkeepingTransaction and safe_commit:

safe_commit(paths=["kitty-specs/042-mission/"], message="chore: Planning artifacts for 042-mission")

Controlled by: auto_commit: true in .kittify/config.yaml (default: true). Can be disabled per-command with --no-auto-commit.

3. Lane Transition Auto-Commits

When a WP moves to doing or for_review, Python uses the safe-commit pattern to commit only the WP frontmatter file:

  • Moving to doing: "chore: Start WP01 implementation [claude]"
  • Moving to for_review: "chore: Start WP01 review [claude]"

The safe-commit pattern prevents accidentally committing agent work-in-progress:

  1. Stash current staging area
  2. Stage only the target files (WP frontmatter, status artifacts)
  3. Commit
  4. Pop stash to restore previous staging
4. Status Event Log (No Auto-Commit)

emit_status_transition() appends to status.events.jsonl, updates status.json, and modifies WP frontmatter — but does NOT auto-commit these files. They accumulate as uncommitted changes until the next lane transition auto-commit or the agent commits them.

This is by design — status changes happen frequently and committing each one would create excessive git noise.

5. Merge Execution

Run spec-kitty accept --mission 042-mission before merge once every WP is approved. Acceptance is a readiness nudge and artifact check; merge still owns the final mission-close transition.

spec-kitty merge --mission 042-mission runs the full merge sequence:

Python creates a detached merge worktree from the target branch, merges lane branches into the mission branch, merges the mission ref using the selected strategy, advances the target branch ref to the detached result, then removes merged lane worktrees and branches.

Merge order follows the dependency graph (topological sort).

Supports 3 strategies: squash (default), merge (--no-ff), rebase.

--push is opt-in — without it, the merge is local only.

6. Pre-flight Validation (Read-Only)

Before merge, Python validates:

  1. All expected WPs have worktrees
  2. All worktrees are clean (git status --porcelain)
  3. Target branch is not behind origin (git rev-list --left-right --count)
  4. WPs in done lane with missing worktrees are skipped (already merged)

If any check fails, merge is blocked with specific error messages.

What Agents Must Do

Show full SKILL.md (388 more words)Show less
1. Implementation Commits

All actual code work must be committed by the agent. Python creates the worktree but never commits code:

bash
cd .worktrees/042-mission-lane-a
# ... write code, run tests ...
git add src/ tests/
git commit -m "feat(WP01): implement auth middleware"

Validation: When the agent tries to move WP to for_review, spec-kitty checks that the worktree has commits ahead of the base branch (git rev-list --count <base>..HEAD). If zero commits, the transition is rejected.

2. Refreshing a Stale Lane Workspace

If a lane branch has advanced while you were away:

bash
cd .worktrees/042-mission-lane-a
spec-kitty implement WP## --mission 042-mission

Let the stale-check and auto-merge classifier decide whether the lane can be refreshed automatically from the mission branch. Only perform a manual rebase when the CLI reports a conflict that requires agent resolution.

Python displays the lane workspace and branch, but the agent resolves conflicts and completes the rebase manually when needed.

3. Multi-Dependency Work

Task finalization computes a lane that already contains the required dependency shape. Agents do not choose one dependency as a manual base and do not manually merge sibling lane outputs to reconstruct the lane.

4. Pushing

spec-kitty merge only pushes with --push. All other pushing is the agent's responsibility.

5. Conflict Resolution

If spec-kitty merge encounters conflicts, the agent must resolve them. Python does not attempt automatic conflict resolution.

Auto-Commit Configuration

yaml
# .kittify/config.yaml
auto_commit: true    # default

When true, spec-kitty auto-commits:

  • Planning artifacts before worktree creation
  • WP frontmatter on lane transitions (doing, for_review)

When false, agents must commit everything manually.

Per-command override: --no-auto-commit flag on spec-kitty implement.

Worktree Lifecycle

1. CREATED
   spec-kitty implement WP01
   → git worktree add -b kitty/mission-042-mission-lane-a .worktrees/042-mission-lane-a kitty/mission-042-mission
   → .kittify/workspaces/042-mission-lane-a.json created

2. ACTIVE (agent works here)
   cd .worktrees/042-mission-lane-a
   → agent writes code, commits, tests
   → WP status: in_progress

3. FOR REVIEW
   spec-kitty agent tasks move-task WP01 --to for_review
   → auto-commit: "chore: Start WP01 review"
   → reviewer checks the diff

4. MERGED
   spec-kitty accept --mission 042-mission
   spec-kitty merge --mission 042-mission
   → detached merge worktree validates and advances target branch
   → git worktree remove .worktrees/042-mission-lane-a --force
   → git branch -d kitty/mission-042-mission-lane-a
   → .kittify/workspaces/042-mission-lane-a.json removed

5. CLEANED UP
   Worktree directory gone, branch deleted, workspace context removed

Git Hooks

Spec Kitty installs a scoped commit-guard hook for managed workflows. Do not edit .git/hooks/ by hand; use the CLI repair path when hook state is stale.

Key Anti-Patterns

  1. Agent creates worktree manually — Don't git worktree add yourself. Use spec-kitty implement. Manual worktrees won't have workspace context, canonical workspace context, or proper branch naming.

  2. Agent commits in the repository root checkout during implementation — Implementation commits belong in the worktree, not in the repository root checkout. The repository root checkout is for planning artifacts only.

  3. Agent pushes without being asked — Never auto-push. Only push when the user explicitly requests it or when using spec-kitty merge --push.

  4. Agent modifies other WPs from a worktree — Each worktree is isolated to one WP. Don't modify files belonging to other WPs.

  5. Agent skips commits before for_review — Spec-kitty validates that worktree has commits ahead of base before accepting the transition.

References

  • references/git-operations-matrix.md -- Complete matrix of every git command spec-kitty runs

© spec-kitty, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 1 other file (references) in src/charter/offering/skills/spec-kitty-git-workflow of spec-kitty/spec-kitty.

  • SKILL.md
  • references/git-operations-matrix.md

Open the folder on GitHubat commit 2fe1172

Compare with similar skills

Spec Kitty Git Workflow next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Spec Kitty Git Workflow compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Spec Kitty Git Workflow this skillspec-kitty/spec-kitty1.7k—~2.3kAutomated safety check: PassMIT
Finishing a Development Branchobra/superpowers296k5 repos~1.9kAutomated safety check: PassMIT
Git Worktree Cleanuplobehub/lobehub83k—~2.8kAutomated safety check: PassCustom licence
Skyvern Version BumpSkyvern-AI/skyvern23k—~1kAutomated safety check: NotesAGPL-3.0
Saleor Commit Workflowsaleor/saleor23k—~575Automated safety check: PassBSD-3-Clause
Ccmanager Configkbwo/ccmanager1.3k—~1.5kAutomated safety check: PassMIT

Similar skills

  • Finishing a Development Branch

    obra/superpowers

    Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.

    296k GitHub starsUsed in 5 repos~1.9k tokens
    DevelopmentAuto-check passed

  • Git Worktree Cleanup

    lobehub/lobehub

    Audits stale Git worktrees and branches with a bundled script, classifies each one, and deletes only after you approve the exact candidates.

    83k GitHub stars~2.8k tokensUpdated today
    DevelopmentAuto-check passed

  • Skyvern Version Bump

    Skyvern-AI/skyvern

    Walks through a Skyvern open-source release bump: update the version, rebuild the Python and TypeScript SDKs with Fern, commit, and open a pull request.

    23k GitHub stars~1k tokensUpdated today
    DevelopmentAuto-check: notes

  • Saleor Commit Workflow

    saleor/saleor

    Commits changes in the Saleor codebase and works through pre-commit hook failures from ruff, mypy, the GraphQL schema check and the migrations check.

    23k GitHub stars~575 tokensUpdated yesterday
    DevelopmentAuto-check passed

  • Ccmanager Config

    kbwo/ccmanager

    Set up, review, or repair a CCManager config — .ccmanager.json at a git repository root, or the global ~/.config/ccmanager/config.json.

    1.3k GitHub stars~1.5k tokensUpdated 10 days ago
    DevelopmentAuto-check passed

  • pybind11 Release Preparation

    pybind/pybind11

    Opens the pybind11 release-preparation pull request: picking the release base, bumping the version in common.h and integrating the changelog, following docs/release.rst.

    18k GitHub stars~1.7k tokensUpdated today
    DevelopmentAuto-check passed

More from spec-kitty/spec-kitty

All 50 skills in this repo

  • Spec Kitty Setup Doctor

    spec-kitty/spec-kitty

    Install, verify, and recover the modern Spec Kitty 2.0.11+ operating surface.

    1.7k GitHub stars~1.4k tokensUpdated today
    Auto-check passed

  • Spk Doctrine Show Me

    spec-kitty/spec-kitty

    Explain Spec Kitty work with compact, checkable visuals. An agent skill from spec-kitty/spec-kitty.

    1.7k GitHub stars~944 tokensUpdated today
    Auto-check passed

  • Spec Kitty Glossary Context

    spec-kitty/spec-kitty

    Curate and apply canonical terminology across Spec Kitty missions.

    1.7k GitHub stars~3.1k tokensUpdated today
    Auto-check passed

  • Spec Kitty Mission System

    spec-kitty/spec-kitty

    Understand how Spec Kitty missions work: the 4 built-in mission types, how they define workflows via step contracts and action indices, how missions and work packages relate, how templates are…

    1.7k GitHub stars~4.3k tokensUpdated today
    Auto-check passed

  • Spec Kitty Orchestrator API Operator

    spec-kitty/spec-kitty

    Teach agents and external systems how to use spec-kitty orchestrator-api to drive workflows from outside the host CLI.

    1.7k GitHub stars~3k tokensUpdated today
    Auto-check passed

  • Spec Kitty Runtime Review

    spec-kitty/spec-kitty

    Review runtime-owned outputs using the Spec Kitty review workflow surface, then direct approval or rejection with structured feedback.

    1.7k GitHub stars~1.5k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Spec Kitty Git Workflow

What does Spec Kitty Git Workflow do?

Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit…. Spec Kitty Git Workflow is an agent skill from spec-kitty/spec-kitty. Understand how Spec Kitty manages git: what git operations Python handles automatically, what agents must do manually, worktree lifecycle, auto-commit behavior, merge execution, and the safe-commit pattern.

When should I use Spec Kitty Git Workflow?

Spec Kitty Git Workflow fits situations like: tasks that involve Git workflow; tasks that involve Git worktrees.

How do I install Spec Kitty Git Workflow in Claude Code?

Run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-git-workflow -a claude-code`. Or copy the skill folder (src/charter/offering/skills/spec-kitty-git-workflow in spec-kitty/spec-kitty) into .claude/skills/spec-kitty-git-workflow in your project. Claude Code loads it when a task matches its description.

How do I install Spec Kitty Git Workflow in Codex?

Run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-git-workflow -a codex`. Or copy the skill folder (src/charter/offering/skills/spec-kitty-git-workflow in spec-kitty/spec-kitty) into .agents/skills/spec-kitty-git-workflow in your project. Codex loads it when a task matches its description.

Can I use Spec Kitty Git Workflow in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add spec-kitty/spec-kitty --skill spec-kitty-git-workflow -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/spec-kitty-git-workflow, .gemini/skills/spec-kitty-git-workflow, .github/skills/spec-kitty-git-workflow and .opencode/skills/spec-kitty-git-workflow in your project.

What does Spec Kitty Git Workflow need to run?

Going by SKILL.md and its folder, Spec Kitty Git Workflow needs the command-line tools its instructions call (git). Our summary lists: Python 3.

Does Spec Kitty Git Workflow access the network?

SKILL.md contains no URLs. Its commands use git, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Spec Kitty Git Workflow safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Spec Kitty Git Workflow use?

Spec Kitty Git Workflow is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Spec Kitty Git Workflow use?

About 2.3k tokens (SKILL.md is roughly 9.3k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 967 tokens, read only when the agent opens those files.

What are the alternatives to Spec Kitty Git Workflow?

Skills that share tags, products or a category with Spec Kitty Git Workflow: Finishing a Development Branch (obra/superpowers, 296k stars), Git Worktree Cleanup (lobehub/lobehub, 83k stars), Skyvern Version Bump (Skyvern-AI/skyvern, 23k stars) and Saleor Commit Workflow (saleor/saleor, 23k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Spec Kitty Git Workflow?

spec-kitty (a GitHub organization) maintains it in spec-kitty/spec-kitty, which has 1,672 GitHub stars. The repository holds 50 skills in this directory. The repository was last updated on October 7, 2026.

Source: spec-kitty/spec-kitty on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.