Skip to content

Commit a084d09

Browse files
committed
feat: add git extension with hooks on all core commands
- Create extensions/git/ with 5 commands: initialize, feature, validate, remote, commit - 18 hooks covering before/after for all 9 core commands - Scripts: create-new-feature, initialize-repo, auto-commit, git-common (bash + powershell) - Configurable: branch_numbering, init_commit_message, per-command auto-commit with custom messages - Add hooks to analyze, checklist, clarify, constitution, taskstoissues command templates - Allow hooks-only extensions (no commands required) - Bundle extension in wheel via pyproject.toml force-include - Resolve bundled extensions locally before catalog lookup - Remove planned-but-unimplemented before/after_commit hook refs - Update extension docs (API ref, dev guide, user guide) - 37 new tests covering manifest, install, all scripts (bash+pwsh), config reading, graceful degradation Stage 1: opt-in via 'specify extension add git'. No auto-install, no changes to specify.md or core git init code. Refs: github#841, github#1382, github#1066, github#1791, github#1191
1 parent 7f08f31 commit a084d09

32 files changed

Lines changed: 2932 additions & 53 deletions

‎extensions/EXTENSION-API-REFERENCE.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -108,7 +108,7 @@ defaults: # Optional, default configuration values
108108
#### `hooks`
109109

110110
- **Type**: object
111-
- **Keys**: Event names (e.g., `after_specify`, `after_plan`, `after_tasks`, `after_implement`, `before_commit`)
111+
- **Keys**: Event names (e.g., `after_specify`, `after_plan`, `after_tasks`, `after_implement`, `before_analyze`)
112112
- **Description**: Hooks that execute at lifecycle events
113113
- **Events**: Defined by core spec-kit commands
114114

@@ -559,8 +559,16 @@ Standard events (defined by core):
559559
- `after_tasks` - After task generation
560560
- `before_implement` - Before implementation
561561
- `after_implement` - After implementation
562-
- `before_commit` - Before git commit *(planned - not yet wired into core templates)*
563-
- `after_commit` - After git commit *(planned - not yet wired into core templates)*
562+
- `before_analyze` - Before cross-artifact analysis
563+
- `after_analyze` - After cross-artifact analysis
564+
- `before_checklist` - Before checklist generation
565+
- `after_checklist` - After checklist generation
566+
- `before_clarify` - Before spec clarification
567+
- `after_clarify` - After spec clarification
568+
- `before_constitution` - Before constitution update
569+
- `after_constitution` - After constitution update
570+
- `before_taskstoissues` - Before tasks-to-issues conversion
571+
- `after_taskstoissues` - After tasks-to-issues conversion
564572

565573
### Hook Configuration
566574

‎extensions/EXTENSION-DEVELOPMENT-GUIDE.md‎

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -177,9 +177,9 @@ Compatibility requirements.
177177

178178
What the extension provides.
179179

180-
**Required sub-fields**:
180+
**Optional sub-fields**:
181181

182-
- `commands`: Array of command objects (must have at least one)
182+
- `commands`: Array of command objects (at least one command or hook is required)
183183

184184
**Command object**:
185185

@@ -196,12 +196,19 @@ Integration hooks for automatic execution.
196196

197197
Available hook points:
198198

199-
- `after_tasks`: After `/speckit.tasks` completes
200-
- `after_implement`: After `/speckit.implement` completes (future)
199+
- `before_specify` / `after_specify`: Before/after specification generation
200+
- `before_plan` / `after_plan`: Before/after implementation planning
201+
- `before_tasks` / `after_tasks`: Before/after task generation
202+
- `before_implement` / `after_implement`: Before/after implementation
203+
- `before_analyze` / `after_analyze`: Before/after cross-artifact analysis
204+
- `before_checklist` / `after_checklist`: Before/after checklist generation
205+
- `before_clarify` / `after_clarify`: Before/after spec clarification
206+
- `before_constitution` / `after_constitution`: Before/after constitution update
207+
- `before_taskstoissues` / `after_taskstoissues`: Before/after tasks-to-issues conversion
201208

202209
Hook object:
203210

204-
- `command`: Command to execute (must be in `provides.commands`)
211+
- `command`: Command to execute (typically from `provides.commands`, but can reference any registered command)
205212
- `optional`: If true, prompt user before executing
206213
- `prompt`: Prompt text for optional hooks
207214
- `description`: Hook description

‎extensions/EXTENSION-USER-GUIDE.md‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -403,8 +403,10 @@ settings:
403403
404404
# Hook configuration
405405
# Available events: before_specify, after_specify, before_plan, after_plan,
406-
# before_tasks, after_tasks, before_implement, after_implement
407-
# Planned (not yet wired into core templates): before_commit, after_commit
406+
# before_tasks, after_tasks, before_implement, after_implement,
407+
# before_analyze, after_analyze, before_checklist, after_checklist,
408+
# before_clarify, after_clarify, before_constitution, after_constitution,
409+
# before_taskstoissues, after_taskstoissues
408410
hooks:
409411
after_tasks:
410412
- extension: jira

‎extensions/catalog.json‎

Lines changed: 16 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,23 @@
11
{
22
"schema_version": "1.0",
3-
"updated_at": "2026-03-10T00:00:00Z",
3+
"updated_at": "2026-04-06T00:00:00Z",
44
"catalog_url": "https://raw.githubusercontent.com/github/spec-kit/main/extensions/catalog.json",
55
"extensions": {
6+
"git": {
7+
"name": "Git Branching Workflow",
8+
"id": "git",
9+
"version": "1.0.0",
10+
"description": "Feature branch creation, numbering (sequential/timestamp), validation, and Git remote detection",
11+
"author": "spec-kit-core",
12+
"repository": "https://github.com/github/spec-kit",
13+
"download_url": "https://github.com/github/spec-kit/releases/download/ext-git-v1.0.0/git.zip",
14+
"tags": [
15+
"git",
16+
"branching",
17+
"workflow",
18+
"core"
19+
]
20+
},
621
"selftest": {
722
"name": "Spec Kit Self-Test Utility",
823
"id": "selftest",

‎extensions/git/README.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Git Branching Workflow Extension
2+
3+
Feature branch creation, numbering (sequential/timestamp), validation, and Git remote detection for Spec Kit.
4+
5+
## Overview
6+
7+
This extension provides Git branching operations as an optional, self-contained module. It manages:
8+
9+
- **Feature branch creation** with sequential (`001-feature-name`) or timestamp (`20260319-143022-feature-name`) numbering
10+
- **Branch validation** to ensure branches follow naming conventions
11+
- **Git remote detection** for GitHub integration (e.g., issue creation)
12+
13+
## Commands
14+
15+
| Command | Description |
16+
|---------|-------------|
17+
| `speckit.git.feature` | Create a feature branch with sequential or timestamp numbering |
18+
| `speckit.git.validate` | Validate current branch follows feature branch naming conventions |
19+
| `speckit.git.remote` | Detect Git remote URL for GitHub integration |
20+
21+
## Hooks
22+
23+
| Event | Command | Optional | Description |
24+
|-------|---------|----------|-------------|
25+
| `before_specify` | `speckit.git.feature` | No | Create feature branch before specification |
26+
| `after_implement` | `speckit.git.validate` | Yes | Validate branch naming after implementation |
27+
28+
## Configuration
29+
30+
Configuration is stored in `.specify/extensions/git/git-config.yml`:
31+
32+
```yaml
33+
# Branch numbering strategy: "sequential" or "timestamp"
34+
branch_numbering: sequential
35+
```
36+
37+
## Installation
38+
39+
```bash
40+
# Install from the bundled extension directory
41+
specify extension add --dev extensions/git
42+
```
43+
44+
## Disabling
45+
46+
```bash
47+
# Disable the git extension (spec creation continues without branching)
48+
specify extension disable git
49+
50+
# Re-enable it
51+
specify extension enable git
52+
```
53+
54+
## Graceful Degradation
55+
56+
When Git is not installed or the directory is not a Git repository:
57+
- Spec directories are still created under `specs/`
58+
- Branch creation is skipped with a warning
59+
- Branch validation is skipped with a warning
60+
- Remote detection returns empty results
61+
62+
## Scripts
63+
64+
The extension bundles cross-platform scripts:
65+
66+
- `scripts/bash/create-new-feature.sh` — Bash implementation
67+
- `scripts/bash/git-common.sh` — Shared Git utilities (Bash)
68+
- `scripts/powershell/create-new-feature.ps1` — PowerShell implementation
69+
- `scripts/powershell/git-common.ps1` — Shared Git utilities (PowerShell)
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
description: "Auto-commit changes after a Spec Kit command completes"
3+
scripts:
4+
sh: ../../scripts/bash/auto-commit.sh
5+
ps: ../../scripts/powershell/auto-commit.ps1
6+
---
7+
8+
# Auto-Commit Changes
9+
10+
Automatically stage and commit all changes after a Spec Kit command completes.
11+
12+
## Behavior
13+
14+
This command is invoked as a post-hook after core commands. It:
15+
16+
1. Checks `.specify/extensions/git/git-config.yml` for the `auto_commit` section
17+
2. Looks up the specific event key (e.g., `after_specify`) to see if auto-commit is enabled
18+
3. Falls back to `auto_commit.default` if no event-specific key exists
19+
4. Uses the per-command `message` if configured, otherwise a default message
20+
5. If enabled and there are uncommitted changes, runs `git add .` + `git commit`
21+
22+
## Execution
23+
24+
The hook system passes the event name to the script:
25+
26+
- **Bash**: `.specify/extensions/git/scripts/bash/auto-commit.sh after_specify`
27+
- **PowerShell**: `.specify/extensions/git/scripts/powershell/auto-commit.ps1 after_specify`
28+
29+
## Configuration
30+
31+
In `.specify/extensions/git/git-config.yml`:
32+
33+
```yaml
34+
auto_commit:
35+
default: false # Global toggle — set true to enable for all commands
36+
after_specify:
37+
enabled: true # Override per-command
38+
message: "[Spec Kit] Add specification"
39+
after_plan:
40+
enabled: false
41+
message: "[Spec Kit] Add implementation plan"
42+
```
43+
44+
## Graceful Degradation
45+
46+
- If Git is not available or not a repository: skips silently
47+
- If no config file exists: skips (disabled by default)
48+
- If no changes to commit: skips with a message
Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
description: "Create a feature branch with sequential or timestamp numbering"
3+
scripts:
4+
sh: ../../scripts/bash/create-new-feature.sh
5+
ps: ../../scripts/powershell/create-new-feature.ps1
6+
---
7+
8+
# Create Feature Branch
9+
10+
Create a new feature branch for the given specification.
11+
12+
## User Input
13+
14+
```text
15+
$ARGUMENTS
16+
```
17+
18+
You **MUST** consider the user input before proceeding (if not empty).
19+
20+
## Prerequisites
21+
22+
- Verify Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
23+
- If Git is not available, warn the user and skip branch creation (spec directory will still be created)
24+
25+
## Branch Numbering Mode
26+
27+
Determine the branch numbering strategy by checking configuration in this order:
28+
29+
1. Check `.specify/extensions/git/git-config.yml` for `branch_numbering` value
30+
2. Check `.specify/init-options.json` for `branch_numbering` value (backward compatibility)
31+
3. Default to `sequential` if neither exists
32+
33+
## Execution
34+
35+
Generate a concise short name (2-4 words) for the branch:
36+
- Analyze the feature description and extract the most meaningful keywords
37+
- Use action-noun format when possible (e.g., "add-user-auth", "fix-payment-bug")
38+
- Preserve technical terms and acronyms (OAuth2, API, JWT, etc.)
39+
40+
Run the appropriate script based on your platform:
41+
42+
- **Bash**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --short-name "<short-name>" "<feature description>"`
43+
- **Bash (timestamp)**: `.specify/extensions/git/scripts/bash/create-new-feature.sh --json --timestamp --short-name "<short-name>" "<feature description>"`
44+
- **PowerShell**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -ShortName "<short-name>" "<feature description>"`
45+
- **PowerShell (timestamp)**: `.specify/extensions/git/scripts/powershell/create-new-feature.ps1 -Json -Timestamp -ShortName "<short-name>" "<feature description>"`
46+
47+
**IMPORTANT**:
48+
- Do NOT pass `--number` — the script determines the correct next number automatically
49+
- Always include the JSON flag (`--json` for Bash, `-Json` for PowerShell) so the output can be parsed reliably
50+
- You must only ever run this script once per feature
51+
- The JSON output will contain BRANCH_NAME and SPEC_FILE paths
52+
53+
If the extension scripts are not found at the `.specify/extensions/git/` path, fall back to:
54+
- **Bash**: `scripts/bash/create-new-feature.sh`
55+
- **PowerShell**: `scripts/powershell/create-new-feature.ps1`
56+
57+
## Graceful Degradation
58+
59+
If Git is not installed or the current directory is not a Git repository:
60+
- The script will still create the spec directory under `specs/`
61+
- A warning will be printed: `[specify] Warning: Git repository not detected; skipped branch creation`
62+
- The workflow continues normally without branch creation
63+
64+
## Output
65+
66+
The script outputs JSON with:
67+
- `BRANCH_NAME`: The created branch name (e.g., `003-user-auth` or `20260319-143022-user-auth`)
68+
- `SPEC_FILE`: Path to the created spec file
69+
- `FEATURE_NUM`: The numeric or timestamp prefix used
Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
---
2+
description: "Initialize a Git repository with an initial commit"
3+
scripts:
4+
sh: ../../scripts/bash/initialize-repo.sh
5+
ps: ../../scripts/powershell/initialize-repo.ps1
6+
---
7+
8+
# Initialize Git Repository
9+
10+
Initialize a Git repository in the current project directory if one does not already exist.
11+
12+
## Execution
13+
14+
Run the appropriate script from the project root:
15+
16+
- **Bash**: `.specify/extensions/git/scripts/bash/initialize-repo.sh`
17+
- **PowerShell**: `.specify/extensions/git/scripts/powershell/initialize-repo.ps1`
18+
19+
If the extension scripts are not found, fall back to:
20+
- **Bash**: `git init && git add . && git commit -m "Initial commit from Specify template"`
21+
- **PowerShell**: `git init; git add .; git commit -m "Initial commit from Specify template"`
22+
23+
The script handles all checks internally:
24+
- Skips if Git is not available
25+
- Skips if already inside a Git repository
26+
- Runs `git init`, `git add .`, and `git commit` with an initial commit message
27+
28+
## Customization
29+
30+
Replace the script to add project-specific Git initialization steps:
31+
- Custom `.gitignore` templates
32+
- Default branch naming (`git config init.defaultBranch`)
33+
- Git LFS setup
34+
- Git hooks installation
35+
- Commit signing configuration
36+
- Git Flow initialization
37+
38+
## Output
39+
40+
On success:
41+
- `✓ Git repository initialized`
42+
43+
## Graceful Degradation
44+
45+
If Git is not installed or `git init` fails:
46+
- Warn the user
47+
- Do NOT block the rest of the workflow
48+
- The project continues to function without Git (specs can still be created under `specs/`)
Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
description: "Detect Git remote URL for GitHub integration"
3+
---
4+
5+
# Detect Git Remote URL
6+
7+
Detect the Git remote URL for integration with GitHub services (e.g., issue creation).
8+
9+
## Prerequisites
10+
11+
- Check if Git is available by running `git rev-parse --is-inside-work-tree 2>/dev/null`
12+
- If Git is not available, output a warning and return empty:
13+
```
14+
[specify] Warning: Git repository not detected; cannot determine remote URL
15+
```
16+
17+
## Execution
18+
19+
Run the following command to get the remote URL:
20+
21+
```bash
22+
git config --get remote.origin.url
23+
```
24+
25+
## Output
26+
27+
Parse the remote URL and determine:
28+
29+
1. **Repository owner**: Extract from the URL (e.g., `github` from `https://github.com/github/spec-kit.git`)
30+
2. **Repository name**: Extract from the URL (e.g., `spec-kit` from `https://github.com/github/spec-kit.git`)
31+
3. **Is GitHub**: Whether the remote points to a GitHub repository
32+
33+
Supported URL formats:
34+
- HTTPS: `https://github.com/<owner>/<repo>.git`
35+
- SSH: `[email protected]:<owner>/<repo>.git`
36+
37+
> [!CAUTION]
38+
> ONLY report a GitHub repository if the remote URL actually points to github.com.
39+
> Do NOT assume the remote is GitHub if the URL format doesn't match.
40+
41+
## Graceful Degradation
42+
43+
If Git is not installed, the directory is not a Git repository, or no remote is configured:
44+
- Return an empty result
45+
- Do NOT error — other workflows should continue without Git remote information

0 commit comments

Comments
 (0)