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--timestampflags are ignoredFEATURE_NUMis extracted when the final path segment starts with a numeric or timestamp feature marker (for example042-name,feat/042-name, orjdoe/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:
- Check
.specify/extensions/git/git-config.ymlforbranch_numberingvalue - Check
.specify/init-options.jsonforfeature_numberingvalue (inherit from core) - Check
.specify/init-options.jsonforbranch_numberingvalue (deprecated, backward compatibility — will be removed in a future release) - Default to
sequentialif 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_PATHfrom the script's JSON output. - Change directory into it before doing anything else:
- Bash:
cd "$WORKTREE_PATH" - PowerShell:
Set-Location "$env:WORKTREE_PATH"
- Bash:
- 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_PATHis 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 (
--jsonfor Bash,-Jsonfor PowerShell) so the output can be parsed reliably - You must only ever run this script once per feature
- The JSON output will contain
BRANCH_NAMEandFEATURE_NUM, andWORKTREE_PATHwhen worktree mode is active - Do not manually expand
branch_template; the script reads the git extension config and applies it consistently - When
WORKTREE_PATHis 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_NAMEandFEATURE_NUMso 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_PATHenvironment variable. - The script still outputs
BRANCH_NAME(the branch name) andFEATURE_NUM; when worktree mode is active it additionally outputsWORKTREE_PATH(the worktree directory). You MUSTcdintoWORKTREE_PATHautomatically — 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, orjdoe/web/003-user-auth)FEATURE_NUM: The numeric or timestamp prefix usedWORKTREE_PATH: (only whencreate_worktree: true) The worktree directory created for the feature
04 同仓库更多 Skills
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
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
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
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
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
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