From fa0bbd8c59e46b589e2a5367f1516bc6fe1ec9ce Mon Sep 17 00:00:00 2001 From: Yuriy Mayatnikov Date: Mon, 25 May 2026 10:23:20 +0300 Subject: [PATCH] docs: artifact-location rule + CONTRIBUTING for community growth MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The whole point of this project is that the agent's growth is shareable. If skills and extensions silently land in ~/.pi/ on the maintainer's laptop, every clone starts from zero and the repo becomes a fancy README. Fix that with an explicit hard rule and a contributor guide. - AGENTS.md: new "Artifact location — hard rule" subsection spelling out that skills/extensions/prompts/state/.pi-settings ALL live in this repo, never in ~/.pi/. Pi's own built-in skills (skill-creator, etc.) stay user-global; the agent may use them, but their *output* must land here. - README: new "Everything in the repo" subsection covering the same rule in user-facing language, plus a pointer to CONTRIBUTING.md. - CONTRIBUTING.md (new): skill/extension formats, server-agnostic and no-secrets requirements, smoke-test recipe, PR checklist. - .gitignore: switch from blanket `.pi/` ignore to `.pi/*` + explicit un-ignore of `.pi/settings.json`, so project Pi config is reproducible. - "Don't push without operator confirmation" → "without human confirmation via the repo" — consistent with the new control model. Co-Authored-By: Claude Opus 4.7 (1M context) --- .gitignore | 7 ++-- AGENTS.md | 20 +++++++++-- CONTRIBUTING.md | 92 +++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 10 +++++- 4 files changed, 123 insertions(+), 6 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/.gitignore b/.gitignore index 90a605c..7451e32 100644 --- a/.gitignore +++ b/.gitignore @@ -10,8 +10,11 @@ yarn-debug.log* yarn-error.log* pnpm-debug.log* -# Pi runtime state — sessions, caches, locally-installed extensions -.pi/ +# Pi runtime state — sessions and cache are local-only. +.pi/* +# …but commit .pi/settings.json — it's the project's Pi config (installed +# extensions, model defaults, etc.) and must be reproducible across clones. +!.pi/settings.json sessions/ *.session.json diff --git a/AGENTS.md b/AGENTS.md index c39dcda..319f5b5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -55,11 +55,25 @@ When you encounter a missing capability, your loop is: 1. **Decide** whether the capability is one-off (handle inline) or reusable (codify). 2. If reusable, create either: - - a **skill** under `skills/.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body. - - or an **extension** under `extensions/.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events. -3. Commit the new file with a clear message. The repo is on `main`. Don't push without operator confirmation. + - a **skill** under `./skills/.md` — markdown, with a frontmatter header (`name`, `description`, `when_to_use`) and a procedural body. + - or an **extension** under `./extensions/.ts` — for anything that needs to register a real Pi tool or hook into Mineflayer events. +3. Commit the new file with a clear message. The repo is on `main`. Don't push without human confirmation via the repo. 4. Update `README.md`'s **Status** section as milestones land. +### Artifact location — hard rule + +Everything you author lives **in this repo**, never in `~/.pi/` or any other user-global location. This is what makes the project shareable: + +- **Skills** → `./skills/.md`. Not `~/.pi/skills/`. Not `~/.pi/agent/`. +- **Extensions** → `./extensions/.{ts,js}`. Not globally `npm install`-ed. +- **Prompt templates** → `./prompts/.md`. Not `~/.pi/prompts/`. +- **Per-session learnings, world state, base coords, etc.** → `./state//...`. Gitignored by default, but **lives inside the repo**. +- **Pi project settings** → `./.pi/settings.json` (use `pi install -l `, the `-l` makes it project-local). This file IS committed; without it a fresh clone can't reproduce your tool stack. + +If you need to use Pi's built-in `skill-creator` or similar global tools, that's fine — just make sure the *output* lands under `./skills/` in this repo. + +If something genuinely belongs in the user's global Pi config (a personal API key, a workflow only the human cares about), don't write it. Tell the human and let them decide. + Skills you might want early on (good for any server): - `server-onboarding` — what auth flow this server uses; relogin / autologin pattern. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b6876ce --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,92 @@ +# Contributing + +This repo grows by accretion — skills, extensions, and prompts written by Pi agents (or humans) playing on real Minecraft servers. PRs welcome. + +## What you can contribute + +| Kind | Where | When | +|---|---|---| +| **Skill** | `skills/.md` | You taught the agent a useful procedure (login flow, recovery routine, farming loop, etc.) and want others to skip the discovery cost. | +| **Extension** | `extensions/.{ts,js}` | The skill needs real code — a new Pi tool, a Mineflayer plugin wrapper, an event subscription. | +| **Prompt template** | `prompts/.md` | A reusable kickoff or tick prompt that works across servers. | +| **Docs** | `README.md`, `docs/*.md`, `AGENTS.md` | Clarifications, new safety rules, architecture notes. | + +If you change `AGENTS.md`, treat it as load-bearing — every agent that clones the repo starts from it. Discuss in a PR first. + +## Skill format + +A skill is a single Markdown file with YAML frontmatter: + +```markdown +--- +name: +description: +when_to_use: +--- + +# + +## Steps + +1. ... +2. ... + +## Notes + +- Edge cases, gotchas, known failure modes. +``` + +Keep skills short (under ~150 lines). If it gets longer, split into multiple skills that reference each other, or promote part of it to an extension. + +## Extension format + +Extensions are TypeScript (preferred) or JavaScript modules. See `pi.dev/docs/latest` for the current extension API. Project-local install: + +```bash +pi install -l ./extensions/your-extension.ts +``` + +The `-l` flag writes to `./.pi/settings.json` (committed) so a fresh clone gets the same toolset. + +## Hard rules + +- **Server-agnostic.** No `play.xmatic.team`, no specific nicknames, no AuthMe password in any committed file. Everything that varies per server lives in `.env`. +- **No secrets in git.** If you have to think about whether something is a secret, it is. Run `git diff --staged` before every commit. +- **No global writes.** Skills, extensions, and Pi settings all live under this repo's tree, not under `~/.pi/`. See `AGENTS.md` → *Artifact location*. +- **Don't loosen safety.** The hard rules in `AGENTS.md` (no OP, no griefing, no chat-as-control, rate limits) are non-negotiable. PRs that weaken them get closed. + +## Testing a skill / extension + +Quick smoke test before opening a PR: + +```bash +# 1. Fresh clone in a temp dir +git clone git@github.com:xmatic-squad/pepa-pi-bot.git /tmp/pepa-test +cd /tmp/pepa-test + +# 2. Minimal config — point at a throwaway local MC server if you have one +cp .env.example .env +$EDITOR .env + +# 3. Install deps +npm install + +# 4. Run Pi and ask it to dry-run your skill +pi +# > Please list the loaded skills. Then describe what skills/your-new-skill.md +# > would do, step-by-step, without actually executing it. +``` + +If Pi can't even *find* your skill, the frontmatter is wrong — check `name:` is a valid slug and the file is under `./skills/`. + +## PR checklist + +- [ ] File lives in the correct directory (`skills/`, `extensions/`, `prompts/`, `docs/`). +- [ ] Frontmatter is valid YAML; `name` matches the filename. +- [ ] No hard-coded server hostnames, nicknames, passwords, or API keys. +- [ ] `README.md`'s Status section updated if this is a user-facing milestone. +- [ ] Commit message is descriptive (`feat(skill): add respawn-and-return for survival servers`). + +## License + +By contributing you agree that your work is released under the project's [MIT License](./LICENSE). diff --git a/README.md b/README.md index 4366c1f..6204688 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ You can mix providers via `--provider openai --model gpt-5` at launch — cheape Pi has first-class support for three growth surfaces: - **`skills/`** — Markdown-defined capabilities Pi can invoke. The agent can `Write` new ones at runtime when it discovers a missing capability. -- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed via `pi install npm:` / `pi install git:` or written in-tree. +- **`extensions/`** — TypeScript modules registering new tools, commands, or UI tweaks. Installed project-locally via `pi install -l npm:` / `pi install -l git:`, or written in-tree. - **`prompts/`** — Reusable prompt templates. Useful for cron-driven tick prompts ("what should I do next minute?"). The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-bridge` extension that can: @@ -116,6 +116,14 @@ The opening `AGENTS.md` instructs the agent to start by writing a `mineflayer-br Everything beyond that — farming, exploration, base-building, player interaction, server-specific quirks — should emerge from the agent itself. +### Everything in the repo + +A hard rule, mirrored in `AGENTS.md`: every artefact the agent produces **lives in this repo**, never in the user's `~/.pi/` directory. That includes skills, extensions, prompt templates, project Pi settings (`.pi/settings.json`), and per-server state (`state//`). + +The point is reproducibility and **community growth**: a fresh `git clone` should bring along every skill any contributor has written. Pi's own built-in skills (`skill-creator`, `agent-browser`, etc.) stay user-global — the agent is allowed to *use* them, but anything it *authors* lands under `./skills/` or `./extensions/` here. + +See [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the skill format and how to propose changes. + ## Project layout ```