pi-prompt-composer

Build composer-owned slash commands from plain Markdown prompts — flat files, grouped menus, typed args, Liquid templating, and visible dispatch for Pi.

Turn .md files under composed/ into single slash commands, or turn directories into grouped commands with Tab-completable subcommands, a rich interactive selector, automatic missing-argument collection, and optional Liquid-powered rendering.

Quick start

# Install
pi install pi-prompt-composer

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

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

# Or create a single Liquid-powered command
cat > .pi/composed/ship.md <<'EOF'
---
description: Prepare a ship checklist
engine: liquid
args:
  - name: change
    required: true
    hint: What changed?
---
Prepare release checklist for {{ args.change | quote }}.
{% xml "checks" %}
- typecheck
- lint
- tests
- docs
{% endxml %}
EOF
#   /ship --change "composed prompt discovery"

How it works

Composer-owned prompts live under composed/ roots so Pi does not also load them as native flat prompts.

.pi/composed/
├── review.md                 ← /review
└── review/
    ├── _index.md             ← /review
    ├── summary.md            ← /review summary
    └── fix.md                ← /review fix

Composer roots:

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

Native Pi prompt roots (~/.pi/agent/prompts/*.md, .pi/prompts/*.md) stay native. Existing grouped prompts under prompts/<group>/ are migrated once into composed/<group>/ with a warning.

Features

| Feature | Behavior | |---------|----------| | Flat composer commands | .pi/composed/review.md → /review without creating a fake group | | Grouped commands | .pi/composed/review/summary.md → /review summary | | Liquid templating | engine: liquid unlocks if, for, where, map, join, structured XML blocks, JSON snippets, and command-batch rendering | | 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 | | Safe helpers | present, quote, tokens, json, shell_quote, and {% xml "tag" %} help build Claude Code skill-style prompts | | Escape syntax | \$ARGUMENTS renders as literal $ARGUMENTS in engine: pi prompts | | Discovery warnings | Malformed metadata and misplaced composer prompts surface 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 for groups)

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

No type: group marker is required. A subfolder under composed/ with _index.md is a group.

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.

Flat composer prompt files

---
description: Review a change
engine: liquid
args:
  - name: change
    required: true
    hint: Change, diff, file, or PR to review
  - name: focus
    required: false
    hint: Optional focus
---
Review {{ args.change | quote }}.

{% if args.focus | present %}
Focus on: {{ args.focus }}
{% endif %}

Save as .pi/composed/review.md, then run /review --change "auth fix" --focus security.

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 defaults to Pi-native: $1, $2, $@, $ARGUMENTS, ${@:N}, ${@:N:L}. Add engine: liquid to use named args ({{ args.change }}), conditionals, loops, and filters.

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.

Liquid helpers

Liquid prompts get { args, argv, arguments, variables, prompt, now } as their render context:

{{ args.change | quote }}
{{ args.items | where: "kind", "risk" | map: "name" | join: ", " }}
{{ args.metadata | json: 2 }}
{{ args.workdir | shell_quote }}
{% xml "task" %}{{ args.goal }}{% endxml %}

Static constants belong in frontmatter variables, not repeated body literals or body-level assign statements:

variables:
  repo_path: acme/app
  review_channel: dev-review

Repo: {{ variables.repo_path }}
Channel: {{ variables.review_channel }}

Use body-level assign for dynamic derived values only, such as args.key | upcase.

Prompt-local partials live beside the prompt in _partials/ and can be included with {% include "name.md" %}. Use them for repeated prompt prose or JSON/tool snippets.

Liquid also gets raw positional context for Pi-like rest behavior: argv is the positional array and arguments is every positional joined by spaces. For nicer frontmatter, mark the final arg rest: true with type: string[] to capture remaining positionals.

args:
  - name: group_name
    required: true
    hint: Group name
  - name: description
    required: false
    type: string[]
    rest: true
    hint: Freeform description

Description: {{ args.description | join: " " }}
Raw argv: {{ argv | join: ", " }}

Useful helpers:

| Helper | Purpose | |--------|---------| | present | True for non-empty strings/arrays | | quote | Trim and double-quote text | | tokens | Rough chars/4 estimate | | json | JSON stringify values, optionally pretty-printed | | shell_quote | Single-quote shell arguments for command text | | {% xml "tag" %} | Emit XML-style blocks only when rendered body is non-empty | | {% shell %}...{% endshell %} | Render a command and optionally execute it when shell frontmatter opts in |

Shell execution is deny-by-default:

| Frontmatter | Behavior | |-------------|----------| | omitted / shell: deny | Show command text; do not execute | | shell: ask | Confirm before execution; stdout replaces the block | | shell: allow | Execute without asking; trusted prompts only |

Configure the default in ~/.pi/agent/prompt-composer.json or project-local .pi/prompt-composer.json:

{
  "shell": { "mode": "ask", "timeoutMs": 30000 }
}

Prompt frontmatter wins over config.

Shell blocks run with bash -lc from the prompt file directory, so relative scripts work:

{% shell %}
python3 scripts/summarize.py --topic {{ args.topic | shell_quote }}
{% endshell %}

This is opt-in because shell can read files, call networks, mutate repos, or expose secrets. Quote user-controlled args with shell_quote. Validate prompt roots before live smoke:

pnpm run prompts:validate
mise run prompts:validate -- prompts ~/.pi/agent/composed/review

See docs/TEMPLATING.md and examples/templating/README.md.

Composer does not pretend to sandbox commands. Portable sandboxing is platform-specific; shell-enabled prompts are trusted code, matching Pi's normal shell trust model.

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 | | Native flat .md prompt behavior under prompts/ | Pi (unchanged) | | Composer flat .md prompt behavior under composed/ | pi-prompt-composer | | 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 default shell execution from templates; shell remains explicit opt-in
• No nesting deeper than /group subcommand
• No aliases or dynamic subcommands

Development

pnpm install
pnpm run typecheck && pnpm run lint && pnpm run test

Autofix: pnpm run fix · Watch: pnpm 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