{"_id":"@arcanemachine/pi-role","_rev":"2-ed72028fa67891bb6cc869df4887bde3","name":"@arcanemachine/pi-role","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@arcanemachine/pi-role","version":"0.1.0","keywords":["pi","pi-coding-agent","pi-extension","pi-package","role","system-prompt"],"author":{"name":"Nicholas Moen"},"license":"MIT","_id":"@arcanemachine/pi-role@0.1.0","maintainers":[{"name":"arcanemachine","email":"arcanemachine@gmail.com"}],"homepage":"https://github.com/arcanemachine/pi-role#readme","bugs":{"url":"https://github.com/arcanemachine/pi-role/issues"},"pi":{"extensions":["./src/index.ts"]},"dist":{"shasum":"cd6262575e786b1f8c07199aa4cc24ddc3bd123d","tarball":"https://registry.npmjs.org/@arcanemachine/pi-role/-/pi-role-0.1.0.tgz","fileCount":6,"integrity":"sha512-tIVNxHPQAuhFAeKTh5Y9vf7zi2kmZlij3R6teA+p51mmrbQViWX44MXFGUl08waprop9r+ZVKQ5IzUwl1h+wlg==","signatures":[{"sig":"MEQCIAYvt7xia+z2OtCup9fEzqw0DTPLOu2THqxV1L9VfcNPAiAVFPc5kvswC2QZ5YasJE5+kr/hHD/q5RmuWVzW8O4XXg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":26296},"type":"module","engines":{"node":">=22.19.0"},"scripts":{"test":"vitest run","build":"tsc","watch":"tsc --watch","format":"prettier --write src/**/*.ts tests/**/*.ts package.json README.md AGENTS.md CHANGELOG.md","typecheck":"tsc --noEmit","prepublishOnly":"npm run typecheck && npm run test"},"_npmUser":{"name":"arcanemachine","email":"arcanemachine@gmail.com"},"repository":{"url":"git+https://github.com/arcanemachine/pi-role.git","type":"git"},"_npmVersion":"11.13.0","description":"Thin, session-scoped roles for Pi with project and user role discovery","directories":{},"_nodeVersion":"24.16.0","publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^4.1.6","prettier":"^3.8.3","typescript":"^5.9.3","@types/node":"^25.3.0","@earendil-works/pi-tui":"0.80.10","@earendil-works/pi-coding-agent":"0.80.10"},"peerDependencies":{"@earendil-works/pi-tui":"*","@earendil-works/pi-coding-agent":"*"},"peerDependenciesMeta":{"@earendil-works/pi-tui":{"optional":true},"@earendil-works/pi-coding-agent":{"optional":true}},"_npmOperationalInternal":{"tmp":"tmp/pi-role_0.1.0_1788424699565_0.7954279628781271","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@arcanemachine/pi-role","version":"0.1.1","description":"Thin, session-scoped roles for Pi with project and user role discovery","type":"module","keywords":["pi","pi-coding-agent","pi-extension","pi-package","role","system-prompt"],"pi":{"extensions":["./src/index.ts"],"image":"https://raw.githubusercontent.com/arcanemachine/pi-role/main/logo.jpg"},"scripts":{"build":"tsc","watch":"tsc --watch","typecheck":"tsc --noEmit","test":"vitest run","format":"prettier --write src/**/*.ts tests/**/*.ts package.json README.md AGENTS.md CHANGELOG.md","prepublishOnly":"npm run typecheck && npm run test"},"author":{"name":"Nicholas Moen"},"license":"MIT","peerDependencies":{"@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*"},"peerDependenciesMeta":{"@earendil-works/pi-coding-agent":{"optional":true},"@earendil-works/pi-tui":{"optional":true}},"devDependencies":{"@earendil-works/pi-coding-agent":"0.80.10","@earendil-works/pi-tui":"0.80.10","@types/node":"^25.3.0","prettier":"^3.8.3","typescript":"^5.9.3","vitest":"^4.1.6"},"repository":{"type":"git","url":"git+https://github.com/arcanemachine/pi-role.git"},"homepage":"https://github.com/arcanemachine/pi-role#readme","bugs":{"url":"https://github.com/arcanemachine/pi-role/issues"},"engines":{"node":">=22.19.0"},"publishConfig":{"access":"public"},"_id":"@arcanemachine/pi-role@0.1.1","_nodeVersion":"24.16.0","_npmVersion":"11.13.0","dist":{"integrity":"sha512-zYInY5kdEN+/XP1LQf/7nfOle2Hjzt07uGxB1fzW2zuXDqhucsNGxpLlsizMYoGJeEf1AJ7h1v+FjfMHa2NsOA==","shasum":"d941192d9d0f16daea4e9ea039f51e3762ba6fed","tarball":"https://registry.npmjs.org/@arcanemachine/pi-role/-/pi-role-0.1.1.tgz","fileCount":7,"unpackedSize":76734,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCnJ2wwP5XLm/EWp/P6vsSfmT+J+4aKZexZPuATXkGtzAIgV4G8Wl1y3Kj+tIOcNf9E71V3B65POMcxmRACdgU4mPU="}]},"_npmUser":{"name":"arcanemachine","email":"arcanemachine@gmail.com"},"directories":{},"maintainers":[{"name":"arcanemachine","email":"arcanemachine@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-role_0.1.1_1788679755153_0.09634298778369454"},"_hasShrinkwrap":false}},"time":{"created":"2026-09-03T08:38:19.356Z","modified":"2026-09-06T07:29:15.520Z","0.1.0":"2026-09-03T08:38:19.758Z","0.1.1":"2026-09-06T07:29:15.300Z"},"bugs":{"url":"https://github.com/arcanemachine/pi-role/issues"},"author":{"name":"Nicholas Moen"},"license":"MIT","homepage":"https://github.com/arcanemachine/pi-role#readme","keywords":["pi","pi-coding-agent","pi-extension","pi-package","role","system-prompt"],"repository":{"type":"git","url":"git+https://github.com/arcanemachine/pi-role.git"},"description":"Thin, session-scoped roles for Pi with project and user role discovery","maintainers":[{"name":"arcanemachine","email":"arcanemachine@gmail.com"}],"readme":"# pi-role\n\n<p align=\"center\">\n  <img src=\"https://raw.githubusercontent.com/arcanemachine/pi-role/main/logo.jpg\" alt=\"Pi mascot choosing a role from a wardrobe\" width=\"250\" />\n</p>\n\nA thin role extension for [Pi](https://pi.dev). Activate a Markdown role for the current session (e.g. architect, worker, etc.) without changing its model, thinking level, tools, or name.\n\n`pi-role` ships no roles. User and project role files are discovered at runtime.\n\n## Features\n\n- `/role` command with role-key autocomplete\n- `--role <key>` startup selection\n- Project roles override user roles\n- Configurable project roles directory\n- Active role body appended to Pi's upstream system prompt\n- Durable, branch-aware role state across resume, reload, fork, and clone\n- Compact, standard informational role-change entries that are not sent to the model\n- No default role and no status text while inactive\n\n## Install\n\nFrom GitHub:\n\n```bash\npi install git:github.com/arcanemachine/pi-role\n```\n\nFrom npm (after publication):\n\n```bash\npi install npm:@arcanemachine/pi-role\n```\n\nFor local development:\n\n```bash\npi -e ./src/index.ts\n```\n\n## Role files\n\nUser roles live in:\n\n```text\n~/.pi/agent/roles/\n```\n\nProject roles default to:\n\n```text\n<project>/.pi/roles/\n```\n\nThe filename basename is the role key. For example, `architect.md` is activated with `/role architect`. Keys are matched case-insensitively. Project roles override user roles with the same key.\n\nThe keys `list`, `current`, `reload`, and `none` are reserved by the command.\n\nA role uses YAML frontmatter followed by its system-prompt body:\n\n```markdown\n---\nname: \"Architect\"\ndescription: Plans architecture and defines implementation boundaries.\nmeta:\n  team: platform\n---\n\nYou are the Architect. Define boundaries and decisions before implementation.\n```\n\nFrontmatter fields:\n\n| Field         | Required | Purpose                                                         |\n| ------------- | -------- | --------------------------------------------------------------- |\n| `name`        | yes      | Unconstrained printed name used in notices and status text      |\n| `description` | yes      | Short description shown by `/role`                              |\n| `meta`        | no       | Open metadata object reserved for future use; currently ignored |\n\nOther frontmatter fields are tolerated and ignored. Frontmatter is never added to the model prompt.\n\n## Project configuration\n\nSet `pi-role.rolesDir` in `<project>/.pi/settings.json` to use another project-relative directory:\n\n```json\n{\n  \"pi-role\": {\n    \"rolesDir\": \".agents/roles\"\n  }\n}\n```\n\nRelative paths resolve from Pi's current project directory (`ctx.cwd`). Absolute paths are also accepted.\n\nProject settings and roles follow Pi's native project-trust result. A bare `.pi/roles` directory does not itself trigger Pi's trust prompt; activating a role is always explicit because there is no default role.\n\n## Commands\n\n| Command         | Behavior                                          |\n| --------------- | ------------------------------------------------- |\n| `/role`         | List effective roles                              |\n| `/role list`    | List effective roles                              |\n| `/role <key>`   | Activate a role, or reload it when already active |\n| `/role current` | Show the active role and source file              |\n| `/role reload`  | Re-read the active role from disk                 |\n| `/role none`    | Disable the active role                           |\n\nActivating a role adds a compact user-visible entry:\n\n```text\nRole type switched to Architect.\n```\n\nThe status bar receives the exact string `Role: Architect 👤 `, including one trailing space after the emoji.\n\n`/role none` clears the status, adds `Role type disabled.` to the transcript, removes the role body from later system prompts, and adds a hidden context message telling the agent to stop following the removed role.\n\n## CLI flag\n\n```bash\npi --role architect\n```\n\nThe flag applies on initial process startup and overrides restored role state. It does not become a default for later `/new` sessions. An unknown key reports an error and starts without a role.\n\n## Session behavior\n\n- New sessions start without a role.\n- Resume and extension reload restore the latest explicit role state silently.\n- Fork and clone inherit the role state copied with their session branch.\n- Restoring or reloading re-reads the role file from disk.\n- Missing or invalid restored roles leave the session inactive without selecting a fallback.\n\n## Prompt behavior\n\nFor every agent invocation while a role is active, the extension composes:\n\n```text\n<complete upstream Pi system prompt>\n\n<active role Markdown body>\n```\n\nThis preserves Pi's default prompt, project context, skills, and changes made by earlier extensions. Switching roles does not trigger a model turn.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck\nnpm run test\nnpm run build\nnpm run format\nnpm pack --dry-run\n```\n\nThe package is source-loaded by Pi from `src/index.ts`; no compiled runtime artifact is required for publication.\n\n## License\n\nMIT. See [LICENSE.md](./LICENSE.md).\n","readmeFilename":"README.md"}