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

Ouverte
  • Quelque chose ne va pas ?
#5,421 0 commentaires 0 réactions 0 personnes assignées Voir sur GitHub

Les mainteneurs répondent en général sous 1 jour

Personne n'a encore pris cette issue.

Évaluation

Difficulté
4/5
Temps estimé
3-5 jours
Accessibilité débutants
28/100
Type d'issue
Fonctionnalité
Clarté
Clairement spécifiée
Activité
Active
Stack technique
python, yaml
Domaine
tooling

Piste de recherche

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.

Rédigé par le modèle d'indexation à partir du texte de l'issue.

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:

  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.
Langage dominant
Python
Étoiles
149k
Forks
13.4k
Merge moyen
1 j 5 h
PR mergées (30 j)
223

Préparer son environnement

Ouvrir dans Codespaces

Lance le conteneur de développement du projet dans votre navigateur, avec votre propre compte GitHub.

Par où commencer

  1. Lisez l'issue en entier, puis le guide de contribution du projet.
  2. Signalez en commentaire que vous la prenez — cela évite que deux personnes fassent le même travail.
  3. Forkez le dépôt et travaillez sur une branche.
  4. Ouvrez une pull request qui référence le numéro de l'issue.

Autres issues de github/spec-kit

Toutes les issues de github/spec-kit

Issues similaires

Plus d'issues Python

Recevez les nouvelles issues par e-mail

Un résumé court des issues GitHub adaptées aux débutants.