@gtrabanco/pi-agentic-workflow

One install of the agentic-workflow method into Pi: the canonical skills, a friendly slash command for each of them, and optional per-command model routing that gives your session back afterwards.

• Canonical skills, unchanged. The package ships the same SKILL.md files as this repository, byte for byte — no Pi-specific fork to drift.
• Friendly commands. Type /unit-lane <slug>, not /skill:unit-lane <slug>.
• Routing you can forget about. Nothing is configured by default: every command runs on the model you already have.

Install

pi install npm:@gtrabanco/pi-agentic-workflow

Restart Pi. /agentic-workflow-settings and the workflow commands are then available in any project. If you previously copied the skills into ~/.pi/agent/skills by hand, delete that copy — the package provides them, and two copies means two versions of the same method.

Commands

Every bundled skill whose frontmatter says user-invocable: true gets a command with the same name. The list is read from the skills at startup, so adding a skill adds its command — there is no alias table to keep in sync. Internal skills that a user-facing skill composes (the review passes, the planning preflight, the envelope contract) ship inside the package but get no command of their own — they are composed by the ones above:

Arguments are forwarded verbatim: /execute-phase P3 --fix reaches the skill as P3 --fix.

Model routing

Two JSON files, both optional:

{
  "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" },
  "commands": {
    "plan-feature": { "model": ["anthropic/claude-sonnet-4-5", "openai/gpt-5.2"], "thinking": "medium" },
    "review-change": { "thinking": "max" }
  },
  "onUnavailableRoute": "stop",
  "onSettle": "keep"
}

A value is taken from the first place that declares it: project command → global command → resolved default route → shipped default. review-change above runs on the default model with max thinking; anything else runs on whatever the session already had, because the shipped default route is {"model": "inherit", "thinking": "inherit"}.

• model can be provider/modelId — the exact reference /model shows — "inherit", or an ordered array of 1–4 references (a fallback chain). For a chain, dispatch probes each reference in order and applies the first one that resolves and has credentials, without touching the session while probing; when every entry is unusable the command stops (or, with onUnavailableRoute inherit, warns and runs on the current model), naming each candidate and why it was skipped. plan-feature above tries anthropic/claude-sonnet-4-5 first, then openai/gpt-5.2.
• thinking is one of off, minimal, low, medium, high, xhigh, max, or "inherit".
• `onSettle` is one of "keep" (the default) or "restore" — see Your session after a command.
• Unknown keys, nulls and malformed references are rejected, not ignored: a typo that silently did nothing is the bug you would never find.

The first workflow command you run after install says once that routing is configurable, then never again. That acknowledgement is stored in ~/.pi/agent/pi-agentic-workflow-state.json, not in your config.

Model profiles

The routing config above is the default profile. A profile is one coherent set of routes, and you can define as many as you like under profiles:

{
  "recommendedModels": true,
  "profileOrder": ["work", "cheap"],
  "profileFallback": { "applyTo": "flow", "resume": "continue", "retryAfterSeconds": 86400 },
  "profiles": {
    "work": { "default": { "model": "anthropic/claude-opus-4-5", "thinking": "high" } },
    "cheap": { "default": { "model": "openai/gpt-5.2", "thinking": "medium" } }
  },
  "default": { "model": "inherit", "thinking": "inherit" },
  "commands": { "review-change": { "thinking": "max" } }
}

• profileOrder — the preference chain, first = most preferred/active. For each command the router probes the profiles in order and the first whose model is usable serves it; when the preferred profile's model is unavailable it falls through to the next. A profile participates only for keys it actually declares.
• profiles — unlimited named profiles. The implicit default profile is the top-level default + commands above, so a config with just those two keys resolves exactly as before.
• Built-in nan profile. With recommendedModels: true (the default), when the session has models from the nan provider, a code-only nan profile is appended to the end of the chain (or used alone when you set no profileOrder). It carries the per-command ladders from the README's NaN section. Any route you declare — including an explicit "inherit" — wins over it. Set recommendedModels: false to switch it off; the settings console writes the key explicitly on save when the provider is available.
• profileFallback — what happens when the preferred profile's model is unusable:
  • applyTo: "flow" (default) records the switch so later commands keep using the fallback profile; "command" falls back for this command only and the next command retries the preferred profile.
  • resume: "continue" (default) lets the in-flight stage run on the fallback profile; "restart" makes the advance conductor defer the switch and re-run the stage under the fallback profile instead.
  • retryAfterSeconds: how long a flow demotion lasts before the preferred profile is probed again (default 86400, one day).
• Rotation. /agentic-workflow-settings is scope → profile → routes: pick the scope, pick the profile to edit, then edit its routes. Rotate the active profile moves a profile to the front of profileOrder and clears any recorded demotion. The built-in nan profile is shown but not editable — create a profile to override it.

Path protection (optional)

The Tier 2 preventive guard blocks a write / edit tool call to an existing protected path with no matching justification record. Its policy is the shipped path-protection-policy@1 default, tightened by an optional pathProtection key in the same config files:

{
  "pathProtection": {
    "protectedGlobs": ["secrets/**"],
    "requirements": { "post-freeze": { "modify": "approval" } }
  }
}

The override is tighten-only: protectedGlobs are unioned with the shipped globs, and each requirements entry takes the stricter of the two — so a removal or a lowering is ignored (the shipped protection stays in force) and reported once per session as a pi-agentic-workflow: path protection — <code>: <detail> notification. requirements is keyed by phase state (pre-freeze, post-freeze, always) and operation (create, modify, delete, rename), with values none < justification < approval. To allow a protected edit, record the matching path-protection-records@1 justification row in the unit's decisions.md.

When a configured model is unavailable

Default: the command refuses to start and tells you why — the model is not in the registry, has no credentials, or could not be selected. Nothing is sent, so nothing runs on a model you did not pick. To run anyway on the current model, set:

{ "onUnavailableRoute": "inherit" }

Your session after a command

By default (onSettle: "keep"), the routed model and thinking level stay in the open chat window once the command settles. If plan-feature runs on glm-5 and you want to tweak the plan it produced, your next prompt keeps running on glm-5 — same for a follow-up question. When you don't need the heavy model, switch it yourself with /model (or Ctrl+P) to something cheaper; nothing restores over your choice.

To bring back the pre-command model and thinking level after a command settles, set:

{ "onSettle": "restore" }

(The restore mode is the historical AC8 contract: after a routed command the session is put back the way you had it — the model and the thinking level, because selecting a model can move the level. If you change the model yourself mid-turn, with /model say, nothing is restored: your choice wins, and the command says so. Change only the thinking level and you keep it while the model still comes back.)

Settings console

/agentic-workflow-settings

/aw-settings is a shorthand for the same console.

Shows what each command runs on right now, and which file is refusing to parse, then lets you edit one file at a time and save to global or project scope. It will not save over a file it cannot parse, and it will not touch the project file while the project is untrusted.

The console's model and thinking pickers are searchable and windowed: typing narrows the list, the cursor stays on screen, a position indicator shows where you are, and the value currently in force is pre-selected and labelled (current) / (default route). A route edit asks which field to change (model, thinking), so a no-change save leaves the file byte-identical; the model field can build an ordered fallback chain (a/m1 → b/m2); and one pass can apply or clear a route across several commands, warning per command when a reference is missing from the live registry. Outside a TUI session the pickers fall back to a plain prompt, so the console never dead-ends. Lists longer than 24 options never reach a single dialog either: over the cap the model picker asks for the provider first, and an overlong provider or model list pages (More options… / ◀ Previous page) instead of crashing the host's select dialog.

Troubleshooting

Notes

• Verified against Pi 0.85.1 (2026-09-05) (pi install, package skills, friendly command registration, routed set/clear, settings console round-trip, sendUserMessage with prompt template expansion).
• The package declares Pi as a peer dependency; it bundles no copy of Pi.
• Skills can instruct the model to run commands. Review them as you would any third-party package.

MIT · Repository · docs/features/27-pi-agentic-workflow/