Repository navigation
Explore opt-in persistence extensions for flow-back, flow-forward, and flow-always (“Living”) #4944
Description
Problem
Spec Kit describes three artifact persistence models, but leaves their maintenance operations to teams and community tooling.
The shared delivery process should remain unchanged: specify, plan, tasks, implement, and converge until the agreed feature is complete. After delivery, teams need to decide how completed specifications, plans, and task records persist and evolve.
We should explore whether separately selectable extensions can support those choices without adding persistence-specific behavior to the core delivery commands.
Proposed direction
Assess three opt-in persistence extensions:
| Extension | Persistence model | Responsibility to explore |
|---|---|---|
| Flow-back | Accepted discoveries flow back into retained artifacts | Reconcile explicitly approved decisions across specifications, plans, and task records. |
| Flow-forward | Completed artifacts remain historical records | Preserve completed feature directories and establish traceable links to subsequent features that extend or supersede them. |
| Flow-always (“Living”) | The specification remains a maintained contract | Update the authoritative specification and refresh derived artifacts while preserving important implementation rationale. |
These are candidate responsibilities, not settled command or package designs. The assessment should establish which operations benefit from automation and whether each model warrants an extension rather than documentation or a preset.
Architectural boundary
Persistence extensions operate on the lifecycle of delivered feature artifacts. They do not replace or alter the shared delivery process.
A persistence operation that establishes new intended behavior requiring implementation must feed that work into the normal delivery loop. It must not:
- Treat acceptance of existing code as proof of convergence while the intended artifacts still disagree.
- Suppress unresolved delivery findings to accommodate a persistence model.
- Make one persistence strategy the required or default behavior.
- Turn a persistence update into implicit authorization for application-code changes.
The assessment must distinguish artifact maintenance from delivering a subsequent change.
Existing work
The community reconcile extension already provides flow-back-related automation and is listed in Spec Kit’s community catalog. Evaluate that existing work before proposing duplicate functionality or a replacement.
github/spec-kit#4940 proposed connecting reconciliation to converge and adding a core amendment step. That request was declined because it crossed the delivery/persistence boundary. This proposal explores separate opt-in persistence extensions instead; it does not reopen that requested core behavior.
github/spec-kit#4943 tracks clarification of the existing documentation. This feature assessment is separate and must not delay that clarification.
Assessment questions
- What concrete post-delivery operations does each model need?
- Which operations require an extension, and which are adequately addressed by conventions, documentation, or presets?
- Are three separate extensions justified by distinct behavior and independently useful workflows?
- What approval, traceability, and artifact-preservation safeguards does each require?
- How does each strategy hand subsequent implementation work back to the unchanged delivery process?
- Should any resulting extensions remain community-maintained or become first-party, and what evidence would justify first-party ownership?
Acceptance criteria for the assessment
- Define the responsibilities and boundaries of all three persistence flows.
- Identify concrete use cases and expected artifact changes for each.
- Evaluate existing community functionality without assuming it must be replaced.
- Recommend an appropriate delivery mechanism for each model: documentation, preset, or extension.
- Demonstrate that proposed persistence behavior leaves core delivery semantics unchanged.
- Document approval and preservation rules, including treatment of completed tasks and historical artifacts.
- Recommend ownership and maintenance scope based on evidence.
- Identify any implementation proposals that require separate approval.
Out of scope
Changing converge’s authority or append-only contract, introducing a mandatory persistence strategy, or committing to three new first-party extensions before the assessment is complete.
AI disclosure
Drafted with GitHub Copilot, powered by GPT-6.1 Sol, in an interactive session for maintainer review. AI assistance covered proposal framing and issue drafting.
Activity
stn1slv commentedon Oct 13, 2026
Thanks for opening this and for pointing at
reconcile. I just released v1.3.0, which follows the boundary described here and in #4940. Below is how it answers the assessment questions for the flow-back row. I can't speak for the other two models.Post-delivery operations. It takes a plain-language gap report for one feature per run. It amends the
spec.mdandplan.mdentries the drift reaches (FRs, scenarios, edge cases, entities, success criteria, assumptions, plan sections), adds a dated revision note to each changed file, and appends remediation tasks totasks.mdfor work the drift leaves open. It reads the shipped code only to resolve file paths for those tasks. Requirements come from the gap report, never from code.Approval. Before any edit, every run asks which drift items the team approves reconciling into the artifacts. An item left out is written nowhere, and the report recommends
/speckit.convergefor it. "Approve none" writes nothing. A gap report that says "approved" still gets the question. The approved items go on anApproved:line in the revision note.Traceability and preservation.
[X]are never edited, and tasks from earlier runs are never deleted.RETIRED,SUPERSEDED by [ID]orCANCELLED, and bugfix strike-throughs, are never revived. The amendment goes to the live entry.[Sync: slug]key, so re-running the same report changes nothing. A re-run changes an earlier entry only where the new report changes what it says.Hand-back to delivery. It never touches application code and never writes into a
## Phase N: Convergencesection. New work becomes ordinary tasks, and the report's next step is/speckit.implementfollowed by/speckit.converge. Convergence is still established by the unchanged delivery loop, against the updated artifacts.The four "must not" points. It doesn't treat accepted code as convergence, since it sends you to converge. It doesn't suppress converge findings, since it never edits a Convergence phase. It is opt-in by install, and when the constitution names flow-forward or living spec, it says the in-place amendment doesn't match. It doesn't authorize code changes; it only appends tasks.
Extension rather than docs or a preset. The work depends on reading each file's own ID scheme, section names and markers, and applying the rules above the same way every time. That is hard to get from documentation alone. A preset would mean overriding core commands, which is the boundary this issue wants to keep.
Known gaps (all recorded in the repo): a same-slug re-run with a narrower approval isn't defined yet, a run that only writes tasks keeps its approval in the printed report only, and every run is now interactive. I test behaviour by running the prompt against a fixture project full of deliberate traps, with the expectations committed before each round. The latest rounds are in
tests/fixture/BASELINE-v1.3.0.md.Ownership. I'm happy to keep maintaining it as a community extension. If the assessment recommends a first-party flow-back extension, I'm also fine with it being used as a starting point.
AI disclosure: drafted with Claude Code (Claude Opus 5.5) at my request in an interactive, human-supervised session, and reviewed by me before posting. The agent also helped prepare the v1.3.0 release referenced above.
github-actions commentedon Oct 13, 2026
Feature assessment — opt-in-persistence-flows · Stage 1/5: Intake
Idea Intake: Opt-in persistence extensions for three artifact models
feature-assess)Idea (as captured)
The issue defines candidate responsibilities for each model, asks about concrete operations, safeguards, hand-back to the unchanged delivery process, and ownership, and explicitly excludes changing converge's authority, introducing a mandatory strategy, or committing to three first-party extensions before assessment. A maintainer comment adds evidence about the community
reconcileextension (v1.3.0) for flow-back and identifies known gaps, while noting that it does not cover the other two models.Restated
Assess whether the three post-delivery artifact persistence models need independently useful automation, and if so whether each should be delivered as documentation, a preset, or an opt-in extension. Preserve the shared delivery loop and keep persistence operations from implicitly authorizing application-code changes.
Origin & Context
First-Glance Unknowns
github-actions commentedon Oct 13, 2026
Feature assessment — opt-in-persistence-flows · Stage 3/5: Problem
Problem Definition: Opt-in persistence extensions for three artifact models
Problem Statement
Teams that retain Spec Kit artifacts after delivery must maintain the relationship between intended behavior, implementation decisions, historical records, and future changes, but the appropriate maintenance work differs across flow-back, flow-forward, and living-spec models. Today the repository provides neutral conventions and a shared delivery loop, while concrete operation-level needs and demand for automation remain insufficiently established, creating risk of drift, fragmented history, lost rationale, or boundary violations.
Affected Users & Stakeholders
Goals
Non-Goals
specify -> plan -> tasks -> implement -> convergedelivery process.Success Metrics
Cost of Inaction
Teams will continue using documentation and manual conventions, or community tooling, with uneven safeguards and uncertain model fit. Flow-back users may duplicate existing community functionality, while flow-forward and living-spec users may improvise incompatible practices; meanwhile, unclear boundaries could reintroduce the delivery/persistence confusion that #4943 was created to address. The magnitude and urgency of these costs are not measured.
Open Questions
github-actions commentedon Oct 13, 2026
Feature assessment — opt-in-persistence-flows · Stage 2/5: Research
Idea Research: Opt-in persistence extensions for three artifact models
Users & Demand
reconcileextension reports a concrete flow-back workflow: a plain-language gap report, explicit approval before edits, amendments to affectedspec.md/plan.mdentries, and remediation tasks for unresolved work. This is direct maintainer evidence for one model, not evidence of broad adoption. [source: https://github.com/Explore opt-in persistence extensions for flow-back, flow-forward, and flow-always (“Living”) #4944#issuecomment-6148222539] (confidence: medium)Prior Art
specify -> plan -> tasks -> implement -> convergeprocess; none is required or default. [source: docs/concepts/spec-persistence.md] (confidence: high)tasks.md. Extensions may provide commands or hooks without changing core responsibilities. [source: docs/concepts/spec-persistence.md] (confidence: high)reconcileextension is existing flow-back prior art. Its README describes bounded inputs, explicit approval, preservation of completed and retired entries, idempotent sync keys, constitution checks, and routing back through implement/converge. It is evidence that a flow-back extension is technically plausible, not proof that it should become first-party or that the other models need extensions. [source: https://github.com/stn1slv/spec-kit-reconcile] (confidence: high)Market & Context
Data & Constraints
Evidence Against the Idea
Gaps & Open Questions
Sources
github-actions commentedon Oct 13, 2026
Feature assessment — opt-in-persistence-flows · Stage 4/5: Concept
Concept: Opt-in persistence extensions for three artifact models
Options
Option A — Documentation-first, community-backed pilots
+- Sketch: Keep the core delivery loop and persistence guidance neutral, define model-specific responsibilities and safeguards in documentation, and evaluate or improve community extensions where concrete automation already exists. Treat flow-back as the first pilot because
reconcilesupplies prior art, while requiring evidence and a separately scoped concept before pursuing automation for flow-forward or living spec.+- Appetite: small
+- Trade-offs: Minimizes duplication, first-party maintenance, and boundary risk while making the three choices clearer. It may leave manual work in place and does not immediately provide automation for teams that need it. Its success depends on obtaining real demand and operation-level evidence.
+- Rabbit holes: Turning documentation into an implicit protocol; trying to standardize every community extension; allowing a flow-back pilot to expand into converge or core amendment behavior.
Option B — One shared opt-in persistence toolkit
+- Sketch: Offer one optional toolkit with separately selected model behaviors, shared approval and preservation expectations, and model-specific user experiences. Teams choose a persistence mode without changing core delivery, and each mode routes subsequent implementation back through the standard process.
+- Appetite: medium
+- Trade-offs: Could reduce duplicated safeguards and offer a coherent user experience across models. It risks a large abstraction before the operations are understood, couples distinct workflows, and could become a de facto required framework or a new source of truth.
+- Rabbit holes: Designing a universal artifact mutation language; reconciling incompatible history and regeneration semantics; supporting every template and preset; accidentally changing core command authority.
Option C — Three independently maintained first-party extensions
+- Sketch: Build separate opt-in extensions for flow-back, flow-forward, and living spec, each with a clearly bounded responsibility and explicit hand-back to the shared delivery loop. Teams choose a persistence mode without changing core delivery, and each mode routes subsequent implementation back through the standard process.
+- Appetite: large
+- Trade-offs: Maximizes model-specific fit and independent adoption, but creates the highest development, testing, documentation, compatibility, and ownership burden. It avoids forcing one abstraction but has no demonstrated demand yet for two of the three extensions and may duplicate existing community flow-back work.
+- Rabbit holes: Three separate protocols for IDs, approvals, links, archival, and rationale; long-term support across agents and presets; migration from community tools; treating package separation as proof of distinct user value.
Recommendation
Recommend Option A as the smallest reversible step. It directly addresses the immediate boundary and clarity goals, leverages existing flow-back prior art, and avoids committing to behavior that the available evidence does not justify. Before any first-party extension is proposed, collect model-specific demand, define operation-level acceptance and preservation rules, and measure whether documentation/manual practice or community tooling fails the success bar.
Out of Scope (for the recommended option)
specify,plan,tasks,implement, orconverge, including converge authority and append-only behavior.reconcileextension.Assumptions to Validate
github-actions commentedon Oct 13, 2026
Feature assessment — opt-in-persistence-flows · Stage 5/5: Decision — verdict needs-clarification
Pipeline note: the Stage 2 research comment was queued after the Stage 3 problem comment due execution sequencing; the artifact content and stage labels are intact.
Decision: Opt-in persistence extensions for three artifact models
Scorecard
Verdict & Rationale
Needs clarification. The problem is plausible and a small documentation-first option is shaped, but the evidence-strength gate for
gois not met: demand and concrete operations are documented only for flow-back, while flow-forward and living spec remain largely unverified. Do not hand off to/speckit-specifyuntil the blocking questions below are answered and the research/shape artifacts are revisited. This is not a kill: the issue may be worth pursuing after evidence improves.If needs-clarification
+- Revisit stage: research, then shape
stn1slv commentedon Oct 13, 2026
A correction to my comment above. I wrote that under a flow-forward or living-spec constitution "it says the in-place amendment doesn't match". That was accurate for v1.3.0 but read like a guard, and it wasn't one: v1.3.0 still amended the completed artifacts and only reported the mismatch afterwards, which doesn't fit "the project's governance" in #4948.
v1.3.1 changes that. When the constitution says the project uses flow-forward, the run writes nothing, asks nothing and recommends a new feature directory. Living spec and an unstated model reconcile normally, with no default model assumed. It also names any open converge task written against an entry it amends, first in the Next Step, so implement doesn't carry out work against the old intent.
One more precision: "re-running the same report changes nothing" is what the prompt instructs and what the fixture checks, not a guarantee. One fixture run broke it during this release cycle and a rule was added to fix it. The baseline files in the repo list which cases ran against which commit.
AI disclosure: drafted with Claude Code (Claude Opus 5.5, session-default reasoning settings) at my request in an interactive, human-supervised session, and reviewed by me before posting.