41 lines
1.8 KiB
Markdown
41 lines
1.8 KiB
Markdown
---
|
|
name: mailbox-interactive
|
|
description: Interactive waiting-task and mailbox workflow. Use when implementing or operating respond/nudge/ack/replay/supervisor-contact behavior.
|
|
---
|
|
|
|
# mailbox-interactive
|
|
|
|
Use this skill for live coordination between leader and workers.
|
|
|
|
## Source patterns distilled
|
|
|
|
- pi-subagents intercom/contact supervisor: blocking decisions vs non-blocking progress updates
|
|
- pi-crew mailbox: `src/state/mailbox.ts`, `src/extension/team-tool/respond.ts`, `src/extension/team-tool/api.ts`, `src/ui/overlays/mailbox-detail-overlay.ts`, `src/ui/run-action-dispatcher.ts`
|
|
- Waiting state: `src/state/contracts.ts`, `src/runtime/supervisor-contact.ts`, `src/ui/status-colors.ts`
|
|
|
|
## Rules
|
|
|
|
- Use `waiting` when a task needs leader input and can safely pause.
|
|
- `respond` should write an inbox mailbox message and transition target waiting tasks back to `running`.
|
|
- Mutating mailbox actions must use run locks and re-read state inside the lock.
|
|
- Respect run ownership: foreign sessions cannot respond/resume owned waiting tasks.
|
|
- Mailbox reads should be contained under run state and tolerate missing/empty JSONL files.
|
|
- Acknowledge/read actions are UI/operator state; preserve message history rather than deleting records.
|
|
- Supervisor contact parsed from child stdout should be recorded as events and surfaced in UI without blocking render paths.
|
|
|
|
## Anti-patterns
|
|
|
|
- Resuming non-waiting tasks via `respond`.
|
|
- Injecting mailbox messages into a foreign owned run.
|
|
- Treating every progress update as a blocking supervisor decision.
|
|
- Reading large mailbox files synchronously in hot render paths.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd pi-crew
|
|
npx tsc --noEmit
|
|
node --experimental-strip-types --test test/unit/respond-tool.test.ts test/unit/mailbox-detail-overlay.test.ts test/unit/mailbox-compose-overlay.test.ts test/unit/supervisor-contact.test.ts
|
|
npm test
|
|
```
|