[Feature]: Preset strategy to replace one section of a template

Offen
  • Stimmt etwas nicht?
#5,421 0 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Maintainer antworten meist innerhalb von 1 Tag

Dieses Issue hat noch niemand übernommen.

Bewertung

Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Anfängerfreundlichkeit
28/100
Issue-Typ
Feature
Klarheit
Klar beschrieben
Aktivitätsstatus
Aktiv
Tech-Stack
python, yaml
Bereich
tooling

Rechercherichtung

Start in PresetResolver.resolve_content (the composition loop) and VALID_PRESET_STRATEGIES, then read manifest validation for the template strategies. The issue also touches the bash, PowerShell and Python runtime scripts and the preset docs (developing.md, api.md). Agree the design with maintainers before coding, since the author's fork is not a PR yet. Done means the acceptance criteria pass: heading-scoped replacement, exactly-one-match failure, fence-aware matching, and validation errors for commands and scripts.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Beschreibung

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:

  1. Find the section by its heading text. Match the text after the # marks exactly, ignoring surrounding whitespace. Any heading level counts.
  2. 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.
  3. 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.
  4. Ignore headings inside fenced code blocks.
  5. Compose like the other strategies. It runs on the resolved lower-priority content, the same base wrap uses, so two presets can each replace a different section of the same template. Like append, prepend and wrap, it needs a lower replace base.
  6. 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
  • replace the 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.
  • wrap with a hand-written copy of the other sections. Same drift problem as replace.
Component

Spec templates (BDD, Testing Strategy, etc.)

Use Cases

These come from SpecKit Companion, which uses this rule in its own template renderer:

  1. Spec: replace ## User Scenarios & Testing with 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.
  2. Plan: a team's own ## Technical Context block with its stack's fields, and every other section stock.
  3. Tasks: replace ## Notes to 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" and section: "<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-section without section, 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.
Vorherrschende Sprache
Python
Sterne
149k
Forks
13.4k
Ø Merge
1 T. 5 Std.
Gemergte PRs (30 T.)
223

Entwicklungsumgebung

In Codespaces öffnen

Startet den Dev-Container des Projekts im Browser, mit Ihrem eigenen GitHub-Konto.

Erste Schritte

  1. Lesen Sie das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreiben Sie ins Issue, dass Sie es übernehmen — das erspart doppelte Arbeit.
  3. Forken Sie das Repository und arbeiten Sie in einem Branch.
  4. Öffnen Sie einen Pull Request, der die Issue-Nummer nennt.

Mehr aus github/spec-kit

Alle Issues in github/spec-kit

Ähnliche Issues

Weitere Issues zu Python

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.