# voice (pi package)

A pi package for building and using a personal writing-voice style guide.

## Skills

- `/skill:voice` — draft text in the user's voice. Takes a register (email, slack, pr-description, pr-comment, review-summary, blog) and a topic.
- `/skill:voice-init` — create the corpus directory with templates so the user can fill in their canonical rules.
- `/skill:voice-distill` — read the corpus and (re)generate the style guide.
- `/skill:voice-pull-emails` — pull recent sent emails via a Gmail MCP server.
- `/skill:voice-pull-blog` — pull blog posts from a URL via web fetch.

Shell-script helpers (run directly, not via skills):

- `scripts/pull_pr_descriptions.sh` — pull GitHub PR descriptions authored by the configured user via `gh`.
- `scripts/pull_review_comments.sh` — pull GitHub PR review/thread comments authored by the configured user via `gh`.

## Where things live

- **Style guide**: `~/.claude/voice/voice.md` (generated by `/skill:voice-distill`)
- **Canonical rules**: `~/.claude/voice/rules.md` (user-edited; `/skill:voice-distill` treats these as authoritative and won't overwrite)
- **Corpus**: `~/.claude/voice/corpus/` with subdirs per source (`emails/`, `blog/`, `github_prs/`, `slack/`, etc.)
- **Manifest**: `~/.claude/voice/manifest.md` (what's been ingested, when, with what filters)

The default location (`~/.claude/voice/`) is kept identical to the Claude Code plugin so a shared corpus works across both harnesses. Users can override by setting `VOICE_HOME` in the environment.

## Authoring the rules

The single most valuable input is `rules.md`. The corpus provides cadence and grounding samples; the rules are the hard constraints (phrases never to use, structural habits, sign-offs). The skills read `rules.md` first and treat it as authoritative when generating drafts.

Default starter rules at `templates/rules.md` cover the common AI-tells (em dashes, leading "I"/"I'm" filler, intensifiers). Users should customize.

## Design

- The corpus is data; the rules are policy. Don't conflate them.
- Filtering matters more than volume. Drop ack-comments, drop forwards-without-commentary, drop AI-co-authored content, drop self-notes. Voice signal is in the *substantive* writing.
- Recent agentic-development output is **not** the user's pure voice. PR descriptions or commits with AI footers, or matching agentic-style structure (heavy `## Summary` / `## Test plan` sections), should be excluded from the voice corpus or tagged separately.
- Multiple registers exist (email vs PR description vs inline review comment vs Slack DM). The skill picks register-appropriate samples rather than averaging across all of them.

## Package layout

- `skills/<name>/SKILL.md` — the five voice skills (pi equivalent of the plugin's `commands/*.md`).
- `templates/` — `rules.md`, `voice.md`, `.gitignore` starter files copied into `$VOICE_HOME` by `/skill:voice-init`.
- `scripts/` — the two `gh`-based pull scripts copied into `$VOICE_HOME/scripts/` by `/skill:voice-init`.
- `package.json` — declares `pi.skills: ["./skills"]` so pi discovers the skills on install.