Add 5 pi extensions: pi-subagents, pi-crew, rpiv-pi, pi-interactive-shell, pi-intercom
This commit is contained in:
238
extensions/pi-crew/docs/usage.md
Normal file
238
extensions/pi-crew/docs/usage.md
Normal file
@@ -0,0 +1,238 @@
|
||||
# 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": true,
|
||||
"notifierIntervalMs": 5000,
|
||||
"requireCleanWorktreeLeader": true,
|
||||
"autonomous": {
|
||||
"profile": "suggested",
|
||||
"enabled": true,
|
||||
"injectPolicy": true,
|
||||
"preferAsyncForLongTasks": false,
|
||||
"allowWorktreeSuggestion": true
|
||||
},
|
||||
"runtime": {
|
||||
"mode": "auto",
|
||||
"groupJoin": "smart",
|
||||
"groupJoinAckTimeoutMs": 300000,
|
||||
"completionMutationGuard": "warn",
|
||||
"requirePlanApproval": false
|
||||
},
|
||||
"ui": {
|
||||
"widgetPlacement": "aboveEditor",
|
||||
"widgetMaxLines": 8,
|
||||
"powerbar": true,
|
||||
"dashboardPlacement": "center",
|
||||
"dashboardWidth": 72,
|
||||
"dashboardLiveRefreshMs": 1000,
|
||||
"autoOpenDashboard": false,
|
||||
"autoOpenDashboardForForegroundRuns": false,
|
||||
"showModel": true,
|
||||
"showTokens": true,
|
||||
"showTools": 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
|
||||
```
|
||||
|
||||
## Default run: real worker execution
|
||||
|
||||
By default, `pi-crew` launches each task as a separate child Pi worker process. The parent Pi session orchestrates; workers execute independently and stream output to durable run state.
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"team": "default",
|
||||
"goal": "Implement login with tests"
|
||||
}
|
||||
```
|
||||
|
||||
## Scaffold / dry run
|
||||
|
||||
Use scaffold mode only when you want durable prompts/artifacts without launching child workers.
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"team": "default",
|
||||
"goal": "Plan only",
|
||||
"config": {
|
||||
"runtime": { "mode": "scaffold" }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Async run
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "run",
|
||||
"team": "implementation",
|
||||
"goal": "Refactor auth module",
|
||||
"async": true
|
||||
}
|
||||
```
|
||||
|
||||
Check status:
|
||||
|
||||
```json
|
||||
{
|
||||
"action": "status",
|
||||
"runId": "team_..."
|
||||
}
|
||||
```
|
||||
|
||||
Background `Agent`/`crew_agent` subagents wake the parent Pi session when they complete, so the parent can call `get_subagent_result`/`crew_agent_result` and continue without waiting for another user prompt.
|
||||
|
||||
## State and API safety
|
||||
|
||||
State paths are validated before read/write operations. Run ids, imported bundles, artifact and transcript references, mailbox files, and agent control/log files must stay inside their expected `.crew` roots and symlink escapes are rejected. Read-only mailbox APIs return default state without creating mailbox files when no messages exist.
|
||||
|
||||
Group-join result delivery uses the normal outbox mailbox and normal `/team-api ... ack-message`. `runtime.groupJoinAckTimeoutMs` only emits observability (`agent.group_join.ack_timeout`) and does not block run completion.
|
||||
|
||||
`runtime.completionMutationGuard` defaults to `warn`. Use `off` to disable or `fail` to fail implementation-style workers that complete without observed mutation tool calls.
|
||||
|
||||
## 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 the project crew root (`.crew/` for new projects, `.pi/teams/` when the repo already has `.pi/`):
|
||||
|
||||
```text
|
||||
<crewRoot>/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 .crew/artifacts/team_.../export/run-export.json # or .pi/teams/artifacts/... on legacy layout
|
||||
/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
|
||||
}
|
||||
```
|
||||
Reference in New Issue
Block a user