Repository navigation
Description
Problem Statement
A preset can change a template in four ways today: replace, prepend, append and wrap. None of them can change one section in the middle of a template. To change only ## User Scenarios & Testing in spec-template.md, a preset has to replace the whole file. That copy then stops picking up upstream changes to every other section, and it stops composing with other presets that touch the same template.
Follow-up to discussion #5326, where @mnriem asked for the cases and a fuller write-up.
Proposed Solution
A fifth template strategy, replace-section, with a section field naming the heading:
provides:
templates:
- type: "template"
name: "spec-template"
file: "templates/outcomes.md"
strategy: "replace-section"
section: "User Scenarios & Testing *(mandatory)*"The file holds the new body of that section. The rules:
- Find the section by its heading text. Match the text after the
#marks exactly, ignoring surrounding whitespace. Any heading level counts. - Keep the heading line. Replace only the body, from after the heading to the next heading of the same or higher level, or the end of the file.
- Exactly one match, or fail. If no heading matches, or more than one does, the preset fails with an error that lists the template's headings. A renamed or duplicated section fails loudly instead of being appended or guessed at.
- Ignore headings inside fenced code blocks.
- Compose like the other strategies. It runs on the resolved lower-priority content, the same base
wrapuses, so two presets can each replace a different section of the same template. Likeappend,prependandwrap, it needs a lowerreplacebase. - Templates only at first. Commands and scripts keep the strategies they have.
In the code, this looks like one more branch in the composition loop of PresetResolver.resolve_content, replace-section added to VALID_PRESET_STRATEGIES, and manifest validation requiring section when the strategy is replace-section.
Alternatives Considered
replacethe whole template. This works today, but the copy drifts from upstream and blocks other presets from composing on that template.- Marker comments in the core templates (
<!-- section:stories -->). They're more precise, but every core template would need markers, and a project's hand-edited template would lose them. Headings already exist, and they're what people and models use to find their way around a template. wrapwith a hand-written copy of the other sections. Same drift problem asreplace.
Component
Spec templates (BDD, Testing Strategy, etc.)
Use Cases
These come from SpecKit Companion, which uses this rule in its own template renderer:
- Spec: replace
## User Scenarios & Testingwith observable outcomes (no P1/P2/P3 stories) for small changes, or with EARS-style numbered requirements (WHEN/THEN/SHALL) that tasks can cite by ID. - Plan: a team's own
## Technical Contextblock with its stack's fields, and every other section stock. - Tasks: replace
## Notesto rule out tasks an agent can't do (UAT, deploy, comms), or the format section so every task says how to verify itself.
Acceptance Criteria
- A preset with
strategy: "replace-section"andsection: "<heading>"replaces only that section's body in the resolved template, and keeps the heading line. - Every other section of the template comes out the same as without the preset.
- The section ends at the next heading of the same or higher level, so its subsections are replaced with it.
- Zero or more than one matching heading fails with an error that names the section and lists the template's headings.
- Headings inside fenced code blocks are not matched.
- Two presets replacing different sections of one template both apply, in priority order.
- Manifest validation rejects
replace-sectionwithoutsection, and rejects it on commands and scripts. - The preset docs (
developing.md,api.md) describe the strategy.
Additional Context
A working version is on my fork, not opened as a PR: full diff against main (branch feat/replace-section-strategy). It covers the CLI resolver, manifest validation, the bash/PowerShell/Python runtime scripts (so feature creation gives the same output as the CLI), the artifact listings, docs and tests. I'm happy to open it as a PR if this direction is agreed.
SpecKit Companion's version of this is replace_section in apps/speckit-extension/scripts/template_render.py in alfredoperez/speckit-companion, with tests. It currently takes the first of two matching headings. The "exactly one match" rule above is stricter, and I'd change ours to match.
AI Disclosure
- Issue text: drafted with Claude Code (Claude Opus 5.5, default settings, interactive under my supervision) after reading the spec-kit preset resolver and docs. I reviewed and edited it before posting.
- Linked branch: implemented with Claude Code (Claude Opus 5.5, default settings) in agent mode running autonomously, following a spec I wrote and reviewed. Covers code generation, tests and docs. It's a proof of concept for this discussion, not a PR.
Activity
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 1/5: Intake
Idea Intake: Replace One Template Section in Presets
Idea (as captured)
Restated
The request is to let presets target and replace a specific markdown section inside a template instead of replacing the entire template file. The goal is to preserve upstream compatibility and allow multiple presets to compose safely when they modify different sections.
Origin & Context
First-Glance Unknowns
*(mandatory)*) be supported?]github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 2/5: Research
Idea Research: Section-Level Template Replacement for Presets
Users & Demand
replaceneeded for one section), composition breakage, and drift risk — [source: https://github.com/[Feature]: Preset strategy to replace one section of a template #5421] (confidence: medium).Prior Art
replace,prepend,append,wrap) and restricts scripts toreplace/wrap, soreplace-sectionis not currently representable in manifest validation — [source: src/specify_cli/presets/_manifest.py:30-32,256-264] (confidence: high).replacebase and appliesprepend/append/wrapbottom-up; this is structurally compatible with adding another composition branch if semantics are well-defined — [source: src/specify_cli/presets/_resolver.py:796,809-820,888-894] (confidence: high).replace-base rule; a new strategy would require docs/API updates to preserve contract clarity — [source: docs/presets/api.md:150-153; docs/presets/developing.md:85] (confidence: high).replace_section) with tests that keep heading line, replace section body and nested subsections, and fail when section is missing — [source: https://github.com/alfredoperez/speckit-companion/blob/946decfb3a597d0733f9d8cc73f4eabb40ae3a81/apps/speckit-extension/scripts/template_render.py ; https://github.com/alfredoperez/speckit-companion/blob/946decfb3a597d0733f9d8cc73f4eabb40ae3a81/apps/speckit-extension/tests/test_template_render.py] (confidence: medium).Market & Context
Data & Constraints
replaceor a discovered lowerreplacebase; section-level replacement should remain consistent with this model — [source: src/specify_cli/presets/_resolver.py:796,809-820] (confidence: high).Evidence Against the Idea
Gaps & Open Questions
*(mandatory)*, case sensitivity, and internal whitespace).]Sources
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 3/5: Problem
Problem Definition: Preset Authors Cannot Safely Customize Single Template Sections
Problem Statement
Preset authors who need to customize one section inside a stock template must currently replace the entire template file, which breaks composability with other presets and increases drift from upstream template updates. This creates recurring maintenance overhead and raises the risk of inconsistent template outcomes as templates evolve.
Affected Users & Stakeholders
Goals
Non-Goals
Success Metrics
Cost of Inaction
If no section-level primitive is added, teams continue using whole-file replacement for localized customizations, making upstream template improvements harder to adopt and reducing compatibility among presets that touch the same template. This sustains avoidable maintenance cost and ecosystem friction.
Open Questions
*(mandatory)*?]github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 4/5: Concept
Concept: Add a Section-Scoped Preset Strategy
replace-sectionwith strict matchingOptions
Option A — Keep Existing Strategies (Do Nothing)
replacefor localized edits, with guidance to minimize drift manually.Option B — Template-only
replace-sectionwith Strict Heading MatchOption C — Rich Marker/AST-Based Section Editing
Recommendation
Recommend Option B. It is the smallest concept that directly addresses the identified user pain while preserving the existing composition mental model (
replacebase plus composition layers). It offers meaningful value over inaction without the large complexity jump of a generalized editing system.Out of Scope (for the recommended option)
Assumptions to Validate
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 5/5: Decision — verdict needs-clarification
Decision: Replace-Section Strategy for Preset Templates
Scorecard
Verdict & Rationale
Verdict: needs-clarification. The problem is valid and a credible medium-size concept exists, but evidence strength is currently too narrow and key behavioral semantics are still open. Under the decision rules, this is not yet a defensible
go: the proposal should return for targeted clarification on demand breadth and contract edge cases before handoff to specification.If needs-clarification
If go — Handoff to
/speckit-specifyNot applicable for
needs-clarification.mnriem commentedon Nov 16, 2026
Maintainer clarification for reassessment:
I accept the use case and maintenance benefit as sufficient justification to proceed into specification: targeted replacement avoids copying and maintaining an entire template or command just to change one section. Broader adoption counts are not a prerequisite for accepting this direction.
The agreed scope and behavior are:
#technical-context: lowercase with hyphens rather than underscores, following GitHub heading-anchor normalization rather than literal heading-text matching. Pin down the exact normalization contract during specification.Please reassess against these decisions. The accepted direction is a bounded feature worth specifying, not approval of the linked implementation; exact anchor semantics and composition edge cases should be resolved in the specification.
AI disclosure: Posted on behalf of @mnriem using GitHub Copilot, model GPT-6.1 Sol (gpt-6.1-sol), default settings in an interactive session with user-directed scope and authorization. AI drafted this clarification from the discussion; no implementation or validation was performed.
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 1/5: Intake
Idea Intake: Replace One Template or Command Section in Presets
Idea (as captured)
Restated
Preset authors need a way to customize only one section of a Markdown artifact without forking the entire file. The requested behavior should compose with existing preset layering and fail explicitly when section selection is ambiguous or invalid.
Origin & Context
First-Glance Unknowns
sectionselectors.]replaceorwrapworkarounds.]github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 2/5: Research
Idea Research: Section-Level Markdown Replacement for Presets
Users & Demand
Prior Art
replace,prepend,append,wrap), with no section-targeted mode. — [source: src/specify_cli/presets/_manifest.py#L30, src/specify_cli/presets/_resolver.py#L735-L905] (confidence: high)replace/wraponly), which aligns with the maintainer’s “no executable script section editing” scope. — [source: docs/presets/api.md#L139-L145] (confidence: high)Market & Context
Data & Constraints
replace|wrap|prepend|append; adding a new strategy touches validation plus artifact APIs. — [source: src/specify_cli/presets/_manifest.py#L30-L31, src/specify_cli/artifacts/mcp_info.py#L71, src/specify_cli/artifacts/mcp_list.py#L75, src/specify_cli/artifacts/_operation_list.py#L27] (confidence: high)Evidence Against the Idea
Gaps & Open Questions
Sources
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 3/5: Problem
Problem Definition: Fine-Grained Preset Customization Without Template Forking
Problem Statement
Preset authors who need to change one Markdown section of a template or command must currently replace or wrap larger content blocks, which increases drift from upstream defaults and reduces safe composition with other presets. This creates recurring maintenance overhead and fragile customization behavior in normal preset composition workflows.
Affected Users & Stakeholders
Goals
Non-Goals
Success Metrics
Cost of Inaction
If this is not addressed, users continue forking whole templates/commands for local section edits, increasing drift, review burden, and conflicts between otherwise compatible presets. Over time, that weakens maintainability of shared preset ecosystems and discourages modular customization.
Open Questions
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 4/5: Concept
Concept: Section-Scoped Preset Composition for Markdown Artifacts
Options
Option A — Template-only section replacement first
type: template, leaving commands unchanged initially. Users gain immediate relief for spec/plan/tasks template customization while command behavior remains current.Option B — Bounded section replacement for templates + Markdown commands
Option C — Do nothing (continue with replace/wrap workarounds)
replaceorwrappatterns for section-level customization intent.Recommendation
Recommend Option B. It directly addresses the defined problem, matches the maintainer’s accepted reassessment scope, and preserves existing composition foundations while adding targeted capability where users need it. The increased implementation surface is manageable if the specification first locks selector normalization, ambiguity handling, and parity test requirements.
Out of Scope (for the recommended option)
Assumptions to Validate
github-actions commentedon Nov 16, 2026
Feature assessment — replace-template-section · Stage 5/5: Decision — verdict go
Decision: Add Bounded Section-Replacement Strategy for Markdown Artifacts
Scorecard
Verdict & Rationale
Verdict: go. The problem is real and materially affects maintainability/composability, the inaction cost is clear, and a bounded concept exists that fits project direction. Evidence is sufficient for specification (though not yet implementation-ready), and the remaining uncertainty is about exact selector/error contracts rather than whether the capability should exist.
If needs-clarification
If go — Handoff to
/speckit-specify