⚒️ Pi Smithy

Forge, shape, and ship Pi packages.

A workshop for building Pi coding-agent packages — one scaffold that ships an extension, a skill, a prompt template, a theme, and release automation.

---

What's in the box

Piece	Path	What it gives you
🧩 Extension	extensions/	Custom commands, a registered tool, and a strict bash safety gate
🎯 Skill	skills/quick-audit/	A reusable quick-audit review workflow with reference docs
📝 Prompt template	prompts/	A focused review template you can invoke with variables
🎨 Theme	themes/	A sample smithy-cyan color theme for the Pi TUI
🚀 Release tooling	scripts/	Validate, changelog, dry-run, and one-command auto-release
🤖 CI/CD	.github/workflows/	Validation on push/PR; npm publish on v* tags

---

Contents

• Install
• Use in Pi
• Forge your own package
• Repository layout
• Development
• License

---

Install

From npm

npm install pi-smithy

From a local path

pi install <path-to-package>

For local extension runtime testing:

pi -e "$(pwd)/extensions/index.ts"

From git

pi install git:github.com/<you>/<repo>

---

Use in Pi

Trigger	What it does
/pkg-status	Quick package status notification
/pkg-version	Prints the package version, read live from package.json
package_stamp (tool)	Returns a status stamp with timestamp, message, and package version
/skill:quick-audit	Runs the audit workflow for a code change
/review-with-lens	Review prompt template (uses {{scope}})
smithy-cyan	Sample theme, selectable from /settings

---

Forge your own package

1. Clone or copy this repository.
2. Rename package.json name to your package (e.g. my-pi-tools).
3. Trim the box: delete the pieces you don't need (extension, skill, prompt, or theme), then remove them from the pi manifest and files list.
4. Rebrand the strings: user-facing output in extensions/index.ts is derived from package.json, so renaming the package updates everything automatically.
5. Validate: npm run release:check and npm test.

---

Repository layout

pi-smithy/
├── extensions/          # runtime extension code (commands, tool, safety gate)
│   ├── index.ts
│   └── policy.js        # shared bash policy evaluator
├── skills/
│   └── quick-audit/     # skill definition + reference docs
├── prompts/             # prompt templates
├── themes/              # theme JSON files
├── scripts/             # validation, changelog, and release automation
├── .github/workflows/   # CI + release pipelines
├── README.md
├── CONTRIBUTING.md      # contributing + full release workflow
├── SECURITY.md          # security policy
├── CHANGELOG.md
└── LICENSE

---

Development

Contributions are welcome. See CONTRIBUTING.md for setup, validation, and the full release workflow. Security issues: see SECURITY.md.

---

Benchmark

npm run benchmark stress-tests the pi workflow end-to-end and reports on it:

• Policy gate — regression table, adversarial security oracle (destructive commands must never be auto-allowed), benign allowlist, throughput (evals/sec).
• Manifest — package/pi manifest integrity + npm pack --dry-run shipping checks.
• Skills — inventory of every installed skill across all sources, frontmatter contract, broken symlinks, duplicate names.
• Config — settings.json, auth provider shape (no secrets), model store, moshi telemetry, context-mode KB, session dir.
• CLI / stress — real pi binary: version latency, pi list, pi --list-models, 16-way concurrent spawns, output-size handling.
• Tooling — npm run validate, npm test, release.sh --check/--dry-run under real execution.

Every check is timed, failures are logged as bugs (benchmark/reports/bugs.jsonl, append-only), debugged (classification + root-cause + file forensics), and written to a prioritized fix plan in benchmark/reports/FIXES.md.

Command	What it does
npm run benchmark	Full run (local, no LLM tokens). Exit 0 clean, 1 bugs found
npm run benchmark:quick	Local-only checks, skips CLI/stress/tooling
npm run benchmark:e2e	Also runs one real agent turn (spends tokens)

Reports: benchmark/reports/latest.{json,md} (overwritten each run) plus a timestamped JSON snapshot.

---

License

MIT