Feature Request: Support Module-Level Persistent Specifications for Knowledge Retention

Problem Statement

Currently, SpecKit follows a task-centric workflow where each development cycle generates specifications (spec.md, plan.md, tasks.md) that are scoped to a single feature or task. While this works well for isolated feature development, it creates a knowledge gap in brownfield/evolving projects:

Current behavior:

Task A → .speckit/specs/001-feature-a/spec.md → Code A (merged)
Task B → .speckit/specs/002-feature-b/spec.md → Code B (merged)

The spec.md files describe "what we're building this time"
After merging, these specs become historical artifacts
New developers must reverse-engineer module state from code, not from specs
AI agents lack context about existing module architecture when generating new code

Real-World Use Case

Scenario: A team is building an authentication module over multiple sprints:

Sprint	Task	Current Approach	Problem
Sprint 1	Add basic login	`specs/001-basic-login/spec.md`	Spec describes only "what's new"
Sprint 2	Add OAuth	`specs/002-oauth/spec.md`	Previous spec doesn't reflect current module state
Sprint 3	Add 2FA	`specs/003-2fa/spec.md`	New dev must read 3 specs + code to understand module

Pain points:

New team members can't understand the complete current state of the auth module from specs
AI agents generate code without knowing what already exists in the module
Team loses institutional knowledge as specs become disconnected from reality
No single source of truth for "what this module does right now"

Expected Behavior

Introduce a two-tier specification architecture:

1. Task-Level Specs (Existing - No Change Needed)

Scope: Describes incremental changes for the current task
Purpose: Drives AI code generation for the specific feature
Example: .speckit/specs/003-add-2fa/spec.md

2. Module-Level Specs (New - Requested Feature)

Scope: Describes complete current state of a module/component
Purpose:
- Knowledge base for developers joining the project
- Context for AI when generating new code
- Living documentation that evolves with the codebase
Example: docs/specs/auth-module-spec.md

Desired workflow:

Task A → task-spec-A.md → Code A → Update auth-module-spec.md
Task B → task-spec-B.md → Code B → Update auth-module-spec.md
                                    ↓
                            auth-module-spec.md (continuously evolving)

Key expectation:

Module-level specs are version-controlled alongside code
They reflect the complete current capabilities of each module
They serve as long-term knowledge artifacts, not temporary task documents

Benefits

Knowledge Retention: Module specs survive across development cycles, becoming institutional knowledge
Onboarding: New developers understand module state from documentation, not code archaeology
AI Context: AI agents generate better code by understanding existing module architecture
Traceability: Git history shows how module capabilities evolved over time
Brownfield Support: Critical for projects that evolve over months/years with multiple contributors
Cross-team Consistency: Different teams can understand module boundaries and contracts

Open Questions

Scope: Should module-level specs be mandatory or optional (enabled via configuration)?
Location: What's the preferred directory structure? (docs/specs/, .speckit/modules/, or configurable?)
Updates: Should module spec updates be:
- Fully automated (on PR merge)?
- Semi-automated (AI suggests, human reviews)?
- Manual (developer-driven)?
Granularity: What constitutes a "module"? File-level? Directory-level? Logical component-level?

Related Issues & Discussions

Establish best practices for evolving specs as features are added to existing projects #916: "Establish best practices for evolving specs" (focuses on SpecKit tool updates, not module-level knowledge)
Discussion Evolving specs #152: "Evolving specs" (addresses spec evolution but not knowledge retention architecture)

This proposal complements those discussions by introducing a dual-layer specification model that addresses both task-level development (existing) and long-term knowledge management (new).

Thank you for considering this enhancement! This would make SpecKit significantly more powerful for real-world, long-term projects where knowledge retention is as important as feature delivery.

@xuxm2007

Hi @xuxm2007,

I ran into this exact same "knowledge gap" problem. The pain of having to reverse-engineer module state from 5 different historical feature specs was getting out of hand.

I actually ended up building a community extension that implements the exact "two-tier architecture" you described here. It's called spec-kit-archive.

How it works:

After a PR is merged, you run /speckit.archive.run specs/###-feature-name.
The agent reads the feature spec and surgically merges the new requirements, entities, and plan details into a centralized project memory (.specify/memory/spec.md and .specify/memory/plan.md).

It treats the feature specs as temporary "deltas" (Task-Level Specs) and maintains the .specify/memory/ directory as the living institutional knowledge (Module-Level Specs). It also logs the completed feature into a rolling changelog.

If you want to test out this workflow today, you can install it via the CLI:

specify extension add archive --from https://github.com/stn1slv/spec-kit-archive/archive/refs/tags/v1.0.0.zip

Let me know if this helps achieve the workflow you were envisioning!

This issue has been automatically marked as stale because it has not had any activity for 150 days. It will be closed in 30 days if no further activity occurs.

This overlaps two extensions I've published, in case either is useful here.

For the retention half — module-level knowledge not surviving into the next feature — spec-kit-memory (community catalog id memory) hooks before_specify and before_plan and pulls prior specs and decisions from a configurable memory backend into the new spec's context. It does not create the persistent module-level spec artifact you're proposing, so it isn't a substitute for this request — but it addresses the symptom that motivates it: every new feature starting cold.

For the enforcement half — spec-kit-coherence, which hooks after_analyze and checks whether the invariants of already-merged sibling specs still hold after the current feature's change, classifying each as HOLDS / SILENTLY BROKEN / AMENDED.

The reason I mention it on this issue: persistent module-level specs give you something to stay consistent with, but nothing yet notices when a later feature quietly invalidates it. In my project a merged spec's central safety control assumed a closed, code-declared set; a later spec made that set page-derived and unbounded. Neither document was internally wrong, both passed their own gate, and no amendment was ever written — /speckit-analyze reads one feature directory and structurally cannot see the pair. A persistent module spec would have made the promise more durable without making the contradiction more visible.

Coherence also insists the amendment be written in the spec that made the original promise, rather than in the feature that broke it — which is the part that keeps a long-lived module spec honest over time.

Caveat: coherence is new — source is public, no release cut yet and not in the catalog, so it is a --dev install for now. Related open thread with the same root cause: #620.

As indicated above you can utilize the extension and/or preset system to deliver this above and beyond the core SDD process

This issue has been automatically marked as stale because it has had no activity for 60 days. It will be closed in 30 days unless there is a substantive update. If the problem still applies, please provide updated context such as whether it is still reproducible, the affected version or environment, its current impact, and any new reproduction details. A comment that only states that the issue is "still relevant" does not give maintainers enough information to reconsider it.

Navigation Menu

Repository navigation

Feature Request: Support Module-Level Persistent Specifications for Knowledge Retention #1100