Proposal: First-Class Support for Global Configurations, Extensions, and Presets (~/.specify)

[RbBtSn0w]

Proposal: First-Class Support for Global Configurations, Extensions, and Presets (~/.specify)

Background & Problem Statement

Currently, Spec Kit manages extensions, presets, integrations, and workflows primarily at the project level (<project_root>/.specify/). While this guarantees that a cloned repository remains self-contained, it introduces a significant maintenance burden for developers who use the same set of extensions, presets, or workflows across multiple local projects.

For example, when using custom-configured integrations, global agent tools, or shared preset profiles, the developer must reinstall or copy these directories into every new project's .specify folder. This results in:

1. Redundancy: Duplicating identical extensions, presets, and scripts across multiple repositories.
2. Maintenance overhead: Updating an extension configuration requires updating every individual repository manually.
3. Friction during bootstrapping: Running specify init creates project-specific settings that must be re-customized each time.

Although Spec Kit already uses ~/.specify/ implicitly for discovering catalogs (extension-catalogs.yml, preset-catalogs.yml, etc.), it does not treat the global directory as a first-class installation target or configuration home.

---

Current State Analysis

Based on the codebase audit, here is how ~/.specify behaves today:

• Global Catalogs: Catalog configuration files (such as extension-catalogs.yml, preset-catalogs.yml, workflow-catalogs.yml, etc.) are resolved with a fallback chain ending at ~/.specify/. This provides global discovery of registries.
• Local Managers: core managers like ExtensionManager and PresetManager resolve active extensions or presets solely within the project_root / ".specify" / ... folder.
• Precedent: The HermesIntegration already utilizes a global directory (~/.hermes/skills/) to share agent skills across repositories, while maintaining a marker file in the local project. This shows that a hybrid global-local model is feasible.

---

Proposed Solution Directions

We propose extending Spec Kit to support a first-class global configuration layer under ~/.specify/. The resolution logic should follow a standard layered approach: Environment Variables -> Project Local (.specify/) -> Global User Profile (~/.specify/) -> Built-in Defaults.

Here are three potential implementation strategies:

Direction A: Global Directory with Multi-Source Resolution

Introduce global target directories:

• ~/.specify/extensions/
• ~/.specify/presets/
• ~/.specify/workflows/

Key changes:

1. ExtensionManager and PresetManager scan both ~/.specify/ and local .specify/ directories.
2. If an extension or preset is referenced, the runtime loads the local one first (shadowing), falling back to the global one.
3. Introduce a --global flag in installation commands:

   specify extension install <extension-name> --global

Direction B: Global Preset Profile as Default Templates (Incremental Start)

Focus on simplifying the setup experience by allowing users to define a default profile in ~/.specify/preset.yml or ~/.specify/config.yml.

• When a user runs specify init, Spec Kit reads the global user profile to automatically enable their preferred default extensions, templates, and integration options, eliminating manual boilerplate setup.

Direction C: Symlink / Reference Model

To keep the project repository clean and self-contained, Spec Kit could support installing extensions globally, and referencing them locally using relative symlinks or configuration pointers (e.g., path references in .specify/extension-config.yml).

• This achieves global maintenance (one file to edit in ~/.specify/) while keeping the git status of the project clear about which extensions are active.

---

Discussion Questions

1. Self-Containment vs. Global Convenience: Should projects remain completely runnable out-of-the-box post-clone (suggesting a reference/symlink or copying mechanism), or is a runtime fallback to ~/.specify acceptable for local development?
2. Configuration Merging: If an extension is configured globally in ~/.specify/extensions/foo/config.yml, should local projects be able to partially override its settings in .specify/extensions/foo/config.yml?
3. Precedence: Is it preferred to prioritize global configuration defaulting (Direction B) or run-time multi-source fallback (Direction A)?

[mnriem]

Go for it I would say, but in incremental backwards compatible small steps. Note that I would like to see this in a way that a user can decide how they want to use it. And the way it is currently doing it should be the default for at least 5 minor releases as it switching it would need a lot of lead time here (as that would be backwards incompatible)