@supierior/workflower-authoring 0.1.0 → 0.1.2

package/README.md

@@ -14,11 +14,11 @@ The skill helps an agent:
 
 - design a folder-safe workflow id and step list;
 - choose step commands and companion skills;
-- scaffold a Pi package that registers a `WorkflowDefinition`;
-- organize generated TypeScript workflow packages with a small `src/index.ts` entrypoint and one `src/workflows/<workflow-id>/` folder per workflow, holding that workflow's definition, bundled skills, and scripts together;
+- scaffold a Pi package that registers a `WorkflowDefinition` with `registerWorkflows([...])`;
+- organize generated TypeScript workflow packages with a small `src/index.ts` entrypoint and one `src/<workflow-id>/` folder per workflow, holding that workflow's definition, bundled skills, and scripts together (nesting under `src/workflows/<workflow-id>/` only when the package needs it), plus a shared `src/routing/` router and shared skill-context folder when multiple workflows need them;
 - teach the garden/flower artifact model, including `.workflower/workflows/<garden-name>/0001-<workflow-id>/` and each flower's `index.json`;
-- configure workflow-level `model` and `thinkingLevel` defaults (including level names `tiny`/`small`/`medium`/`large`/`xl`), optional step-level runtime overrides, workflow-level `autoNext`, `userInvocable`, and `modelInvocable`, and workflow-level `pollen`/`acceptPollen` when chained workflows should pass or ignore previous flower outputs;
-- document garden state keys, `workflower_state_set`/`workflower_state_get`/`workflower_state_list` calls, and deterministic router commands/tools when small facts such as review ratings drive later steps;
+- configure workflow-level `model` and `thinkingLevel` defaults (including level names `tiny`/`small`/`medium`/`large`/`xl`) deliberately, with step-level overrides tuned to each step's cost, workflow-level `autoNext`, `userInvocable`, and `modelInvocable`, and workflow-level `pollen`/`acceptPollen` when chained workflows should pass or ignore previous flower outputs;
+- document garden state keys, `workflower_state_set`/`workflower_state_get`/`workflower_state_list` calls, and a single shared `<package-id>-route` router command when small facts such as review ratings drive later steps, including bounded review loops with an attempt cap;
 - register computed step prompts with `registerWorkflowerCommand` when a step needs generated content instead of a static bundled skill;
 - add package metadata that loads the generated extension and skills;
 - document a smoke test using `/wf:<workflow-id> <garden-name>`, optional active handoff with `/wf:<next-workflow-id>`, `/next`, and the `/wf` management subcommands (`status`, `stop`, `list`, `clean`, `state`, `resume`, `config`).
@@ -38,13 +38,15 @@ Generated guidance should align with Workflower's garden/flower model:
 - Workflow ids must be folder-safe (`^[a-z0-9_-]+$`) because ids become `/wf:<workflow-id>` commands and flower folder names.
 - Start a fresh garden with `/wf:<workflow-id> <garden-name>`.
 - While a workflow is active, hand off to another workflow in the same garden with `/wf:<next-workflow-id>` and no garden name.
-- Artifacts live in flower folders such as `.workflower/workflows/<garden-name>/0001-<workflow-id>/`; each flower has an `index.json` recording status and pollen paths. A flower only exists at runtime, once a workflow starts in a garden — it is distinct from a package's own `src/workflows/<workflow-id>/` source folder, which holds that workflow's definition, skills, and scripts at author time.
-- Use workflow-level `model` and `thinkingLevel` as defaults for all steps; step-level runtime settings override only the current step before falling back to workflow settings and then starting defaults. `model` may be a level name (`tiny`/`small`/`medium`/`large`/`xl`), a `provider/model-id` string, or an ordered fallback array; level names resolve through the user's `/wf config` model-level mapping.
+- Artifacts live in flower folders such as `.workflower/workflows/<garden-name>/0001-<workflow-id>/`; each flower has an `index.json` recording status and pollen paths. A flower only exists at runtime, once a workflow starts in a garden — it is distinct from a package's own `src/<workflow-id>/` source folder, which holds that workflow's definition, skills, and scripts at author time.
+- Register workflows with `registerWorkflows([...])`, not the deprecated singular `registerWorkflow`; the registry already dedupes idempotently, so no manual "already registered" guard is needed in the extension entrypoint.
+- Use workflow-level `model` and `thinkingLevel` as defaults for all steps, set deliberately rather than left unset; step-level runtime settings override only the current step, tuned to that step's actual cost, before falling back to workflow settings and then starting defaults. `model` may be a level name (`tiny`/`small`/`medium`/`large`/`xl`), a `provider/model-id` string, or an ordered fallback array; level names resolve through the user's `/wf config` model-level mapping.
 - Use workflow-level `autoNext` to set the default for steps that omit their own `autoNext`.
-- Use workflow-level `userInvocable` (default `true`) and `modelInvocable` (default `true`) to control whether a workflow can be started with `/wf:<id>` and/or via `workflower_handoff`.
+- Use workflow-level `userInvocable` (default `true`) and `modelInvocable` (default `true`) to control whether a workflow can be started with `/wf:<id>` and/or via `workflower_handoff`. Several public workflows may intentionally share the same private loop chain (a full entry and a shortcut entry, for example).
 - Use workflow-level `pollen` and `acceptPollen` to control which output paths are referenced during handoff.
+- `clearOnStart`, `clearOnCompletion`, and `cleanupOnCompletion` all default to `true`; only set them to `false`, and only when turning that default off is actually wanted — `cleanupOnCompletion: false` in particular should be reserved for workflows whose outputs are a genuine user-facing deliverable, not a debugging convenience.
 - Use garden state for small JSON-compatible facts that must survive context-clearing boundaries, such as `review.rating`; instruct agents exactly when to call `workflower_state_set`, `workflower_state_get`, and `workflower_state_list`.
-- Use `registerWorkflowerCommand` for step commands whose prompt content must be computed at step-start time instead of a static bundled skill.
+- Use `registerWorkflowerCommand` for step commands whose prompt content must be computed at step-start time instead of a static bundled skill. When a package has more than one deterministic branch, register a single router command named `<package-id>-route` that switches on a route-name argument, rather than one command per branch.
 - Use deterministic router code or model-callable tools for autonomous branching; do not rely on assistant text printing slash commands.
 - Use the built-in `/wf` subcommands (`status`, `stop`, `list`, `clean <garden-name>`, `state list|get|set`, `resume [garden-name]`, `config`) for manual inspection, cleanup, and model-level configuration.
 - Cleanup waits until the whole garden completes; handoffs preserve previous flowers for pollen and inspection.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supierior/workflower-authoring",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Pi skill package for creating Workflower workflow packages.",
   "keywords": [
     "pi-package",
@@ -15,16 +15,16 @@
     "skills",
     "README.md"
   ],
-  "pi": {
-    "skills": [
-      "./skills"
-    ]
-  },
   "scripts": {
     "build": "echo \"No build for workflower-authoring\"",
     "test": "echo \"No tests for workflower-authoring\"",
     "typecheck": "echo \"No typecheck for workflower-authoring\"",
     "lint": "echo \"No lint for workflower-authoring\"",
     "clean": "rimraf dist coverage .turbo || true"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
   }
-}
+}

package/skills/workflower-authoring/SKILL.md

@@ -26,12 +26,13 @@ Ask only for missing information. Gather:
    - pass the latest completed step outputs by default when handing off to another workflow;
    - set workflow-level `pollen` when only specific output path(s) should be pinned and handed off;
    - set workflow-level `acceptPollen: false` when a workflow should ignore incoming pollen paths from a previous flower.
-8. Lifecycle preferences:
-   - preserve artifacts after final garden completion? Set `cleanupOnCompletion: false`.
-   - keep same visible session on start? Set `clearOnStart: false`.
-   - keep same visible session on completion? Set `clearOnCompletion: false`.
+8. Lifecycle preferences. `clearOnStart`, `clearOnCompletion`, and `cleanupOnCompletion` all default to `true`; only set them when turning that default _off_ (`false`), and only leave a field unset when the default is what you want:
+   - preserve artifacts after final garden completion instead of cleaning them up? Set `cleanupOnCompletion: false` — only when the workflow's outputs are a real user-facing deliverable (a final report, a doc meant for later review, screenshots), not as a standing habit and never just to make inspection easier while iterating on the workflow itself.
+   - continue the visible session that was already active instead of starting cold? Set `clearOnStart: false` — typical for a shortcut entry workflow chained into mid-conversation, not typical for a private loop workflow reached only by handoff.
+   - keep the visible session instead of clearing it when the workflow completes? Set `clearOnCompletion: false`.
    - keep context between specific steps? Set that step's `clearOnNext: false`.
    - immediately advance after a step finishes? Set that step's `autoNext: true`.
+9. Composability: does this workflow need more than one public entry point? A shortcut entry workflow (skips an early question-gathering step, `clearOnStart: false`, jumps straight into a shared step) can hand off into the same private loop chain as the full entry workflow. Design the shared private chain once; add thin entry workflows around it as needed.
 
 ## Validate the design
 
@@ -55,13 +56,16 @@ For a new package, create this structure. In a monorepo it may live under `packa
 <package-root>/
 ├── src/
 │   ├── index.ts                        # registers every workflow + calls setupWorkflower(pi)
-│   └── workflows/
-│       └── my-workflow/                # folder name matches the workflow id
-│           ├── my-workflow-workflow.ts # WorkflowDefinition
-│           ├── skills/
-│           │   └── my-first-step/SKILL.md   # when using skill-backed steps
-│           └── scripts/
-│               └── helper.ts           # workflow-scoped helper scripts, if any
+│   ├── routing/
+│   │   └── <package-id>-router.ts      # one shared router command for all deterministic branching, if any
+│   ├── <shared-context-folder>/        # markdown context shared by skills across workflows, if any
+│   └── my-workflow/                    # folder name matches the workflow id
+│       ├── my-workflow-workflow.ts     # WorkflowDefinition
+│       ├── skills/
+│       │   └── my-first-step/SKILL.md  # when using skill-backed steps
+│       └── scripts/
+│           └── helper.js               # workflow-scoped scripts, if any
+├── docs/                                # optional: standards multiple skills/scripts enforce
 ├── package.json
 ├── README.md
 ├── tsconfig.json
@@ -69,17 +73,21 @@ For a new package, create this structure. In a monorepo it may live under `packa
 └── vitest.config.ts
 ```
 
-One folder per workflow id, even for a single-workflow package: everything that workflow needs (definition, its skills, its scripts) stays together under `src/workflows/<workflow-id>/`. Use an existing small workflow package as a scaffold when available, but prefer the architecture above for new packages.
+One folder per workflow id, even for a single-workflow package: everything that workflow needs (definition, its skills, its scripts) stays together directly under `src/<workflow-id>/`. Default to this flat shape; only nest an extra `src/workflows/<workflow-id>/` layer when the package also has other non-workflow top-level `src/` concerns that a flat `src/<workflow-id>/` would otherwise crowd. Use an existing small workflow package as a scaffold when available, but prefer the architecture above for new packages.
 
 ## Architecture guidance
 
 Generated TypeScript workflow packages should follow the suPIerior package architecture direction:
 
-- Keep `src/index.ts` small and stable: import each `WorkflowDefinition`, call `registerWorkflow` for each, then call `setupWorkflower(pi)`, and export the result as the default extension entrypoint. This is the one file that shows the whole package's workflow registration at a glance.
-- Group everything one workflow needs under its own `src/workflows/<workflow-id>/` folder: the `WorkflowDefinition`, its bundled step skills (`skills/`), and any helper scripts (`scripts/`). Add other folders local to that workflow (for example its own `internals/`) only when that workflow's own logic grows past a few files.
-- If multiple workflows share non-Pi logic, put it under `src/internals/<domain-capability>/` using workflow domain language, not generic names like `utils` or `helpers`. Workflows may import shared `src/internals/`; shared internals should not import from a specific workflow or from `src/index.ts`.
+- Keep `src/index.ts` small and stable: import each `WorkflowDefinition`, call `registerWorkflows([...])` once with all of them, then call `setupWorkflower(pi)`, and export the result as the default extension entrypoint. This is the one file that shows the whole package's workflow registration at a glance. Do not hand-roll a module-level "already registered" boolean guard: `registerWorkflows` already dedupes idempotently (re-registering the same definition is a no-op; a conflicting redefinition under the same id throws), so the extension entrypoint can call it unconditionally on every load.
+- Group everything one workflow needs under its own `src/<workflow-id>/` folder: the `WorkflowDefinition`, its bundled step skills (`skills/`), and any helper scripts (`scripts/`). Add other folders local to that workflow (for example its own `internals/`) only when that workflow's own logic grows past a few files.
+- If multiple workflows share deterministic routing logic, put it in one `src/routing/<package-id>-router.ts` that registers a single `registerWorkflowerCommand` named `<package-id>-route`, whose handler switches on a route-name argument (see "Step archetypes" below), rather than one command per branch.
+- If multiple skills across different workflows share instructional context (methodology docs, contracts, quality bars), put that markdown under a domain-named shared folder, for example `src/global-skill-context/`, and reference it by relative path from each skill's own instructions.
+- If multiple workflows share non-Pi logic that is neither routing nor skill context, put it under `src/internals/<domain-capability>/` using workflow domain language, not generic names like `utils` or `helpers`. Workflows may import shared `src/internals/`; shared internals should not import from a specific workflow or from `src/index.ts`.
+- `scripts/` inside a workflow folder may hold either TypeScript helpers imported by that workflow's definition, or standalone executable scripts (plain `.js`, run as `node path/to/script.js --flag`) that a bundled skill's instructions shell out to via bash. When a skill relies on the latter, its `SKILL.md` should show the exact copy-paste invocation.
+- An optional `docs/` folder at the package root can hold standards documents that multiple skills or scripts enforce (for example a required output file-layout convention) — distinct from the README (user-facing smoke test) and from shared skill-context markdown (instructional content meant to be injected into a skill's own prompt).
 - Do not create empty architecture folders for tiny packages; add seams when they clarify navigation.
-- Reserve "flower" for the runtime run-instance concept (`.workflower/workflows/<garden-name>/0001-<workflow-id>/`). A `src/workflows/<workflow-id>/` folder holds a workflow's source — its definition, skills, and scripts — not a flower; a flower only exists once that workflow starts running in a garden.
+- Reserve "flower" for the runtime run-instance concept (`.workflower/workflows/<garden-name>/0001-<workflow-id>/`). A `src/<workflow-id>/` folder holds a workflow's source — its definition, skills, and scripts — not a flower; a flower only exists once that workflow starts running in a garden.
 
 Markdown-only companion skill packages can stay simple. If a skill grows beyond one `SKILL.md` plus a few directly referenced files, use an analogous split with `SKILL.md`, `skill-api/`, and `internals/`.
 
@@ -89,19 +97,19 @@ Markdown-only companion skill packages can stay simple. If a skill grows beyond
 
 ```ts
 import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import setupWorkflower, { registerWorkflow } from "@supierior/workflower";
+import setupWorkflower, { registerWorkflows } from "@supierior/workflower";
 
-import { myWorkflow } from "./workflows/my-workflow/my-workflow-workflow";
+import { myWorkflow } from "./my-workflow/my-workflow-workflow";
 
 export { myWorkflow };
 
 export default function myWorkflowPackageExtension(pi: ExtensionAPI): void {
-  registerWorkflow(myWorkflow);
+  registerWorkflows([myWorkflow]);
   setupWorkflower(pi);
 }
 ```
 
-`src/workflows/my-workflow/my-workflow-workflow.ts`:
+`src/my-workflow/my-workflow-workflow.ts`:
 
 ```ts
 import type { WorkflowDefinition } from "@supierior/workflower";
@@ -110,9 +118,12 @@ export const myWorkflow: WorkflowDefinition = {
   id: "my-workflow",
   userInvocable: true,
   modelInvocable: true,
+  // cleanupOnCompletion defaults to true (artifacts are cleaned up); only set it to
+  // false when the workflow's outputs are a real user-facing deliverable meant to
+  // survive after the garden finishes, e.g. this workflow's second-step.md report.
   cleanupOnCompletion: false,
-  model: ["openai-codex/gpt-5.3-codex-spark"],
-  thinkingLevel: "medium",
+  model: "medium",
+  thinkingLevel: "low",
   autoNext: false,
   pollen: "second-step.md",
   acceptPollen: true,
@@ -121,6 +132,8 @@ export const myWorkflow: WorkflowDefinition = {
       id: "first-step",
       command: "/skill:my-first-step",
       outputs: ["first-step.md"],
+      // Override the workflow default for the one step doing real authoring work.
+      model: "large",
       thinkingLevel: "high",
       clearOnNext: false,
     },
@@ -136,19 +149,20 @@ export const myWorkflow: WorkflowDefinition = {
 For a package with several workflows, `src/index.ts` imports each `WorkflowDefinition` and registers all of them before calling `setupWorkflower(pi)` once:
 
 ```ts
-import { firstWorkflow } from "./workflows/first-workflow/first-workflow-workflow";
-import { secondWorkflow } from "./workflows/second-workflow/second-workflow-workflow";
+import { firstWorkflow } from "./first-workflow/first-workflow-workflow";
+import { secondWorkflow } from "./second-workflow/second-workflow-workflow";
 
 export default function myWorkflowPackageExtension(pi: ExtensionAPI): void {
-  registerWorkflow(firstWorkflow);
-  registerWorkflow(secondWorkflow);
+  registerWorkflows([firstWorkflow, secondWorkflow]);
   setupWorkflower(pi);
 }
 ```
 
 Use `setupWorkflower(pi)` in workflow packages so installing the workflow package also initializes Workflower's `/wf`, `/wf:<id>`, and `/next` commands.
 
-Workflow-level `model` and `thinkingLevel` set defaults for every step. Step-level `model` and `thinkingLevel` override those defaults for only that step; the next step falls back to the workflow settings, then the model and thinking level that were active when the garden started. `model` accepts a level name (`tiny`, `small`, `medium`, `large`, `xl`), a `provider/model-id` string, or an ordered fallback array of `provider/model-id` strings. Level names resolve against the user's `/wf config` model-level mapping (`.workflower/config.json`); do not assume a level name resolves to a specific model.
+Set `model` and `thinkingLevel` deliberately — do not leave every workflow on Workflower's start-of-garden defaults. Set workflow-level `model`/`thinkingLevel` as the default for every step, then override per step to match that step's actual cost: a cheap router-only step (see "Step archetypes" below) can drop to a low/minimal thinking level, while the one step doing real authoring or review work should get the workflow's best model and a higher thinking level. Step-level `model` and `thinkingLevel` override the workflow default for only that step; the next step falls back to the workflow settings, then the model and thinking level that were active when the garden started. `model` accepts a level name (`tiny`, `small`, `medium`, `large`, `xl`), a `provider/model-id` string, or an ordered fallback array of `provider/model-id` strings. Level names resolve against the user's `/wf config` model-level mapping (`.workflower/config.json`); do not assume a level name resolves to a specific model.
+
+`WorkflowDefinition` and `WorkflowStep` are fully documented in `@supierior/workflower`'s type declarations, including which fields are optional and each field's default — treat the installed package's `.d.ts` as the source of truth for current optional/required fields and defaults, and re-check it if this skill's guidance and the type declarations ever disagree.
 
 Workflow-level `autoNext?: boolean` sets the default for steps that omit their own `autoNext`; it defaults to `false`. Step-level `autoNext` overrides it for that step only.
 
@@ -190,7 +204,7 @@ await wf.handoff(nextWorkflow);
 
 ## Custom private step commands
 
-Use `registerWorkflowerCommand` when a step's `command` should expand to generated, per-invocation prompt content instead of a static skill body, for example injecting the current garden state or a computed file list into the kickoff prompt. Register once at extension startup, next to `registerWorkflow`:
+Use `registerWorkflowerCommand` when a step's `command` should expand to generated, per-invocation prompt content instead of a static skill body, for example injecting the current garden state or a computed file list into the kickoff prompt. Register once at extension startup, next to `registerWorkflows`:
 
 ```ts
 import { registerWorkflowerCommand } from "@supierior/workflower";
@@ -206,6 +220,16 @@ registerWorkflowerCommand({
 
 Reference it from a step as `command: "/my-workflow-review-brief"`. Prefer a bundled skill (`/skill:<name>`) for static, hand-written step instructions; reach for `registerWorkflowerCommand` only when the prompt content must be computed at step-start time.
 
+## Step archetypes
+
+Most steps are one of three shapes. Recognizing which one a step is decides whether it needs a skill, `outputs`, `autoNext`, or none of those:
+
+- **Skill step** — does the actual work. `command: "/skill:<name>"`, declares `outputs` when it writes files, usually `autoNext: true` unless a human should review the result before continuing.
+- **Router step** — pure deterministic branching, no skill. `command: "/<package-id>-route <route-name>"` hitting the single shared router command (see "Architecture guidance" above), never declares `outputs`, always `autoNext: true` and `clearOnNext: true` since it only reads/writes garden state and hands off. Give it a step id starting with `route-`.
+- **Human-pause step** — waits for a person to reply before continuing, no skill required if the prompt is simple. No `autoNext`, and usually `clearOnNext: false` so the question and the eventual answer stay in the same visible context. This differs from a router step's missing `autoNext`: a router step still moves on its own by calling `workflower_handoff`, a human-pause step genuinely stops until the user responds.
+
+A bounded review loop composes a skill step (implement/improve), another skill step (review, writes a `review.score` state key), and a router step (reads the score, either hands off forward on pass or hands back to the first skill step with an incremented attempt counter). Cap the attempt counter with a constant; once exceeded, the router step's prompt should tell the model to stop and ask the user to intervene rather than handing off again.
+
 ## Compact kickoff prompt display
 
 Current Workflower shows generated workflow kickoff prompts compactly in chat. A user may see only a label such as `Workflow: my-workflow — demo-garden` or `Step: first-step` instead of the whole generated prompt.
@@ -219,7 +243,7 @@ Teach junior workflow authors these rules:
 
 ## Step skill template
 
-`src/workflows/my-workflow/skills/my-first-step/SKILL.md`:
+`src/my-workflow/skills/my-first-step/SKILL.md`:
 
 ```markdown
 ---
@@ -245,6 +269,29 @@ Describe the concrete outcome of this step.
 5. Tell the user what was written and, unless this step has `autoNext: true`, tell them to inspect the output and run `/next` when ready.
 ```
 
+## Minimal workflow example
+
+Not every workflow needs `outputs` or `pollen`. A workflow with no file artifacts at all is valid — for example a two-step counter that only reads and writes garden state:
+
+```ts
+export const counterWorkflow: WorkflowDefinition = {
+  id: "counter",
+  model: "medium",
+  thinkingLevel: "low",
+  steps: [
+    { id: "initialize-counter", command: "/skill:counter-init", clearOnNext: true },
+    {
+      id: "start-counter-loop",
+      command: "/skill:counter-start-loop",
+      autoNext: true,
+      clearOnNext: true,
+    },
+  ],
+};
+```
+
+Don't add `outputs`, `pollen`, or lifecycle overrides a workflow doesn't need just to match a bigger template.
+
 ## package.json requirements
 
 A workflow package should include:
@@ -260,7 +307,7 @@ A workflow package should include:
   },
   "pi": {
     "extensions": ["./dist/index.mjs"],
-    "skills": ["./src/workflows/*/skills"]
+    "skills": ["./src/*/skills"]
   }
 }
 ```
@@ -316,12 +363,17 @@ Cleanup waits until the whole garden completes. Handoffs preserve earlier flower
 
 Before finishing:
 
-- Each workflow lives in its own `src/workflows/<workflow-id>/` folder alongside its bundled skills and scripts.
-- The workflow is registered exactly once, in `src/index.ts`, during extension startup.
+- Each workflow lives in its own `src/<workflow-id>/` folder alongside its bundled skills and scripts (nested under `src/workflows/<workflow-id>/` only if the package needs that extra layer — see "Minimal workflow package shape").
+- Every workflow is registered in one `registerWorkflows([...])` call in `src/index.ts`, during extension startup, with no hand-rolled "already registered" guard.
 - The package initializes Workflower with `setupWorkflower(pi)`.
 - Every `/skill:<name>` command has a matching bundled skill under its workflow's `skills/` folder.
-- Skill instructions and workflow `outputs` agree.
+- Skill instructions and workflow `outputs` agree; steps that don't write files (router steps, state-only review steps) correctly omit `outputs` rather than declaring an empty or fake one.
 - The package manifest loads both extension and skills.
+- Every workflow-level and step-level field set on a `WorkflowDefinition` differs from that field's documented default; fields left at their default are omitted rather than restated (check `@supierior/workflower`'s type declarations for current defaults).
+- `model` and `thinkingLevel` are set deliberately at the workflow level and tuned per step (higher for the step doing real authoring/review work, lower for router-only steps), not left unset by default.
+- `cleanupOnCompletion: false` is only used when the workflow's outputs are a genuine user-facing deliverable meant to survive after the garden completes — not left over from debugging, and not set merely to make artifacts easier to inspect while iterating.
+- A package with more than one loop-back branch shares a single `registerWorkflowerCommand` router named `<package-id>-route`, rather than one command per branch; router steps have no skill, no `outputs`, and always `autoNext: true` + `clearOnNext: true`.
+- If several public workflows share a private loop chain (a full entry and a shortcut entry, for example), that composability is intentional and documented, not accidental duplication.
 - The README includes a copy-paste smoke test using `/wf:<workflow-id> <garden-name>`.
 - The README and bundled skills explain active handoff with `/wf:<next-workflow-id>` when relevant.
 - The README or workflow usage notes explain compact prompt display and warn authors not to verify private skill injection by visible transcript content alone.