Treating Spec-Kit artifacts as packages (and managing the .specify directory)

[markuswondrak]

Hi everyone,

While cleaning up the Extended Flow bundle for Workflow Cockpit, I found that treating Spec-Kit artifacts as loose files under .specify/ can lead to arbitrary repository boundaries. I believe we should treat them as packages and dependencies instead.

I wrote an article on this approach, focusing on a few key practices:

• Separating catalog-published components from project intent, like constitution files and extension configurations.
• Ignoring anything in .specify/ that can be reconstructed via catalogs, including installed extension copies and runtime caches.
• Using priorities to deliberately control how presets compose, rather than relying on alphabetical resolution.

How are others handling multi-bundle Spec-Kit projects?

I would love to hear your thoughts on this package-driven approach and how you are handling in day-to-day work!

[mnriem]

Thanks for writing this up. Your article highlights something we haven’t made easy enough to find in our documentation: Spec Kit’s default is to share the .specify/ setup in the repository, not to treat installed components as disposable dependencies. specify init now creates a .specify/.gitignore for the current-feature pointer and machine-local extension overrides, while leaving the shared tooling available to teammates on a fresh checkout.

I can see why the boundary looks unclear: our version-control guidance is scattered, and the extension guide’s advice about ignoring installation state needs to be reconciled with that default. We should make the recommended tracked files and the purpose of the generated ignore file explicit in one place, then describe your bundle-driven reconstruction approach as a valid alternative with its bootstrap and versioning requirements.

Your multi-bundle example is useful for testing that guidance. In particular, which part prompted the cleanup most: repository size, reviewing installed-file changes, or uncertainty about which declarations would reconstruct the setup?

[markuswondrak]

Actually I really try to always have as less in the source tree as possible. Everything that can be generated (or installed) does not need to be tracked. I don't like a huge diff just because I updated specify or some bundles.

So to answer your question it would rather go into the direction of reconstructing the setup for new developers and to leverage the Spec-kit distribution capability to achieve that.

[mnriem]

Yes, I agree with the less is more sentiment. Ultimately any change we do has to be done gradually