type: message

role: user

type: text

text: can you create a couple of prompts: one for plan mode, review, explain


role: assistant

type: thinking

thinking:
The user is asking me to create a couple of prompts for plan mode, review, and explain. This seems to be related to pi agent prompts. I should look at the current working directory and understand the context better. They want prompts for different modes of the pi coding agent.

Let me first explore what's in the current directory to understand the project structure and what kind of prompts might be appropriate.

thinkingSignature: reasoning

text: I'll create a set of reusable prompts for plan, review, and explain modes. First, let me check the current project context to tailor them appropriately.

bash

type: toolCall

command: ls -la /home/liph/dotfiles/pi/.pi/agent

api: openai-completions

provider: ollama

stopReason: toolUse


role: toolResult

toolName: bash

text:
total 64
drwxr-xr-x 11 liph liph 4096 Jul 24 16:29 .
drwxr-xr-x  6 liph liph 4096 Jul 23 20:54 ..
drwxr-xr-x  2 liph liph 4096 Jul 24 08:04 agents
-rw-r--r--  1 liph liph  121 Jul 21 21:24 auth.json
drwxr-xr-x  2 liph liph 4096 Jul 23 20:51 chains
drwxr-xr-x  4 liph liph 4096 Jul 24 08:22 extensions
-rw-r--r--  1 liph liph 1345 Jul 22 12:50 models.json
drwxr-xr-x  3 liph liph 4096 Jul 21 21:26 npm
drwxr-xr-x  2 liph liph 4096 Jul 23 20:51 profiles
-rw-r--r--  1 liph liph 3120 Jul 24 10:29 run-history.jsonl
drwxr-xr-x 20 liph liph 4096 Jul 24 12:54 sessions
-rw-r--r--  1 liph liph 1452 Jul 24 16:28 settings.json
drwxr-xr-x  2 liph liph 4096 Jul 24 09:36 skills
drwxr-xr-x  2 liph liph 4096 Jul 23 20:34 state
drwxr-xr-x  2 liph liph 4096 Jul 24 08:34 themes
-rw-r--r--  1 liph liph   25 Jul 22 12:50 trust.json


thinking: This is the pi agent config directory. I should check the docs about prompt templates to understand how pi handles prompts. The system prompt says to read pi docs when working on pi topics. Let me read the prompt templates docs.


toolName: read

text:
> pi can create prompt templates. Ask it to build one for your workflow.

# Prompt Templates

Prompt templates are Markdown snippets that expand into full prompts. Type `/name` in the editor to invoke a template, where `name` is the filename without `.md`.

## Locations

Pi loads prompt templates from:

- Global: `~/.pi/agent/prompts/*.md`
- Project: `.pi/prompts/*.md` (only after the project is trusted)
- Packages: `prompts/` directories or `pi.prompts` entries in `package.json`
- Settings: `prompts` array with files or directories
- CLI: `--prompt-template <path>` (repeatable)

Disable discovery with `--no-prompt-templates`.

## Format

```markdown
---
description: Review staged git changes
---
Review the staged changes (`git diff --cached`). Focus on:
- Bugs and logic errors
- Security issues
- Error handling gaps
```

- The filename becomes the command name. `review.md` becomes `/review`.
- `description` is optional. If missing, the first non-empty line is used.
- `argument-hint` is optional. When set, the hint is displayed before the description in the autocomplete dropdown.

### Argument Hints

Use `argument-hint` in frontmatter to show expected arguments in autocomplete. Use `<angle brackets>` for required arguments and `[square brackets]` for optional ones:

```markdown
---
description: Review PRs from URLs with structured issue and code analysis
argument-hint: "<PR-URL>"
---
```

This renders in the autocomplete dropdown as:

```
→ pr   <PR-URL>       — Review PRs from URLs with structured issue and code analysis
  is   <issue>        — Analyze GitHub issues (bugs or feature requests)
  wr   [instructions] — Finish the current task end-to-end
  cl   — Audit changelog entries before release
```

## Usage

Type `/` followed by the template name in the editor. Autocomplete shows available templates with descriptions.

```
/review                           # Expands review.md
/component Button                 # Expands with argument
/component Button "click handler" # Multiple arguments
```

## Arguments

Templates support positional arguments, defaults, and simple slicing:

- `$1`, `$2`, ... positional args
- `$@` or `$ARGUMENTS` for all args joined
- `${1:-default}` uses arg 1 when present/non-empty, otherwise `default`
- `${@:-default}` or `${ARGUMENTS:-default}` uses all arguments when present/non-empty, otherwise `default`
- `${@:N}` for args from the Nth position (1-indexed)
- `${@:N:L}` for `L` args starting at N

Example:

```markdown
---
description: Create a component
---
Create a React component named $1 with features: $@
```

Default values are useful for optional arguments:

```markdown
Summarize the current state in ${1:-7} bullet points.
```

Usage: `/component Button "onClick handler" "disabled support"`

## Loading Rules

- Template discovery in `prompts/` is non-recursive.
- If you want templates in subdirectories, add them explicitly via `prompts` settings or a package manifest.


thinking:
Good, so pi uses prompt templates as markdown files with frontmatter. I need to create prompts for:
1. Plan mode
2. Review
3. Explain

The current agent directory is at /home/liph/dotfiles/pi/.pi/agent. The global prompt location is ~/.pi/agent/prompts/*.md. But since we're in /home/liph/dotfiles/pi/.pi/agent, it looks like this might be the actual ~/.pi/agent or a dotfiles version. Either way, I should create a prompts directory if it doesn't exist.

Let me check if prompts directory exists.

command: ls -la /home/liph/dotfiles/pi/.pi/agent/prompts 2>/dev/null || echo "prompts directory does not exist"


text: prompts directory does not exist


thinking:
I need to create the prompts directory and three prompt files. The user asked for "a couple of prompts: one for plan mode, review, explain". So three prompts total. Let me design them:

1. `/plan` - For planning mode, helps create implementation plans
2. `/review` - For reviewing code/changes
3. `/explain` - For explaining code/concepts

I should create markdown files with frontmatter. Let me make them practical and useful for a coding agent context.

I'll create:
- prompts/plan.md
- prompts/review.md
- prompts/explain.md

Each with good descriptions, argument hints, and useful content.


text: (no output)


thinking:
Now let me create the three prompt template files. I'll make them useful, with frontmatter and well-structured content.

For plan.md - a planning prompt that asks pi to create a structured implementation plan.
For review.md - a code review prompt.
For explain.md - an explanation prompt for code or concepts.

I'll use the ARGUMENTS variable for optional context, and include useful defaults.

write

content:
---
description: Create a structured implementation plan before coding
argument-hint: "[task or feature]"
---
Create a structured implementation plan for: ${@:-the current task}

Follow this format:
1. **Goal** — one-sentence objective
2. **Constraints** — existing code, dependencies, tests, or assumptions to respect
3. **Approach** — high-level strategy and rationale
4. **Steps** — numbered, actionable tasks small enough to verify one at a time
5. **Verification** — how to confirm each step works (tests, logs, manual checks)
6. **Risks & Rollbacks** — what could go wrong and how to undo safely
7. **Open Questions** — anything that needs clarification before starting

Use the codebase context as needed. Do not write implementation code yet; only produce the plan.

content:
---
description: Review code, diffs, or changes with actionable feedback
argument-hint: "[target: file path, diff, or PR]"
---
Review the following code or changes: ${@:-the current file / diff / staged changes}

Provide feedback in these categories:
- **Correctness** — bugs, logic errors, edge cases, race conditions
- **Security** — injection, unsafe defaults, secrets, auth/z issues
- **Performance** — unnecessary work, memory leaks, hot-path inefficiencies
- **Maintainability** — naming, complexity, duplication, testability
- **Style & Idioms** — consistency with the surrounding codebase
- **Error Handling** — missing or misleading failure modes

For each issue, include:
- The specific location (file, line, function)
- A clear description of the problem
- A concrete suggestion or example fix

Also call out anything done well. Keep the review concise and prioritized.

content:
---
description: Explain code, concepts, or errors in plain terms
argument-hint: "[topic: code, concept, or error]"
---
Explain the following in clear, plain language: ${@:-the current code or context}

Structure your answer as:
1. **What it is** — one-sentence summary
2. **How it works** — walk through the key parts step by step
3. **Why it matters** — purpose, trade-offs, or design intent
4. **Connections** — how it relates to the surrounding system or codebase
5. **Key details to know** — important gotchas, assumptions, or common pitfalls

Avoid unnecessary jargon. If showing code, keep snippets short and annotate them. If explaining an error, include the likely cause and how to fix it.


toolName: write

text: Successfully wrote 773 bytes to /home/liph/dotfiles/pi/.pi/agent/prompts/plan.md


text: Successfully wrote 880 bytes to /home/liph/dotfiles/pi/.pi/agent/prompts/review.md


text: Successfully wrote 698 bytes to /home/liph/dotfiles/pi/.pi/agent/prompts/explain.md


thinking: Great, I've created the three prompt files. Now I should verify they exist and maybe summarize what I created for the user.


text:
total 20
drwxr-xr-x  2 liph liph 4096 Jul 24 16:31 .
drwxr-xr-x 12 liph liph 4096 Jul 24 16:31 ..
-rw-r--r--  1 liph liph  708 Jul 24 16:31 explain.md
-rw-r--r--  1 liph liph  787 Jul 24 16:31 plan.md
-rw-r--r--  1 liph liph  892 Jul 24 16:31 review.md


thinking: Good. Now I'll give a concise summary of what I created and how to use them.

text:
Created three prompt templates in `~/.pi/agent/prompts/`:

- `/plan` — Produces a structured implementation plan (goal, constraints, steps, verification, risks, open questions) before any code is written.
- `/review` — Reviews code or diffs across correctness, security, performance, maintainability, style, and error handling, with location-specific, actionable feedback.
- `/explain` — Explains code, concepts, or errors in plain language with a clear walkthrough and important gotchas.

Usage: type `/plan`, `/review`, or `/explain` in the pi editor. You can also pass an optional argument, e.g. `/review src/utils/auth.ts`.

stopReason: stop