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)

[RbBtSn0w]

Hi @mnriem,

Following up on this proposal, I have built a working prototype/demo of the global plugin architecture in my fork (RbBtSn0w/spec-kit), and I'd like to share the design and initial results.

Design Principles & Architecture

To address the tension between project self-containment and global convenience, we designed the prototype using an opt-in global plugin model built on top of the external adg (Agent Directory Group) tool:

1. Opt-in & Backwards Compatible (Default Preserved):
   The default installation remains project-local. The global behavior is explicitly enabled via the --plugin flag during specify init or specify integration use (e.g., specify init --here --plugin).

2. Global Provisioning via adg:
   When --plugin is used:

   • Instead of duplicating skill directories into the project's local agent folder (e.g., .claude/skills/), we bundle the core Spec Kit skills into a single, global ADG plugin managed in ~/.agents/plugins/.
   • On first use, the CLI automatically compiles and registers the global plugin into the user's coding agent runtimes (like Claude Code) via adg. Subsequent usages consume the global plugin directly.

3. Degraded Mode for CI/Offline Environments:
   If the adg CLI is absent on the local machine (or in a CI pipeline), the init command runs in a degraded mode:

   • It outputs the plugin source tree to a directory specified by --plugin-out <dir>.
   • This prevents execution from blocking, while allowing offline or CI environments to capture the code for a later global import (adg plugins add).

Status of the Demo

This prototype is currently running successfully on my fork, and we have addressed initial edge cases (such as silencing hook execution outputs and ensuring type-safe plugin detection).

I would love to hear your thoughts on this design direction as a starting point for global configuration support!

[mnriem]

Thanks for building this out, @RbBtSn0w — the prototype makes the tradeoffs concrete, which is really helpful for the discussion.

I want to flag two concerns before this goes further, both rooted in Spec Kit's layering rather than the goal (which I support).

1. Core should not depend on an external executable.

The --plugin path is built on adg (@rbbtsn0w/adg), and adg_bridge.py shells out to that binary for the feature's primary path. The --plugin-out degraded mode only emits a source tree — it doesn't actually deliver the feature without adg present. That makes a separately-installed, single-maintainer npm binary a hard runtime dependency for the intended workflow, and wires Spec Kit's init flow to an artifact outside the project's release/security process. I'd like to keep the core free of external-executable dependencies; if adg interop is valuable, it belongs as an optional, separately-installed extension, never on the core init path.

2. The global install globalizes the wrong layer.

Spec Kit deliberately separates two layers:

• Agent-agnostic content — extensions/, presets/, workflows/, templates/. Authored once; the real substance.
• Agent-specific integration — integrations/<agent>/ (~30 agents). Thin, per-project scaffolding that renders that content into each agent's required shape (.claude/skills/, .github/prompts/, .gemini/commands/, a context file, etc.).

The --plugin mode globalizes the agent-specific layer: it packages core skills (the rendered output of the Claude/skills integration) into a global adg plugin under ~/.agents/plugins/. That's the one layer that is intentionally cheap, disposable, and per-project — it's what keeps a clone self-contained and what lets the same content target Claude, Copilot, Gemini, Codex, and the rest.

I think this happens because adg's unit of distribution is agent skills, so the design conforms to adg's model rather than Spec Kit's. Two consequences fall out of that:

• It installs scaffolding globally instead of content. The thing worth installing once is the agent-agnostic extensions/presets/workflows; the per-agent scaffolding should stay local and regenerable.
• It collapses ~30 agents to one family. A ~/.agents/plugins plugin is Claude-Code-shaped; globalizing at the skills layer bakes in one agent's format.

Suggested direction

Keep the goal, change the seam. A global install should populate the agent-agnostic layer once:

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

…and then each project's specify init / specify integration use runs its normal, thin, local per-agent scaffolding, resolving content with layered precedence (env → project .specify/ → global ~/.specify/ → built-in defaults) — essentially Direction A from the original proposal, implemented natively. The integration layer already knows how to render every supported agent from shared content; global install just needs to give it a global content source to render from, not a pre-rendered global plugin for a single agent.

To echo my earlier point: opt-in, backwards-compatible, and with the current project-local behavior remaining the default for several minor releases. I'm fully on board with first-class ~/.specify support along those lines.