# @creative-int/pi-prompts

Shared system-prompt scaffolding for `@mariozechner/pi-coding-agent` forks. Removes the duplicated boilerplate across `*-mono` specialist runtimes: date/time injection, working-directory footer, project context files, available-skills XML block, and the tool-aware guidelines bullet list.

Forks supply the domain-specific body (identity paragraph, core expertise, principles, domain docs pointer, and fork-specific tool descriptions). This package wraps that body with the shared scaffolding.

## Install

```bash
pnpm add @creative-int/pi-prompts
```

## Minimal example

```typescript
import {
  STANDARD_TOOL_DESCRIPTIONS,
  buildStandardGuidelines,
  buildSystemPrompt,
  renderToolsList,
} from "@creative-int/pi-prompts";

// 1. Merge your domain tool descriptions onto the standard set.
const toolDescriptions = {
  ...STANDARD_TOOL_DESCRIPTIONS,
  apple_project_analyze: "Analyze Xcode project structure, targets, Swift packages, frameworks, codebase metrics",
  apple_concurrency_audit: "Audit Swift concurrency — data races, missing Sendable, isolation issues, Swift 6 readiness",
};

// 2. Build the domain body. Forks own the identity + principles + domain docs pointer.
const body = `You are Apple Mono, a specialist coding agent for Apple platform development.

## Core expertise

### UIKit (interaction-critical UI)
- UICollectionView with CompositionalLayout + DiffableDataSource
- Custom UIPresentationController and interactive transitions

Available tools:
${renderToolsList(selectedTools, toolDescriptions)}

Guidelines:
${[...buildStandardGuidelines(selectedTools), "60fps or bust — every transition at 60fps"].map((g) => `- ${g}`).join("\n")}
`;

// 3. Compose the final prompt. pi-prompts appends context/skills/date/cwd.
const prompt = buildSystemPrompt({
  body,
  selectedTools,
  contextFiles,
  skills,
});
```

## Why

Before this package, every fork's `src/core/system-prompt.ts` duplicated:

- `getCurrentDateTimeString()` — locale-formatted "Current date and time"
- `formatSkillsForPrompt(skills)` — `<available_skills>` XML block + escaping
- `buildStandardGuidelines(tools)` — tool-aware guideline bullets (`Prefer grep/find/ls over bash`, `Use read before edit`, etc.)
- `renderProjectContextSection(files)` — `# Project Context` block
- `STANDARD_TOOL_DESCRIPTIONS` — descriptions for the seven standard tools

7 forks × ~150 lines of duplicated scaffolding = real drift risk. This package owns the primitives once; forks import them and keep only the domain body and principles in their repo.

## Exports

| Export | Purpose |
|---|---|
| `buildSystemPrompt(options)` | Canonical composer. Wraps a fork's `body` with shared scaffolding. |
| `buildStandardGuidelines(selectedTools)` | Tool-aware guideline bullet list. |
| `renderToolsList(selectedTools, descriptions)` | Bulleted "Available tools" list from a name→description map. |
| `STANDARD_TOOL_DESCRIPTIONS` | Descriptions for read, bash, edit, write, grep, find, ls. |
| `STANDARD_TOOL_NAMES` | The seven standard tool names. |
| `getCurrentDateTimeString(now?)` | Locale-formatted "Current date and time" string. |
| `renderProjectContextSection(files)` | `# Project Context` block from file snippets. |
| `formatSkillsForPrompt(skills)` | `<available_skills>` XML block. |
| `PromptSkill`, `PromptContextFile`, `BuildSystemPromptOptions` | Shared types. |

## Compatibility

`PromptSkill` is a minimal subset of the `Skill` type fork-local `skills.ts` files define. Fork-local types are structurally assignable to `PromptSkill`, so callers can pass their richer type directly without adapters.

## Scope

This package owns prompt composition only. It does not ship tools, extensions, or agent-runtime primitives. See sibling pi packages:

- `@creative-int/pi-tools` — tool-pack contract + composition helpers (`composePackFactories`, `whenEnabled`)
- `@lnittman/pi-steer` — steering compiler + pickup/handoff synthesis
- `@lnittman/pi-pad` — persistent execution memory
- `@creative-int/pi-outline` — outline-powered structural analysis (private lane)

The shared standard-tools baseline (bash/read/write/edit/grep/find/ls implementations, as opposed to just their descriptions) is a separate extraction tracked under `rules/mono-ecosystem.md` as `@creative-int/pi-shell` (TBD).