Repository navigation
Product Book Workflows
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.
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.
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.
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.
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.
PB-WORKFLOW-01 … 39 — 39 atomic behaviour rows
| 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 |
| 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 |
| 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 |
| 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
|