github / github/spec-kit

[Feature]: Separate Spec Kit framework assets from repository-specific project memory

Open
#2,681 10 comments 0 reactions 0 assignees View on GitHub
enhancement feature-assess feature-needs-clarification
Dominant language
Python
Stars
137k
Forks
12.3k
Avg merge
2d 12h
Merged PRs (30d)
159

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:

```text
.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:

```text
.specify/
extensions/
scripts/
templates/
workflows/
integrations/

.project-memory/
architecture...
constitution...
features...
```

### Component

Agent integrations (command files, workflows)

### AI Agent (if applicable)

None

### Use Cases

1. When a repository uses Spec Kit over time and needs to distinguish tool-managed framework assets from repo-owned project knowledge.
2. During architecture, spec, or implementation review, when reviewers need to know whether a file is generated/tooling infrastructure or an intentional project decision record.
3. When configuring `.gitignore`, CI checks, or repository hygiene rules for Spec Kit files.
4. 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.
5. 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_

Contributor guide

Open the contributing guide

Research direction

Start by inventorying the current .specify/ layout, including extensions, scripts, templates, workflows, integrations, memory, and features, then trace the commands and templates that read or write them. Define and document the ownership boundary, update those entry points consistently, and verify supported-agent workflows. Done includes migration or compatibility guidance and a layout that makes tracking and review expectations clear.

Written by the indexing model from the issue text.

Assessment

Domain
developer-experience, documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.