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

Abierto
  • ¿Algo no está bien?
#5,421 0 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
4/5
Tiempo estimado
3-5 días
Aptitud para principiantes
28/100
Tipo de issue
Nueva funcionalidad
Claridad
Bien especificado
Estado de actividad
Activo
Stack tecnológico
python, yaml
Área
tooling

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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.
Lenguaje dominante
Python
Estrellas
149k
Forks
13.4k
Merge medio
1 d 5 h
PR fusionados (30 d)
223

Preparar el entorno

Abrir en Codespaces

Inicia el contenedor de desarrollo del proyecto en tu navegador, con tu propia cuenta de GitHub.

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de github/spec-kit

Todos los issues de github/spec-kit

Issues similares

Más issues de Python

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.