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

Đang mở
  • Có gì không ổn?
#5,421 0 bình luận 0 reaction 0 người được giao Xem trên GitHub

Maintainer thường phản hồi trong vòng 1 ngày

Chưa có ai nhận issue này.

Đánh giá

Độ khó
4/5
Thời gian dự kiến
3-5 ngày
Mức phù hợp với người mới
28/100
Loại issue
Tính năng
Độ rõ ràng
Đặc tả rõ ràng
Mức độ hoạt động
Sôi nổi
Công nghệ
python, yaml
Lĩnh vực
tooling

Hướng nghiên cứu

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.

Do mô hình lập chỉ mục viết ra từ nội dung của issue.

Mô tả

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.
Ngôn ngữ chính
Python
Star
149k
Fork
13.4k
Merge trung bình
1 ngày 5 giờ
Pull request đã merge (30 ngày)
223

Chuẩn bị môi trường

Mở trong Codespaces

Khởi chạy dev container của dự án ngay trên trình duyệt, bằng tài khoản GitHub của bạn.

Bắt đầu từ đâu

  1. Đọc hết issue, rồi đọc hướng dẫn đóng góp của dự án.
  2. Bình luận trên issue rằng bạn sẽ nhận — tránh hai người làm cùng một việc.
  3. Fork repository và làm thay đổi trên một nhánh.
  4. Mở pull request có tham chiếu số hiệu của issue.

Issue khác của github/spec-kit

Tất cả issue của github/spec-kit

Issue tương tự

Thêm issue về Python

Nhận issue mới trong hộp thư của bạn

Bản tóm tắt ngắn những issue GitHub phù hợp với người mới.