tune-templates

Turn the review-comment history into better templates. The templates are the per-type spec shells, one template-<type> per kind of spec, stored — and edited — as ordinary specs. Editing a template spec changes what every future spec of that type scaffolds from.

Read the list at run time, never from memory:

node "${CLAUDE_PLUGIN_ROOT}/lib/spec-types-cli.mjs"

Six kinds ship with the plugin and the user can add more from the configuration page, so the list is not knowable when this file is written. Enumerating it here is how a type gets silently skipped.

template-general is deliberately section-free: tune its chrome and its authoring comment, never add sections to it.

${CLAUDE_PLUGIN_ROOT} below denotes the installed plugin directory. Claude and Pi export it; Codex provides the exact value in SpecForge SessionStart context. Substitute that value in every path and shell command. Templates live in the store at ~/.specforge/specs/template-<type>/spec.html; the bundled seeds are at ${CLAUDE_PLUGIN_ROOT}/templates/spec-base-<type>.html (fallback + fresh-install).

Scope rule (non-negotiable): this skill edits templates only. It never touches, rewrites, or lints existing specs. The recurring themes become template scaffolding, not retroactive edits.

1. Learn — mine the comment corpus

node "${CLAUDE_PLUGIN_ROOT}/lib/mine-comments.mjs" --json

Every human-authored comment across the store, keyed to its spec (title/type) and the section it anchored to. Agent replies are excluded. Cluster them into recurring cross-spec themes — weight spread (how many distinct specs carry a theme) over raw count, because the goal is to bake in what comes up "again and again across many specs", not one loud spec. Also look for redundant sections: shapes the templates scaffold that the human keeps deleting or collapsing.

The canonical first run of this analysis is spec cbc766178e ("Template Learnings — What 588 Review Comments Teach Us") — read it for the 13 themes (T1..T13) and the structural defects already found. On a re-run, diff new themes against it.

2. Propose — discuss via a spec, never edit silently

Author the proposal as a research spec (via the create-spec flow), one theme to one concrete template change, with an evidence index back to the comments. Present:

• the ranked themes (spread + representative quotes),
• redundant / missing sections per template,
• the exact change proposed for each template the command above lists, the user's own types included (a kind added from the configuration page appears there without this file changing). For template-general the proposal covers chrome and the authoring comment only, since adding sections to it would defeat the type,
• open questions the user must decide.

Attach it and wait for the user's decisions. Do not proceed to §3 until they have reacted. This mirrors how cbc766178e was reviewed.

3. Apply — edit the template specs in place

Only on the user's go-ahead, and only for the changes they approved:

1. Edit ~/.specforge/specs/template-<type>/spec.html with the Edit tool. Keep every <section id="…"> and its id, the theme CSS, the palette tokens, and the floating TOC (update TOC entries + section numbers together). Follow the house rules the themes encode: lead with the number, prefer tables/cards/diagrams over prose, crisp headings with no flair, present the number then explain. Template prose sets the register for every spec written from it, so it is held to the language contract twice over: ${CLAUDE_PLUGIN_ROOT}/references/spec-language.md. A placeholder that models an aphorism, an em dash or a hedge teaches every future spec to copy it.
2. Lint each edited template — must pass:

   node "${CLAUDE_PLUGIN_ROOT}/lib/lint-spec.mjs" "~/.specforge/specs/template-<type>/spec.html"

3. Sync the bundled seed so fresh installs match: mirror the finalized template into ${CLAUDE_PLUGIN_ROOT}/templates/spec-base-<type>.html (a per-type seed wins over the shared doc/impl shell — see lib/store-templates.mjs bundledShell).
4. Restart the daemon so the running server serves the edited templates:

   node "${CLAUDE_PLUGIN_ROOT}/lib/specforge-cli.mjs" start

ensureTemplates never overwrites an existing store template, so edits survive a reseed. Templates are protected from deletion; they stay attachable so they can be reviewed and tuned exactly like this.

4. Guard — commentability advisory

The lint carries an advisory commentability check (T7): it warns, without failing, when a spec traps text directly inside a bare <div> that the review layer cannot anchor a comment to. It is advisory at authoring time and never edits a spec — the fix is to wrap trapped text in a <p>/<li> or a commentable .card/.panel/.stat/.callout. When authoring or tuning, aim for a clean commentability line.