pi-prompt-composer

Build multi-option slash commands from plain prompts — variable expansion, arg collection & interactive selectors for Pi.

Turn a directory of .md prompt files into a single /command with Tab-completable subcommands, a rich interactive selector, and automatic missing-argument collection.

Quick start

# Install
pi install pi-prompt-composer

# Copy the bundled examples into your project prompt root
mkdir -p .pi/prompts/review
cp -r $(pi resolve pi-prompt-composer)/examples/prompts/review/* .pi/prompts/review/

# Reload Pi, then try:
#   /review           → interactive selector
#   /review summary   → asks for missing "change" arg, then sends
#   /review fix "bug" → dispatches immediately

How it works

A folder with an _index.md (containing type: group) becomes a grouped command. Every other .md file in that folder becomes a subcommand.

.pi/prompts/
├── workspace.md              ← flat Pi prompt, unchanged
├── review/
│   ├── _index.md             ← type: group  →  /review
│   ├── summary.md            ←                  /review summary
│   └── fix.md                ←                  /review fix

Both prompt roots are scanned:

• User: ~/.pi/agent/prompts/
• Project: <project>/.pi/prompts/

Flat .md files outside group directories continue to work as native Pi prompts.

Features

Feature	Behavior
Direct dispatch	/review fix "the bug" → substitutes args, sends immediately
Bare-command selector	/review → rich TUI selector with aligned descriptions and dynamic usage hints
Missing-arg collection	Prompts with required args metadata pause and ask before sending
Autocomplete	Tab after /review shows subcommand names with descriptions
Unknown subcommand	Typos show a warning with available alternatives
Escape syntax	\$ARGUMENTS renders as literal $ARGUMENTS
Discovery warnings	Malformed metadata surfaces as Pi notifications on session start
Bundled /compose	Built-in helpers for creating, extending, and simplifying grouped prompts
Authoring skill	Comprehensive compose-grouped-prompts skill loaded on demand for deep guidance

Bundled /compose command

The package ships a built-in /compose grouped command for authoring grouped prompts:

Command	Purpose
/compose	Interactive selector for compose operations
/compose new <group-name>	Create a new grouped prompt set
/compose add <group-name>	Add subcommands to an existing group
/compose remove <group-name>	Remove or simplify a subcommand

The bundled /compose is loaded with lowest precedence. If you create your own compose/ group in user or project prompts, it overrides the built-in version.

Required tools

The /compose prompts work best with pi-ask-user installed — it provides the ask_user tool for interactive decision handshakes during prompt authoring. If required tools are missing, a persistent warning banner appears at session start:

 Missing tools: ask_user — run pi install pi-ask-user

Authoring skill

The package also ships a compose-grouped-prompts skill with:

• Workflow guidance for creating, adding, and removing prompts
• Layout conventions and naming rules
• Frontmatter and args reference
• Realistic examples and anti-patterns

The skill is loaded on demand when the model needs deeper guidance beyond what the /compose prompts provide.

Writing prompts

_index.md (required)

---
type: group
description: Review workflows
order: [summary, fix]
---

type: group is the hard gate — directories without it are ignored.

order is optional — controls subcommand display order in autocomplete and the selector. Listed names appear first in the given order; unlisted subcommands are appended alphabetically. Omit for default alphabetical ordering.

Nested prompt files

---
description: Summarize a change
args:
  - name: change
    required: true
    hint: What changed?
  - name: context
    required: false
    hint: Additional context
---
Summarize the following change:
$ARGUMENTS

Argument syntax is Pi-native: $1, $2, $@, $ARGUMENTS, ${@:N}, ${@:N:L}.

Use \$ to escape a literal dollar sign (e.g., \$ARGUMENTS renders as $ARGUMENTS).

args metadata

Each item needs:

Field	Required	Default	Notes
name	yes	—	Items without name are skipped with a warning
required	no	false	Whether the extension asks for this arg when missing
hint	no	""	Shown in the input prompt and selector usage hint

Parsing is lenient — a missing hint or required won't break the prompt. Only a missing name drops that individual arg item.

What this package owns vs Pi-native

Concern	Owned by
Frontmatter parsing, arg syntax, substitution	Pi (reused)
Folder → command grouping, selector, arg collection	pi-prompt-composer
Flat .md prompt behavior	Pi (unchanged)
Command precedence (grouped wins over flat)	Pi (extension commands take precedence)

Known limitations

See docs/ISSUES.md for tracked defects and status.

Non-goals (this version)

• No shell substitution or preprocessing
• No nesting deeper than /group subcommand
• No aliases or dynamic subcommands

Development

bun install
bun run typecheck && bun run lint && bun run test

Autofix: bun run fix · Watch: bun run test:watch

Related packages

Package	Description
@victor-software-house/pi-openai-proxy	OpenAI-compatible HTTP proxy for Pi's multi-provider model registry

License

MIT