@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

/skill:workflower-authoring create a workflow for <goal>

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/<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) 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).

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:<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/<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. 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 <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.