Skip to content

Product Book Workflows

Grzegorz Nowak edited this page Oct 12, 2026 · 7 revisions

Workflows — Repeat the Procedure, Not the Steering

Part of the Product Book. Observable product behaviour at pi-schematic @ 36bd569 (main, 2026-10-12).

A workflow is a reusable procedure saved for Pi, the coding-agent environment in which pi-schematic runs. Instead of restating the same instructions and settings in a conversation, a team can keep them with a prompt or skill and invoke them by name. The procedure can accept one supplied argument, while its frontmatter—the metadata at the top of its file—can attach model-selection, thinking, and readonly policy to that invocation.

1. A procedure that can be named and reused

A project can save a prompt at .pi/prompts/<name>.md and run it with /<name>. A skill uses the distinct /skill:<name> form. These are saved procedures: their body contains the repeatable instruction, while a named Model Group can hold the replaceable choice of model. For example, a project might run /review parser refactor; the prompt can use $@ wherever it needs the supplied parser refactor argument.

The file can give the procedure a human-facing description and an argument-hint, which declares the expected shape of that argument. $@ expands to the text supplied after the slash command, so the same procedure can be applied to different subjects.

Prompt-frontmatter lookup has defined boundaries. pi-schematic checks the trusted project directory cwd/.pi/prompts/ before ~/.pi/agent/prompts/; an untrusted project does not contribute its directory. A resolved prompt command takes precedence over same-named files in either standard directory. Conversely, an ordinary built-in slash command does not inherit policy merely because a same-named prompt file exists.

2. Frontmatter separates procedure from operating policy

Frontmatter is the small metadata block that can accompany a saved prompt or skill. readonly accepts only true or false: true turns on the session's readonly posture for the resolved workflow, while false turns it off. Readonly is not a statement in the procedure's prose; once active, pi-schematic enforces the posture at the tool boundary.

The same metadata can choose a model or a Model Group. model has the form <provider>/<model-id> and selects a configured, authenticated model. Only its first slash divides provider from model ID, so a model ID may itself contain slashes. model-group accepts a non-empty group name and, when there is no explicit model, routes the command through that named group. When both are present, the explicit model wins and the interactive interface warns that it overrode the group.

A workflow can also set thinking to off, minimal, low, medium, high, xhigh, or max. That value overrides a Model Group's thinking level, and pi-schematic clamps it to the selected model's capabilities. A workflow that specifies only thinking changes the current model's thinking level rather than switching models. Once frontmatter model or thinking changes succeed, they remain in effect for later commands.

3. Policy resolves at a particular moment

In the interactive terminal interface (TUI), pi-schematic resolves model, model-group, and thinking while idle input is being handled, before it expands the slash command. It postpones readonly to before_agent_start, where complete skill metadata is available. This split means pi-schematic decides a workflow's model policy before its procedure expands, while it applies readonly at the later lifecycle point intended for that metadata.

The same automatic policy is not applied everywhere. Headless and RPC invocations ignore saved-workflow model-selection policy and readonly policy. They therefore do not gain these settings merely from the workflow frontmatter. Policy lookup also applies only to the first token of a slash command: embedded text such as /review/typo does not select the /review workflow's policy.

The policy has a separate rule for an active exchange. During a streaming steer or follow-up, pi-schematic blocks a command carrying model, model-group, or thinking with a warning that it requires an idle agent. It blocks a command carrying readonly in the same circumstance. A streaming command without either model-selection or readonly frontmatter continues, rather than being stopped by this policy. A successful readonly workflow remains a session posture because its restrictions are enforced where tools are called.

4. Warnings preserve the current session when policy cannot apply

Not every frontmatter problem has the same result. pi-schematic ignores an invalid readonly, model-group, model, or thinking value and produces a TUI warning naming both the field and its source file; it likewise ignores malformed frontmatter or an unreadable workflow file with a warning. In particular, invalid thinking does not prevent an otherwise valid explicit model from applying: the invalid thinking value is warned about and left unapplied.

By contrast, an explicit model that is unknown, unauthenticated, unavailable, or cannot be switched to blocks command expansion and displays an error. An unknown or unusable Model Group does the same. A failed model change leaves the current model and thinking level unchanged and records no successful model, group, or thinking selection. The streaming block has that same non-mutating character: it leaves model and thinking unchanged and records no successful selection entry.

Within this reviewed workflow-frontmatter scope, the baseline identifies no additional known gaps. The appendix keeps the atomic behaviour rows stable for later comparison; they are the detailed contracts behind the narrative above.

Appendix — baseline behaviour rows

PB-WORKFLOW-01 … 39 — 39 atomic behaviour rows

1. Saved procedures and invocation

ID Behaviour Evidence
PB-WORKFLOW-01 A project can store a reusable prompt as .pi/prompts/<name>.md and invoke it as /<name>. README.md:48-60
PB-WORKFLOW-02 Prompt-frontmatter fallback checks trusted cwd/.pi/prompts/ before ~/.pi/agent/prompts/. frontmatter-cache.ts:255-292
PB-WORKFLOW-03 A resolved prompt command takes precedence over same-named prompt files in either standard prompt directory. frontmatter-cache.ts:261-279
PB-WORKFLOW-04 A project prompt directory is considered only when the project is trusted. frontmatter-cache.ts:286-288
PB-WORKFLOW-05 A skill is invoked with /skill:<name>, while a prompt command is invoked with /<name>. index.ts:171-183
PB-WORKFLOW-06 Built-in, non-prompt slash commands do not acquire saved-prompt frontmatter policy from a same-named file. index.ts:623-625
PB-WORKFLOW-07 description supplies the human-facing description of a saved workflow. README.md:50-55
PB-WORKFLOW-08 argument-hint declares the expected argument shape presented for a saved workflow. README.md:51-55
PB-WORKFLOW-09 $@ in a workflow body expands to the argument supplied after its slash command. README.md:58-60, README.md:114-114
PB-WORKFLOW-10 A saved workflow owns the repeatable procedure; a named Model Group owns the replaceable model choice. README.md:108-114

2. Frontmatter policy contract

ID Behaviour Evidence
PB-WORKFLOW-11 readonly accepts only the boolean values true and false. frontmatter-cache.ts:96-115
PB-WORKFLOW-12 readonly: true enables the session’s readonly posture when the invoked workflow is resolved. index.ts:240-262
PB-WORKFLOW-13 readonly: false disables the session’s readonly posture when the invoked workflow is resolved. index.ts:240-262
PB-WORKFLOW-14 model-group accepts a non-empty group name. frontmatter-cache.ts:96-115
PB-WORKFLOW-15 model accepts <provider>/<model-id>; only the first slash separates provider from model ID, so model IDs may themselves contain slashes. frontmatter-cache.ts:51-59
PB-WORKFLOW-16 thinking accepts off, minimal, low, medium, high, xhigh, or max. frontmatter-cache.ts:49-49, frontmatter-cache.ts:61-65
PB-WORKFLOW-17 A valid model selects that configured, authenticated model for the command. index.ts:272-289, index.ts:314-332
PB-WORKFLOW-18 An explicit model takes precedence over model-group; the TUI warns that the group was overridden. index.ts:314-332
PB-WORKFLOW-19 model-group routes the command through the named Model Group when no explicit model is supplied. index.ts:382-402
PB-WORKFLOW-20 A frontmatter thinking value overrides the Model Group’s thinking level. index.ts:364-376
PB-WORKFLOW-21 A frontmatter thinking value is clamped to the selected model’s capabilities. index.ts:326-329, index.ts:371-372
PB-WORKFLOW-22 thinking alone changes the current model’s thinking level without switching models. index.ts:405-417
PB-WORKFLOW-23 Successful frontmatter model and thinking changes remain in effect for later commands. README.md:143-143

3. Resolution timing and enforcement

ID Behaviour Evidence
PB-WORKFLOW-24 In the interactive TUI, model, model-group, and thinking resolve during idle input, before slash-command expansion. index.ts:613-644
PB-WORKFLOW-25 readonly resolution is deferred to before_agent_start, where complete skill metadata is available. index.ts:746-752
PB-WORKFLOW-26 Headless/RPC invocation ignores saved-workflow model-selection policy. index.ts:613-616
PB-WORKFLOW-27 Headless/RPC invocation also ignores saved-workflow readonly policy. index.ts:210-213
PB-WORKFLOW-28 During a streaming steer or follow-up, a command with model, model-group, or thinking frontmatter is blocked with a warning that it requires an idle agent. index.ts:419-431
PB-WORKFLOW-29 During a streaming steer or follow-up, a command with readonly frontmatter is blocked with a warning that it requires an idle agent. index.ts:426-430
PB-WORKFLOW-30 A streaming command without model-selection or readonly frontmatter continues rather than being blocked by this policy. index.ts:419-431
PB-WORKFLOW-31 Readonly posture is enforced at the tool boundary after a workflow activates it. index.ts:570-606

4. Visible failures and invalid policy

ID Behaviour Evidence
PB-WORKFLOW-32 An unknown, unauthenticated, unavailable, or failed-to-switch explicit model blocks command expansion and displays an error. index.ts:272-289, index.ts:314-329
PB-WORKFLOW-33 An unknown or unusable Model Group blocks command expansion and displays an error. index.ts:382-402
PB-WORKFLOW-34 A failed model switch records no successful model/group/thinking change entry. tests/unit/model-group-frontmatter.test.ts:949-968
PB-WORKFLOW-35 An invalid readonly, model-group, model, or thinking value is ignored and produces a TUI warning that identifies the field and source file. frontmatter-cache.ts:198-216, index.ts:185-195
PB-WORKFLOW-36 Malformed frontmatter or an unreadable workflow file is ignored with a TUI warning. frontmatter-cache.ts:198-216
PB-WORKFLOW-37 Invalid thinking does not prevent an otherwise valid explicit model from being applied; the invalid thinking value is warned and not applied. tests/unit/model-group-frontmatter.test.ts:477-508
PB-WORKFLOW-38 A failed model change leaves the current model and thinking level unchanged. index.ts:291-301, index.ts:326-329, index.ts:371-376
PB-WORKFLOW-39 A streaming model-selection block leaves model and thinking unchanged and records no successful selection entry. index.ts:419-431, tests/unit/model-group-frontmatter.test.ts:895-912

Clone this wiki locally