# @supierior/workflower-authoring Standalone Pi skill package for creating Workflower workflow packages. Install this package when you want to ask Pi to scaffold or modify a workflow package. It does not load the Workflower runtime extension itself; generated workflow packages should depend on `@supierior/workflower` and initialize it from their extension entrypoint. ## Skill ```text /skill:workflower-authoring create a workflow for ``` 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` with `registerWorkflows([...])`; - organize generated TypeScript workflow packages with a small `src/index.ts` entrypoint and one `src//` folder per workflow, holding that workflow's definition, bundled skills, and scripts together (nesting under `src/workflows//` 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//0001-/` and each flower's `index.json`; - 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 `-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: `, optional active handoff with `/wf:`, `/next`, and the `/wf` management subcommands (`status`, `stop`, `list`, `clean`, `state`, `resume`, `config`). ## Why standalone? Authoring workflows and running workflows are separate concerns: - `@supierior/workflower-authoring` teaches Pi how to create workflow packages. - `@supierior/workflower` provides the runtime commands and workflow state handling. - Generated workflow packages can depend on `@supierior/workflower` internally so users install only the workflow package they intend to run. The authoring guidance follows the repository architecture notes for AI-navigable package structure without adding unnecessary folders to this small Markdown-only skill package. ## Runtime model taught by this package Generated guidance should align with Workflower's garden/flower model: - Workflow ids must be folder-safe (`^[a-z0-9_-]+$`) because ids become `/wf:` commands and flower folder names. - Start a fresh garden with `/wf: `. - While a workflow is active, hand off to another workflow in the same garden with `/wf:` and no garden name. - Artifacts live in flower folders such as `.workflower/workflows//0001-/`; 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//` 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:` 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. When a package has more than one deterministic branch, register a single router command named `-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 `, `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.