pi-crew 0.1.0

package/agents/executor.md

@@ -0,0 +1,11 @@
+---
+name: executor
+description: Implement planned code changes
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+---
+
+You are an implementation specialist. Follow the provided plan, make targeted changes, keep edits minimal, and report changed files plus validation status. Do not broaden scope without explaining why.

package/agents/explorer.md

@@ -0,0 +1,11 @@
+---
+name: explorer
+description: Fast codebase discovery and file/symbol mapping
+model: claude-haiku-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a fast codebase explorer. Map relevant files, symbols, data flow, and constraints. Do not modify files. Return concise findings with paths and evidence.

package/agents/planner.md

@@ -0,0 +1,11 @@
+---
+name: planner
+description: Create an execution plan with clear sequencing and risk notes
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls
+---
+
+You are a planning specialist. Convert the goal and discovery notes into a concrete, ordered plan. Identify dependencies, risks, validation steps, and handoff instructions for implementers.

package/agents/reviewer.md

@@ -0,0 +1,11 @@
+---
+name: reviewer
+description: Review code changes for correctness, maintainability, and regressions
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a code reviewer. Review the implementation for bugs, regressions, maintainability issues, missing tests, and project-rule violations. Return prioritized findings with evidence.

package/agents/security-reviewer.md

@@ -0,0 +1,11 @@
+---
+name: security-reviewer
+description: Review changes for security vulnerabilities and trust-boundary issues
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a security reviewer. Look for injection, authn/authz flaws, insecure defaults, secret exposure, unsafe filesystem/network behavior, and dependency risks. Return severity and remediation.

package/agents/test-engineer.md

@@ -0,0 +1,11 @@
+---
+name: test-engineer
+description: Design and implement test strategy for a change
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash, edit, write
+---
+
+You are a test engineer. Identify the right test level, add or adjust tests when asked, detect flaky assumptions, and report exact validation commands and results.

package/agents/verifier.md

@@ -0,0 +1,11 @@
+---
+name: verifier
+description: Verify that implementation satisfies the requested goal
+model: claude-sonnet-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, bash
+---
+
+You are a verification specialist. Check whether the work is complete, correct, tested, and aligned with project constraints. Prefer evidence over assumptions. Return PASS or FAIL with reasons.

package/agents/writer.md

@@ -0,0 +1,11 @@
+---
+name: writer
+description: Write concise documentation, migration notes, and summaries
+model: claude-haiku-4-5
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+tools: read, grep, find, ls, edit, write
+---
+
+You are a documentation specialist. Produce clear, concise, maintainable docs and summaries. Preserve technical accuracy and avoid marketing fluff.

package/docs/architecture.md

@@ -0,0 +1,92 @@
+# pi-crew Architecture
+
+Canonical architecture documentation currently lives at workspace level:
+
+- `../docs/pi-crew-source-review-and-lessons.md`
+- `../docs/pi-crew-architecture.md`
+- `../docs/pi-crew-mvp-plan.md`
+
+This project-local document exists so the package contains an obvious documentation entry point. Keep it in sync as implementation progresses.
+
+## Current scaffold
+
+Implemented now:
+
+- Pi package manifest
+- autonomous delegation policy injection so the agent can decide when to use the `team` tool
+- dynamic autonomous resource guidance generated from discovered agents/teams/workflows
+- `recommend` action for agent-side team/workflow routing, decomposition, and fanout hints before plan/run
+- `autonomy` action and `/team-autonomy` command for toggling autonomous delegation and profiles
+- centralized state contracts plus task-claim, worker-heartbeat, run-lock, progress-artifact, mailbox files, dashboard progress/action helpers, and safe API interop contracts for runtime hardening
+- extension entrypoint
+- main `team` tool
+- slash commands: `/teams`, `/team-run`, `/team-status`, `/team-doctor`
+- builtin agent/team/workflow markdown resources
+- resource discovery for builtin/user/project paths
+- TypeBox tool schema
+- model fallback helper
+- state type definitions
+- atomic state writes
+- JSONL event log
+- artifact store with content hashes
+- durable run manifests and task files
+- workflow validation
+- foreground workflow scheduler
+- safe scaffold task execution
+- optional real child Pi execution via `PI_TEAMS_EXECUTE_WORKERS=1`
+- safety-first create/update/delete for agents, teams, and workflows
+- backups for update/delete mutations
+- dry-run support for management mutations
+- detached async background runner
+- opt-in git worktree task workspace creation
+- worktree diff artifacts
+- child prompt runtime for inherited project-context/skills stripping
+- retryable model fallback attempts per worker task
+- rich status output with recent artifacts and event tail
+- recent run listing
+- `/team-cleanup` worktree cleanup command
+- improved `/team-run` parser for `--async`, `--worktree`, `--team=`, `--workflow=`, `--role=`, `--agent=`
+- async completion polling notifications during Pi sessions
+- active run summary on session start
+- reference checks before deleting referenced agents/workflows
+- optional reference updates when renaming agents/workflows
+- expanded doctor checks for `pi`, `git`, writable state paths, and resource discovery
+- durable run integration-style test coverage
+- user config loader for async defaults, worker execution, notifier interval, and worktree cleanliness policy
+- `pi-crew` install helper that creates default config
+- worktree branch mismatch detection before reuse
+- simple interactive `/team-manager` built with Pi UI dialogs
+- dedicated `events` and `artifacts` actions plus slash commands
+- persisted worktree metadata on task state/status
+- mocked child Pi execution path for integration-style tests
+- package polish: `.gitignore`, `tsconfig.json`, `npm run check`
+- project-local `AGENTS.md` development rules
+- run resume action/command that re-queues failed/cancelled/skipped/running tasks
+- dedicated worktrees inspection action and `/team-worktrees`
+- real temp-git worktree integration test
+- async run metadata persisted in manifest/status
+- stale async PID detection that marks active orphaned runs failed on status inspection
+- child Pi JSON output parsing for final text, usage, and JSON event counts
+- aggregate usage totals in status/summary
+- summary artifact and `summary` action/`/team-summary` command
+- custom overlay `/team-dashboard` run browser built with `ctx.ui.custom`
+- dashboard details pane with status counts and selected run metadata
+- prune action and `/team-prune` to remove old finished runs after confirmation
+- export action and `/team-export` to write portable JSON/Markdown run bundles
+- import action and `/team-import` to store exported bundles under local imports
+- imports action and `/team-imports` to browse imported bundles
+- help action and `/team-help` command
+- validate action and `/team-validate` command for agents/teams/workflows
+- doctor auto-runs resource validation and reports validation errors/warnings
+- project init action and `/team-init` command for `.pi` directories, `.gitignore`, and optional builtin resource copying
+- config action and `/team-config` command
+- published `schema.json` for config validation
+- publishing checklist docs
+- `/team-cancel` command alias
+- forget action and `/team-forget` to delete run state/artifacts after confirmation
+- resource format documentation
+- unit tests for async stale detection, autonomous config toggling, autonomous policy, autonomous recommendation/decomposition, config, project config merge, config action, dashboard rendering/navigation, discovery, doctor/model validation, events/artifacts/worktrees inspection, export/import run bundles and schema validation, help output, imported bundle listing, forget run cleanup, management, management reference checks, mocked child execution, child JSON output parsing and fixtures, model fallback, project init, prompt runtime, prune run cleanup, resource validation, resume/cancel, routing metadata, runtime hardening/progress/API interop, state contracts, state store, summary artifact/action, task claims, team run persistence, worker heartbeat, worktree mode, and workflow validation
+
+Not implemented yet:
+
+- richer multi-pane custom TUI manager

package/docs/live-mailbox-runtime.md

@@ -0,0 +1,36 @@
+# Live Mailbox Runtime Direction
+
+`pi-crew` currently uses workflow child-process orchestration: a run materializes tasks, executes them through the scheduler, writes artifacts/events, and optionally launches child Pi workers.
+
+A full live mailbox runtime is intentionally out of scope for the current stable surface. Current foundational mailbox files are intentionally simple and local:
+
+```text
+{stateRoot}/mailbox/inbox.jsonl
+{stateRoot}/mailbox/outbox.jsonl
+{stateRoot}/mailbox/delivery.json
+{stateRoot}/mailbox/tasks/{taskId}/inbox.jsonl
+{stateRoot}/mailbox/tasks/{taskId}/outbox.jsonl
+```
+
+They are exposed through safe API operations (`read-mailbox`, `send-message`, `ack-message`, `read-delivery`, `validate-mailbox`) but do not yet imply always-on long-lived workers. If a full runtime is added later, it should build on the foundations already present:
+
+- `src/state/contracts.ts` for status/event contracts
+- `src/state/task-claims.ts` for claim/lease safety
+- `src/runtime/worker-heartbeat.ts` for liveness
+- `src/state/locks.ts` for run-level mutation safety
+- `action: "api"` for safe interop boundaries
+
+## Proposed phases
+
+1. **Read-only interop** — already started with `api` operations.
+2. **Heartbeat writers** — allow workers to update heartbeat/progress safely.
+3. **Claim-safe task lifecycle** — expose claim/release/transition operations with tokens.
+4. **Mailbox** — add worker inbox/leader inbox files and delivery state.
+5. **Live workers** — only after the above contracts are stable.
+
+## Non-goals for now
+
+- No always-on background worker pool.
+- No automatic destructive cleanup of dirty worktrees.
+- No recursive team spawning by workers.
+- No mailbox mutation without locks and schema validation.

package/docs/publishing.md

@@ -0,0 +1,65 @@
+# Publishing pi-crew
+
+This package is published as the scoped public npm package:
+
+```text
+pi-crew
+```
+
+Before publishing to npm:
+
+1. Confirm package metadata in `package.json`:
+   - `author`
+   - `repository`
+   - `homepage`
+   - `bugs`
+   - `publishConfig.access = public`
+2. Confirm license and notices:
+   - keep `LICENSE`
+   - keep `NOTICE.md`
+   - document copied/adapted MIT source if any substantial code is ported
+3. Run checks:
+
+```bash
+npm run check
+```
+
+4. Verify package contents:
+
+```bash
+npm pack --dry-run
+```
+
+5. Verify local install in Pi:
+
+```bash
+pi install ./pi-crew
+/team-doctor
+/team-validate
+```
+
+6. Publish when ready:
+
+```bash
+npm publish --access public
+```
+
+Users can install the published package with:
+
+```bash
+pi install npm:pi-crew
+```
+
+## Config schema
+
+The package exports:
+
+```text
+./schema.json
+```
+
+Use this for editor validation of:
+
+```text
+~/.pi/agent/extensions/pi-crew/config.json
+```

package/docs/resource-formats.md

@@ -0,0 +1,131 @@
+# pi-crew Resource Formats
+
+## Agent files
+
+Location:
+
+```text
+agents/{name}.md
+~/.pi/agent/agents/{name}.md
+.pi/agents/{name}.md
+```
+
+Format:
+
+```md
+---
+name: executor
+description: Implement planned code changes
+model: claude-sonnet-4-5
+fallbackModels: openai/gpt-5-mini, anthropic/claude-sonnet-4
+thinking: high
+tools: read, grep, find, ls, bash, edit, write
+extensions: /path/to/extension.ts
+skills: safe-bash
+systemPromptMode: replace
+inheritProjectContext: true
+inheritSkills: false
+triggers: auth, tests
+useWhen: multi-file implementation with tests
+avoidWhen: one-line typo
+cost: cheap
+category: implementation
+---
+
+System prompt body.
+```
+
+Optional routing metadata fields:
+
+| Field | Meaning |
+| --- | --- |
+| `triggers` | Comma-separated terms that should route work to this agent/team |
+| `useWhen` | Comma-separated natural-language use cases |
+| `avoidWhen` | Comma-separated cases where the agent/team should not be used |
+| `cost` | `free`, `cheap`, or `expensive` hint for autonomous routing |
+| `category` | Free-form grouping such as `frontend`, `security`, `docs` |
+
+## Team files
+
+Location:
+
+```text
+teams/{name}.team.md
+~/.pi/agent/teams/{name}.team.md
+.pi/teams/{name}.team.md
+```
+
+Format:
+
+```md
+---
+name: implementation
+description: Full implementation team
+defaultWorkflow: implementation
+workspaceMode: single
+maxConcurrency: 3
+triggers: implementation, refactor
+useWhen: multi-file implementation
+cost: cheap
+category: implementation
+---
+
+- explorer: agent=explorer map the codebase
+- planner: agent=planner create plan
+- executor: agent=executor implement
+- verifier: agent=verifier verify
+```
+
+Role line:
+
+```text
+- {role-name}: agent={agent-name} optional description
+```
+
+## Workflow files
+
+Location:
+
+```text
+workflows/{name}.workflow.md
+~/.pi/agent/workflows/{name}.workflow.md
+.pi/workflows/{name}.workflow.md
+```
+
+Format:
+
+```md
+---
+name: default
+description: Explore, plan, execute, verify
+---
+
+## explore
+role: explorer
+
+Explore for: {goal}
+
+## plan
+role: planner
+dependsOn: explore
+output: plan.md
+
+Create a plan for: {goal}
+```
+
+Step fields:
+
+| Field | Meaning |
+| --- | --- |
+| `role` | Team role to run |
+| `dependsOn` | Comma-separated step IDs |
+| `parallelGroup` | Optional grouping metadata |
+| `output` | Output file name or `false` |
+| `reads` | Comma-separated read files or `false` |
+| `model` | Step model override |
+| `skills` | Comma-separated skills or `false` |
+| `progress` | `true`/`false` |
+| `worktree` | `true`/`false` metadata |
+| `verify` | `true`/`false` verification marker |
+
+Avoid using level-2 headings (`##`) inside task bodies because they delimit workflow steps.

package/docs/usage.md

@@ -0,0 +1,203 @@
+# pi-crew Usage
+
+## Config
+
+Optional config path:
+
+```text
+~/.pi/agent/extensions/pi-crew/config.json
+```
+
+Create a default config:
+
+```bash
+node ./pi-crew/install.mjs
+```
+
+Supported fields:
+
+```json
+{
+  "asyncByDefault": false,
+  "executeWorkers": false,
+  "notifierIntervalMs": 5000,
+  "requireCleanWorktreeLeader": true,
+  "autonomous": {
+    "profile": "suggested",
+    "enabled": true,
+    "injectPolicy": true,
+    "preferAsyncForLongTasks": false,
+    "allowWorktreeSuggestion": true
+  }
+}
+```
+
+## Local Pi smoke test
+
+```bash
+cd pi-crew
+npm run smoke:pi
+```
+
+Then open Pi and run:
+
+```text
+/team-doctor
+/team-validate
+/team-autonomy status
+```
+
+## Safe run
+
+By default, `pi-crew` does not launch child workers. It creates a durable run, prompts, placeholder results, events, and artifacts.
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Implement login with tests"
+}
+```
+
+## Real worker execution
+
+Start Pi with:
+
+```bash
+PI_TEAMS_EXECUTE_WORKERS=1 pi
+```
+
+Then run normally. Each task can spawn a child Pi worker.
+
+## Async run
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor auth module",
+  "async": true
+}
+```
+
+Check status:
+
+```json
+{
+  "action": "status",
+  "runId": "team_..."
+}
+```
+
+## Worktree mode
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor API layer",
+  "workspaceMode": "worktree"
+}
+```
+
+The leader repository must be clean. Per-task worktrees are created under:
+
+```text
+.pi/teams/worktrees/{runId}/{taskId}
+```
+
+Cleanup:
+
+```json
+{
+  "action": "cleanup",
+  "runId": "team_..."
+}
+```
+
+Dirty worktrees are preserved unless `force: true` is provided.
+
+## Slash commands
+
+```text
+/teams
+/team-run default "Implement login with tests"
+/team-run --team=implementation --workflow=implementation --async "Refactor auth"
+/team-cancel team_...
+/team-run --worktree default "Change API safely"
+/team-status team_...
+/team-summary team_...
+/team-resume team_...
+/team-events team_...
+/team-artifacts team_...
+/team-worktrees team_...
+/team-cleanup team_...
+/team-forget team_... --confirm
+/team-export team_...
+/team-import .pi/teams/artifacts/team_.../export/run-export.json
+/team-imports
+/team-prune --keep=20 --confirm
+/team-manager
+/team-dashboard
+/team-api team_... read-mailbox direction=outbox
+/team-api team_... send-message direction=outbox taskId=task_... to=worker body="hello"
+/team-api team_... validate-mailbox repair=true
+/team-init
+/team-init --copy-builtins
+/team-config
+/team-config autonomous.profile=assisted autonomous.preferAsyncForLongTasks=true --project
+/team-config --unset=autonomous.preferAsyncForLongTasks --project
+/team-autonomy status
+/team-autonomy on
+/team-autonomy off
+/team-autonomy manual
+/team-autonomy suggested
+/team-autonomy assisted
+/team-autonomy aggressive
+/team-validate
+/team-help
+/team-doctor
+```
+
+## Management
+
+Create resources:
+
+```json
+{
+  "action": "create",
+  "resource": "team",
+  "config": {
+    "name": "Backend Team",
+    "description": "Backend work",
+    "scope": "project",
+    "defaultWorkflow": "default",
+    "roles": [{ "name": "executor", "agent": "executor" }]
+  }
+}
+```
+
+Rename an agent and update team references:
+
+```json
+{
+  "action": "update",
+  "resource": "agent",
+  "agent": "worker",
+  "scope": "project",
+  "updateReferences": true,
+  "config": { "name": "better-worker" }
+}
+```
+
+Delete requires confirmation:
+
+```json
+{
+  "action": "delete",
+  "resource": "team",
+  "team": "backend-team",
+  "scope": "project",
+  "confirm": true
+}
+```

package/index.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { registerPiTeams } from "./src/extension/register.ts";
+
+export default function (pi: ExtensionAPI): void {
+	registerPiTeams(pi);
+}

package/install.mjs

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const configDir = path.join(os.homedir(), ".pi", "agent", "extensions", "pi-crew");
+const configPath = path.join(configDir, "config.json");
+fs.mkdirSync(configDir, { recursive: true });
+if (!fs.existsSync(configPath)) {
+  fs.writeFileSync(configPath, `${JSON.stringify({ asyncByDefault: false, executeWorkers: false, notifierIntervalMs: 5000, requireCleanWorktreeLeader: true, autonomous: { enabled: true, injectPolicy: true, preferAsyncForLongTasks: false, allowWorktreeSuggestion: true } }, null, 2)}\n`, "utf-8");
+  console.log(`Created default pi-crew config: ${configPath}`);
+} else {
+  console.log(`pi-crew config already exists: ${configPath}`);
+}
+
+console.log("\nInstall this package in Pi with:");
+console.log("  pi install ./pi-crew");
+console.log("\nEnable real child workers by setting either config executeWorkers=true or environment:");
+console.log("  PI_TEAMS_EXECUTE_WORKERS=1 pi");