[Feature]: `provides.branch_patterns` — let extensions register branch naming conventions and spec directory mappings

[pradeepmouli]

Background

spec-kit's branch validation is built around a single naming convention: ###-description. This works well for the standard feature workflow, but the extension ecosystem has naturally evolved richer branching models — typed prefixes that carry semantic meaning about the kind of work being done (bugfix/, hotfix/, refactor/, etc.) and corresponding subdirectory structures in specs/.

Currently, there is no way for an extension to register these patterns with spec-kit. Any branch that doesn't match ^[0-9]{3}- is rejected, and any spec path that lives outside the top-level specs/ directory isn't found by path resolution.

Problem

Two related gaps:

Branch validation — Extensions that introduce typed branch prefixes have no supported registration point. Branches like bugfix/003-login-crash or refactor/007-auth-module are structurally valid but fail check_feature_branch() because only the core pattern is known.

Spec path resolution — Extensions that organise specs into subdirectories (specs/bugfix/, specs/refactor/, etc.) have no way to tell spec-kit where to look. Any command that resolves a spec path from the current branch name will fail to find documents that live in an extension-managed subdirectory.

Proposal

Add provides.branch_patterns to the extension manifest schema, letting extensions declaratively register the branch patterns and directory mappings they own:

# extension.yml
provides:
  branch_patterns:
    - pattern: "^bugfix/[0-9]{3}-"
      description: "Bug fix workflow branches"
      spec_dir: "specs/bugfix"
    - pattern: "^hotfix/[0-9]{3}-"
      description: "Emergency hotfix branches"
      spec_dir: "specs/hotfix"
    - pattern: "^refactor/[0-9]{3}-"
      description: "Refactoring branches"
      spec_dir: "specs/refactor"
    - pattern: "^modify/[0-9]{3}\\^[0-9]{3}-"
      description: "Feature modification branches"
      spec_dir: "specs/modify"

specify extension add would collect registered patterns into a lightweight registry (e.g. .specify/extensions/.branch-patterns). check_feature_branch() would consult this registry before rejecting a branch name, and spec path resolution would use the associated spec_dir when resolving branch-relative paths.

This keeps the validation logic in spec-kit — extensions simply declare what they need.

Relationship to Existing Work

The preset system introduced in v0.3.0 established a clean precedent: extensions declare what they provide in a manifest, and spec-kit's runtime consults those declarations rather than requiring extensions to modify core files. branch_patterns follows the same model — presets override template data, branch patterns extend validation rules.

The specify doctor command would be a natural place to surface which extensions have registered patterns and whether any conflicts exist between them.

Acceptance Criteria

• extension.yml schema accepts provides.branch_patterns[] entries with pattern (required), description (optional), and spec_dir (optional)
• specify extension add writes registered patterns to a per-install registry
• specify extension remove removes the extension's registered patterns from the registry
• check_feature_branch() accepts branches matching any registered extension pattern
• Spec path resolution uses spec_dir when resolving paths for extension-managed branches
• specify doctor reports registered branch patterns per extension and flags any conflicts