From e5f170b9b004ecb573eda9831165bfa9cb175f6f Mon Sep 17 00:00:00 2001 From: MrTango Date: Fri, 22 May 2026 04:06:26 -0700 Subject: [PATCH 1/3] Add template-question catalogue to plonecli skill Add reference/templates.md cataloguing every copier-template question (keys, defaults, choices, conditional and computed answers, required keys) so the skill builds non-interactive --defaults -d invocations without guessing or hitting prompts. Strengthen SKILL.md description and add a scaffold-don't-hand-write rule so the skill triggers when a plan decides to create a behavior or other feature. Wire the new reference into add.md and create.md. --- plonecli/skills/plonecli/SKILL.md | 5 +- plonecli/skills/plonecli/reference/add.md | 4 +- plonecli/skills/plonecli/reference/create.md | 2 +- .../skills/plonecli/reference/templates.md | 293 ++++++++++++++++++ 4 files changed, 300 insertions(+), 4 deletions(-) create mode 100644 plonecli/skills/plonecli/reference/templates.md diff --git a/plonecli/skills/plonecli/SKILL.md b/plonecli/skills/plonecli/SKILL.md index 0ae5e84..6a31bb8 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 for any plonecli command (create, add, setup, serve, test, debug, update, config) and whenever working on Plone add-on features: creating a backend add-on or Zope project; adding a content type, behavior, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, theme, or any other subtemplate; scaffolding an upgrade step / GenericSetup migration after changing profile XML (catalog, types, workflows, registry, rolemap) so it reaches already-installed sites; adapting an old/legacy package (mr.bob/bobtemplates, buildout, setup.py) to the structure plonecli's templates need; running/testing/reconfiguring a generated project. Triggers on "plonecli ...", "create a Plone addon", "add a content type / behavior / restapi service", "add upgrade_step", "migrate already-installed Plone sites", "use plonecli on an old/legacy package", "convert setup.py / buildout addon to plonecli", "zope-setup". +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 upgrade_step", "migrate installed Plone sites", "zope-setup". The -d KEY=VALUE answers each template accepts are in reference/templates.md. --- # plonecli @@ -43,7 +43,8 @@ On first run, plonecli clones the copier-templates to `~/.copier-templates/plone ## Critical rules -- **`create`/`add` are interactive by default — always run them non-interactively here.** copier opens prompts you cannot answer in Claude Code / CI (they hang or fail). Pass `--defaults` (use template defaults for unasked questions) plus `-d/--data KEY=VALUE` (repeatable) for each answer the user specified — or `--data-file PATH` for a YAML/JSON file of answers (`-d` overrides matching keys). Required answers without a default (`content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be given via `-d`. Example: `plonecli add upgrade_step --defaults -d upgrade_step_title="Reimport viewlets"`. **Never give up on a prompt and hand-write the files the subtemplate would generate** — drive plonecli non-interactively instead. Don't invoke `copier` directly. See [reference/add.md](reference/add.md). +- **Scaffold Plone features with plonecli — don't hand-write them.** The moment a task or plan calls for a behavior, content type, view, viewlet, portlet, vocabulary, indexer, subscriber, control panel, form, REST API service, theme, upgrade step, or any other Plone artifact, the first step is `plonecli add ` (inside the addon), not creating `.py`/`.zcml`/`.xml` files by hand. The templates wire up registration, profiles, and tests correctly; hand-rolled files miss those. Only fall back to manual edits for the legacy-package case below, and even then only the minimal hooks plonecli needs. +- **`create`/`add` are interactive by default — always run them non-interactively here.** copier opens prompts you cannot answer in Claude Code / CI (they hang or fail). Pass `--defaults` (use template defaults for unasked questions) plus `-d/--data KEY=VALUE` (repeatable) for each answer the user specified — or `--data-file PATH` for a YAML/JSON file of answers (`-d` overrides matching keys). Required answers without a default (`content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be given via `-d`. **The full catalogue of every template's `-d` keys, defaults, choices, conditional/computed answers and which are required is [reference/templates.md](reference/templates.md)** — consult it to build the invocation instead of guessing or triggering a prompt. Example: `plonecli add upgrade_step --defaults -d upgrade_step_title="Reimport viewlets"`. **Never give up on a prompt and hand-write the files the subtemplate would generate** — drive plonecli non-interactively instead. Don't invoke `copier` directly. See [reference/add.md](reference/add.md). - **Never start the dev server yourself.** Do not run `plonecli serve` / `plonecli debug` / `invoke start`. Assume the instance is already running; if it is not, ask the user to start it. (`plonecli test` is fine to run.) - **Use native `uv`.** Run things as `uv run `; never `uv pip` or `pip` unless explicitly told. - **Tests must pass — never skip them.** After scaffolding or adding a feature, run `plonecli test` and report real results. diff --git a/plonecli/skills/plonecli/reference/add.md b/plonecli/skills/plonecli/reference/add.md index c25c6f7..fb7be5a 100644 --- a/plonecli/skills/plonecli/reference/add.md +++ b/plonecli/skills/plonecli/reference/add.md @@ -26,7 +26,9 @@ plonecli add behavior --defaults -d behavior_name="IFeatured" plonecli add restapi_service --defaults -d service_name="@todos" ``` -Pass `-d` for every answer the user has specified; `--defaults` covers the rest. Required answers that have no default (e.g. `content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be supplied with `-d` or copier still has to prompt. Don't invent values the user hasn't given — ask first, then pass them via `-d`. The per-template question/answer keys are listed below and shown by the prompts themselves. +Pass `-d` for every answer the user has specified; `--defaults` covers the rest. Required answers that have no default (e.g. `content_type_name`, `behavior_name`, `service_name`, `upgrade_step_title`) **must** be supplied with `-d` or copier still has to prompt. Don't invent values the user hasn't given — ask first, then pass them via `-d`. + +**The complete `-d KEY=VALUE` reference for every template — keys, defaults, choices, conditional `when` questions, computed/hidden keys you must not pass, and which answers are required — is [templates.md](templates.md).** Use it to assemble the command up front; the prompts also echo the same keys. ## Subtemplates are gated by project type diff --git a/plonecli/skills/plonecli/reference/create.md b/plonecli/skills/plonecli/reference/create.md index 385c534..2dd378f 100644 --- a/plonecli/skills/plonecli/reference/create.md +++ b/plonecli/skills/plonecli/reference/create.md @@ -6,7 +6,7 @@ plonecli create addon collective.todo # backend add-on + zope-setup ( plonecli create zope-setup my-project # Zope project setup ``` -Like `add`, `create` is interactive by default. In Claude Code / CI run it non-interactively with `--defaults` (use template defaults) plus `-d/--data KEY=VALUE` for any answer you want to set, e.g. `plonecli create backend_addon collective.todo --defaults -d package_description="Todo manager"`. Do not call `copier` directly. +Like `add`, `create` is interactive by default. In Claude Code / CI run it non-interactively with `--defaults` (use template defaults) plus `-d/--data KEY=VALUE` for any answer you want to set, e.g. `plonecli create backend_addon collective.todo --defaults -d package_description="Todo manager"`. Do not call `copier` directly. The `-d` keys each project template accepts (`backend_addon`, `zope-setup`, the `addon` composite) — defaults, choices, and conditional questions like `db_storage`/`distribution` — are catalogued in [templates.md](templates.md). ## Project templates diff --git a/plonecli/skills/plonecli/reference/templates.md b/plonecli/skills/plonecli/reference/templates.md new file mode 100644 index 0000000..97136ec --- /dev/null +++ b/plonecli/skills/plonecli/reference/templates.md @@ -0,0 +1,293 @@ +# Template questions — what `-d KEY=VALUE` answers each template accepts + +This is the authoritative catalogue of every copier-template question, so you can build the +non-interactive `--defaults -d KEY=VALUE …` invocation **without** triggering a prompt and +**without** guessing. It is derived from the templates' `copier.yml`. The live source of truth is +still the templates clone (`~/.copier-templates/plone-copier-templates/