From c00194b6d9b8e27a6e094ccb4381be459d3b9b7e Mon Sep 17 00:00:00 2001
From: MrTango <md@derico.de>
Date: Tue, 26 May 2026 17:58:17 +0300
Subject: [PATCH] Add declarative apply spec and direct dev commands

- apply <spec.yaml>: scaffold addon + features from one validated YAML, with
  --check dry-run and fail-fast validation (templates, answers, choices)
- test/serve/debug run uv run/runwsgi/pytest directly (no invoke); add check
- feed config plone_version (minor) and github_user into copier user_defaults
- document the spec format, language template and service_for in the skill
---
 plonecli/cli.py                               | 143 ++++++++-
 plonecli/skills/plonecli/SKILL.md             |  25 +-
 plonecli/skills/plonecli/reference/spec.md    |  71 +++++
 .../skills/plonecli/reference/templates.md    |  17 +-
 plonecli/spec.py                              | 295 ++++++++++++++++++
 plonecli/templates.py                         |  25 +-
 tests/test_all_templates_data.py              |   1 +
 tests/test_plonecli.py                        |  82 ++++-
 tests/test_spec.py                            | 200 ++++++++++++
 tests/test_spec_e2e_integration.py            | 133 ++++++++
 tests/test_templates.py                       |  20 ++
 11 files changed, 984 insertions(+), 28 deletions(-)
 create mode 100644 plonecli/skills/plonecli/reference/spec.md
 create mode 100644 plonecli/spec.py
 create mode 100644 tests/test_spec.py
 create mode 100644 tests/test_spec_e2e_integration.py

diff --git a/plonecli/cli.py b/plonecli/cli.py
index 8442b31..c63b3d5 100644
--- a/plonecli/cli.py
+++ b/plonecli/cli.py
@@ -147,8 +147,8 @@ class ClickFilteredAliasedGroup(ClickAliasedGroup):
     def list_commands(self, ctx):
         existing_cmds = super().list_commands(ctx)
         project = find_project_root()
-        global_cmds = ["completion", "create", "config", "update", "skill"]
-        global_only_cmds = ["create"]
+        global_cmds = ["completion", "create", "apply", "config", "update", "skill"]
+        global_only_cmds = ["create", "apply"]
         if not project:
             cmds = [cmd for cmd in existing_cmds if cmd in global_cmds]
         else:
@@ -368,6 +368,87 @@ def add(context, template, data, data_file, defaults, no_git):
         echo(f"  Committed: {committed}", fg="green")
 
 
+@cli.command("apply")
+@click.argument("spec_file", type=click.Path(exists=True, dir_okay=False))
+@click.option(
+    "--check",
+    is_flag=True,
+    help="Validate the spec and print the plan without generating anything.",
+)
+@click.option(
+    "--no-git",
+    "no_git",
+    is_flag=True,
+    help="Do not initialise git or auto-commit generated output.",
+)
+@click.pass_context
+def apply(context, spec_file, check, no_git):
+    """Scaffold a complete addon from a declarative spec file"""
+    from pathlib import Path
+
+    from plonecli.spec import SpecError, describe_plan, load_spec, validate_spec
+
+    config = context.obj["config"]
+    ensure_templates(config)
+
+    try:
+        spec = load_spec(spec_file)
+    except SpecError as exc:
+        raise click.ClickException(
+            "Invalid spec:\n  " + "\n  ".join(exc.errors)
+        ) from exc
+
+    errors = validate_spec(spec, config)
+    if errors:
+        raise click.ClickException(
+            "Spec validation failed:\n  " + "\n  ".join(errors)
+        )
+
+    echo(describe_plan(spec, config), fg="green")
+    if check:
+        echo("\nSpec is valid (dry-run, nothing generated).", fg="green")
+        return
+
+    reg = TemplateRegistry(config)
+    resolved = reg.resolve_template_name(spec.template)
+
+    if not confirm_clean_git(spec.name, defaults=True):
+        echo("Aborted.", fg="yellow")
+        return
+
+    git_commit = config.auto_commit and not no_git
+    echo(f"\nCreating {resolved} project: {spec.name}", fg="green", reverse=True)
+    steps = reg.get_composite_steps(resolved)
+    if steps:
+        for index, step in enumerate(steps):
+            echo(f"\n  Applying template: {step}", fg="green")
+            run_create(
+                step, spec.name, config, data=spec.data, defaults=True,
+                git_commit=git_commit, overwrite=index > 0,
+            )
+    else:
+        run_create(
+            resolved, spec.name, config, data=spec.data, defaults=True,
+            git_commit=git_commit,
+        )
+
+    project = find_project_root(Path(spec.name).resolve())
+    if project is None:
+        raise click.ClickException(
+            f"Generated project not detected at {spec.name!r}"
+        )
+
+    for feat in spec.features:
+        sub = reg.resolve_template_name(feat.template)
+        echo(f"\n  Adding {sub}", fg="green")
+        run_add(
+            sub, project, config, data=feat.data, defaults=True,
+            git_commit=git_commit,
+        )
+
+    echo("\nDone.", fg="green")
+
+
 @cli.command()
 @click.pass_context
 def setup(context):
@@ -389,14 +470,32 @@ def setup(context):
     run_create("zope-setup", str(project.root_folder), config, overwrite=True)
 
 
+def _find_zope_ini(root_folder):
+    """Locate the instance zope.ini, preferring var/instance/etc/zope.ini."""
+    from pathlib import Path
+
+    root = Path(root_folder)
+    default = root / "var" / "instance" / "etc" / "zope.ini"
+    if default.exists():
+        return default
+    matches = sorted(root.glob("*/*/etc/zope.ini"))
+    return matches[0] if matches else None
+
+
 @cli.command("serve")
 @click.pass_context
 def run_serve(context):
-    """Start the Plone instance (delegates to invoke start)"""
+    """Start the Plone instance"""
     project = context.obj.get("project")
     if project is None:
         raise NotInPackageError(context.command.name)
-    params = ["uv", "run", "invoke", "start"]
+    zope_ini = _find_zope_ini(project.root_folder)
+    if zope_ini is None:
+        raise click.UsageError(
+            "No instance found. Run 'plonecli setup' (zope-setup) first."
+        )
+    rel_ini = zope_ini.relative_to(project.root_folder)
+    params = ["uv", "run", "runwsgi", str(rel_ini)]
     echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
     echo("\nINFO: Open this in a Web Browser: http://localhost:8080")
     echo("INFO: You can stop it by pressing CTRL + c\n")
@@ -407,25 +506,51 @@ def run_serve(context):
 @click.option("-v", "--verbose", is_flag=True, help="Verbose test output")
 @click.pass_context
 def run_test(context, verbose):
-    """Run the tests in your package (delegates to invoke test)"""
+    """Run the tests in your package"""
     project = context.obj.get("project")
     if project is None:
         raise NotInPackageError(context.command.name)
-    params = ["uv", "run", "invoke", "test"]
+    params = ["uv", "run", "--extra", "test", "pytest"]
     if verbose:
-        params.append("--verbose")
+        params.append("-v")
     echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
     subprocess.call(params, cwd=str(project.root_folder))
 
 
+@cli.command("check")
+@click.pass_context
+def run_check(context):
+    """Run ruff and the test suite"""
+    project = context.obj.get("project")
+    if project is None:
+        raise NotInPackageError(context.command.name)
+    cwd = str(project.root_folder)
+    ruff = ["uv", "run", "ruff", "check", "."]
+    echo(f"\nRUN: {' '.join(ruff)}", fg="green", reverse=True)
+    rc = subprocess.call(ruff, cwd=cwd)
+    if rc != 0:
+        raise SystemExit(rc)
+    pytest = ["uv", "run", "--extra", "test", "pytest"]
+    echo(f"\nRUN: {' '.join(pytest)}", fg="green", reverse=True)
+    rc = subprocess.call(pytest, cwd=cwd)
+    if rc != 0:
+        raise SystemExit(rc)
+
+
 @cli.command("debug")
 @click.pass_context
 def run_debug(context):
-    """Start the Plone instance in debug mode (delegates to invoke debug)"""
+    """Start the Plone instance in debug mode"""
     project = context.obj.get("project")
     if project is None:
         raise NotInPackageError(context.command.name)
-    params = ["uv", "run", "invoke", "debug"]
+    zope_ini = _find_zope_ini(project.root_folder)
+    if zope_ini is None:
+        raise click.UsageError(
+            "No instance found. Run 'plonecli setup' (zope-setup) first."
+        )
+    rel_ini = zope_ini.relative_to(project.root_folder)
+    params = ["uv", "run", "runwsgi", "-d", str(rel_ini)]
     echo(f"\nRUN: {' '.join(params)}", fg="green", reverse=True)
     echo("INFO: You can stop it by pressing CTRL + c\n")
     subprocess.call(params, cwd=str(project.root_folder))
diff --git a/plonecli/skills/plonecli/SKILL.md b/plonecli/skills/plonecli/SKILL.md
index cd71953..3ed29ce 100644
--- a/plonecli/skills/plonecli/SKILL.md
+++ b/plonecli/skills/plonecli/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: plonecli
-description: Scaffold and develop Plone packages with plonecli (copier-template based). Use this BEFORE hand-writing any Plone add-on code — including when a plan or task step decides to create/implement a Plone feature such as a behavior, content type, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, REST API service, theme, or upgrade step. Scaffold these with plonecli subtemplates instead of writing files by hand. Also for any plonecli command (create, add, setup, serve, test, debug, update, config); creating a backend add-on or Zope project; scaffolding a GenericSetup upgrade step after profile XML changes so they reach installed sites; adapting an old/legacy package (mr.bob, buildout, setup.py) to plonecli's structure. Triggers on "plonecli ...", "create a Plone addon", "add/create/implement a behavior (or content type / restapi service / ...)", "add a field / add fields to a content type or behavior", "add upgrade_step", "migrate installed Plone sites", "zope-setup". The -d KEY=VALUE answers each template accepts are in reference/templates.md; the per-field question flow and the Plone field/widget catalogue are in reference/fields.md.
+description: Scaffold and develop Plone packages with plonecli (copier-template based). Use this BEFORE hand-writing any Plone add-on code — including when a plan or task step decides to create/implement a Plone feature such as a behavior, content type, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, REST API service, theme, language/translation, or upgrade step. Scaffold these with plonecli subtemplates instead of writing files by hand. To scaffold a whole addon plus several features from one declarative YAML file, use `plonecli apply spec.yaml`. Also for any plonecli command (apply, create, add, setup, serve, test, check, debug, update, config); creating a backend add-on or Zope project; scaffolding a GenericSetup upgrade step after profile XML changes so they reach installed sites; adapting an old/legacy package (mr.bob, buildout, setup.py) to plonecli's structure. Triggers on "plonecli ...", "create a Plone addon", "add/create/implement a behavior (or content type / restapi service / language / ...)", "add a field / add fields to a content type or behavior", "add upgrade_step", "migrate installed Plone sites", "zope-setup". The declarative spec format is in reference/spec.md; the -d KEY=VALUE answers each template accepts are in reference/templates.md; the per-field question flow and the Plone field/widget catalogue are in reference/fields.md.
 ---
 
 # plonecli
@@ -19,21 +19,24 @@ On first run, plonecli clones the copier-templates to `~/.copier-templates/plone
 
 | Command | Scope | What it does |
 |---|---|---|
+| `apply <spec.yaml>` | anywhere | Scaffold a whole addon + features from one declarative spec, non-interactively. `--check` validates only. See [reference/spec.md](reference/spec.md). |
 | `create <template> <name>` | anywhere | Scaffold a new project (`backend_addon`, `addon` = backend_addon+zope-setup, or `zope-setup`). See [reference/create.md](reference/create.md). |
 | `add <subtemplate>` | inside a project | Add a feature. Gated by project type. See [reference/add.md](reference/add.md). |
 | `setup` | inside a `backend_addon` | Apply `zope-setup` in place (run a Plone instance around the addon). |
-| `serve` | inside a project | `uv run invoke start` → http://localhost:8080. **See server rule below.** |
-| `test [-v]` | inside a project | `uv run invoke test`. |
-| `debug` | inside a project | `uv run invoke debug`. |
+| `serve` | inside a project | `uv run runwsgi <instance>/etc/zope.ini` → http://localhost:8080. Needs an instance (run `setup` first). **See server rule below.** |
+| `test [-v]` | inside a project | `uv run --extra test pytest`. |
+| `check` | inside a project | `uv run ruff check .` then `uv run --extra test pytest`. |
+| `debug` | inside a project | `uv run runwsgi -d <instance>/etc/zope.ini`. |
 | `update` | anywhere | Pull latest copier-templates + check PyPI for plonecli updates. |
 | `config` | anywhere | Interactive global settings → `~/.plonecli/config.toml`. |
 
-`add`, `setup`, `serve`, `test`, `debug` require being inside a plonecli-generated project (detected from `pyproject.toml`); otherwise they fail with `NotInPackageError`. Subtemplates are filtered by the project's type, so `plonecli -l` shows different options depending on where you are.
+`add`, `setup`, `serve`, `test`, `check`, `debug` require being inside a plonecli-generated project (detected from `pyproject.toml`); otherwise they fail with `NotInPackageError`. Subtemplates are filtered by the project's type, so `plonecli -l` shows different options depending on where you are.
 
-`serve`, `test`, `debug` additionally need the `invoke` harness (`tasks.py`), which only the **`zope-setup`** layer provides. A project made with `create backend_addon` alone has no `tasks.py` — run `plonecli setup` first (or scaffold with the `addon` composite / `zope-setup`) before these commands work.
+`test` and `check` run directly via `uv run` and work in any addon. `serve`/`debug` need a runnable instance (`var/instance/etc/zope.ini`), which the **`zope-setup`** layer creates — run `plonecli setup` first (or scaffold with the `addon` composite / `zope-setup`).
 
 ## Decision flow
 
+0. **Whole addon with several features in one shot?** → write a spec file and run `plonecli apply spec.yaml` (validate first with `--check`). One declarative file → addon + all features, non-interactive, ruff-clean, tests passing. Best for an agent scaffolding from a feature list. Format and rules: [reference/spec.md](reference/spec.md). For single steps, use `create`/`add` below.
 1. **New project?** → `create`. Pure backend add-on: `plonecli create backend_addon my.addon`. Add-on **with** a runnable instance in one step: `plonecli create addon my.addon` (composite = `backend_addon` + `zope-setup`). Zope project: `plonecli create zope-setup my-project`. `addon` is **not** an alias of `backend_addon` — they are different templates. Details and template list: [reference/create.md](reference/create.md).
 2. **Add a feature to an existing addon?** → `cd` into the project, then `plonecli add content_type` / `behavior` / `restapi_service`. Wiring specifics: [reference/add.md](reference/add.md). **Adding fields to a content type or behavior** has no subtemplate — gather name/type/required/default per field and edit the schema by hand following [reference/fields.md](reference/fields.md). **Old/legacy package that doesn't fit the templates?** (no `[tool.plone.backend_addon.settings]`, `setup.py`/`bobtemplate.cfg`/buildout layout, `plonecli -l` lists nothing, or `add` lands files/registrations wrong) → don't hand-write subtemplate files, and don't re-run the `backend_addon` template (it overwrites `__init__.py` and real code). Inspect the structure and make the minimal edits the subtemplate hooks need. See the legacy rule below and [reference/migrate.md](reference/migrate.md).
 3. **Changed GenericSetup profile XML (`profiles/default/*`) that must reach already-installed sites?** → `plonecli add upgrade_step` to scaffold the migration. See the upgrade-step rule below and [reference/add.md](reference/add.md).
@@ -65,14 +68,18 @@ cd collective.todo
 plonecli add content_type --defaults -d content_type_name="Talk"
 plonecli add behavior --defaults -d behavior_name="IFeatured"
 plonecli add restapi_service --defaults -d service_name="@todos"
+plonecli add language --defaults -d language_code="de" -d language_name="German"
 
-# wrap it in a runnable Plone instance (adds the zope-setup / invoke harness)
+# wrap it in a runnable Plone instance (adds the zope-setup layer)
 plonecli setup
 
-# verify (needs the zope-setup layer added above)
-plonecli test
+# verify — works in any addon, no instance needed
+plonecli test          # uv run --extra test pytest
+plonecli check         # ruff check + pytest
 ```
 
 Shortcut: `plonecli create addon collective.todo` scaffolds `backend_addon` **and** `zope-setup` in one step — use it instead of `create backend_addon` + `setup`. Do not run both; that applies zope-setup twice.
 
+To scaffold an addon **and** all its features from one declarative file, use `plonecli apply spec.yaml` — see [reference/spec.md](reference/spec.md).
+
 For anything beyond this happy path, read the matching file in `reference/`.
diff --git a/plonecli/skills/plonecli/reference/spec.md b/plonecli/skills/plonecli/reference/spec.md
new file mode 100644
index 0000000..5075922
--- /dev/null
+++ b/plonecli/skills/plonecli/reference/spec.md
@@ -0,0 +1,71 @@
+# Declarative spec (`plonecli apply`)
+
+`plonecli apply spec.yaml` scaffolds a complete addon — the main project plus an
+ordered list of feature subtemplates — from **one** declarative YAML file, fully
+non-interactively. Use it when you have a feature list up front (e.g. an agent
+turning a requirements doc into an addon). For one-off steps, use `create`/`add`.
+
+```shell
+plonecli apply spec.yaml            # validate, then generate
+plonecli apply --check spec.yaml    # validate + print the plan, generate nothing
+plonecli apply --no-git spec.yaml   # skip git init / auto-commit
+```
+
+`apply` validates the **whole** spec up front (fail-fast) before writing any
+files, so a typo in feature #5 is reported before feature #1 is generated.
+
+## Format
+
+```yaml
+addon:
+  template: backend_addon        # backend_addon | addon (composite) | zope-setup
+  name: collective.todo          # target package/project name (also the directory)
+  data:                          # answers for the main template (optional)
+    plone_version: "6.1"
+features:                        # ordered subtemplates (optional)
+  - template: content_type
+    data:
+      content_type_name: Todos
+      global_allow: true
+  - template: content_type
+    data:
+      content_type_name: Todo
+      global_allow: false
+      parent_content_type: Todos
+  - template: behavior
+    data:
+      behavior_name: IFeatured
+  - template: restapi_service
+    data:
+      service_name: stats
+  - template: language
+    data:
+      language_code: de
+      language_name: German
+```
+
+* `addon.template` / `addon.name` are required.
+* `data` keys are the template's `-d` answers — see [templates.md](templates.md)
+  for every template's keys, defaults and choices.
+* `features` run in order, each on top of the generated addon, exactly as
+  repeated `plonecli add` calls would.
+* `package_name`/`package_folder` for features are filled automatically from the
+  generated addon — do not put them in feature `data`.
+
+## What the spec does NOT cover: fields
+
+Fields are **out of scope**. `content_type` and `behavior` emit an empty schema
+(`pass`); the spec only chooses templates and their options. Add fields **after**
+generation by editing the generated schema class (see [fields.md](fields.md)) or
+with plone-snippets. Do not expect the spec to define fields.
+
+## Validation rules
+
+`apply` (and `--check`) report, before generating:
+
+* unknown `addon.template` (not a project template);
+* a feature `template` that is not a valid subtemplate for the project type;
+* unknown answer keys for a template;
+* missing required answers (e.g. `content_type_name`);
+* values outside a template's fixed `choices` (dynamic choices like
+  `plone_version` are not range-checked here — copier validates them at run time).
diff --git a/plonecli/skills/plonecli/reference/templates.md b/plonecli/skills/plonecli/reference/templates.md
index 23b72c8..924e280 100644
--- a/plonecli/skills/plonecli/reference/templates.md
+++ b/plonecli/skills/plonecli/reference/templates.md
@@ -138,9 +138,10 @@ Example (containment): `plonecli add content_type --defaults -d content_type_nam
 | `http_post` | `false` | |
 | `http_patch` | `false` | |
 | `http_delete` | `false` | |
-| `service_for` | `plone.dexterity.interfaces.IDexterityContainer` | choices: `…IDexterityContainer`, `…IDexterityContent`, `Products.CMFPlone.interfaces.IPloneSiteRoot`, `zope.interface.Interface`. |
+| `service_for` | `plone.dexterity.interfaces.IDexterityContainer` | choices: default Plone content-type interfaces **plus the addon's own content-type interfaces** (scanned) **plus `<enter manually>`**. |
+| `service_for_manual` | "" | only asked when `service_for=<enter manually>`; must be non-empty. |
 
-Hidden/computed: `service_module`, `service_class`, `service_endpoint`.
+Hidden/computed: `service_module`, `service_class`, `service_endpoint`, `service_for_resolved`.
 
 ### `view` — BrowserView (optional page template)
 
@@ -244,6 +245,18 @@ See [add.md](add.md) for the full upgrade-step workflow (fill the handler, add a
 | `site_name` | `New Plone Site` (name†) | site title in header/tab. |
 | `language` | `en` | ISO 639-1 two-letter code. |
 
+### `language` — translation locale (`.po` catalog)
+
+| Key | Default | Notes |
+|---|---|---|
+| `language_code` | **required** | ISO 639-1 code, e.g. `de`, `fr`, `es`. |
+| `language_name` | `<language_code>` | human-readable name, e.g. `German`. |
+
+Creates `src/<pkg>/locales/<code>/LC_MESSAGES/<pkg>.po`. The addon already ships
+an empty `<pkg>.pot` and a `_` MessageFactory in `src/<pkg>/i18n.py`; fill the
+`.po`, then the dev instance/tests compile `.mo` automatically
+(`zope_i18n_compile_mo_files`). Hidden/computed: `current_date`.
+
 ### `mockup_pattern` — Mockup JS pattern scaffold
 
 | Key | Default | Notes |
diff --git a/plonecli/spec.py b/plonecli/spec.py
new file mode 100644
index 0000000..4c0a0f5
--- /dev/null
+++ b/plonecli/spec.py
@@ -0,0 +1,295 @@
+"""Declarative spec for scaffolding a complete addon non-interactively.
+
+A spec is a single YAML file describing the main project template plus an
+ordered list of feature subtemplates, so an agent can write one file and run
+one command (``plonecli apply spec.yaml``). It is validated fail-fast against
+the live template metadata *before* any files are generated.
+
+Fields are intentionally out of scope: ``content_type``/``behavior`` emit an
+empty schema and fields are added afterwards. The spec covers template/addon
+options only.
+
+Schema::
+
+    addon:
+      template: addon            # backend_addon | addon | zope-setup
+      name: derico.todos         # target package/project name
+      data:                      # answers for the main template
+        plone_version: "6.1"
+    features:                    # ordered subtemplates (optional)
+      - template: content_type
+        data:
+          content_type_name: Todos
+      - template: restapi_service
+        data:
+          service_name: "@todos"
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from plonecli.config import PlonecliConfig
+from plonecli.registry import TemplateRegistry
+
+# Main-template answers supplied implicitly by ``addon.name`` (copier derives
+# them from the destination directory) or carrying a usable default.
+_IMPLICIT_MAIN_ANSWERS = frozenset(
+    {"package_name", "project_name", "project_title", "project_description"}
+)
+
+# Subtemplate answers ``run_add`` fills from the detected project context.
+_IMPLICIT_FEATURE_ANSWERS = frozenset({"package_name", "package_folder"})
+
+
+class SpecError(Exception):
+    """Raised when a spec is malformed or fails validation.
+
+    Carries a list of human-readable problems so the caller can show them all.
+    """
+
+    def __init__(self, errors: list[str]):
+        self.errors = list(errors)
+        super().__init__("\n".join(self.errors))
+
+
+@dataclass
+class FeatureSpec:
+    template: str
+    data: dict = field(default_factory=dict)
+
+
+@dataclass
+class AddonSpec:
+    template: str
+    name: str
+    data: dict = field(default_factory=dict)
+    features: list[FeatureSpec] = field(default_factory=list)
+
+
+def load_spec(path: str | Path) -> AddonSpec:
+    """Parse a spec file into an :class:`AddonSpec` (structure only).
+
+    Raises :class:`SpecError` if the file is not a well-formed spec. Template
+    existence and answer correctness are checked separately by
+    :func:`validate_spec`.
+    """
+    path = Path(path)
+    try:
+        raw = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except OSError as exc:
+        raise SpecError([f"{path}: cannot read spec ({exc})"]) from exc
+    except yaml.YAMLError as exc:
+        raise SpecError([f"{path}: invalid YAML ({exc})"]) from exc
+
+    if not isinstance(raw, dict):
+        raise SpecError([f"{path}: spec must be a YAML mapping"])
+
+    errors: list[str] = []
+    addon = raw.get("addon")
+    if not isinstance(addon, dict):
+        raise SpecError([f"{path}: missing 'addon' section (a mapping)"])
+
+    template = addon.get("template")
+    name = addon.get("name")
+    if not template:
+        errors.append("addon.template is required")
+    if not name:
+        errors.append("addon.name is required")
+
+    data = addon.get("data") or {}
+    if not isinstance(data, dict):
+        errors.append("addon.data must be a mapping")
+        data = {}
+
+    raw_features = raw.get("features") or []
+    if not isinstance(raw_features, list):
+        errors.append("features must be a list")
+        raw_features = []
+
+    features: list[FeatureSpec] = []
+    for i, item in enumerate(raw_features):
+        if not isinstance(item, dict):
+            errors.append(f"features[{i}] must be a mapping")
+            continue
+        ftemplate = item.get("template")
+        if not ftemplate:
+            errors.append(f"features[{i}].template is required")
+        fdata = item.get("data") or {}
+        if not isinstance(fdata, dict):
+            errors.append(f"features[{i}].data must be a mapping")
+            fdata = {}
+        if ftemplate:
+            features.append(FeatureSpec(template=ftemplate, data=fdata))
+
+    if errors:
+        raise SpecError(errors)
+
+    return AddonSpec(template=template, name=name, data=data, features=features)
+
+
+def _load_questions(template_name: str, config: PlonecliConfig) -> dict:
+    """Return ``{question_name: spec}`` for a template's declared questions.
+
+    Skips copier internals (``_*``). Hidden/computed questions (``when: false``)
+    are kept: they are not prompted, but copier still accepts them via ``--data``
+    (e.g. ``behavior_marker``), so they are valid answer keys. :func:`_is_required`
+    treats anything with a ``when`` as optional.
+    """
+    cfg = Path(config.templates_dir) / template_name / "copier.yml"
+    if not cfg.exists():
+        return {}
+    try:
+        data = yaml.safe_load(cfg.read_text()) or {}
+    except (OSError, yaml.YAMLError):
+        return {}
+    questions = {}
+    for name, spec in data.items():
+        if name.startswith("_") or not isinstance(spec, dict):
+            continue
+        questions[name] = spec
+    return questions
+
+
+def _is_required(spec: dict) -> bool:
+    """A question must be answered when it has no usable default.
+
+    Conditional questions (a ``when`` expression) are treated as optional: they
+    may not be asked at all. bool/int questions always have an effective value.
+    """
+    if "when" in spec:
+        return False
+    if spec.get("type") in ("bool", "int"):
+        return False
+    default = spec.get("default")
+    return default is None or default == ""
+
+
+def _choice_values(choices) -> list:
+    """Normalise copier ``choices`` (list of scalars/dicts, or mapping) to values."""
+    if isinstance(choices, dict):
+        return list(choices.values())
+    values = []
+    for choice in choices:
+        if isinstance(choice, dict):
+            values.extend(choice.values())
+        else:
+            values.append(choice)
+    return values
+
+
+def _is_jinja(value) -> bool:
+    return isinstance(value, str) and ("{{" in value or "{%" in value)
+
+
+def _step_templates(main: str, reg: TemplateRegistry) -> list[str]:
+    """Return the concrete templates a main template expands to."""
+    steps = reg.get_composite_steps(main)
+    return steps if steps else [main]
+
+
+def _validate_answers(
+    template_names: list[str],
+    data: dict,
+    config: PlonecliConfig,
+    where: str,
+    skip_required: frozenset = frozenset(),
+) -> list[str]:
+    """Validate ``data`` against the union of questions for ``template_names``."""
+    errors: list[str] = []
+    merged: dict = {}
+    for name in template_names:
+        merged.update(_load_questions(name, config))
+    if not merged:
+        # No metadata available (templates not cloned); cannot validate.
+        return errors
+
+    known = set(merged)
+    for key in data:
+        if key not in known:
+            errors.append(
+                f"{where}: unknown answer {key!r} "
+                f"(template {'/'.join(template_names)})"
+            )
+
+    for qname, spec in merged.items():
+        if qname in skip_required:
+            continue
+        if qname not in data:
+            if _is_required(spec):
+                errors.append(f"{where}: missing required answer {qname!r}")
+            continue
+        choices = spec.get("choices")
+        if isinstance(choices, list) and choices:
+            valid = _choice_values(choices)
+            if any(_is_jinja(v) for v in valid):
+                continue
+            value = data[qname]
+            valid_str = {str(v) for v in valid}
+            if str(value) not in valid_str:
+                errors.append(
+                    f"{where}: {qname}={value!r} not in choices {sorted(valid_str)}"
+                )
+    return errors
+
+
+def validate_spec(spec: AddonSpec, config: PlonecliConfig) -> list[str]:
+    """Return a list of validation errors (empty when the spec is valid)."""
+    errors: list[str] = []
+    reg = TemplateRegistry(config)
+
+    main = reg.resolve_template_name(spec.template)
+    if main is None or not reg.is_main_template(main):
+        errors.append(
+            f"addon.template {spec.template!r} is not a known project template; "
+            f"choose from {sorted(reg.get_main_templates())}"
+        )
+        return errors
+
+    steps = _step_templates(main, reg)
+    errors += _validate_answers(
+        steps, spec.data, config, "addon.data", skip_required=_IMPLICIT_MAIN_ANSWERS
+    )
+
+    for i, feat in enumerate(spec.features):
+        where = f"features[{i}] ({feat.template})"
+        sub = reg.resolve_template_name(feat.template)
+        if sub is None:
+            errors.append(f"{where}: unknown template {feat.template!r}")
+            continue
+        valid_sub = any(
+            sub in reg._get_subtemplates_for_type(step) for step in steps
+        )
+        if not valid_sub:
+            errors.append(
+                f"{where}: not a valid feature for project type(s) "
+                f"{sorted(steps)}"
+            )
+            continue
+        errors += _validate_answers(
+            [sub],
+            feat.data,
+            config,
+            f"{where}.data",
+            skip_required=_IMPLICIT_FEATURE_ANSWERS,
+        )
+
+    return errors
+
+
+def describe_plan(spec: AddonSpec, config: PlonecliConfig) -> str:
+    """Render a human-readable summary of what applying the spec would do."""
+    reg = TemplateRegistry(config)
+    main = reg.resolve_template_name(spec.template) or spec.template
+    lines = [f"Plan for {spec.name!r}:", f"  create {main} {spec.name}"]
+    if spec.data:
+        for key, value in spec.data.items():
+            lines.append(f"      -d {key}={value}")
+    for feat in spec.features:
+        lines.append(f"  add {feat.template}")
+        for key, value in feat.data.items():
+            lines.append(f"      -d {key}={value}")
+    return "\n".join(lines)
diff --git a/plonecli/templates.py b/plonecli/templates.py
index 372a66d..2d38634 100644
--- a/plonecli/templates.py
+++ b/plonecli/templates.py
@@ -119,13 +119,30 @@ def get_templates_info(config: PlonecliConfig) -> str:
     return "unknown"
 
 
-def _build_user_defaults(config: PlonecliConfig) -> dict:
-    """Build user_defaults dict from global config for copier."""
+def _minor_version(version: str) -> str:
+    """Reduce a full Plone version (e.g. ``6.1.1``) to its minor (``6.1``)."""
+    return ".".join(version.split(".")[:2])
+
+
+def _build_user_defaults(
+    config: PlonecliConfig, template_name: str | None = None
+) -> dict:
+    """Build user_defaults dict from global config for copier.
+
+    ``plone_version`` is template-aware: ``backend_addon`` asks for the minor
+    series (e.g. ``6.1``), so the configured full version is reduced. ``zope-setup``
+    asks for a full version and derives it from the addon minor inside the
+    composite, so no default is injected here.
+    """
     defaults = {}
     if config.author_name and config.author_name != "Plone Developer":
         defaults["author_name"] = config.author_name
     if config.author_email and config.author_email != "dev@plone.org":
         defaults["author_email"] = config.author_email
+    if config.github_user:
+        defaults["github_organization"] = config.github_user
+    if config.plone_version and template_name == "backend_addon":
+        defaults["plone_version"] = _minor_version(config.plone_version)
 
     return defaults
 
@@ -164,7 +181,7 @@ def run_create(
         src_path=src,
         dst_path=target_name,
         data=data or {},
-        user_defaults=_build_user_defaults(config),
+        user_defaults=_build_user_defaults(config, template_name),
         defaults=defaults,
         overwrite=overwrite,
         unsafe=True,
@@ -215,7 +232,7 @@ def run_add(
         src_path=src,
         dst_path=str(project.root_folder),
         data=template_data,
-        user_defaults=_build_user_defaults(config),
+        user_defaults=_build_user_defaults(config, template_name),
         defaults=defaults,
         unsafe=True,
     )
diff --git a/tests/test_all_templates_data.py b/tests/test_all_templates_data.py
index 8300cea..1bea451 100644
--- a/tests/test_all_templates_data.py
+++ b/tests/test_all_templates_data.py
@@ -43,6 +43,7 @@
     "content_type_name": "Article",
     "service_name": "myservice",
     "upgrade_step_title": "Reimport viewlets",
+    "language_code": "de",
 }
 
 
diff --git a/tests/test_plonecli.py b/tests/test_plonecli.py
index 2877057..bb31b65 100644
--- a/tests/test_plonecli.py
+++ b/tests/test_plonecli.py
@@ -532,10 +532,18 @@ def test_add_outside_project(mock_config, mock_project, runner, tmp_path):
     assert result.exit_code != 0
 
 
+def _make_zope_ini(tmp_path):
+    ini = tmp_path / "var" / "instance" / "etc" / "zope.ini"
+    ini.parent.mkdir(parents=True, exist_ok=True)
+    ini.write_text("[server:main]\n")
+    return ini
+
+
 @patch("plonecli.cli.find_project_root")
 @patch("plonecli.cli.load_config")
 @patch("plonecli.cli.subprocess.call", return_value=0)
 def test_serve_command(mock_call, mock_config, mock_project, runner, tmp_path):
+    _make_zope_ini(tmp_path)
     mock_config.return_value = MagicMock(templates_dir=str(tmp_path))
     mock_project.return_value = MagicMock(
         root_folder=tmp_path,
@@ -547,7 +555,28 @@ def test_serve_command(mock_call, mock_config, mock_project, runner, tmp_path):
     assert result.exit_code == 0
     mock_call.assert_called_once()
     call_args = mock_call.call_args[0][0]
-    assert call_args == ["uv", "run", "invoke", "start"]
+    assert call_args == [
+        "uv",
+        "run",
+        "runwsgi",
+        "var/instance/etc/zope.ini",
+    ]
+
+
+@patch("plonecli.cli.find_project_root")
+@patch("plonecli.cli.load_config")
+@patch("plonecli.cli.subprocess.call", return_value=0)
+def test_serve_command_no_instance(mock_call, mock_config, mock_project, runner, tmp_path):
+    mock_config.return_value = MagicMock(templates_dir=str(tmp_path))
+    mock_project.return_value = MagicMock(
+        root_folder=tmp_path,
+        project_type="zope-setup",
+        settings={},
+    )
+
+    result = runner.invoke(cli, ["serve"])
+    assert result.exit_code != 0
+    mock_call.assert_not_called()
 
 
 @patch("plonecli.cli.find_project_root")
@@ -564,7 +593,7 @@ def test_test_command(mock_call, mock_config, mock_project, runner, tmp_path):
     result = runner.invoke(cli, ["test"])
     assert result.exit_code == 0
     call_args = mock_call.call_args[0][0]
-    assert call_args == ["uv", "run", "invoke", "test"]
+    assert call_args == ["uv", "run", "--extra", "test", "pytest"]
 
 
 @patch("plonecli.cli.find_project_root")
@@ -581,13 +610,52 @@ def test_test_command_verbose(mock_call, mock_config, mock_project, runner, tmp_
     result = runner.invoke(cli, ["test", "--verbose"])
     assert result.exit_code == 0
     call_args = mock_call.call_args[0][0]
-    assert "--verbose" in call_args
+    assert "-v" in call_args
+
+
+@patch("plonecli.cli.find_project_root")
+@patch("plonecli.cli.load_config")
+@patch("plonecli.cli.subprocess.call", return_value=0)
+def test_check_command(mock_call, mock_config, mock_project, runner, tmp_path):
+    mock_config.return_value = MagicMock(templates_dir=str(tmp_path))
+    mock_project.return_value = MagicMock(
+        root_folder=tmp_path,
+        project_type="backend_addon",
+        settings={},
+    )
+
+    result = runner.invoke(cli, ["check"])
+    assert result.exit_code == 0
+    assert mock_call.call_count == 2
+    first = mock_call.call_args_list[0][0][0]
+    second = mock_call.call_args_list[1][0][0]
+    assert first == ["uv", "run", "ruff", "check", "."]
+    assert second == ["uv", "run", "--extra", "test", "pytest"]
+
+
+@patch("plonecli.cli.find_project_root")
+@patch("plonecli.cli.load_config")
+@patch("plonecli.cli.subprocess.call", return_value=1)
+def test_check_command_ruff_fail_stops(
+    mock_call, mock_config, mock_project, runner, tmp_path
+):
+    mock_config.return_value = MagicMock(templates_dir=str(tmp_path))
+    mock_project.return_value = MagicMock(
+        root_folder=tmp_path,
+        project_type="backend_addon",
+        settings={},
+    )
+
+    result = runner.invoke(cli, ["check"])
+    assert result.exit_code != 0
+    mock_call.assert_called_once()
 
 
 @patch("plonecli.cli.find_project_root")
 @patch("plonecli.cli.load_config")
 @patch("plonecli.cli.subprocess.call", return_value=0)
 def test_debug_command(mock_call, mock_config, mock_project, runner, tmp_path):
+    _make_zope_ini(tmp_path)
     mock_config.return_value = MagicMock(templates_dir=str(tmp_path))
     mock_project.return_value = MagicMock(
         root_folder=tmp_path,
@@ -598,4 +666,10 @@ def test_debug_command(mock_call, mock_config, mock_project, runner, tmp_path):
     result = runner.invoke(cli, ["debug"])
     assert result.exit_code == 0
     call_args = mock_call.call_args[0][0]
-    assert call_args == ["uv", "run", "invoke", "debug"]
+    assert call_args == [
+        "uv",
+        "run",
+        "runwsgi",
+        "-d",
+        "var/instance/etc/zope.ini",
+    ]
diff --git a/tests/test_spec.py b/tests/test_spec.py
new file mode 100644
index 0000000..0560b7b
--- /dev/null
+++ b/tests/test_spec.py
@@ -0,0 +1,200 @@
+"""Tests for the declarative spec (plonecli.spec) and the apply command."""
+
+from __future__ import annotations
+
+import textwrap
+
+import pytest
+
+from plonecli.config import PlonecliConfig
+from plonecli.spec import (
+    AddonSpec,
+    FeatureSpec,
+    SpecError,
+    load_spec,
+    validate_spec,
+)
+
+
+def _write(tmp_path, text):
+    path = tmp_path / "spec.yaml"
+    path.write_text(textwrap.dedent(text))
+    return path
+
+
+# --- fake template metadata -------------------------------------------------
+
+BACKEND_QUESTIONS = {
+    "package_name": {"type": "str", "default": "{{ x }}"},
+    "plone_version": {"type": "str", "default": "6.1", "choices": ["6.0", "6.1"]},
+    "is_headless": {"type": "bool", "default": False},
+}
+
+CONTENT_TYPE_QUESTIONS = {
+    "content_type_name": {"type": "str"},  # required (no default)
+    "global_allow": {"type": "bool", "default": True},
+}
+
+
+def _fake_questions(name, config):
+    return {
+        "backend_addon": BACKEND_QUESTIONS,
+        "content_type": CONTENT_TYPE_QUESTIONS,
+    }.get(name, {})
+
+
+@pytest.fixture
+def patched_registry(monkeypatch):
+    """Patch registry classification + question loading with fakes."""
+    import plonecli.spec as spec_mod
+
+    monkeypatch.setattr(spec_mod, "_load_questions", _fake_questions)
+
+    def resolve(self, alias):
+        return alias if alias in {"backend_addon", "content_type"} else None
+
+    monkeypatch.setattr(
+        spec_mod.TemplateRegistry, "resolve_template_name", resolve, raising=True
+    )
+    monkeypatch.setattr(
+        spec_mod.TemplateRegistry,
+        "is_main_template",
+        lambda self, n: n == "backend_addon",
+        raising=True,
+    )
+    monkeypatch.setattr(
+        spec_mod.TemplateRegistry,
+        "get_main_templates",
+        lambda self: ["backend_addon"],
+        raising=True,
+    )
+    monkeypatch.setattr(
+        spec_mod.TemplateRegistry,
+        "get_composite_steps",
+        lambda self, n: None,
+        raising=True,
+    )
+    monkeypatch.setattr(
+        spec_mod.TemplateRegistry,
+        "_get_subtemplates_for_type",
+        lambda self, t: ["content_type"] if t == "backend_addon" else [],
+        raising=True,
+    )
+
+
+# --- load_spec --------------------------------------------------------------
+
+
+def test_load_spec_minimal(tmp_path):
+    path = _write(
+        tmp_path,
+        """
+        addon:
+          template: backend_addon
+          name: collective.todo
+        """,
+    )
+    spec = load_spec(path)
+    assert spec == AddonSpec(
+        template="backend_addon", name="collective.todo", data={}, features=[]
+    )
+
+
+def test_load_spec_with_features(tmp_path):
+    path = _write(
+        tmp_path,
+        """
+        addon:
+          template: backend_addon
+          name: collective.todo
+          data:
+            plone_version: "6.1"
+        features:
+          - template: content_type
+            data:
+              content_type_name: Todo
+        """,
+    )
+    spec = load_spec(path)
+    assert spec.data == {"plone_version": "6.1"}
+    assert spec.features == [
+        FeatureSpec(template="content_type", data={"content_type_name": "Todo"})
+    ]
+
+
+def test_load_spec_missing_addon(tmp_path):
+    path = _write(tmp_path, "features: []\n")
+    with pytest.raises(SpecError) as exc:
+        load_spec(path)
+    assert any("addon" in e for e in exc.value.errors)
+
+
+def test_load_spec_missing_required_fields(tmp_path):
+    path = _write(tmp_path, "addon:\n  data: {}\n")
+    with pytest.raises(SpecError) as exc:
+        load_spec(path)
+    assert any("template" in e for e in exc.value.errors)
+    assert any("name" in e for e in exc.value.errors)
+
+
+def test_load_spec_not_a_mapping(tmp_path):
+    path = _write(tmp_path, "- just\n- a\n- list\n")
+    with pytest.raises(SpecError):
+        load_spec(path)
+
+
+# --- validate_spec ----------------------------------------------------------
+
+
+def test_validate_spec_valid(patched_registry):
+    spec = AddonSpec(
+        template="backend_addon",
+        name="collective.todo",
+        data={"plone_version": "6.1"},
+        features=[
+            FeatureSpec(template="content_type", data={"content_type_name": "Todo"})
+        ],
+    )
+    assert validate_spec(spec, PlonecliConfig()) == []
+
+
+def test_validate_spec_unknown_main_template(patched_registry):
+    spec = AddonSpec(template="bogus", name="x")
+    errors = validate_spec(spec, PlonecliConfig())
+    assert errors and "not a known project template" in errors[0]
+
+
+def test_validate_spec_unknown_answer(patched_registry):
+    spec = AddonSpec(
+        template="backend_addon", name="x", data={"nope": "1"}
+    )
+    errors = validate_spec(spec, PlonecliConfig())
+    assert any("unknown answer 'nope'" in e for e in errors)
+
+
+def test_validate_spec_bad_choice(patched_registry):
+    spec = AddonSpec(
+        template="backend_addon", name="x", data={"plone_version": "9.9"}
+    )
+    errors = validate_spec(spec, PlonecliConfig())
+    assert any("not in choices" in e for e in errors)
+
+
+def test_validate_spec_missing_required_feature_answer(patched_registry):
+    spec = AddonSpec(
+        template="backend_addon",
+        name="x",
+        features=[FeatureSpec(template="content_type", data={})],
+    )
+    errors = validate_spec(spec, PlonecliConfig())
+    assert any("missing required answer 'content_type_name'" in e for e in errors)
+
+
+def test_validate_spec_invalid_feature_for_type(patched_registry):
+    spec = AddonSpec(
+        template="backend_addon",
+        name="x",
+        features=[FeatureSpec(template="bogus_feature", data={})],
+    )
+    errors = validate_spec(spec, PlonecliConfig())
+    assert any("unknown template" in e for e in errors)
diff --git a/tests/test_spec_e2e_integration.py b/tests/test_spec_e2e_integration.py
new file mode 100644
index 0000000..a2a7902
--- /dev/null
+++ b/tests/test_spec_e2e_integration.py
@@ -0,0 +1,133 @@
+"""End-to-end test: scaffold an addon from a spec, lint and test the result.
+
+Generates a backend_addon plus a representative set of features from a single
+declarative spec (the ``plonecli apply`` contract), then:
+
+* runs ``ruff check`` — the generated tree must be lint-clean with zero edits;
+* builds the package with ``uv sync --extra test`` and runs its own pytest
+  suite inside a real Plone instance.
+
+It is slow (builds Plone via ``uv sync``) and needs network on first run, so it
+is marked ``integration`` and deselected by default. Run explicitly with::
+
+    uv run pytest -m integration tests/test_spec_e2e_integration.py
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import textwrap
+from pathlib import Path
+
+import pytest
+
+from plonecli.config import PlonecliConfig
+from plonecli.project import find_project_root
+from plonecli.spec import load_spec, validate_spec
+from plonecli.templates import run_add, run_create
+
+DEV_TEMPLATES_DIR = Path("/home/node/develop/plone/src/copier-templates")
+FALLBACK_TEMPLATES_DIR = Path("/home/node/.copier-templates/plone-copier-templates")
+
+
+def _templates_dir() -> Path:
+    env_dir = os.environ.get("PLONECLI_TEMPLATES_DIR")
+    if env_dir and Path(env_dir).exists():
+        return Path(env_dir)
+    if DEV_TEMPLATES_DIR.exists():
+        return DEV_TEMPLATES_DIR
+    if FALLBACK_TEMPLATES_DIR.exists():
+        return FALLBACK_TEMPLATES_DIR
+    pytest.skip("No copier-templates checkout available")
+
+
+SPEC = """\
+addon:
+  template: backend_addon
+  name: collective.spectest
+  data:
+    package_name: collective.spectest
+features:
+  - template: content_type
+    data: {content_type_name: Todos, global_allow: true}
+  - template: content_type
+    data: {content_type_name: Todo, global_allow: false, parent_content_type: Todos}
+  - template: behavior
+    data: {behavior_name: IFeatured}
+  - template: restapi_service
+    data: {service_name: stats}
+  - template: view
+    data: {view_name: my-view}
+  - template: language
+    data: {language_code: de, language_name: German}
+"""
+
+
+def _apply_spec(spec, config, target_dir: Path) -> None:
+    """Generate the spec's addon + features (mirrors ``plonecli apply``)."""
+    run_create(
+        spec.template,
+        str(target_dir),
+        config,
+        data=spec.data,
+        defaults=True,
+    )
+    project = find_project_root(target_dir)
+    assert project is not None, "addon not detected after create"
+    for feat in spec.features:
+        run_add(feat.template, project, config, data=feat.data, defaults=True)
+
+
+@pytest.mark.integration
+def test_spec_scaffold_is_clean_and_tests_pass(tmp_path: Path) -> None:
+    if shutil.which("uv") is None:
+        pytest.skip("uv is required for the integration test")
+
+    templates_dir = _templates_dir()
+    config = PlonecliConfig(templates_dir=str(templates_dir))
+
+    spec_file = tmp_path / "spec.yaml"
+    spec_file.write_text(textwrap.dedent(SPEC))
+    spec = load_spec(spec_file)
+    assert validate_spec(spec, config) == [], "spec should validate"
+
+    project_dir = tmp_path / spec.name
+    _apply_spec(spec, config, project_dir)
+    assert (project_dir / "pyproject.toml").exists()
+
+    env = os.environ.copy()
+    env.pop("VIRTUAL_ENV", None)
+    env.setdefault("PIP_DISABLE_PIP_VERSION_CHECK", "1")
+
+    # Lint: the generated tree must be ruff-clean with no hand-edits.
+    lint = subprocess.run(
+        ["uvx", "ruff", "check", "."],
+        cwd=project_dir,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    assert lint.returncode == 0, (
+        f"generated tree not ruff-clean:\n{lint.stdout}\n{lint.stderr}"
+    )
+
+    # Build + run the generated package's own test suite inside Plone.
+    subprocess.run(
+        ["uv", "sync", "--extra", "test"],
+        cwd=project_dir,
+        env=env,
+        check=True,
+    )
+    result = subprocess.run(
+        ["uv", "run", "--extra", "test", "pytest", "tests/", "-q"],
+        cwd=project_dir,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+    assert result.returncode == 0, (
+        f"Generated package tests failed.\n"
+        f"STDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
+    )
diff --git a/tests/test_templates.py b/tests/test_templates.py
index 9d7e0c9..d027946 100644
--- a/tests/test_templates.py
+++ b/tests/test_templates.py
@@ -6,6 +6,7 @@
 
 from plonecli.config import PlonecliConfig
 from plonecli.templates import (
+    _build_user_defaults,
     ensure_templates_cloned,
     get_template_path,
     get_templates_info,
@@ -14,6 +15,25 @@
 )
 
 
+def test_build_user_defaults_backend_addon_uses_minor_version():
+    config = PlonecliConfig(plone_version="6.1.1", github_user="acme")
+    defaults = _build_user_defaults(config, "backend_addon")
+    assert defaults["plone_version"] == "6.1"
+    assert defaults["github_organization"] == "acme"
+
+
+def test_build_user_defaults_zope_setup_omits_plone_version():
+    config = PlonecliConfig(plone_version="6.1.1")
+    defaults = _build_user_defaults(config, "zope-setup")
+    assert "plone_version" not in defaults
+
+
+def test_build_user_defaults_no_version_when_unset():
+    config = PlonecliConfig()
+    defaults = _build_user_defaults(config, "backend_addon")
+    assert "plone_version" not in defaults
+
+
 def test_ensure_templates_cloned_existing(tmp_path):
     """If clone exists, return path without cloning."""
     templates_dir = tmp_path / "templates"