π« Toolkit to help you get started with SDD or any other process!
docs: add branch naming convention to AGENTS.md and CONTRIBUTING.md (#2678)
Manfred Riem2dc79a7e0626
diff --git a/AGENTS.md b/AGENTS.mdindex d711b4214..448ccd37e 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -379,6 +379,32 @@ Implementation: Extends `YamlIntegration` (parallel to `TomlIntegration`):4. Uses `yaml.safe_dump()` for header fields to ensure proper escaping5. Sets `context_file = "AGENTS.md"` so the base setup manages the Spec Kit context section there+## Branch Naming Convention++All branches **must** follow this pattern:++```+<type>/<number>-<short-slug>+```++Where `<number>` is either an issue number or a PR number β whichever is created first.++| Prefix | When to use | Example |+|---|---|---|+| `feat/` | New features | `feat/2342-workflow-cli-alignment` |+| `fix/` | Bug fixes | `fix/2653-paths-only-validation` |+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |+| `community/` | Community catalog additions | `community/2492-add-mde-extension` |+| `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |++**Rules:**++1. Always include the issue or PR number immediately after the prefix β this is what makes branches traceable+2. Use kebab-case for the slug+3. Keep the slug short β enough to identify the work without looking up the issue++---+## Common Pitfalls1. **Using shorthand keys for CLI-based integrations**: For CLI-based integrations (`requires_cli: True`), the `key` must match the executable name (e.g., `"cursor-agent"` not `"cursor"`). `shutil.which(key)` is used for CLI tool checks β mismatches require special-case mappings. IDE-based integrations (`requires_cli: False`) are not subject to this constraint.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 5188d70a7..12b095f5f 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -38,7 +38,7 @@ On [GitHub Codespaces](https://github.com/features/codespaces) it's even simpler1. Fork and clone the repository1. Configure and install the dependencies: `uv sync --extra test`1. Make sure the CLI works on your machine: `uv run specify --help`-1. Create a new branch: `git checkout -b my-branch-name`+1. Create a new branch: `git checkout -b <type>/<number>-<short-slug>` (see [Branch naming](#branch-naming) below)1. Make your change, add tests, and make sure everything still works1. Test the CLI functionality with a sample project if relevant1. Push to your fork and submit a pull request@@ -55,6 +55,20 @@ Here are a few things you can do that will increase the likelihood of your pull- Write a [good commit message](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).- Test your changes with the Spec-Driven Development workflow to ensure compatibility.+### Branch naming++We recommend naming branches as `<type>/<number>-<short-slug>`, where `<number>` is the issue or PR number (whichever comes first) and `<type>` is one of:++| Prefix | When to use | Example |+|---|---|---|+| `feat/` | New features | `feat/2342-workflow-cli-alignment` |+| `fix/` | Bug fixes | `fix/2653-paths-only-validation` |+| `docs/` | Documentation changes | `docs/2677-branch-naming-convention` |+| `community/` | Community catalog additions | `community/2492-add-mde-extension` |+| `chore/` | Maintenance, tooling, CI | `chore/2366-editorconfig` |++Including the issue or PR number makes branches traceable β especially useful since the project uses squash merges and `git branch --merged` won't detect merged branches. If you start with a PR (no issue), use the PR number once it's assigned.+## Development workflowWhen working on spec-kit: