Repository navigation
[Feature]: Separate Spec Kit framework assets from repository-specific project memory #2681
Description
Problem Statement
I’m frustrated when .specify/ contains both reusable Spec Kit framework/tooling assets and repository-specific project artifacts.
For example, a repository may have generic or tool-managed content such as extensions, scripts, templates, workflows, and integrations under .specify/, while also storing repo-owned artifacts such as memory, architecture records, constitution, feature state, plans, and other project-specific knowledge in nearby paths.
This makes ownership ambiguous:
- It is not obvious which files are framework-managed versus repo-authored.
- Review expectations differ, but the directory structure does not make that visible.
- Git ignore/tracking decisions become harder because some
.specify/content is generated/tooling-like while other content may be architectural source of truth. - Project memory feels important and repository-specific, but it sits beside imported or reusable framework assets.
The result is a blurry boundary between Spec Kit as a tool/runtime and Spec Kit as the location for project decision records.
Proposed Solution
Please introduce a clearer directory boundary between Spec Kit framework assets and repository-specific artifacts.
One possible structure would be:
.specify/
system/
extensions/
scripts/
templates/
workflows/
integrations/
project/
memory/
features/
The exact naming matters less than the principle: reusable/tool-managed Spec Kit assets should not live next to repository-authored project memory without a visible ownership boundary.
Ideally, Spec Kit would document the intended ownership model for each area and update scripts/templates so generated project artifacts are written into the project-owned area consistently.
Alternatives Considered
Another option would be to keep framework assets under .specify/ and move project-owned artifacts to a separate top-level location, for example:
.specify/
extensions/
scripts/
templates/
workflows/
integrations/
.project-memory/
architecture...
constitution...
features...
Component
Agent integrations (command files, workflows)
AI Agent (if applicable)
None
Use Cases
- When a repository uses Spec Kit over time and needs to distinguish tool-managed framework assets from repo-owned project knowledge.
- During architecture, spec, or implementation review, when reviewers need to know whether a file is generated/tooling infrastructure or an intentional project decision record.
- When configuring
.gitignore, CI checks, or repository hygiene rules for Spec Kit files. - When teams want to preserve project memory, architecture, constitution, and feature artifacts as source-of-truth records without mixing them with reusable extensions, scripts, or templates.
- When Spec Kit is installed or upgraded and users need confidence that framework updates will not be confused with project-specific state.
Acceptance Criteria
- Spec Kit has a documented ownership model that distinguishes framework/tool-managed assets from repository-specific project artifacts.
- Repository-specific artifacts such as memory, architecture records, constitution, feature state, specs, plans, or tasks are written under a clearly named project-owned area.
- Framework assets such as extensions, scripts, templates, workflows, and integrations are grouped under a clearly named tool/system-owned area.
- Existing Spec Kit commands and templates consistently read from and write to the new or clarified locations.
- Migration or compatibility guidance is provided for repositories that already use the current
.specify/layout. - The directory layout makes git tracking and review expectations clear without requiring users to inspect individual files.
- The change works with supported agents and does not break existing Spec Kit workflows without a documented transition path.
Additional Context
No response
Activity
mnriem commentedon May 26, 2026
Feel free to spearhead the effort. Note it does need to be backwards compatible for at least 4 minor releases so we can give folks time to get used to this
github-actions commentedon Aug 18, 2026
Feature assessment — separate-framework-assets · Stage 1/5: Intake
Idea Intake: Separate Spec Kit Framework Assets from Project Memory
feature-assessIdea (as captured)
Restated
Users of Spec Kit over time find that
.specify/conflates two distinct ownership classes — tool-managed framework assets (extensions, scripts, templates, integrations) and repository-authored project state (memory, constitution, features, specs) — creating ambiguity about which files are generated infrastructure vs. intentional decision records. The request is to introduce a visible directory boundary between these two classes.Origin & Context
.specify/created confusion during code review,.gitignoreconfiguration, and project hygiene@mnriemaffirmed the direction and stated a backward-compatibility constraint of at least 4 minor releasesFirst-Glance Unknowns
.specify/are actually written by the Spec Kit CLI/extensions at runtime vs. committed by the user as project artifacts?].specify/subdirectories standardized, or do projects vary significantly in what they put there?]agent-contextextension and its config at.specify/extensions/agent-context/factor into the new boundary?]Posted by GitHub Copilot (model: claude-sonnet-4.6) running the
feature-assesspipeline on behalf of@mnriem.github-actions commentedon Aug 18, 2026
Feature assessment — separate-framework-assets · Stage 2/5: Research
Idea Research: Separate Spec Kit Framework Assets from Project Memory
Users & Demand
@mnriemaffirmed the direction and confirmed backward-compatibility requirement ("at least 4 minor releases") — [source: issue [Feature]: Separate Spec Kit framework assets from repository-specific project memory #2681 comment, 2026-05-26] (confidence: high)Prior Art
.specify/: codebase inspection confirms framework-managed subdirectories (scripts/,templates/,extensions/,workflows/,presets/,integrations/,init-options.json,integration.json,.gitignore) coexist with project-owned state (memory/,feature.json,assessments/). This is the problem observed in practice. [source: grep of.specify/references insrc/specify_cli/__init__.py,agents.py,extensions/__init__.py] (confidence: high)~/.specify/already separates user-global state (auth.json, extension-catalogs.yml) from project state — precedent for namespacing exists in the same codebase. [source:src/specify_cli/authentication/config.py,src/specify_cli/extensions/_commands.py] (confidence: high).git/directory: entirely framework-managed, no user files ever placed inside. Spec Kit's.specify/started similarly but diverged by hosting user knowledge artifacts alongside CLI state. [source: ASSUMPTION / general knowledge] (confidence: medium)Market & Context
.gitignoredecisions. — ASSUMPTION (confidence: medium)pyproject.tomlversion, maintainer comment] (confidence: high)Data & Constraints
pyproject.toml]INTEGRATION_JSON = ".specify/integration.json",INIT_OPTIONS_FILE = ".specify/init-options.json",.specify/memory/rewrite inagents.py,.specify/extensions/.registry,.specify/workflows/,.specify/scripts/,.specify/templates/— all referenced by name across multiple Python modules, shell scripts, and command templates [source:integration_state.py,_init_options.py,agents.py,extensions/__init__.py,scripts/bash/common.sh] (confidence: high)agents.pyrewrites relative paths (e.g.../../memory/→.specify/memory/) when rendering command files — a path reorganization requires updating these rewrites and all consumers [source:src/specify_cli/agents.py~line 250–275] (confidence: high).specify/integrations/<key>.manifest.json; a rename would break existing manifests [source:src/specify_cli/integrations/manifest.py] (confidence: high)Evidence Against the Idea
.specify/<subdir>references across Python source, shell scripts (bash + PowerShell), Python scripts, command templates, and extension bodies. A rename is a breaking API change for every existing project and extension author. [source: codebase grep] (confidence: high)system/andproject/are illustrative in the issue; no canonical naming has been agreed — bike-shedding risk. — ASSUMPTION (confidence: low)Gaps & Open Questions
.specify/subdirectories are "framework-managed" vs. "project-owned"? Some generated-but-project-specific dirs (e.g.workflows/runs/) are ambiguous.].specify/" approach vs. moving project artifacts to a top-level directory?]Sources
src/specify_cli/__init__.py,agents.py,integration_state.py,_init_options.py,extensions/__init__.py,integrations/manifest.py,scripts/bash/common.sh,pyproject.toml,CHANGELOG.md(no network fetch)Posted by GitHub Copilot (model: claude-sonnet-4.6) running the
feature-assesspipeline on behalf of@mnriem.github-actions commentedon Aug 18, 2026
Feature assessment — separate-framework-assets · Stage 3/5: Problem
Problem Definition: Separate Spec Kit Framework Assets from Project Memory
Problem Statement
Teams using Spec Kit over time cannot distinguish, at a glance, which files under
.specify/are managed by the Spec Kit CLI/framework (safe to regenerate or ignore) from which files are project-authored source-of-truth (must be version-controlled and reviewed as first-class artifacts), because both ownership classes currently share a flat, boundary-less directory.Affected Users & Stakeholders
.gitignoredecisions, and review friction..specify/files are safe to delete/regenerate vs. require careful review without inspecting file contents.@mnriemhas explicitly affirmed the direction..specify/would need to adopt the new layout during the compatibility window.Goals
.gitignoreand CI hygiene decisions obviously correct without per-file inspection.Non-Goals
.gitignoremanagement.Success Metrics
.specify/file from its directory path alone, without reading its contents. (qualitative; verifiable by user testing) (baseline: not possible today)Cost of Inaction
Without a change, ownership ambiguity grows as more project state accumulates under
.specify/. Teams will continue facing inconsistent.gitignorepractices, code review confusion, and risk that CLI upgrades alter what users consider source-of-truth artifacts. The problem compounds with each new extension or feature that writes to.specify/.Open Questions
workflows/runs/(framework-generated but containing project-specific run state) be classified as framework-managed or project-owned?].specify/<subdir>paths and whose operators must be contacted separately?]Posted by GitHub Copilot (model: claude-sonnet-4.6) running the
feature-assesspipeline on behalf of@mnriem.github-actions commentedon Aug 18, 2026
Feature assessment — separate-framework-assets · Stage 4/5: Concept
Concept: Separate Spec Kit Framework Assets from Project Memory
Options
Option A — Immediate Structural Split (
.specify/system/and.specify/project/).specify/system/; all project-authored artifacts move under.specify/project/. Old paths trigger deprecation warnings and are read for ≥ 4 minor releases. Maximum clarity.agents.py, and all three script variants must be updated. Extensions that hard-code.specify/<subdir>in command bodies break silently.Option B — Documented Ownership Model + Gradual Path Migration
.specify/subdirectories are framework-managed vs. project-owned (documentation page orspecify docs layoutcommand), without moving anything yet. In subsequent minor releases, introduce new canonical paths for the highest-ambiguity cases (memory/,assessments/) as purely additive changes with old paths as aliases, incrementally resolving the boundary.Option C — Top-Level Separation (
.specify/for framework, new.project/for project artifacts).specify/unchanged. Project-owned artifacts (memory/,feature.json,assessments/) move to a new top-level.project/directory. Dual-read during compatibility window..git/and.nx/. Costs: a new top-level dotfile is a bigger repository change;.gitignore, CI, and third-party tooling must update. Highest visibility surface area for breakage..project/has no established convention. Every extension injecting into.specify/memory/must move. Dual-read logic needed in same places as Option A.Recommendation
Option B. Evidence shows: (a) migration cost for Options A/C is very high (dozens of hard-coded paths across three script variants, all command templates, community extensions); (b) user signal is thin (1 reporter, 0 upvotes), making a large-appetite immediate rewrite disproportionate; (c) the maintainer's 4-minor-release backward-compat constraint is most naturally satisfied by a phased approach. Option B delivers the highest-value near-term artifact (a documented ownership model) at low risk, and leaves the door open for incremental path migrations.
Out of Scope (for Option B)
.specify/<subdir>path.gitignoremanagementspecify migratecommand (future work)Assumptions to Validate
memory/andassessments/are unambiguously project-owned and can be first candidates for a future migration phase.Posted by GitHub Copilot (model: claude-sonnet-4.6) running the
feature-assesspipeline on behalf of@mnriem.github-actions commentedon Aug 18, 2026
Feature assessment — separate-framework-assets · Stage 5/5: Decision — verdict needs-clarification
Decision: Separate Spec Kit Framework Assets from Project Memory
Scorecard
.specify/creates genuine ambiguity for long-term users. Maintainer affirmed the direction. Single reporter with zero upvotes limits confidence..gitignore, review friction) but not urgent — no reported breakage, no blocked workflows.Verdict & Rationale
needs-clarification. The problem is valid and the maintainer has affirmed its direction, but evidence strength is rated
weak— one reporter, zero upvotes, no quantified demand. Per the decide command's downgrade rules, agorequires evidence strengthadequateor better; weak evidence mandatesneeds-clarification. Three specific blocking questions (below) must be resolved before agois warranted: the release cadence (required to plan a migration timeline), the classification of ambiguous paths likeworkflows/runs/, and whether there is broader latent demand beyond this single issue. The shaped concept (Option B) is sound and low-risk; the gap is in evidence and planning specifics, not in the idea itself.Blocking Questions
workflows/runs/(framework-generated but containing project-specific run history) be classified — framework-managed or project-owned? This boundary question must be resolved before a canonical ownership model can be documented.]weaktoadequateand remove the primary blocker for ago.]Revisit stage: research (re-assess demand signal after community input) → define (update ownership classifications with release cadence and boundary decisions).
Posted by GitHub Copilot (model: claude-sonnet-4.6) running the
feature-assesspipeline on behalf of@mnriem.grafvonb commentedon Aug 18, 2026
Great, thorough analysis. Thanks. This issue shows that Spec Kit is not enterprise-ready. Sad but true.
mnriem commentedon Aug 19, 2026
Thanks @grafvonb — glad the assessment was useful, and I appreciate you engaging this deeply.
I'd gently push back on the conclusion, though. This issue is about one thing: introducing a clearer directory boundary between framework-managed assets and project-authored artifacts under
.specify/. That's a real ergonomics and hygiene improvement, and it will absolutely help enterprise adoption — but the absence of that boundary today doesn't make the tool "not enterprise-ready." An organizational refinement isn't the load-bearing definition of enterprise readiness.Worth being concrete about what Spec Kit already ships for enterprise use:
install_allowed), rather than depending on the public catalog.SPECIFY_INIT_DIR, a member project can be targeted from the monorepo root withoutcd, and the override applies uniformly across every project-scoped command (integration,extension,workflow,preset, …). One monorepo can host multiple independent.specify/projects.assess(idea assessment) andbug(triage) pipeline ship in-box — in fact, this very assessment was produced by theassessextension.gitbranching-workflow extension, with its own configurable behavior, so teams enable only what they need.Also worth noting: the assessment's own verdict was needs-clarification, not a rejection — the reservation was thin demand signal (one reporter, zero upvotes), not a structural gap in the product. That's a prioritization question, not an enterprise-readiness verdict.
So I'd frame it the other way around: this issue describes a potential roadmap for even better enterprise improvements.
Co-authored with GitHub Copilot (model: Claude Opus 4.8) on behalf of @mnriem.
sean-freeman commentedon Sep 11, 2026
I would be wary of the nomenclature suggested this GH Issue as it currently stands.
I have been evaluating
spec-kitfor Enterprise usage, and determined it not ready because the scope focuses fairly specifically on feature-append (does this amazingly) but does not have the conceptual representations for controlling those features pertaining to a higher level, such as:/spec/featurecontents do map to this)For this reason, the GH Issue has significant benefit and merit for Enterprise usage - but I would not blend in the specific suggestions above, such as
/system/extensionsor/project/memory.Compounding to this GH Issue, which I do not see the point raised elsewhere, is scoping correctly to reduce Read Token and Context Window impacts.
More files / larger files which are stored inside a repo, the wider it's potential footprint (even if during runtime spec-kit attempts to scope to a specific feature).
The file ownership and structure, would need to carefully reflect separation of content that provides long-term value to the
spec-kitinitiative. An example of this delineation:External to code repopulled into context when required via defined spec-kit versionExternal to code reposeparately generated/controlled and pulled into context when required; contains Product, Project, System, Application, Service conceptual definitions as required + any additional optional content such as additional rules for quality controls (EARS syntax for REQ or NFRs), governance, traceability or other related content such as stakeholder map/objectives etc.Inside repo, the memory as-is and acting "Resident" subset files of the larger "Reference"; via specifications "store" (see OpenSpec, could be another git repo or S3 bucket etc.)\Inside repo, as-is.I acknowledge my POVs likely warrant a separate GH Issue and discussion
mnriem commentedon Sep 14, 2026
Thanks @sean-freeman for explaining your evaluation. I’d like to understand what led you from these particular requirements to the broader conclusion that Spec Kit is not enterprise-ready.
The published ecosystem already extends beyond feature-by-feature implementation. Our community catalogs currently list 168 extensions, 35 presets, and 2 workflows. More importantly, there are concrete examples relevant to your concerns:
[Product Definition as Code](https://github.com/juangcarmona/productshape) grounds features in an accepted product definition, fetches a cited context projection before specification, and checks citations afterward.
[Architecture Workflow](https://github.com/bigsmartben/spec-kit-arch) provides project-level architecture views; [Spec Roadmap](https://github.com/srobroek/speckit-roadmap) connects individual specifications to a durable roadmap.
[adrkit](https://github.com/mbeacom/adrkit) brings governing decisions into context and checks plans against them. Published presets also address architecture, security, accessibility, and delivery governance.
[ContextForge](https://github.com/capatinore/contextforge-mcp) targets context compression and code intelligence. There are also organization-hosted contributions such as [Luno’s Jira preset](https://github.com/luno/spec-kit-preset-jira) and [Azure-Samples’ Spec2Cloud](https://github.com/Azure-Samples/Spec2Cloud).
These are published approaches, not hypothetical future extension points. The core does not need to prescribe every enterprise’s organizational hierarchy for the ecosystem to support enterprise workflows.
Did your evaluation include these capabilities, or primarily the stock command templates? Could you share one concrete requirement or workflow that remains unsupported after considering the ecosystem—and why it requires a core change rather than an extension, preset, or workflow?
The ownership and context concerns are worth discussing. I’m asking because a specific unmet requirement gives us something actionable; the blanket readiness conclusion doesn’t tell us what actually prevents adoption in your environment.
Drafted for @mnriem by GitHub Copilot (model: GPT-6 Astra).