@supierior/workflower-authoring 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @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 <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`;
+- 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;
+- 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;
+- 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/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.
+- 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 `pollen` and `acceptPollen` to control which output paths are referenced during handoff.
+- 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 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

@@ -0,0 +1,30 @@
+{
+  "name": "@supierior/workflower-authoring",
+  "version": "0.1.0",
+  "description": "Pi skill package for creating Workflower workflow packages.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "skill",
+    "workflow",
+    "workflower",
+    "authoring"
+  ],
+  "license": "Apache-2.0",
+  "files": [
+    "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"
+  }
+}

package/skills/workflower-authoring/SKILL.md

@@ -0,0 +1,336 @@
+---
+name: workflower-authoring
+description: Creates or modifies Pi Workflower workflow packages, workflow definitions, and companion step skills. Use when a user asks Pi to create, scaffold, or update a Workflower workflow.
+allowed-tools: read write edit bash
+---
+
+# Workflower Authoring
+
+Use this skill when the user wants a Workflower workflow created or changed.
+
+This is a standalone authoring skill. The user does not need to install or run `@supierior/workflower` just to use this skill. Generated workflow packages should depend on `@supierior/workflower` internally and initialize it from their extension entrypoint, so workflow users can install the generated workflow package rather than manually installing Workflower first.
+
+Workflower runs garden-scoped multi-step workflows. Start the first flower with `/wf:<workflow-id> <garden-name>`, hand off to another workflow while active with `/wf:<next-workflow-id>`, and advance steps with `/next`. A workflow package usually registers a `WorkflowDefinition` from a Pi extension entrypoint and may ship companion skills used by each step.
+
+## First, clarify the workflow
+
+Ask only for missing information. Gather:
+
+1. Workflow id, for example `feature`, `github_issue`, or `release-notes`.
+2. Initial garden name example for README smoke tests, such as `demo-garden`.
+3. What the workflow should accomplish.
+4. Step list, including each step's purpose.
+5. Command for each step. Prefer `/skill:<skill-name>` when the step should be implemented by a bundled skill.
+6. Expected output files for each step, if any.
+7. Pollen behavior:
+   - 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`.
+   - keep context between specific steps? Set that step's `clearOnNext: false`.
+   - immediately advance after a step finishes? Set that step's `autoNext: true`.
+
+## Validate the design
+
+Before writing files:
+
+- Workflow ids must be folder-safe and match `^[a-z0-9_-]+$`: lowercase ASCII letters, digits, underscores, and hyphens only. Do not use colon-separated, uppercase, whitespace, slash, dot-segment, or quoted ids.
+- The initial garden name is provided by the user at runtime with `/wf:<workflow-id> <garden-name>` and becomes `.workflower/workflows/<garden-name>/`.
+- The first workflow execution creates a flower workdir like `.workflower/workflows/<garden-name>/0001-<workflow-id>/` and a flower index at `.workflower/workflows/<garden-name>/0001-<workflow-id>/index.json`.
+- While a workflow is active, hand off to another workflow with `/wf:<next-workflow-id>` and no garden name; Workflower creates the next flower in the same garden, such as `.workflower/workflows/<garden-name>/0002-<next-workflow-id>/`.
+- Step ids should be short, stable, lowercase kebab-case.
+- Step commands should exist or be created as bundled skills/commands.
+- Output paths should be relative file paths under the workflow workdir.
+- If a skill writes an output, its instructions must mention the exact output filename declared in the workflow definition.
+- If a skill reads a previous output, its instructions must read from the previous-step output path provided by the kickoff prompt.
+
+## Minimal workflow package shape
+
+For a new package, create this structure. In a monorepo it may live under `packages/<package-name>/`; in a standalone repo it can live at the repository root.
+
+```text
+<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
+├── package.json
+├── README.md
+├── tsconfig.json
+├── tsup.config.ts
+└── 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.
+
+## 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`.
+- 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.
+
+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/`.
+
+## Extension entrypoint templates
+
+`src/index.ts`:
+
+```ts
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import setupWorkflower, { registerWorkflow } from "@supierior/workflower";
+
+import { myWorkflow } from "./workflows/my-workflow/my-workflow-workflow";
+
+export { myWorkflow };
+
+export default function myWorkflowPackageExtension(pi: ExtensionAPI): void {
+  registerWorkflow(myWorkflow);
+  setupWorkflower(pi);
+}
+```
+
+`src/workflows/my-workflow/my-workflow-workflow.ts`:
+
+```ts
+import type { WorkflowDefinition } from "@supierior/workflower";
+
+export const myWorkflow: WorkflowDefinition = {
+  id: "my-workflow",
+  userInvocable: true,
+  modelInvocable: true,
+  cleanupOnCompletion: false,
+  model: ["openai-codex/gpt-5.3-codex-spark"],
+  thinkingLevel: "medium",
+  autoNext: false,
+  pollen: "second-step.md",
+  acceptPollen: true,
+  steps: [
+    {
+      id: "first-step",
+      command: "/skill:my-first-step",
+      outputs: ["first-step.md"],
+      thinkingLevel: "high",
+      clearOnNext: false,
+    },
+    {
+      id: "second-step",
+      command: "/skill:my-second-step",
+      outputs: ["second-step.md"],
+    },
+  ],
+};
+```
+
+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";
+
+export default function myWorkflowPackageExtension(pi: ExtensionAPI): void {
+  registerWorkflow(firstWorkflow);
+  registerWorkflow(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.
+
+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.
+
+Workflow-level `userInvocable?: boolean` (default `true`) controls whether Workflower registers `/wf:<id>` for users to start the workflow directly. Set `userInvocable: false` for workflows that should only be reached by handoff. Workflow-level `modelInvocable?: boolean` (default `true`) controls whether `workflower_handoff` may start this workflow; set `modelInvocable: false` to keep a workflow user-started only.
+
+Workflow-level `pollen?: string | string[]` pins the output path or paths that should be referenced when another workflow is started in the same garden. If omitted, completed step outputs become unpinned pollen as `/next` advances. Workflow-level `acceptPollen?: boolean` defaults to `true`; set `acceptPollen: false` when a workflow should not receive previous flower pollen paths in its kickoff prompt. Pollen paths are referenced from the previous flower's `index.json`; files are not copied into the new flower.
+
+## Garden state and deterministic routing
+
+Use Workflower garden state for small structured facts that must survive context-clearing boundaries or drive deterministic routing. State lives at `.workflower/workflows/<garden-name>/state.json`, is shared by all flowers in the garden, and is deleted on final garden completion. Use output files for large artifacts: do not use state for large reports, logs, diffs, or plans; write those as declared output files instead.
+
+When authoring workflows and companion skills:
+
+- Declare expected state keys in README and skill instructions, for example `review.rating`, `review.summary`, and `review.required_changes`.
+- Tell agents exactly when to call `workflower_state_set` and which JSON value shape to write.
+- Tell agents to use `workflower_state_get` when a later step depends on previously saved state.
+- Use `workflower_state_list` when an agent needs to discover which state keys are already set without guessing key names.
+- Use code/router commands or model-callable tools for deterministic branching, then call `createWorkflowerRuntime(pi, ctx).handoff(...)` or the `workflower_handoff` tool.
+- For autonomous branching, prefer a model-callable router tool. Do not rely on assistant text to invoke `/wf:<id>` or `/review-route`; printed slash commands are not executed by Pi.
+
+Example reviewer instruction:
+
+```markdown
+After writing `implementation-review.md`, call `workflower_state_set` three times:
+
+1. `{ "key": "review.rating", "value": <integer 1-5> }`
+2. `{ "key": "review.summary", "value": "<one-sentence summary>" }`
+3. `{ "key": "review.required_changes", "value": ["<change>"] }`
+```
+
+Example deterministic router:
+
+```ts
+const rating = await wf.state.getValue("review.rating");
+const nextWorkflow =
+  typeof rating === "number" && rating >= 4 ? "feature-next-steps" : "implementation-review-loop";
+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`:
+
+```ts
+import { registerWorkflowerCommand } from "@supierior/workflower";
+
+registerWorkflowerCommand({
+  name: "my-workflow-review-brief",
+  description: "Builds the review-step prompt from current garden state.",
+  handler: async (args, ctx) => {
+    return { kind: "prompt", content: `Review garden ${ctx.gardenName}, step ${ctx.stepId}.` };
+  },
+});
+```
+
+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.
+
+## 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.
+
+Teach junior workflow authors these rules:
+
+- The model still receives the full kickoff prompt, including workflow id, garden name, workdir, previous pollen paths, previous outputs, expected output paths, and expanded private skill instructions.
+- Private Workflower skills may be injected into model context even when their Markdown body is not visible in the transcript. Do not rely on visible transcript content to verify full private skill injection.
+- This is not a token-saving feature. Keep workflow prompts and private skills concise because the full prompt still uses context.
+- Assistant text that prints `/wf:<id>`, `/next`, or a router command does not execute that slash command. Autonomous workflow movement should call `workflower_handoff` or a deterministic model-callable router tool instead.
+
+## Step skill template
+
+`src/workflows/my-workflow/skills/my-first-step/SKILL.md`:
+
+```markdown
+---
+name: my-first-step
+description: Performs the first step of the my-workflow Workflower workflow and writes first-step.md.
+allowed-tools: read write edit bash
+---
+
+# My First Step
+
+You are step 1 of the `my-workflow` Workflower workflow.
+
+## Goal
+
+Describe the concrete outcome of this step.
+
+## Instructions
+
+1. Use the workflow kickoff prompt for the workflow id, garden name, active flower workdir, previous pollen paths, previous outputs, and expected output paths.
+2. Create the declared output file: `first-step.md`.
+3. Write the file at the absolute expected output path shown in the kickoff prompt. If no absolute path is visible, write it relative to the current working directory.
+4. If this step is expected to write garden state, call `workflower_state_set` with the exact documented key names and JSON-compatible values.
+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.
+```
+
+## package.json requirements
+
+A workflow package should include:
+
+```json
+{
+  "keywords": ["pi-package", "pi", "workflow", "workflower"],
+  "dependencies": {
+    "@supierior/workflower": "workspace:^"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": ["./dist/index.mjs"],
+    "skills": ["./src/workflows/*/skills"]
+  }
+}
+```
+
+`pi.skills` is a glob (Pi's array fields support glob patterns and `!exclusions`), so it picks up every workflow's `skills/` directory without listing each workflow by name. Skills are plain Markdown and load directly from `src/`; they do not need a build step or a `dist/` copy. Update the glob (or list workflow folders explicitly) only if a workflow intentionally ships no skills and an author wants tighter filtering.
+
+Use `workspace:^` for monorepo workflow packages so pnpm links the local workspace package during development and publishes the dependency as a compatible semver range such as `^0.1.0`. For published packages outside this monorepo, use a real `@supierior/workflower` version/range. Follow current Pi package dependency rules for the target distribution method; if publishing an npm Pi package that depends on another Pi package, consider adding `@supierior/workflower` to `bundledDependencies` so the generated package is self-contained for users.
+
+## README smoke test
+
+Document how to run the workflow from a fresh session:
+
+```text
+/wf:<workflow-id> <garden-name>
+```
+
+Then after each non-auto step:
+
+```text
+/next
+```
+
+If the README demonstrates chaining to another workflow while active, use the handoff form with no garden name:
+
+```text
+/wf:<next-workflow-id>
+```
+
+Also mention the built-in `/wf` management subcommands:
+
+```text
+/wf status
+/wf stop
+/wf list
+/wf clean <garden-name>
+/wf state list | get <key> | set <key> <json-value>
+/wf resume [garden-name]
+/wf config
+```
+
+`/wf clean` removes a garden's artifacts by hand (refuses while a workflow is still active in it). `/wf state` lets a user inspect or edit garden state without a running step. `/wf resume` restarts an interrupted garden from its durable resume metadata. `/wf config` opens an interactive editor for the model-level mapping (`tiny`/`small`/`medium`/`large`/`xl`), default model, and fallback strategy used to resolve level-name `model` settings.
+
+and where artifacts are written:
+
+```text
+.workflower/workflows/<garden-name>/0001-<workflow-id>/
+.workflower/workflows/<garden-name>/0001-<workflow-id>/index.json
+```
+
+Cleanup waits until the whole garden completes. Handoffs preserve earlier flowers so their pollen can be referenced by later workflows; final `/next` cleanup applies each flower's producing workflow `cleanupOnCompletion` setting.
+
+## Final checklist
+
+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.
+- 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.
+- The package manifest loads both extension and skills.
+- 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.
+- Artifact examples use `.workflower/workflows/<garden-name>/0001-<workflow-id>/` flower paths and mention `index.json`.
+- Workflow-level `pollen` and `acceptPollen` choices are documented when handoff behavior matters.
+- Expected garden state keys and `workflower_state_set` calls are documented when state drives later steps or routing.
+- Deterministic routers are implemented as commands/tools or extension code, not as printed slash-command text.
+- Cleanup timing is clear: flower artifacts are cleaned only after final garden completion, not during handoff; garden state is also deleted on final completion.
+- `userInvocable` / `modelInvocable` are set explicitly whenever a workflow should not be both user-startable and handoff-startable.
+- Level-name `model` settings (`tiny`/`small`/`medium`/`large`/`xl`) are only used when the README tells users they must configure `/wf config` first.
+- Any `registerWorkflowerCommand` step commands are registered once at extension startup and documented alongside the bundled skills.
+- Run package-local validation when practical: `pnpm test`, `pnpm typecheck`, `pnpm lint`, `pnpm build`.