pi-command

# Pi Command Authoring ## Boundary Use `pi-command` for command surface and placement decisions. Use `skills-engineer` for generic skill quality, frontmatter, or activation trigger editing. ## Placement Rules | Need | Preferred surface | | --- | --- | | Prompt-only slash command | `pi/prompts/<name>.md` (frontmatter, auto-discovered) | | Workflow command with TS logic or state | `pi/extensions/` registration + body in `pi/skills/workflow/<name>.md` (no frontmatter) | | Structured tool-backed command | `pi/extensions/` | | Shared Claude/OpenCode wrapper | `claude/commands/` only when cross-client support is requested | | OpenCode override | `opencode/commands/` | Keep command-specific model instructions in the owning prompt template, workflow skill, or extension. Do not place them in `pi/AGENTS.md`; reserve AGENTS for repository-wide rules that apply independently of the active command and tool set. Pi-first rule: when improving agent runtime features, implement in Pi unless the request is explicitly Claude/OpenCode-only. ## Practical Steps 1. Identify the owning runtime: Pi, shared wrapper, or client-specific. 2. Check for command name collisions and existing behavior. 3. Choose prompt template vs TypeScript extension based on whether tools/state are required. 4. Keep command docs and examples near the owning surface. 5. Validate with Pi-specific pnpm commands for TypeScript changes. ## State and Safety Stateful commands must be idempotent and use locked read-modify-write plus atomic writes for shared `.pi/*.json` files. Reset commands must target exact owned files, never broad globs. A command whose output is visible to the user must persist that output or a faithful summary in model context. UI-only notifications, widgets, and overlays are defects when they contain state the model cannot read back. ## Anti-Patterns - Modifying `claude/` as a proxy for Pi behavior. - Creating duplicate commands with unclear precedence. - Adding state without lock/atomic-write behavior.