@zenera/cli 1.1.0

package/templates/.github/prompts/new-agent.prompt.md

@@ -0,0 +1,38 @@
+---
+mode: agent
+description: Add an agent to agents.yaml, with its prompt, tools and handoffs.
+---
+
+Add an agent to this project. Ask for the one sentence that states its job
+before writing anything; if I have already given it, do not ask again.
+
+First, argue against it. An agent is worth adding only when one of these is
+true, and you should say which:
+
+- it needs a **different model tier** from every existing agent
+- it needs a **different tool set**, and the difference is a permission
+- its instructions **contradict** an existing agent's rather than extend them
+- it is a **parallel branch** target for a `fork:`
+
+If none holds, propose the smaller change instead — a skill, a prompt line, a
+tool grant — and stop. Adding an agent to solve a prompt problem is the failure
+mode this project cares most about.
+
+If it is warranted:
+
+1. Pick a name matching `^[a-z0-9]+(?:[-_][a-z0-9]+)*$`. It reaches the model as
+   `transfer_to_<name>`, so the name is part of the routing surface.
+2. Write `agents/prompts/<name>.md`: one sentence of identity, a short procedure
+   or three to five rules, then what it must **not** do — especially the
+   neighbouring agent's job. Second person, imperative, failure paths stated.
+   No frontmatter, no meta-talk about the runtime.
+3. Add the `agents.yaml` entry. `description:` is written **for the model** — it
+   is the whole of what a sibling sees when deciding to hand off. Grant the
+   narrowest `tools:` the job needs.
+4. Wire the handoffs in both directions only if both directions are real.
+   Specialists handing back to a router is ping-pong; prefer terminating.
+5. Add a one-line comment above the entry saying why this agent exists — its
+   job or its tier, not what the keys mean.
+
+Then run `zen check` and report what it said. If it fails, fix the file it
+named rather than working around it.

package/templates/.github/prompts/new-skill.prompt.md

@@ -0,0 +1,37 @@
+---
+mode: agent
+description: Add a skill under agents/skills, with a description that routes.
+---
+
+Add a skill to this project. A skill is curated instruction content — and
+optionally tools — loaded on demand instead of sitting in every system prompt.
+Reach for one whenever a rule applies only sometimes, or holds a fact that will
+change without the prompt changing.
+
+Ask what the skill must say and when it applies, if I have not already said.
+
+1. Choose the layout. A flat `agents/skills/<name>.md` for text alone; a folder
+   `agents/skills/<name>/SKILL.md` when it needs companions — a rate table, an
+   example letter, a schema. Siblings of `SKILL.md` become readable resources.
+2. Write the `description`. This is the routing key and the only thing the model
+   sees before deciding to load the skill, so write it as **the condition under
+   which the skill is needed**, not as a title. `Water policy` is a title;
+   `Escape of water from plumbing and tanks — and the freezing exclusion` is a
+   condition. If two skills could both match a case, sharpen both until they
+   cannot.
+3. Write the body as instructions the model can act on: thresholds, exact
+   wording, the boundaries of the rule, and what to do when the case falls
+   outside it. Put the facts here rather than in a prompt — that is the point of
+   the file.
+4. Declare `tools:` in the frontmatter only for tools that must not run until
+   this skill is active. They are advertised from turn 0 and refuse to execute
+   while the skill is dormant, which is how gating happens without breaking the
+   prompt cache.
+5. Leave `name` out unless it must differ from the file or folder name, and
+   leave `version`/`tags` out unless something uses them.
+
+Do not `preload:` it unless every case genuinely needs it — a preloaded skill is
+a longer prompt, paid for on every call. Bind it under `agents[].skills.allow`
+if the agent's catalog is restricted.
+
+Then run `zen check` and report what it said.

package/templates/.github/prompts/review-project.prompt.md

@@ -0,0 +1,31 @@
+---
+mode: agent
+description: Review the project against the checklist before committing.
+---
+
+Review this project the way a maintainer would, then report. Read
+`agents.yaml`, `INSTRUCTIONS.md`, every file under `agents/prompts/` and the
+skill descriptions under `agents/skills/` before saying anything.
+
+Work the checklist in §9 of the copilot instructions. In particular:
+
+- **Loads.** Run `zen check`. Nothing else in this review matters if it fails.
+- **One job each.** Can you state every agent's job in one sentence? If not,
+  say which agent and what the two jobs are.
+- **Prompts.** Second person, imperative, failure paths stated, no hedging, no
+  politeness padding, no meta-talk about the runtime. Nothing in
+  `INSTRUCTIONS.md` that is true of only one agent.
+- **Facts.** Any number, threshold, fee or date living in a prompt is in the
+  wrong file. Name it and say which skill it belongs in.
+- **Skill descriptions.** Each one a condition, not a title; no two overlapping.
+- **Tools.** Every grant justified by the agent's job; nothing mutating held by
+  an agent that only reads; every granted tool mentioned by the prompt.
+- **Routing.** Handoff targets have descriptions written for the model. No
+  ping-pong edges. No router that answers.
+- **Models.** Each agent on the cheapest tier that is right, not the safest.
+- **Cache.** Nothing volatile — dates, ids, counts — in the stable prefix.
+- **Secrets.** No key inlined anywhere; `.env` ignored, `sessions/` ignored.
+
+Report as a list of findings, each naming the file and the line, ordered by how
+much it will cost to leave. Say plainly if you find nothing worth changing.
+Do not edit anything unless I ask.

package/templates/.github/skills/zen-cli/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: zen-cli
+description: How to drive this project from the terminal with `zen` — running it, validating it, credentials, the sandbox and run reports.
+---
+
+# The `zen` command line
+
+Everything here operates on a project directory. The project is resolved from
+the working directory, or by name from the registry `zen init` wrote to, or
+explicitly with `--project <name|dir>`. Every command takes `--json` and prints
+a machine-readable answer instead of a rendered one.
+
+## Running
+
+```
+zen run [project] [prompt] [options]
+```
+
+On a terminal with no prompt it opens the TUI; with a prompt, or without a tty,
+it answers once on stdout. The first word is the project when it names one, and
+the first word of the prompt when it does not — `--project` settles it.
+
+| Flag                    | What it does                                 |
+| ----------------------- | -------------------------------------------- |
+| `--project <name\|dir>` | Which project. Inferred from the directory   |
+| `--session <id>`        | Continue a particular session                |
+| `--new`                 | Start a fresh one                            |
+| `--workspace <dir>`     | What the agent may read and write            |
+| `--model <ref>`         | Override the default model for this run      |
+| `--image <ref>`         | Override the container commands run in       |
+| `--read-only`           | Withhold every tool that can write           |
+| `--quiet`               | The answer only; no narration                |
+| `--plain`               | One shot, even on a terminal                 |
+| `--out <file>`          | Write the answer to a file as well as stdout |
+| `--yes`                 | Accept the questions it would otherwise ask  |
+
+Flags always win over the file: the repository states intent, the invocation
+overrides it. There is no `resume` — a session continues itself, because its
+state is what it is.
+
+With a prompt on the command line nothing is asked: a fresh session, the current
+directory as the workspace, writable.
+
+## Validating
+
+```
+zen check [dir] [--strict] [--quiet]     everything agents.yaml names
+zen models [--project <name|dir>]         providers, models and embeddings resolved
+```
+
+`zen check` reads the project the way `zen run` does and reports in full without
+calling a model — a missing prompt file, an unknown tool, a handoff to nobody, a
+model alias on an undeclared provider. `zen models` answers the narrower
+question of what each agent would actually talk to, and which credential it
+needs. Run `zen check` after any edit to `agents.yaml`, a prompt or a skill; it
+is the cheapest possible test.
+
+## Credentials
+
+```
+zen key ls [--check]              what is on the keyring, and whether it works
+zen key add <provider>[/name]     add one — never on the command line
+zen key use <provider>/<name>     choose the active key for a provider
+zen key check [provider[/name]]   a round trip per key
+zen key show <provider>[/name]    masked, or --reveal for the secret itself
+zen key rm <provider>/<name>      forget it
+zen key env [provider …]          `eval "$(zen key env)"` for other tools
+```
+
+The secret never comes from argv — a command line lands in `ps`, in shell
+history and in CI logs. `zen key add` takes it from piped stdin or an echo-off
+prompt, and nowhere else. Real environment variables win over the keyring, so
+`.env` still decides inside a run.
+
+## The sandbox
+
+```
+zen sandbox status    is a container runtime there, is the image pulled
+zen sandbox up        start it
+zen sandbox pull      fetch the image ahead of the first run
+zen sandbox clean     throw away persisted containers
+```
+
+Shell commands run in a container over the session workspace, not on the host.
+If runs begin by installing a toolchain, set `sandbox.image` to one that already
+has it, or `sandbox.persist: true`, rather than paying for it every run.
+
+## Reports and sessions
+
+```
+zen list [--sessions] [--prune]                       every known project
+zen inspect [run] [--session <id>] [--open] [--serve]  a run's report.html
+zen open [project] [--editor <cmd>] [--wait]           open it in an editor
+zen version                                            CLI, library and Node
+```
+
+`zen inspect` renders the trajectory of a run — every message, tool call, skill
+activation and handoff, in order, with what each one cost. It is the first place
+to look when behaviour is wrong and the prompt looks right: it shows what the
+model was actually given, which is rarely what you assumed.
+
+Sessions live under `sessions/` and hold run state, memory, blobs and whatever
+the agent wrote. None of it is source and none of it is committed.
+
+## Exit codes
+
+Non-zero on failure, with the offending key or file named in the message. A load
+error names the exact path — `agents.yaml: agents[1].skills.discovery — …` — so
+read it rather than guessing; the loader is strict on purpose and an unknown key
+is an error, not a value quietly ignored.