{"_id":"@aggarwal0897/pi-teams","name":"@aggarwal0897/pi-teams","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aggarwal0897/pi-teams","version":"0.1.0","description":"Persistent, communicating specialist teams for Pi","type":"module","license":"MIT","author":{"name":"Anupam Aggarwal"},"keywords":["pi-package","pi","pi-coding-agent","multi-agent","agent-teams"],"scripts":{"test":"node --experimental-strip-types --test *.test.ts"},"pi":{"extensions":["./index.ts"]},"peerDependencies":{"@earendil-works/pi-ai":"*","@earendil-works/pi-coding-agent":"*","@earendil-works/pi-tui":"*","typebox":"*"},"_id":"@aggarwal0897/pi-teams@0.1.0","_nodeVersion":"22.19.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-S7hW7uudx6qw8xO6etSmVNYrQhOBYlsxvCqnnFq8aZNYnyTAeftlauKrwi28uWEfuQ32bv+l4YSb2rJnisWtwQ==","shasum":"7b57481ed9a6cc1664974401ce3ca1a4a764dd7c","tarball":"https://registry.npmjs.org/@aggarwal0897/pi-teams/-/pi-teams-0.1.0.tgz","fileCount":10,"unpackedSize":88830,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCnQwjFay1Sd0IsXSsIoZ6gOCtgAA5CL4dFJ6Ej/ItJEgIhAMFw5WXQYdV0ww0Rhs0ftd6REPF+shQiX5yyV6AEmcIM"}]},"_npmUser":{"name":"aggarwal0897","email":"aggarwal0897@gmail.com"},"directories":{},"maintainers":[{"name":"aggarwal0897","email":"aggarwal0897@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pi-teams_0.1.0_1785736158552_0.7933895603810228"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-03T05:49:18.413Z","0.1.0":"2026-08-03T05:49:18.696Z","modified":"2026-08-03T05:49:18.890Z"},"maintainers":[{"name":"aggarwal0897","email":"aggarwal0897@gmail.com"}],"description":"Persistent, communicating specialist teams for Pi","keywords":["pi-package","pi","pi-coding-agent","multi-agent","agent-teams"],"author":{"name":"Anupam Aggarwal"},"license":"MIT","readme":"# pi-teams\n\nProject-local Pi extension for persistent, communicating specialist teams. A\nteam session is owned by one parent Pi session and contains one child Pi\nconversation per assigned member.\n\n## When to use it\n\nUse pi-teams when a task benefits from explicit ownership, dependency ordering,\nindependent testing/review, inspectable handoffs, or later reuse. A single\nsubagent is usually faster and cheaper for a small isolated task.\n\nGood fits:\n\n- feature work with design → tests → implementation → review\n- risky correctness, security, or data-migration changes\n- parallel independent research feeding one implementation owner\n- follow-up revisions that should retain specialist context\n\nAvoid it for one-file trivial edits or when several agents would concurrently\nedit the same production files.\n\n## Install\n\nFrom npm:\n\n```bash\npi install npm:@aggarwal0897/pi-teams\n```\n\nOr try it for one Pi process:\n\n```bash\npi -e npm:@aggarwal0897/pi-teams\n```\n\nTeam definitions remain project-specific under `.pi/teams/<team>/`. After\ncreating or changing a team definition, run `/reload`. For local development,\nPi auto-discovers `.pi/extensions/pi-teams/index.ts`.\n\n## Recommended prompt\n\nGive the main Pi agent the shared goal, acceptance criteria, ownership, and\ntrue dependencies. Let it call `team_start`; do not ask every member to solve\nthe whole problem.\n\nCopy and adapt this:\n\n```text\nUse pi-teams with the development team for this task.\n\nShared goal:\n<one concrete outcome>\n\nAcceptance criteria:\n- <observable requirement>\n- <observable requirement>\n- <exact verification command, if known>\n\nCreate one new saved, reusable team session in the background.\nAssign:\n- architect: inspect the current design and return the smallest implementation\n  contract; do not edit files.\n- tester: create or update focused tests from the agreed contract; depend on\n  architect if requirements need interpretation.\n- implementer: own all production edits and make the tests pass; depend on\n  architect and tester.\n- reviewer: independently inspect the final diff and run verification; depend\n  on implementer. Request a revision only for a material defect.\n\nKeep each assignment narrow, name allowed paths, avoid duplicate production\nfile ownership, and report the team session ID. Do not duplicate the team's\nwork in the main agent.\n```\n\n### Faster parallel variant\n\nArchitect and tester may start together only when the contract is already\nprecise. Put the exact same units, error behavior, paths, and edge cases in the\nshared goal or both assignments. Otherwise make tester depend on architect;\nparallel ambiguity can produce conflicting tests and correctly block the team.\n\n```text\nUse pi-teams/development. The specification below is authoritative and needs no\ninterpretation: <precise specification>.\nRun architect and tester in parallel, implementer after both, and reviewer after\nimplementer. Only implementer owns production files. Save the session and run\nin the background.\n```\n\n### Reuse an existing team session\n\n```text\nReuse team session <team-session-id> with team_continue.\nGive architect/tester/implementer/reviewer these related follow-up assignments:\n<assignments and dependencies>.\nDo not create a new team session.\n```\n\nReuse works only when the original session used `save: true`,\n`ephemeral: false`, and the current Pi session owns it.\n\n### One-off inspectable session\n\n```text\nUse pi-teams for this one-off task with save: true and ephemeral: true.\nI want persisted transcripts and statistics, but the session must not be\nreusable.\n```\n\nUse `save: false` instead when no team state or child JSONL should be written.\nThat session exists only until the current extension process ends.\n\n## Tool flow\n\n| Tool | Purpose |\n|---|---|\n| `team_start` | Always creates a new team session |\n| `team_status` | Returns current member status and dependency waits |\n| `team_result` | Optionally waits and returns structured results |\n| `team_continue` | Reuses a saved, non-ephemeral session |\n| `team_steer` | Sends guidance to one running member |\n| `team_close` | Parks, archives, or deletes a session |\n\nMinimal direct call:\n\n```json\n{\n  \"team\": \"development\",\n  \"goal\": \"Add and verify a strict parser\",\n  \"assignments\": [\n    { \"member\": \"architect\", \"task\": \"Define the minimal contract; do not edit.\" },\n    { \"member\": \"tester\", \"task\": \"Write focused tests from the contract.\", \"depends_on\": [\"architect\"] },\n    { \"member\": \"implementer\", \"task\": \"Implement and run the tests.\", \"depends_on\": [\"architect\", \"tester\"] },\n    { \"member\": \"reviewer\", \"task\": \"Review the final behavior and rerun tests.\", \"depends_on\": [\"implementer\"] }\n  ],\n  \"background\": true,\n  \"save\": true,\n  \"ephemeral\": false\n}\n```\n\nDependency-ready members run concurrently. A dependent member receives its\ncompleted dependencies' summaries and handoffs in its task prompt.\n\n## Monitoring\n\nWhile a team is running, the fleet is displayed below the editor:\n\n1. Empty the main prompt.\n2. Press `↓` or `←` to activate the fleet.\n3. Use `↑/↓` and press `Enter` on a member.\n4. Scroll with `↑/↓`, `j/k`, `PgUp/PgDn`, `Home`, or `End`.\n5. Press `Enter` inside a running conversation to steer it.\n6. Press `Esc` or `q` to return.\n\nCommands:\n\n```text\n/teams\n/teams <team-session-id>\n/team-stats\n```\n\n`/teams` also opens completed persisted conversations after the live fleet has\ndisappeared.\n\n## Team definitions\n\nDefinitions are project-specific:\n\n```text\n.pi/teams/<team>/\n├── team.json\n├── members/\n│   ├── architect.md\n│   ├── tester.md\n│   ├── implementer.md\n│   └── reviewer.md\n└── memory/\n```\n\nMember Markdown frontmatter supports:\n\n- `name`, `display_name`, `role`, `description`\n- `tools`: allowed built-in tools\n- `skills`: exact Pi skill names, or `none`\n- `model`, `thinking`\n- `memory`: shared project-memory access\n- `max_turns`: per-assignment hard limit\n- `can_request_revisions`: authorize targeted revision requests\n\nKeep one production owner. Give reviewers `can_request_revisions: true`; normal\ninformational messages never reopen completed work.\n\n## Storage and ownership\n\n```text\n.pi/teams/\n├── <team>/\n│   ├── team.json\n│   ├── members/\n│   └── memory/\n└── session/<team-session-id>/\n    ├── state.json\n    ├── architect.jsonl\n    ├── tester.jsonl\n    ├── implementer.jsonl\n    └── reviewer.jsonl\n```\n\n`state.json` records the owning parent Pi session ID. Resume that same Pi\nsession with `/resume` to restore its team sessions. Another Pi session receives\nan ownership error and cannot attach.\n\n| Options | Disk | Reusable |\n|---|---:|---:|\n| `save: true`, `ephemeral: false` | yes | yes |\n| `save: true`, `ephemeral: true` | yes | no |\n| `save: false` | no | no |\n\nProject memory is shared across parent sessions under\n`.pi/teams/<team>/memory/`. Store durable decisions and conventions there, not\nsecrets or transient progress.\n\nLegacy `.pi/teams/runs/` data is ignored and retained to avoid data loss.\n\n## Prompting rules that matter\n\n1. Put universal requirements in the shared goal.\n2. Give each member one deliverable and one owner role.\n3. Use dependencies for information that must be agreed before later work.\n4. Parallelize only genuinely independent work.\n5. Name exact paths and verification commands.\n6. State who may edit production code versus tests.\n7. Ask the reviewer for observable evidence, not a generic approval.\n8. Reuse a session only for closely related follow-up work.\n9. Use an ephemeral session for benchmarks and disposable experiments.\n10. Do not over-team trivial work; role overhead costs tokens and time.\n\n## Verification\n\n```bash\nnode --experimental-strip-types --test .pi/extensions/pi-teams/*.test.ts\npi -e ./.pi/extensions/pi-teams/index.ts --list-models\n```\n","readmeFilename":"README.md","_rev":"1-40771cf4adb42dbc9ef57c6919912e44"}