github / github/spec-kit

[Bug]: Template files are inconsistently formatted

Offen
#4,335 1 Kommentar 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
bug-assess severity-low
Vorherrschende Sprache
Python
Sterne
137k
Forks
12.3k
Ø Merge
2 T. 12 Std.
Gemergte PRs (30 T.)
159

Beschreibung

### Bug Description

The speckit template files are inconsistently formatted.

### Steps to Reproduce

1. Clone the latest release and enter it:

```shell
git clone --depth 1 --branch v1.0.1 https://github.com/github/spec-kit.git
cd spec-kit
```

2. Read the five templates in `templates/`:

```shell
for f in spec plan tasks checklist constitution; do
echo "===== $f-template.md ====="; cat "templates/$f-template.md"
done
```

Version checked: v1.0.1, tagged 2026-08-21. `templates/` tree hash `8730ddb`.

### Expected Behavior

Consistent templates.

### Actual Behavior

Inconsistent templates.

### Specify CLI Version

1.0.0

### AI Agent

Claude Code

### Operating System

Not relevant

### Python Version

Not relevant

### Error Logs

```shell

```

### Additional Context

I've been working with the stock templates and noticed a handful of small inconsistencies between them. Individually none of these matter much, but I think this is a place where consistency pays off more than usual: these templates are the standard the model follows when it fills them in. If the standard is ambiguous, the output inherits the ambiguity. So I'd rather raise them than not.

I looked at `spec-template.md`, `plan-template.md`, `tasks-template.md`, `checklist-template.md`, and `constitution-template.md`.

#### Issues

**The pointer to the upstream document has three names and three formats.** Three templates each point at the document they derive from, and no two agree on what to call it:

| Template | Field | Value |
| --- | --- | --- |
| `plan-template.md:5` | `Input` | Feature specification from `/specs/[###-feature-name]/spec.md` |
| `tasks-template.md:8` | `Input` | Design documents from `/specs/[###-feature-name]/` |
| `checklist-template.md:5` | `Feature` | `[Link to spec.md or relevant documentation]` |

`plan-template.md` names it twice, under two names, in two formats: line 3 carries `**Spec**: [link]` (an unfilled placeholder) and line 5 carries the `Input` field above (a backticked path to that same document).

The values also differ in mechanism, not just wording: two are literal paths containing a `[###-feature-name]` placeholder, one is a bare `[Link to ...]` placeholder. Nothing states which is expected.

**`spec-template.md` uses `Input` for something else.** Line 9 is `**Input**: User description: "$ARGUMENTS"` — the raw user request, substituted by the command, not a pointer to an upstream document. That may be a reasonable use of the word, but it means `Input` denotes two unrelated things across the template set: provenance in `plan`/`tasks`, captured arguments in `spec`.

**The date fields could be more precise.** `spec-template.md` and `checklist-template.md` use `Created`; `plan-template.md` uses `Date`, which doesn't say whether it means created or last-edited. `Date Created` and `Date Last Edited` would be unambiguous, and would let a template carry one, the other, or both as appropriate.

**Some of these fields could be filled mechanically, and currently are not.** `$ARGUMENTS` shows the templates already support machine substitution, but the values that are mechanically derivable are left to the model:

- `[DATE]` is never substituted. `create-new-feature.sh:362` copies the spec template through verbatim (`printf '%s' "$SPEC_TEMPLATE_CONTENT" > "$SPEC_FILE"`) with no rewriting of the body. The only date logic in the scripts (`create-new-feature.sh:263`, `create_new_feature.py:276`, and the PowerShell equivalent) generates a timestamp for the feature number in a fallback path — it never touches `[DATE]`. So the creation date reaches the model as a literal placeholder for it to fill in. `templates/commands/specify.md:152` emits the same `**Created**: [DATE]` into a generated checklist, reproducing the gap downstream.
- The upstream pointer is always derivable. The `Input` of `plan.md` is always the `spec.md` of the same feature.
- Could `[FEATURE NAME]` be substituted too? `create-new-feature.sh` already computes `BRANCH_NAME` and `FEATURE_NUM` and returns them on stdout, so a feature identifier exists at generation time. I have not looked into whether the name itself is available at that point, or whether leaving it to the model is deliberate.

**`Status` exists in one template only, with undefined values.** `spec-template.md` ships `Status: Draft`. Nothing I could find defines the other legal values, and no other template carries the field. I'm unsure whether the intent is that only specs are status-tracked, or whether it's meant to be broader.

**Header layout varies, including within one file.** Most templates put one field per line. `plan-template.md` pipe-joins three fields on its first metadata line and then switches to one-per-line.

**`tasks-template.md` is the only template with YAML front matter**, and there's a blank line between the opening `---` and the `description:` key, which I believe stops most parsers from reading it as front matter at all. Since no other template has front matter, I wasn't sure whether it's needed here. Either way I think it might not be a bad idea for all front matter to be YAML, but I assume you have already considered this.

#### Less important

**Instructional comments use a few different conventions.** Some blocks are marked `ACTION REQUIRED`, others are boxed `IMPORTANT … SAMPLE` blocks, and `constitution-template.md` uses inline ``. The `Example:` usage reads as genuinely different to me — it labels illustrative values rather than flagging content to delete — but the first two seem to overlap.

**Sample content isn't flagged uniformly.** `tasks-template.md` and `checklist-template.md` both say explicitly not to keep the sample items. `spec-template.md` ships three sample user stories without an equivalent instruction, though they look like the same kind of placeholder.

#### Probably deliberate

A couple of differences look deliberate rather than accidental, and I'd leave them alone: `constitution-template.md` reasonably has no branch, input, or status fields since it isn't per-feature, and its version/ratified footer is a document lifecycle rather than header metadata.

#### Caveats

Happy to be told some of these are intentional. I may be missing context on how the commands consume these fields.

The field names, values, and line numbers above are quoted from the v1.0.1 tag, and the claim that `[DATE]` is never substituted was checked against the scripts. The reasoning about intent is mine and may be missing context. I don't have time to spend more time on this without knowing that the issue is something you think is important enough to dive into. If you agree that this is a real issue I could sit down and do the actual work after we decide what the appropriate solution should be.

#### Possible long-term solution

Perhaps the long term solution should even be to create some kind of template generator. This would allow mechanically verifiable consistency and the possibility for users to change the formatting of templates if they want to, or create new ones which might be needed for extensions. For example, I got started with this review because I prefer links in my documents to be proper markdown links so they can be followed by humans.

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Compare the five files in templates/ alongside create-new-feature.sh, create_new_feature.py, the PowerShell equivalent, and templates/commands/specify.md. First determine which inconsistencies are intentional and agree on canonical field names, layout, front matter, and substitutions. Done means the agreed conventions are applied consistently and generated template content no longer preserves unintended placeholders.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python, shell
Bereich
documentation, tooling
Issue-Typ
Bug
Schwierigkeit
4/5
Geschätzter Aufwand
3-5 Tage
Aktivitätsstatus
Aktiv
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
45/100

Neue Issues direkt in Ihr Postfach

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