AGENT SKILL

speckit-git-feature

Create a feature branch with sequential or timestamp numbering

License 许可
MIT
所属仓库
arrrrny/ziki
最近更新
2026-11-11
Stars
★ 0
Forks
0

01 前言 Front Matter

name
speckit-git-feature
metadata
{ "author": "spec-kit-core", "source": "git:commands/speckit.git.feature.md" }
description
Create a feature branch with sequential or timestamp numbering
compatibility
Requires spec-kit project structure with .specify/ directory

03 SKILL.md 正文

Create Feature Branch

Create and switch to a new git feature branch for the given specification. This command handles branch creation only — the spec directory and files are created by the core /speckit-specify workflow.

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Environment Variable Override

If the user explicitly provided GIT_BRANCH_NAME (e.g., via environment variable, argument, or in their request), pass it through to the script by setting the GIT_BRANCH_NAME environment variable before invoking the script. When GIT_BRANCH_NAME is set:

  • The script uses the exact value as the branch name, bypassing all prefix/suffix generation
  • --short-name, --number, and --timestamp flags are ignored
  • FEATURE_NUM is extracted when the final path segment starts with a numeric or timestamp feature marker (for example 042-name, feat/042-name, or jdoe/app/042-name), otherwise set to the full branch name

Prerequisites

  • Verify Git is available by running git rev-parse --is-inside-work-tree 2>/dev/null
  • If Git is not available, warn the user and skip branch creation

Branch Numbering Mode

Determine the branch numbering strategy by checking configuration in this order:

  1. Check .specify/extensions/git/git-config.yml for branch_numbering value
  2. Check .specify/init-options.json for feature_numbering value (inherit from core)
  3. Check .specify/init-options.json for branch_numbering value (deprecated, backward compatibility — will be removed in a future release)
  4. Default to sequential if none of the above exist

Branch Name Template

Check .specify/extensions/git/git-config.yml for an optional branch_template value. If it is empty or missing, use the default branch shape {number}-{slug}. If it is set, {slug} must not appear before {number}, its final path segment must start with {number}-, and the script expands these tokens:

  • {author}: sanitized Git config author (user.name, falling back to the email local part)
  • {app}: sanitized Spec Kit init directory name
  • {number}: sequential number or timestamp
  • {slug}: generated short branch slug

For monorepos, a template such as {author}/{app}/{number}-{slug} creates names like jdoe/web/008-guided-tour while preserving per-project feature numbering.

The script also accepts branch_prefix as a shorthand for simple namespaces; it expands to <branch_prefix>/{number}-{slug}.

Execution

Generate a concise short name (2-4 words) for the branch:

  • Analyze the feature description and extract the most meaningful keywords
  • Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
  • Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)

Run the appropriate script based on your platform:

  • Bash: .specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --short-name "<short-name>" "<feature description>"
  • Bash (timestamp): .specify/extensions/git/scripts/bash/create-new-feature-branch.sh --json --timestamp --short-name "<short-name>" "<feature description>"
  • PowerShell: .specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -ShortName "<short-name>" "<feature description>"
  • PowerShell (timestamp): .specify/extensions/git/scripts/powershell/create-new-feature-branch.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"

Worktree Activation (MANDATORY when create_worktree: true)

If the JSON output contains WORKTREE_PATH, you MUST automatically switch the working directory into that worktree immediately after the script returns, and run every subsequent Spec Kit command from there. This is not optional: the primary checkout must stay on its original branch, and the spec, plan, and tasks must be created inside the worktree so the feature is fully isolated.

  • Parse WORKTREE_PATH from the script's JSON output.
  • Change directory into it before doing anything else:
    • Bash: cd "$WORKTREE_PATH"
    • PowerShell: Set-Location "$env:WORKTREE_PATH"
  • Verify the switch with git rev-parse --show-toplevel; it must match the worktree directory, not the primary checkout.
  • Continue the workflow (e.g. /speckit-specify) from the worktree root.
  • If WORKTREE_PATH is absent, the feature branch was created on the current checkout as usual — do not change directory.

IMPORTANT:

  • Do NOT pass --number — the script determines the correct next number automatically
  • Always include the JSON flag (--json for Bash, -Json for PowerShell) so the output can be parsed reliably
  • You must only ever run this script once per feature
  • The JSON output will contain BRANCH_NAME and FEATURE_NUM, and WORKTREE_PATH when worktree mode is active
  • Do not manually expand branch_template; the script reads the git extension config and applies it consistently
  • When WORKTREE_PATH is present, switching into it (above) is mandatory before any further steps

Graceful Degradation

If Git is not installed or the current directory is not a Git repository:

  • Branch creation is skipped with a warning: [specify] Warning: Git repository not detected; skipped branch creation
  • The script still outputs BRANCH_NAME and FEATURE_NUM so the caller can reference them

Worktree Mode

If .specify/extensions/git/git-config.yml sets create_worktree: true, the script creates a git worktree for the new feature branch instead of checking out the branch on the current checkout. Concretely it runs git worktree add -b <branch> <path> (attaching to an existing branch with git worktree add <path> <branch> when --allow-existing-branch is given), leaving HEAD of the primary checkout untouched so multiple features can be worked on in parallel.

  • By default the worktree is created inside the project at .worktrees/<branch> (e.g. myproject/.worktrees/003-user-auth).
  • Override the computed path with the SPECIFY_WORKTREE_PATH environment variable.
  • The script still outputs BRANCH_NAME (the branch name) and FEATURE_NUM; when worktree mode is active it additionally outputs WORKTREE_PATH (the worktree directory). You MUST cd into WORKTREE_PATH automatically — see the Worktree Activation section above — so the rest of the Spec Kit workflow runs inside the worktree rather than the primary checkout.

Output

The script outputs JSON with:

  • BRANCH_NAME: The branch name (e.g., 003-user-auth, 20260319-143022-user-auth, or jdoe/web/003-user-auth)
  • FEATURE_NUM: The numeric or timestamp prefix used
  • WORKTREE_PATH: (only when create_worktree: true) The worktree directory created for the feature

04 同仓库更多 Skills

arrrrny
arrrrny/ziki

speckit-tdd-verify

Audit the feature's TDD discipline and test strength from cold context: test-first evidence in git history, red-phase evidence, test-smell rubric, mutation testing on the changed files, and acceptance-criteria coverage, then write specs/<feature>/tdd/verification.md with a verdict and remediation tasks

★ 0
arrrrny
arrrrny/ziki

speckit-tdd-setup

Detect the repository's test stack and write .specify/memory/tdd-profile.md with the exact verified commands the loop needs (single test, full suite, coverage, mutation), plus the TDD principle to add to the project constitution

★ 0
arrrrny
arrrrny/ziki

speckit-tdd-run

Drive the red-green-refactor loop one behavior at a time from the test list: write one failing test, prove it fails for the right reason, make it pass with the smallest change, refactor while green, record the evidence in the feature's tdd/cycle-log.md, and tick the tasks.md tasks the completed behaviors cover

★ 0
arrrrny
arrrrny/ziki

speckit-tdd-plan

Derive the feature's test list from spec.md and plan.md into specs/<feature>/tdd/test-list.md (outer acceptance behaviors, inner unit behaviors, each traced to an acceptance criterion) and make the test tasks in tasks.md mandatory and correctly ordered

★ 0
arrrrny
arrrrny/ziki

speckit-spec-stats-runs

On-demand execution — reads verified suite command from .specify/memory/tdd-profile.md, runs it for selected specs (--all, spec id/slug, or default active feature), captures pass/fail + duration + tail, appends run record to .specify/stats/runs.json, refreshes dashboard health column

★ 0
arrrrny
arrrrny/ziki

speckit-spec-stats-report

Main generator — scans all specs/*/, derives per-feature stage, task progress, health, last updated; when the TDD extension is installed, adds a deep TDD table (acceptance/unit/characterization counts, DONE, loop mode, tasks.md state); renders dashboard to configurable output path and writes .specify/stats/stats.json snapshot

★ 0