pi-agents-workflow

Register .agents/workflows/*.md as pi slash commands that behave exactly like native prompt templates.

Each markdown file becomes a / command: /name args expands the file body with pi's native argument semantics and sends it as the user message in the current session — no subagent dispatch, no context switching. Built for workflow playbooks (PM orchestration rules, verification checklists, release procedures) that live in .agents/ next to your skills.

.agents/
├── skills/          ← pi reads these natively
└── workflows/       ← pi reads these once you install this package
    ├── deploy.md
    └── dev-agent-cycle.md

Install

pi install npm:pi-agents-workflow

Or try it without installing:

pi -e npm:pi-agents-workflow

Usage

Given .agents/workflows/deploy.md:

---
description: Deploy the stack to an environment
argument-hint: "<env>"
---
Deploy to ${1:-prod} with these extras: ${@:-none}.

Typing /deploy staging --fast in pi sends:

Deploy to staging with these extras: staging --fast.

($@ is all args joined — same as native templates.)

• /deploy — expand and send the workflow (autocomplete shows description + argument hint)
• /agents-workflows — list discovered workflows, scanned directories, and issues

Scopes

Scope	Directory	Notes
Project	<project>/.agents/workflows/*.md	wins on name clash
User	~/.agents/workflows/*.md	shared across projects

Discovery is non-recursive, matching native prompts/ behavior. Files added mid-session still work on submit (input-event fallback); they appear in autocomplete after /reload.

Workflow file format

Same as a native prompt template:

• Filename (minus .md) becomes the command name — use single-token names (dev-agent-cycle.md, not my flow.md)
• description — autocomplete text; falls back to the first non-empty body line
• argument-hint — shown in autocomplete as <hint> — description
• Body — the template, with full native argument substitution:
  • $1, $2, … positional args
  • $@ / $ARGUMENTS — all args joined
  • ${1:-default}, ${@:-default} — fallback values
  • ${@:N}, ${@:N:L} — arg slicing

Other frontmatter keys are ignored (forward compatible).

Notes

• Extension commands take precedence over same-named native templates in .pi/prompts/ — keep names distinct if you use both.
• Expansion happens once at submit; a body starting with / will not chain into another command.
• This package intentionally does not dispatch to subagents. If you want a workflow to run as a subagent task, pair it with pi-subagents via its own prompts directory instead.

Development

npm install
npm test             # node:test suite
npm run typecheck    # tsc --noEmit
pi -e .              # try it interactively

MIT License.