feat(templates): add reusable spec template system (#8)

SpecBridge v0.7.0: secure, deterministic, offline-first templates for
Kiro-compatible specs.

- Versioned template manifest (specbridge-template.json, schema 1.0.0)
  with strict validation and stable error codes SBT001-SBT025
- Restricted one-pass {{variable}} renderer: no code execution, no
  expressions, no environment access, no network, no recursion
- Ten built-in templates embedded at build time; project-local packs
  under .specbridge/templates with atomic script-free local install
- template list/search/show/validate/preview/apply/install/uninstall/
  scaffold CLI, spec new --template, append-only template records
- MCP template_list/search/show/preview plus candidate-hash-bound
  template_apply; /specbridge:templates plugin skill (10 skills total)
- Generated template gallery and embedded-pack module with CI drift
  checks; template documentation set and threat model

Author: HelloThisWorld

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "specbridge",
       "source": "./integrations/claude-code-plugin/specbridge",
       "description": "Kiro-compatible spec workflows, verified interactive task execution, and deterministic drift checks.",
-      "version": "0.6.1",
+      "version": "0.7.0",
       "license": "MIT",
       "keywords": [
         "spec-driven-development",

.github/workflows/ci.yml

@@ -45,6 +45,12 @@ jobs:
       - name: CLI smoke test against the example Kiro workspace
         run: node scripts/smoke.mjs
 
+      - name: Built-in template module matches the packs on disk
+        run: pnpm check:builtin-templates
+
+      - name: Template gallery matches the built-in manifests
+        run: pnpm check:template-gallery
+
       - name: GitHub Action bundle is reproducible
         if: matrix.os == 'ubuntu-latest'
         run: git diff --exit-code integrations/github-action/dist

CHANGELOG.md

@@ -1,5 +1,89 @@
 # Changelog
 
+## 0.7.0
+
+Added:
+
+- Versioned template manifest (`specbridge-template.json`, schema 1.0.0)
+  with strict validation: template IDs, semver versions, kinds, workflow
+  modes, file sets, typed variables (string/boolean/integer/enum with
+  constraints), compatibility ranges, and safe optional metadata.
+- Restricted deterministic template renderer: `{{variableName}}`
+  substitution only — one pass, no expressions, no conditionals, no
+  includes, no environment access, values never re-scanned.
+- Built-in template catalog bundled with SpecBridge (immutable at runtime,
+  embedded at build time so every bundle ships it).
+- Project-local template packs under `.specbridge/templates/<id>/`.
+- Deterministic local template search over IDs, display names,
+  descriptions, and tags (exact ID > ID prefix > exact tag > display-name
+  token > description token; no model, no network).
+- `template list | search | show | validate | preview | apply` CLI
+  commands; preview and `apply --dry-run` share the exact rendering path
+  with apply and write nothing.
+- Local template installation and uninstallation
+  (`template install <local-path>` / `template uninstall project:<id>`):
+  validated, script-free, atomic (temp directory + rename), never
+  overwriting; built-in templates cannot be uninstalled.
+- `template scaffold` — generates a complete community-ready template pack
+  (manifest, README with validation instructions and a contribution
+  checklist, plain-Markdown template files); no TypeScript required.
+- `spec new --template <reference> [--var key=value]`, delegating to the
+  same template application service (existing non-template `spec new`
+  behavior unchanged).
+- Append-only template operation records in
+  `.specbridge/template-records.jsonl` (apply/install/uninstall/scaffold)
+  storing variable names and rendered-content hashes, never values.
+- MCP template tools: `template_list`, `template_search`, `template_show`,
+  `template_preview` (read-only), and `template_apply` (candidate-hash
+  bound, acknowledgement-gated). Install/uninstall/scaffold remain
+  CLI-only.
+- Claude Code `/specbridge:templates` Skill: list/search/show/preview, and
+  apply only after explicit confirmation with the previewed candidate
+  hash.
+- Generated template gallery in `docs/templates.md`
+  (`pnpm generate:template-gallery`) with a CI drift check
+  (`pnpm check:template-gallery`); built-in packs are likewise embedded via
+  `pnpm generate:builtin-templates` with `pnpm check:builtin-templates`.
+- Template contribution workflow and documentation
+  (`docs/creating-templates.md`, `docs/template-manifest.md`,
+  `docs/template-rendering.md`, `docs/template-security.md`,
+  `docs/template-installation.md`, `docs/template-contribution-guide.md`).
+- Stable template error codes SBT001–SBT025 with remediation in every
+  message.
+
+Built-in templates:
+
+- REST API (`rest-api`)
+- CLI tool (`cli-tool`)
+- Database migration (`database-migration`)
+- Authentication (`authentication`)
+- Background job (`background-job`)
+- Event-driven service (`event-driven-service`)
+- Bugfix regression (`bugfix-regression`)
+- Performance optimization (`performance-optimization`)
+- Security hardening (`security-hardening`)
+- Refactoring (`refactoring`)
+
+Security:
+
+- No executable template code, lifecycle scripts, or shell execution.
+- No environment interpolation and no network access anywhere in the
+  template system (no remote registry, no URL or npm installation).
+- Path traversal and symlinks rejected; targets restricted to the exact
+  Kiro spec file set; variables never allowed in target paths.
+- One-pass rendering: substituted values are never re-rendered.
+- Bounded packs and output (20 files, 256 KB manifest, 1 MB per template
+  file, 5 MB per pack, 1 MB per rendered document).
+- Candidate-hash binding and an explicit acknowledgement for MCP apply.
+- Atomic installation and atomic spec creation; existing specs are never
+  overwritten; generated stages always start unapproved.
+
+Deferred to v0.7.1:
+
+- Extension/plugin SDK, runner SDK distribution, analyzer/verifier/exporter
+  SDKs.
+- Remote extension registry and community ecosystem index.
+
 ## 0.6.1
 
 Added:

README.md

@@ -14,7 +14,33 @@ Codex, local models, or any supported coding agent.
 
 > Your `.kiro` specs remain the source of truth.
 
-New in v0.6.1 — keep your existing `.kiro` specs and **choose a compatible
+New in v0.7.0 — **reusable spec templates, without executable generators or
+platform lock-in**:
+
+```bash
+specbridge template search migration
+
+specbridge template preview database-migration \
+  --name add-payment-status-index \
+  --var tableName=payments
+
+specbridge template apply database-migration \
+  --name add-payment-status-index \
+  --var tableName=payments
+```
+
+Ten built-in templates ship with SpecBridge — `rest-api`, `cli-tool`,
+`database-migration`, `authentication`, `background-job`,
+`event-driven-service`, `bugfix-regression`, `performance-optimization`,
+`security-hardening`, `refactoring` — plus project-local packs, local
+installation, and `template scaffold` for community templates. Templates
+are plain Markdown plus a JSON manifest: rendering is deterministic and
+offline (`{{variable}}` substitution only — no scripts, no network, no
+model), preview writes nothing, apply never overwrites an existing spec,
+and generated stages start unapproved like every other spec. See
+[docs/templates.md](docs/templates.md).
+
+From v0.6.1 — keep your existing `.kiro` specs and **choose a compatible
 coding agent or authoring model per operation**:
 
 ```text
@@ -261,12 +287,16 @@ Working today (fully offline, no model, no API key):
 | `specbridge spec affected` | **v0.4** — which specs does this change set touch (read-only) |
 | `specbridge spec policy init / show / validate` | **v0.4** — per-spec verification policies (impact areas, required commands, rule overrides) |
 | `specbridge verify rules / explain <id>` | **v0.4** — inspect the stable rule registry SBV001–SBV025 |
-| `specbridge mcp serve / doctor / manifest / tools` | **v0.5** — local stdio MCP server (25 tools since v0.6.1, 7 resources, 4 prompts) |
+| `specbridge mcp serve / doctor / manifest / tools` | **v0.5** — local stdio MCP server (30 tools since v0.7.0, 7 resources, 4 prompts) |
 | `specbridge run recover-lock` | **v0.5** — diagnose and explicitly recover the interactive execution lock |
 | `specbridge runner list / matrix / show / doctor` | **v0.6** — profile-based runner diagnostics and the generated capability matrix (read-only) |
 | `specbridge runner test / conformance / models <profile>` | **v0.6** — bounded structured-output probe (`--network`), conformance suite, provider-supported model listing |
 | `specbridge config doctor / migrate` | **v0.6** — configuration validation and the explicit v1 → v2 migration (dry-run by default, atomic apply with backup) |
 | `specbridge runner doctor gemini-default / openai-compatible-local / antigravity` | **v0.6.1** — diagnostics for the new adapters; MCP `runner_list` / `runner_show` / `runner_doctor` / `runner_matrix` expose the same read-only services |
+| `specbridge template list / search / show / validate` | **v0.7.0** — deterministic, offline template discovery and validation (read-only) |
+| `specbridge template preview / apply [--dry-run]` | **v0.7.0** — one rendering path; preview writes nothing, apply is atomic and never overwrites |
+| `specbridge template install / uninstall / scaffold` | **v0.7.0** — local, script-free pack installation and community-template scaffolding |
+| `specbridge spec new <name> --template <ref> --var k=v` | **v0.7.0** — template-based spec creation through the same service |
 
 Planned commands (`spec sync/export`) are registered, marked "(planned)" in
 `--help`, and exit with an honest error — see the [roadmap](docs/roadmap.md).
@@ -549,7 +579,7 @@ stores no credentials of any kind.
   secrets or environment variables.
 - Full model: [docs/security.md](docs/security.md).
 
-## Limitations (v0.6.1)
+## Limitations (v0.7.0)
 
 - The MCP server is stdio-only and local-only: no HTTP/SSE/WebSocket
   transport, no OAuth, no cloud hosting. One server process serves one
@@ -570,6 +600,13 @@ stores no credentials of any kind.
   references, chore-task exclusion) are labelled and never default to error.
 - `spec sync` and `spec export` are not implemented yet (they fail
   honestly). SARIF output is deferred.
+- Templates are local-only: there is no remote registry, no GitHub/npm/URL
+  installation, and no signed packs in v0.7.0. Template rendering is plain
+  `{{variable}}` substitution — no expressions, no conditionals, and
+  literal double braces are not supported in template files. Rendered
+  Markdown can still contain untrusted prose; SpecBridge control rules
+  (approvals, protected paths, verification) are never overridable by
+  template content.
 - Production runners are claude-code, codex-cli, gemini-cli, ollama
   (authoring-only), openai-compatible (authoring-only), and mock; the
   antigravity-cli adapter is experimental detection only. Provider usage
@@ -623,13 +660,16 @@ deterministic drift verification (rule engine SBV001–SBV025, policies,
 affected-spec resolution, evidence freshness, four report formats) and the
 production GitHub Action. v0.5: the local stdio MCP server, direct
 interactive task execution, and the self-contained Claude Code plugin with
-its repository-local marketplace. v0.6.0 (this release): the
-capability-driven runner platform with a frozen adapter contract, runner
-profiles and explicit configuration migration, deterministic selection and
-bounded authoring fallback, the conformance framework, and the production
-Codex CLI and Ollama (authoring-only) runners. Next — v0.6.1: Gemini CLI,
-OpenAI-compatible authoring, Antigravity, MCP runner diagnostics, and the
-runner-management Skill. v0.7: templates, plugin SDK, extension registry,
+its repository-local marketplace. v0.6.0: the capability-driven runner
+platform with a frozen adapter contract, runner profiles and explicit
+configuration migration, deterministic selection and bounded authoring
+fallback, the conformance framework, and the production Codex CLI and
+Ollama (authoring-only) runners. v0.6.1: Gemini CLI, OpenAI-compatible
+authoring, Antigravity, MCP runner diagnostics, and the runner-management
+Skill. v0.7.0 (this release): the offline template system — versioned
+manifests, a restricted deterministic renderer, ten built-in templates,
+project-local packs, local installation, scaffolding, MCP template tools,
+and the templates Skill. Next — v0.7.1: plugin SDK, extension registry,
 community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
 
 ## Documentation
@@ -638,6 +678,13 @@ community ecosystem. Full detail: [docs/roadmap.md](docs/roadmap.md).
 [Kiro compatibility](docs/kiro-compatibility.md) ·
 [Spec authoring](docs/spec-authoring.md) ·
 [Spec analysis](docs/spec-analysis.md) ·
+[Templates](docs/templates.md) ·
+[Creating templates](docs/creating-templates.md) ·
+[Template manifest](docs/template-manifest.md) ·
+[Template rendering](docs/template-rendering.md) ·
+[Template installation](docs/template-installation.md) ·
+[Template security](docs/template-security.md) ·
+[Template contribution guide](docs/template-contribution-guide.md) ·
 [Approval workflow](docs/approval-workflow.md) ·
 [Sidecar state](docs/sidecar-state.md) ·
 [Runners (v0.6)](docs/runners.md) ·

docs/claude-code-plugin.md

@@ -22,6 +22,8 @@ integrations/claude-code-plugin/specbridge/
 │   ├── approve/SKILL.md       /specbridge:approve <spec> <stage>   (human-only)
 │   ├── implement/SKILL.md     /specbridge:implement <spec> [task]
 │   ├── continue/SKILL.md      /specbridge:continue <run-id>
+│   ├── runners/SKILL.md       /specbridge:runners [profile]
+│   ├── templates/SKILL.md     /specbridge:templates [query | show … | apply …]
 │   └── verify/SKILL.md        /specbridge:verify [spec]
 ├── bin/
 │   ├── specbridge             POSIX wrapper → dist/cli.cjs
@@ -87,6 +89,13 @@ and controlled lifecycle operations and never duplicate core logic:
   never sends a network request itself, and never starts a login. The
   existing implementation workflow is unchanged: `task_begin` → the
   current Claude Code session edits → `task_complete`.
+- `templates` (v0.7.0) discovers templates with `template_list`/
+  `template_search`, inspects with `template_show`, always previews with
+  `template_preview`, and applies only after explicit user confirmation via
+  `template_apply` with the previewed `candidateHash` and the
+  `"apply-reviewed-template"` acknowledgement. It never installs,
+  uninstalls, or scaffolds templates (CLI-only operations), never renders
+  content itself, and never edits `.kiro` or `.specbridge` directly.
 
 No skill uses `bypassPermissions`, `dangerously-skip-permissions`,
 unrestricted `Bash(*)`, or unrestricted `Write`, and no skill instructs

docs/cli-mcp-parity.md

@@ -11,7 +11,10 @@ over both. This table maps every capability to its surfaces:
 | List/read specs | `spec list/show` | `spec_list`, `spec_read` | `status` |
 | Spec status | `spec status` | `spec_status` | `status` |
 | Agent context | `spec context` | `spec_context` | (used internally) |
-| Create templates | `spec new` | `spec_create` (preview→apply) | `new` |
+| Create a spec | `spec new` | `spec_create` (preview→apply) | `new` |
+| Discover templates | `template list/search/show/validate` | `template_list`, `template_search`, `template_show` | `templates` |
+| Apply a template | `template preview/apply`, `spec new --template` | `template_preview` + `template_apply` (hash-bound) | `templates` (after confirmation) |
+| Manage template packs | `template install/uninstall/scaffold` | **no** (deliberately CLI-only) | **no** |
 | Analyze spec | `spec analyze` | `spec_analyze` | `author`/`status` |
 | Apply authored stage | `spec generate/refine` (runner-drafted) | `spec_stage_validate` + `spec_stage_apply` (session-drafted) | `author` |
 | **Approve stage** | `spec approve` | **no direct model tool** | `approve` (human-invoked CLI) |

docs/creating-templates.md

@@ -0,0 +1,113 @@
+# Creating templates
+
+This is the contributor happy path: scaffold a template pack, edit plain
+Markdown, validate, try it locally, share it. No TypeScript is ever
+required — a template pack is a JSON manifest plus Markdown files, and
+that is the whole format. For what templates are and what they cannot do,
+start with [the template overview](templates.md).
+
+## 1. Scaffold a pack
+
+```bash
+specbridge template scaffold my-template --kind feature --output ./my-template
+```
+
+This generates a complete, already-valid pack:
+
+```
+my-template/
+├── specbridge-template.json      # the manifest
+├── README.md                     # usage, variables table, checklist
+└── files/
+    ├── requirements.md.template
+    ├── design.md.template
+    └── tasks.md.template
+```
+
+A `--kind bugfix` scaffold generates `files/bugfix.md.template` instead of
+`files/requirements.md.template` — the file set always mirrors the full
+Kiro layout for the kind, nothing more and nothing less:
+
+| Kind | Rendered files |
+| --- | --- |
+| `feature` | `requirements.md`, `design.md`, `tasks.md` |
+| `bugfix` | `bugfix.md`, `design.md`, `tasks.md` |
+
+Useful scaffold options: `--modes` (comma-separated workflow modes),
+`--display-name`, `--description`, `--license` (default `MIT`), and
+`--dry-run` to list the files without writing. Scaffolding works outside a
+SpecBridge workspace too — you do not need a `.kiro` project to author a
+template — and it never overwrites an existing directory.
+
+## 2. Edit the template files and manifest
+
+Template files are plain Markdown with `{{variable}}` placeholders. There
+are no scripts, expressions, conditionals, or loops — the
+[rendering rules](template-rendering.md) are deliberately small. The
+scaffold starts you with the built-in variables (`{{title}}`,
+`{{description}}`) and one example variable (`actor`); declare your own in
+the manifest's `variables` array. Use `<angle-bracket>` placeholders for
+content the spec author fills in by hand after applying.
+
+Everything the manifest can say — IDs, variables, constraints, file
+entries, compatibility — is specified in the
+[manifest reference](template-manifest.md).
+
+## 3. Validate
+
+```bash
+specbridge template validate ./my-template
+
+# Treat warnings (missing README, stylistic render findings) as failures:
+specbridge template validate ./my-template --strict
+```
+
+Validation checks the pack structure, the manifest, every declared file,
+and a full render with deterministic sample values, and reports every
+issue at once with a stable `SBT` code and a category (`manifest`,
+`variables`, `rendering`, `kiro-layout`, …). Add `--json` for a
+machine-readable report.
+
+## 4. Install and preview locally
+
+```bash
+specbridge template install ./my-template
+
+specbridge template preview project:my-template --name example-spec
+```
+
+Install copies the validated pack into `.specbridge/templates/my-template/`
+(atomically, never overwriting — see
+[installation](template-installation.md)). Preview renders everything and
+writes nothing; `template apply --dry-run` does the same through the exact
+same rendering path. When the output looks right:
+
+```bash
+specbridge template apply project:my-template --name my-first-real-spec
+```
+
+The `project:` prefix is only mandatory when the same ID also exists as a
+built-in; an unambiguous ID works unqualified.
+
+## 5. Share it
+
+A template pack is just a directory of text files. To share it:
+
+- **Within a team**: commit the directory to your repository (anywhere
+  inside it) and let teammates run
+  `specbridge template install ./path/to/my-template`. There is no remote
+  registry, URL, or npm installation in v0.7.0 — installation reads a
+  local directory inside the repository, and nothing else. A community
+  index is deferred to v0.7.1+ per the [roadmap](roadmap.md).
+- **As a built-in**: open a pull request adding the pack under
+  `packages/templates/builtins/` in this repository — see the
+  [contribution guide](template-contribution-guide.md).
+
+## Related documentation
+
+- [Template overview](templates.md)
+- [Manifest reference](template-manifest.md)
+- [Rendering rules](template-rendering.md)
+- [Installation](template-installation.md)
+- [Security](template-security.md)
+- [Contribution guide](template-contribution-guide.md)

docs/mcp-server.md

@@ -32,6 +32,11 @@ specbridge mcp manifest [--json]                # identity + capability counts
 specbridge mcp tools    [--json] [--verbose]    # tool/resource/prompt catalog
 ```
 
+v0.7.0 adds five template tools: read-only `template_list`,
+`template_search`, `template_show`, and `template_preview`, plus the
+candidate-hash-bound `template_apply` (acknowledgement-gated, atomic,
+never overwriting). Template install/uninstall/scaffold remain CLI-only.
+
 v0.6.1 adds four read-only runner diagnostic tools (`runner_list`,
 `runner_show`, `runner_doctor`, `runner_matrix`) — thin adapters over the
 same shared runner services the CLI uses; see [mcp-tools.md](mcp-tools.md).