pi-crew 0.2.3 → 0.2.4

package/README.md

@@ -1,323 +1,323 @@
-# pi-crew
-
-**Coordinate AI agent teams inside [Pi](https://github.com/nicekate/pi-coding-agent).**
-
-pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults.
-
-```text
-npm: pi-crew
-repo: https://github.com/baphuongna/pi-crew
-```
-
-**v0.2.0**: Security hardening + 76% faster startup. See [CHANGELOG.md](CHANGELOG.md).
-
----
-
-## Features
-
-- **One Pi tool** — `team` handles routing, planning, execution, review, and cleanup
-- **Autonomous delegation** — policy injection decides when/how to delegate based on task complexity
-- **Real child Pi workers** — each task spawns a separate Pi process by default; scaffold/dry-run opt-out
-- **Adaptive planning** — implementation workflow lets a planner agent decide subagent fanout
-- **Parallel execution** — tasks in the same phase run concurrently with configurable concurrency
-- **Durable state** — manifest, tasks, events, artifacts all persisted to disk
-- **Async/background runs** — detached runs survive session switches with completion notifications
-- **Worktree isolation** — opt-in git worktrees per task for safe parallel edits
-- **Rich UI** — live widget, dashboard, progress tracking, model/token display
-- **Observability** — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue
-- **Resource management** — create/update/delete agents, teams, workflows with validation
-- **Import/export** — portable run bundles for sharing and archiving
-
----
-
-## Install
-
-```bash
-pi install npm:pi-crew
-```
-
-Local development:
-
-```bash
-pi install ./pi-crew
-```
-
-Post-install config bootstrap:
-
-```bash
-pi-crew          # after npm install
-node ./pi-crew/install.mjs   # from local clone
-```
-
----
-
-## Quick Start
-
-### 1. Initialize project
-
-```text
-/team-init
-```
-
-### 2. Run a team
-
-```text
-/team-run Investigate failing tests and propose a fix
-```
-
-Or via tool call:
-
-```json
-{
-  "action": "run",
-  "team": "default",
-  "goal": "Investigate failing tests and propose a fix"
-}
-```
-
-### 3. Check status
-
-```text
-/team-status <runId>
-/team-dashboard
-```
-
-### 4. Get a recommendation
-
-When unsure which team/workflow fits:
-
-```json
-{
-  "action": "recommend",
-  "goal": "Refactor auth flow and add tests"
-}
-```
-
----
-
-## Builtin Teams
-
-| Team | Workflow | Mục đích |
-|------|----------|----------|
-| `default` | explore → plan → execute → verify | Cân bằng, đa năng |
-| `fast-fix` | explore → execute → verify | Sửa bug nhỏ nhanh |
-| `implementation` | Adaptive planner quyết fanout | Multi-file implementation |
-| `review` | explore → code-review → security-review → verify | Code review + security audit |
-| `research` | explore → analyze → write | Nghiên cứu và viết tài liệu |
-
-## Builtin Agents
-
-```
-analyst  ·  critic  ·  executor  ·  explorer  ·  planner  ·  reviewer
-security-reviewer  ·  test-engineer  ·  verifier  ·  writer
-```
-
----
-
-## Runtime Safety
-
-By default, `run` launches each task as a **separate child Pi process**. Workers execute independently and stream output to durable state.
-
-Scaffold/dry-run mode (no real workers):
-
-```json
-{ "runtime": { "mode": "scaffold" } }
-```
-
-Disable workers globally:
-
-```json
-{ "executeWorkers": false }
-```
-
-Worktree mode is **opt-in** and requires a clean repo:
-
-```json
-{
-  "action": "run",
-  "team": "implementation",
-  "goal": "Refactor auth",
-  "workspaceMode": "worktree"
-}
-```
-
----
-
-## Configuration
-
-### Config Paths
-
-| Scope | Path |
-|-------|------|
-| User | `~/.pi/agent/extensions/pi-crew/config.json` |
-| Project (new) | `.crew/config.json` |
-| Project (legacy) | `.pi/teams/config.json` |
-
-### Quick Config
-
-```text
-/team-config                                       # view
-/team-config asyncByDefault=true                    # update
-/team-config runtime.mode=scaffold                  # scaffold mode
-/team-config --unset=asyncByDefault                 # reset
-/team-config autonomous.profile=assisted --project  # project scope
-```
-
-### Key Settings
-
-| Section | Key Settings | Default |
-|---------|-------------|---------|
-| **Runtime** | `mode`: `auto` \| `scaffold` \| `child-process` \| `live-session` | `auto` |
-| **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent (2–4) |
-| **Async** | `asyncByDefault`, `runtime.groupJoin` | `false`, `smart` |
-| **Autonomy** | `profile`: `manual` \| `suggested` \| `assisted` \| `aggressive` | `suggested` |
-| **UI** | `widgetPlacement`, `dashboardPlacement`, `showModel`, `showTokens` | compact widget |
-| **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | all opt-in |
-| **Observability** | `prometheus.enabled`, `otlp.enabled` | opt-in |
-
-> ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only.
-
-📖 Full config reference: [docs/configuration.md](docs/configuration.md) *(coming soon — see [docs/usage.md](docs/usage.md) for now)*
-
----
-
-## Tool Actions
-
-```json
-{ "action": "run", "team": "default", "goal": "..." }       // execute
-{ "action": "status", "runId": "team_..." }                   // monitor
-{ "action": "cancel", "runId": "team_..." }                   // stop
-{ "action": "resume", "runId": "team_..." }                   // continue
-{ "action": "recommend", "goal": "..." }                       // get advice
-{ "action": "list" }                                            // discover
-{ "action": "create", "resource": "agent", ... }              // extend
-{ "action": "doctor" }                                          // diagnose
-```
-
-📖 Full actions reference: [docs/actions-reference.md](docs/actions-reference.md)
-
----
-
-## Slash Commands
-
-```text
-/team-run [--team=X] [--async] [--worktree] <goal>
-/team-status <runId>
-/team-dashboard
-/team-doctor
-/team-init [--copy-builtins]
-/team-config [key=value]
-/team-autonomy [status|on|off|suggested|assisted]
-```
-
-📖 Full commands reference: [docs/commands-reference.md](docs/commands-reference.md)
-
----
-
-## Resource Discovery
-
-Agents, teams, and workflows are discovered from three layers:
-
-```
-builtin (package)  <  user (~/.pi/agent/)  <  project (.crew/ or .pi/teams/)
-```
-
-Project resources can add new names but **cannot shadow** builtin/user resources.
-
-### Resource Paths
-
-| Type | Builtin | User | Project |
-|------|---------|------|---------|
-| Agent | `agents/*.md` | `~/.pi/agent/agents/*.md` | `.crew/agents/*.md` |
-| Team | `teams/*.team.md` | `~/.pi/agent/teams/*.team.md` | `.crew/teams/*.team.md` |
-| Workflow | `workflows/*.workflow.md` | `~/.pi/agent/workflows/*.workflow.md` | `.crew/workflows/*.workflow.md` |
-
-### Custom Resources with Routing Metadata
-
-```yaml
----
-name: api-reviewer
-description: Reviews API changes
-triggers: api, endpoint, contract
-useWhen: backend API changes, OpenAPI changes
-avoidWhen: docs-only edits
-cost: cheap
-category: backend
----
-Your system prompt here.
-```
-
-📖 Full resource formats: [docs/resource-formats.md](docs/resource-formats.md)
-
----
-
-## State Layout
-
-```
-<crewRoot>/                          # .crew/ (new) or .pi/teams/ (legacy)
-├── state/runs/{runId}/
-│   ├── manifest.json                # run metadata
-│   ├── tasks.json                   # task graph + status
-│   ├── events.jsonl                 # append-only events
-│   └── agents/{taskId}/status.json  # per-agent state
-├── artifacts/{runId}/
-│   ├── goal.md
-│   ├── prompts/{taskId}.md
-│   ├── results/{taskId}.txt
-│   ├── logs/{taskId}.log
-│   └── summary.md
-├── worktrees/{runId}/{taskId}/
-└── imports/{runId}/run-export.json
-```
-
----
-
-## Environment Variables
-
-| Variable | Purpose |
-|----------|---------|
-| `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) |
-| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag |
-| `PI_TEAMS_MOCK_CHILD_PI=success` | Mock child worker for testing |
-| `PI_TEAMS_PI_BIN=<path>` | Explicit Pi CLI path |
-| `PI_TEAMS_HOME=<path>` | Override home for tests |
-
----
-
-## Development
-
-```bash
-cd pi-crew
-npm install          # dependencies
-npm test             # unit + integration tests
-npm run typecheck    # tsc --noEmit
-npm run ci           # full CI-equivalent check
-npm pack --dry-run   # package verification
-```
-
-CI runs on: `ubuntu-latest` · `windows-latest` · `macos-latest`
-
----
-
-## Documentation
-
-| Doc | Contents |
-|-----|----------|
-| [docs/actions-reference.md](docs/actions-reference.md) | Full tool actions + examples |
-| [docs/commands-reference.md](docs/commands-reference.md) | Slash commands + `/team-api` |
-| [docs/resource-formats.md](docs/resource-formats.md) | Agent/team/workflow file formats |
-| [docs/usage.md](docs/usage.md) | Usage patterns + config examples |
-| [docs/architecture.md](docs/architecture.md) | Internal architecture + run flow |
-| [docs/runtime-flow.md](docs/runtime-flow.md) | Runtime execution details |
-| [docs/live-mailbox-runtime.md](docs/live-mailbox-runtime.md) | Mailbox + live-session runtime |
-| [docs/publishing.md](docs/publishing.md) | Release & publish process |
-| [docs/next-upgrade-roadmap.md](docs/next-upgrade-roadmap.md) | Future upgrade roadmap |
-| [schema.json](schema.json) | Config JSON schema |
-
-Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/baphuongna/pi-crew/tree/main/docs) — audits, deep research, distillation notes.
-
----
-
-## Acknowledgements
-
-`pi-crew` builds on ideas and selected MIT-licensed implementation patterns from `pi-subagents` and `oh-my-claudecode`, with conceptual inspiration from `oh-my-openagent`.
+# pi-crew
+
+**Coordinate AI agent teams inside [Pi](https://github.com/nicekate/pi-coding-agent).**
+
+pi-crew is a Pi extension that orchestrates autonomous multi-agent workflows — research, implementation, review, testing, and more — with durable state, parallel execution, worktree isolation, and safe defaults.
+
+```text
+npm: pi-crew
+repo: https://github.com/baphuongna/pi-crew
+```
+
+**v0.2.0**: Security hardening + 76% faster startup. See [CHANGELOG.md](CHANGELOG.md).
+
+---
+
+## Features
+
+- **One Pi tool** — `team` handles routing, planning, execution, review, and cleanup
+- **Autonomous delegation** — policy injection decides when/how to delegate based on task complexity
+- **Real child Pi workers** — each task spawns a separate Pi process by default; scaffold/dry-run opt-out
+- **Adaptive planning** — implementation workflow lets a planner agent decide subagent fanout
+- **Parallel execution** — tasks in the same phase run concurrently with configurable concurrency
+- **Durable state** — manifest, tasks, events, artifacts all persisted to disk
+- **Async/background runs** — detached runs survive session switches with completion notifications
+- **Worktree isolation** — opt-in git worktrees per task for safe parallel edits
+- **Rich UI** — live widget, dashboard, progress tracking, model/token display
+- **Observability** — metrics registry, Prometheus/OTLP exporters, heartbeat watching, deadletter queue
+- **Resource management** — create/update/delete agents, teams, workflows with validation
+- **Import/export** — portable run bundles for sharing and archiving
+
+---
+
+## Install
+
+```bash
+pi install npm:pi-crew
+```
+
+Local development:
+
+```bash
+pi install ./pi-crew
+```
+
+Post-install config bootstrap:
+
+```bash
+pi-crew          # after npm install
+node ./pi-crew/install.mjs   # from local clone
+```
+
+---
+
+## Quick Start
+
+### 1. Initialize project
+
+```text
+/team-init
+```
+
+### 2. Run a team
+
+```text
+/team-run Investigate failing tests and propose a fix
+```
+
+Or via tool call:
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Investigate failing tests and propose a fix"
+}
+```
+
+### 3. Check status
+
+```text
+/team-status <runId>
+/team-dashboard
+```
+
+### 4. Get a recommendation
+
+When unsure which team/workflow fits:
+
+```json
+{
+  "action": "recommend",
+  "goal": "Refactor auth flow and add tests"
+}
+```
+
+---
+
+## Builtin Teams
+
+| Team | Workflow | Mục đích |
+|------|----------|----------|
+| `default` | explore → plan → execute → verify | Cân bằng, đa năng |
+| `fast-fix` | explore → execute → verify | Sửa bug nhỏ nhanh |
+| `implementation` | Adaptive planner quyết fanout | Multi-file implementation |
+| `review` | explore → code-review → security-review → verify | Code review + security audit |
+| `research` | explore → analyze → write | Nghiên cứu và viết tài liệu |
+
+## Builtin Agents
+
+```
+analyst  ·  critic  ·  executor  ·  explorer  ·  planner  ·  reviewer
+security-reviewer  ·  test-engineer  ·  verifier  ·  writer
+```
+
+---
+
+## Runtime Safety
+
+By default, `run` launches each task as a **separate child Pi process**. Workers execute independently and stream output to durable state.
+
+Scaffold/dry-run mode (no real workers):
+
+```json
+{ "runtime": { "mode": "scaffold" } }
+```
+
+Disable workers globally:
+
+```json
+{ "executeWorkers": false }
+```
+
+Worktree mode is **opt-in** and requires a clean repo:
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor auth",
+  "workspaceMode": "worktree"
+}
+```
+
+---
+
+## Configuration
+
+### Config Paths
+
+| Scope | Path |
+|-------|------|
+| User | `~/.pi/agent/extensions/pi-crew/config.json` |
+| Project (new) | `.crew/config.json` |
+| Project (legacy) | `.pi/teams/config.json` |
+
+### Quick Config
+
+```text
+/team-config                                       # view
+/team-config asyncByDefault=true                    # update
+/team-config runtime.mode=scaffold                  # scaffold mode
+/team-config --unset=asyncByDefault                 # reset
+/team-config autonomous.profile=assisted --project  # project scope
+```
+
+### Key Settings
+
+| Section | Key Settings | Default |
+|---------|-------------|---------|
+| **Runtime** | `mode`: `auto` \| `scaffold` \| `child-process` \| `live-session` | `auto` |
+| **Concurrency** | `limits.maxConcurrentWorkers` | workflow-dependent (2–4) |
+| **Async** | `asyncByDefault`, `runtime.groupJoin` | `false`, `smart` |
+| **Autonomy** | `profile`: `manual` \| `suggested` \| `assisted` \| `aggressive` | `suggested` |
+| **UI** | `widgetPlacement`, `dashboardPlacement`, `showModel`, `showTokens` | compact widget |
+| **Reliability** | `autoRetry`, `autoRecover`, `deadletterThreshold` | all opt-in |
+| **Observability** | `prometheus.enabled`, `otlp.enabled` | opt-in |
+
+> ⚠️ **Trust boundary**: project config cannot override sensitive execution controls (workers, runtime mode, autonomy, agent overrides). Set those in **user config** only.
+
+📖 Full config reference: [docs/configuration.md](docs/configuration.md) *(coming soon — see [docs/usage.md](docs/usage.md) for now)*
+
+---
+
+## Tool Actions
+
+```json
+{ "action": "run", "team": "default", "goal": "..." }       // execute
+{ "action": "status", "runId": "team_..." }                   // monitor
+{ "action": "cancel", "runId": "team_..." }                   // stop
+{ "action": "resume", "runId": "team_..." }                   // continue
+{ "action": "recommend", "goal": "..." }                       // get advice
+{ "action": "list" }                                            // discover
+{ "action": "create", "resource": "agent", ... }              // extend
+{ "action": "doctor" }                                          // diagnose
+```
+
+📖 Full actions reference: [docs/actions-reference.md](docs/actions-reference.md)
+
+---
+
+## Slash Commands
+
+```text
+/team-run [--team=X] [--async] [--worktree] <goal>
+/team-status <runId>
+/team-dashboard
+/team-doctor
+/team-init [--copy-builtins]
+/team-config [key=value]
+/team-autonomy [status|on|off|suggested|assisted]
+```
+
+📖 Full commands reference: [docs/commands-reference.md](docs/commands-reference.md)
+
+---
+
+## Resource Discovery
+
+Agents, teams, and workflows are discovered from three layers:
+
+```
+builtin (package)  <  user (~/.pi/agent/)  <  project (.crew/ or .pi/teams/)
+```
+
+Project resources can add new names but **cannot shadow** builtin/user resources.
+
+### Resource Paths
+
+| Type | Builtin | User | Project |
+|------|---------|------|---------|
+| Agent | `agents/*.md` | `~/.pi/agent/agents/*.md` | `.crew/agents/*.md` |
+| Team | `teams/*.team.md` | `~/.pi/agent/teams/*.team.md` | `.crew/teams/*.team.md` |
+| Workflow | `workflows/*.workflow.md` | `~/.pi/agent/workflows/*.workflow.md` | `.crew/workflows/*.workflow.md` |
+
+### Custom Resources with Routing Metadata
+
+```yaml
+---
+name: api-reviewer
+description: Reviews API changes
+triggers: api, endpoint, contract
+useWhen: backend API changes, OpenAPI changes
+avoidWhen: docs-only edits
+cost: cheap
+category: backend
+---
+Your system prompt here.
+```
+
+📖 Full resource formats: [docs/resource-formats.md](docs/resource-formats.md)
+
+---
+
+## State Layout
+
+```
+<crewRoot>/                          # .crew/ (new) or .pi/teams/ (legacy)
+├── state/runs/{runId}/
+│   ├── manifest.json                # run metadata
+│   ├── tasks.json                   # task graph + status
+│   ├── events.jsonl                 # append-only events
+│   └── agents/{taskId}/status.json  # per-agent state
+├── artifacts/{runId}/
+│   ├── goal.md
+│   ├── prompts/{taskId}.md
+│   ├── results/{taskId}.txt
+│   ├── logs/{taskId}.log
+│   └── summary.md
+├── worktrees/{runId}/{taskId}/
+└── imports/{runId}/run-export.json
+```
+
+---
+
+## Environment Variables
+
+| Variable | Purpose |
+|----------|---------|
+| `PI_CREW_EXECUTE_WORKERS=0` | Disable child workers (scaffold mode) |
+| `PI_TEAMS_EXECUTE_WORKERS=0` | Legacy disable flag |
+| `PI_TEAMS_MOCK_CHILD_PI=success` | Mock child worker for testing |
+| `PI_TEAMS_PI_BIN=<path>` | Explicit Pi CLI path |
+| `PI_TEAMS_HOME=<path>` | Override home for tests |
+
+---
+
+## Development
+
+```bash
+cd pi-crew
+npm install          # dependencies
+npm test             # unit + integration tests
+npm run typecheck    # tsc --noEmit
+npm run ci           # full CI-equivalent check
+npm pack --dry-run   # package verification
+```
+
+CI runs on: `ubuntu-latest` · `windows-latest` · `macos-latest`
+
+---
+
+## Documentation
+
+| Doc | Contents |
+|-----|----------|
+| [docs/actions-reference.md](docs/actions-reference.md) | Full tool actions + examples |
+| [docs/commands-reference.md](docs/commands-reference.md) | Slash commands + `/team-api` |
+| [docs/resource-formats.md](docs/resource-formats.md) | Agent/team/workflow file formats |
+| [docs/usage.md](docs/usage.md) | Usage patterns + config examples |
+| [docs/architecture.md](docs/architecture.md) | Internal architecture + run flow |
+| [docs/runtime-flow.md](docs/runtime-flow.md) | Runtime execution details |
+| [docs/live-mailbox-runtime.md](docs/live-mailbox-runtime.md) | Mailbox + live-session runtime |
+| [docs/publishing.md](docs/publishing.md) | Release & publish process |
+| [docs/next-upgrade-roadmap.md](docs/next-upgrade-roadmap.md) | Future upgrade roadmap |
+| [schema.json](schema.json) | Config JSON schema |
+
+Research docs (not in package): [`docs/pi-crew-research/`](https://github.com/baphuongna/pi-crew/tree/main/docs) — audits, deep research, distillation notes.
+
+---
+
+## Acknowledgements
+
+`pi-crew` builds on ideas and selected MIT-licensed implementation patterns from `pi-subagents` and `oh-my-claudecode`, with conceptual inspiration from `oh-my-openagent`.