Spec templates: author, promote, manage, and create from scaffolds

The spec is completely blank — no scope, no goals, no audience defined yet. What are we building here? Give me the overview of what you need, and I'll start grilling toward a finished spec.

Let me go read the codebase first. Good. I've read the full codebase. Here's what I found: **How a spec is created today:** 1. User types free-text into the CaptureBox (the only entry point) 2. That raw text becomes the spec's `title`, `summary`, and `key` 3. The editor document is initialized with exactly **two blocks**: an "Overview" section_header and a paragraph containing the raw overview text 4. That's it — the agent then grills the user through structured sections (intent, constraints, acceptance, tasks) from scratch **What the codebase knows about but doesn't use as starting points:** - There's already a `specType` enum: `"initiative" | "epic" | "spec"` — but the create flow hardcodes `"spec"` every time - There's already a `parentId` field for hierarchical specs (children of children of initiatives) - The block types include `goal`, `acceptance_criterion`, `constraint`, `section_header` — the editor already supports structured specs - There's zero template infrastructure — no "create spec from template", no pre-composed block structures, no template library **The concrete problem:** A team creating an "integration spec" or "migration spec" gets the same blank two-block doc as a "new feature spec," and the writer has to remember what sections, questions, and constraints that type of spec needs. The existing `specType` enum (`initiative | epic | spec`) is too coarse for what you're describing — an integration spec and a feature spec are both `"spec"` today, so the template system needs its own dimension. The first question: how many template types should v1 ship with? I'd recommend starting with **2-3** — a feature spec, an integration/API spec, and a migration spec — enough to prove the mechanism covers genuinely different spec shapes without over-investing in templates you don't know teams will use.

That's a much better framing. Let me answer the grilling question by reading exactly how the agent handles pre-existing blocks. Good. I found the critical mechanism. Here's exactly what happens: **`resolveSpecPhase` is driven solely by section scores, not block presence.** Even with 20 pre-filled goals/constraints/acceptance blocks, if `sectionScores` is empty, the phase is `"intent-open"` and the agent's directive says "Ask ONE question about what the user cannot do today." The agent **sees** the existing blocks in SPEC STATE — they render in `blocksSummary`. So with a template, the agent opens the session, sees a partially populated spec, sees an unscored intent section, and gets told "work the open section." Two paths diverge: - **Path A — scaffolds that pass the gate:** template blocks happen to cover the semantic coverage dimensions well enough that `report_section_score` returns 0.9+. The agent advances to constraints without grilling those topics. The PM gets a pre-filled spec that "passes" on boilerplate they never thought about. - **Path B — scaffolds in placeholder/probing language:** template blocks contain typed gaps (e.g. `"**Target user:** [who will use this?]"`). The agent sees incomplete blocks, semantic coverage finds missing dimensions, scoring clamps below 0.9, and the agent must ask the PM to fill the gaps. This is the productive path — the template provides shape, not answers. The bad outcome you described **is real** under Path A. The right behavior is Path B: templates carry **structure + prompts**, not finished prose. That way the agent treats a template-spec the same way it treats a blank-page spec — it grills — but the grilling is more targeted because the template already framed what *kind* of thing is being built. Let me capture all the decisions you've already confirmed into goal blocks, then ask one tight question about the template-block design. Intent is clean at 0.92. Let me surface the highest-impact constraint decision. Here's where we are — intent is locked. The remaining open question for constraints: who has authority to author and retire templates? I'd recommend **org admins only** — templates propagate shape across every new spec, so a bad template is worse than no template, and promotion-from-spec is already low-friction for any member who wants to contribute a template (they just ask an admin to promote). But that's my recommendation — you decide.

Terrific answer. Let me capture it all. The last AC was rejected as describing test behavior, not user-visible product outcome. Let me fold that bar into the first AC (which already covers all templates including starters) and resubmit the remaining three clean ACs.

All three sections pass. Now let me plan and create the tasks. **Proposed split — three coarse, independently demoable capabilities:** 1. **Template management gallery + authoring + lifecycle** — the data model (new `spec_templates` table), CRUD API for templates, admin gallery UI listing/managing templates, from-scratch template creation, and retirement. This is the shelf templates live on. Demoable on its own (an org can see and manage its templates even if none exist yet). 2. **Promote an existing spec to a template** — the "make more like this one" action on a spec, including the assertion-to-prompt conversion (stripping specific prose from goal/constraint/acceptance blocks into probing language). This is the path that makes templates productive. Demoable as "old spec became a template with prompts instead of answers." 3. **Create a new spec from a template** — template picker in the spec-creation flow, seeding the editor document with the template's blocks instead of the two-block Overview-only scaffold, producing an unscored spec the agent grills from. All three tasks created. Now I'll build the complete trace graph. The spec is complete. Here's the final state: **Title:** Spec templates: author, promote, manage, and create from scaffolds **Summary:** Teams create reusable spec scaffolds from existing specs or from scratch, then create new specs against them instead of starting from a blank page. Templates live in the org, are listed/managed/retired, and ship with a small starter set. Template blocks use prompting language so the agent still grills — templates accelerate shape, never bypass review. **Three coarse tasks, each independently demoable:** 1. **Template gallery with authoring and lifecycle management** — data model, admin-gated CRUD API, gallery UI listing templates with create-from-scratch and retire actions, three seeded starter templates (feature, integration, migration). 2. **Promote an existing spec to a template** — "Promote to template" action on a spec, converting each goal/constraint/acceptance block's prose into probing/placeholder language. The conversion is visible to the reviewing admin before saving. 3. **Create a new spec from a template** — template picker extended into the spec creation flow; selecting a template seeds the editor document with its scaffold blocks instead of the two-block Overview default. The resulting spec starts unscored, so the agent grills normally. **The hard part** is task 2 — the assertion-to-prompt conversion is genuinely non-trivial. A straight block copy is the failure mode the spec explicitly guards against, so the conversion mechanism (automatic stripping, or a review step where the author converts each block, or a hybrid) is the design work that makes or breaks the feature.