pi-crew 0.8.13 → 0.9.0

package/docs/actions-reference.md

@@ -1,52 +1,58 @@
 # pi-crew — Tool Actions Reference
 
-Tool `team` là công cụ chính mà pi-crew đăng ký vào Pi. Mọi thao tác đều đi qua `action`.
+The `team` tool is the primary tool that pi-crew registers with Pi. All operations go through `action`.
 
 ## Quick Reference
 
-| Action | Purpose | Trọng tâm |
-|--------|---------|-----------|
-| `recommend` | Gợi ý team/workflow phù hợp | Bắt đầu khi chưa chắc chọn gì |
-| `run` | Tạo run và thực thi workflow | Thao tác chính |
-| `plan` | Preview workflow không chạy tasks | Dry-run planning |
-| `orchestrate` | Execute từ plan document | Tự động hóa plan |
-| `schedule` | Lên lịch recurring runs | Tự động định kỳ |
-| `scheduled` | List scheduled jobs | Xem lịch trình |
-| `status` | Đọc trạng thái run | Theo dõi tiến độ |
-| `summary` | Đọc/ghi run summary artifact | Tổng kết |
-| `cancel` | Hủy queued/running work | Dừng run |
-| `resume` | Re-queue failed/cancelled tasks | Tiếp tục run |
-| `list` | List teams, agents, workflows, runs | Khám phá tài nguyên |
-| `get` | Inspect agent/team/workflow | Xem chi tiết |
-| `search` | BM25 ranked agent/team discovery | Tìm kiếm thông minh |
-| `events` | Đọc event log | Debug/audit |
-| `artifacts` | List run artifacts | Xem outputs |
-| `worktrees` | List run worktree metadata | Kiểm tra worktrees |
-| `graph` | Load/save/list run graphs | Trực quan hóa |
-| `cleanup` | Xóa run worktrees | Dọn dẹp |
-| `forget` | Xóa run state/artifacts | Xóa hẳn (cần `confirm`) |
-| `prune` | Xóa nhiều old finished runs | Dọn dẹp hàng loạt |
-| `export` | Export portable run bundle | Chia sẻ/backup |
-| `import` | Import run bundle | Nhận run từ nơi khác |
-| `imports` | List imported bundles | Xem imports |
-| `create` | Tạo agent/team/workflow | Mở rộng tài nguyên |
-| `update` | Cập nhật agent/team/workflow | Sửa tài nguyên |
-| `delete` | Xóa agent/team/workflow | Xóa tài nguyên (cần `confirm`) |
-| `validate` | Validate resources | Kiểm tra sức khỏe |
-| `doctor` | Kiểm tra readiness | Chẩn đoán môi trường |
-| `config` | Show/update config | Cấu hình |
-| `init` | Khởi tạo project layout | Setup ban đầu |
-| `autonomy` | Quản lý delegation settings | Điều chỉnh tự động hóa |
-| `api` | Safe interop cho state operations | Tích hợp nâng cao |
-| `help` | Hiển thị help text | Trợ giúp |
+| Action | Purpose | When to use |
+|--------|---------|-------------|
+| `recommend` | Suggest a suitable team/workflow | Starting point when unsure what to pick |
+| `run` | Create a run and execute a workflow | Main operation |
+| `plan` | Preview a workflow without running tasks | Dry-run planning |
+| `orchestrate` | Execute from a plan document | Automate a plan |
+| `schedule` | Schedule recurring runs | Periodic automation |
+| `scheduled` | List scheduled jobs | View schedules |
+| `status` | Read run status | Track progress |
+| `summary` | Read/write run summary artifact | Summarize |
+| `cancel` | Cancel queued/running work | Stop a run |
+| `resume` | Re-queue failed/cancelled tasks | Resume a run |
+| `list` | List teams, agents, workflows, runs | Explore resources |
+| `get` | Inspect agent/team/workflow | View details |
+| `search` | BM25-ranked agent/team discovery | Smart search |
+| `events` | Read the event log | Debug/audit |
+| `artifacts` | List run artifacts | View outputs |
+| `worktrees` | List run worktree metadata | Inspect worktrees |
+| `graph` | Load/save/list run graphs | Visualization |
+| `cleanup` | Delete run worktrees | Cleanup |
+| `forget` | Delete run state/artifacts | Remove entirely (requires `confirm`) |
+| `prune` | Delete multiple old finished runs | Bulk cleanup |
+| `export` | Export a portable run bundle | Share/backup |
+| `import` | Import a run bundle | Receive a run from elsewhere |
+| `imports` | List imported bundles | View imports |
+| `create` | Create an agent/team/workflow | Extend resources |
+| `update` | Update an agent/team/workflow | Edit resources |
+| `delete` | Delete an agent/team/workflow | Remove resources (requires `confirm`) |
+| `validate` | Validate resources | Health check |
+| `doctor` | Check readiness | Diagnose environment |
+| `config` | Show/update config | Configuration |
+| `init` | Initialize project layout | Initial setup |
+| `autonomy` | Manage delegation settings | Adjust automation |
+| `api` | Safe interop for state operations | Advanced integration |
+| **`goal`** | **v0.9.0** Autonomous goal loop (worker → LLM judge → feedback → iterate) | Autonomous multi-turn |
+| **`workflow-create`** | **v0.9.0** Create a `.dwf.ts` (requires `confirm:true`, ACE-gated) | Author dynamic workflow |
+| **`workflow-get`** | **v0.9.0** View source + metadata of a dynamic workflow | Inspect `.dwf.ts` |
+| **`workflow-list`** | **v0.9.0** List static + dynamic workflows | Discover workflows |
+| **`workflow-save`** | **v0.9.0** Overwrite `.dwf.ts` source (requires `confirm:true`) | Update dynamic workflow |
+| **`workflow-delete`** | **v0.9.0** Delete a `.dwf.ts` (requires `confirm:true`) | Remove dynamic workflow |
+| `help` | Display help text | Help |
 
 ---
 
-## Chi tiết từng Action
+## Action Details
 
-### `recommend` — Gợi ý định hướng
+### `recommend` — Guided suggestions
 
-Khi chưa biết dùng team/workflow nào, gọi `recommend` để nhận phân tích + đề xuất:
+When you are unsure which team/workflow to use, call `recommend` to get analysis and suggestions:
 
 ```json
 {
@@ -55,19 +61,19 @@ Khi chưa biết dùng team/workflow nào, gọi `recommend` để nhận phân
 }
 ```
 
-Response gồm:
-- Team/workflow được gợi ý
-- Fanout hints (bao nhiêu subagents)
-- Có nên async hay worktree không
-- Lý do lựa chọn
+The response includes:
+- The suggested team/workflow
+- Fanout hints (how many subagents)
+- Whether to use async or worktree mode
+- The rationale for the choice
 
 ---
 
-### `run` — Thực thi workflow
+### `run` — Execute a workflow
 
-Đây là action chính. Tạo run manifest, task graph, và thực thi.
+This is the main action. It creates a run manifest, a task graph, and executes it.
 
-#### Cú pháp cơ bản
+#### Basic syntax
 
 ```json
 {
@@ -77,17 +83,17 @@ Response gồm:
 }
 ```
 
-#### Chọn team
+#### Choose a team
 
-| Team | Mục đích |
-|------|----------|
-| `default` | Cân bằng, 4 bước: explore → plan → execute → verify |
-| `fast-fix` | Sửa bug nhỏ: explore → execute → verify |
-| `implementation` | Adaptive planner tự quyết fanout |
+| Team | Purpose |
+|------|---------|
+| `default` | Balanced, 4 steps: explore → plan → execute → verify |
+| `fast-fix` | Small bug fixes: explore → execute → verify |
+| `implementation` | Adaptive planner decides fanout on its own |
 | `review` | Code review + security review |
-| `research` | Nghiên cứu và viết tài liệu |
+| `research` | Research and documentation writing |
 
-#### Chạy bất đồng bộ (async)
+#### Run asynchronously (async)
 
 ```json
 {
@@ -98,7 +104,7 @@ Response gồm:
 }
 ```
 
-Run tách riêng khỏi session, có thể sống qua session switch/reload. Pi-crew tự động notify khi run hoàn thành.
+The run is detached from the session and survives session switches/reloads. pi-crew automatically notifies you when the run completes.
 
 #### Worktree isolation
 
@@ -111,7 +117,7 @@ Run tách riêng khỏi session, có thể sống qua session switch/reload. Pi-
 }
 ```
 
-Mỗi task chạy trong git worktree riêng — an toàn cho codebase chính. Yêu cầu repo clean.
+Each task runs in its own git worktree — safe for the main codebase. Requires a clean repo.
 
 #### Override model
 
@@ -124,7 +130,7 @@ Mỗi task chạy trong git worktree riêng — an toàn cho codebase chính. Y
 }
 ```
 
-#### Override config cho run
+#### Override config for a run
 
 ```json
 {
@@ -140,7 +146,7 @@ Mỗi task chạy trong git worktree riêng — an toàn cho codebase chính. Y
 
 #### Plan approval gate
 
-Yêu cầu explicit approve sau khi planner tạo plan, trước khi executor chạy:
+Requires explicit approval after the planner creates the plan, before the executor runs:
 
 ```json
 {
@@ -175,9 +181,9 @@ Cancel plan:
 
 ---
 
-### `plan` — Preview workflow
+### `plan` — Preview a workflow
 
-Giống `run` nhưng **không spawn workers**. Xem trước task graph sẽ tạo:
+Like `run` but **does not spawn workers**. Previews the task graph that would be created:
 
 ```json
 {
@@ -189,9 +195,9 @@ Giống `run` nhưng **không spawn workers**. Xem trước task graph sẽ tạ
 
 ---
 
-### `orchestrate` — Execute từ plan document
+### `orchestrate` — Execute from a plan document
 
-Thực thi workflow từ plan document có tag sections:
+Executes a workflow from a plan document that contains tagged sections:
 
 ```markdown
 # Design Phase
@@ -220,9 +226,9 @@ TAG→chain mapping:
 
 ---
 
-### `schedule` — Lên lịch recurring runs
+### `schedule` — Schedule recurring runs
 
-Tạo scheduled job với cron, interval, hoặc once:
+Creates a scheduled job using cron, interval, or once:
 
 ```json
 {
@@ -258,9 +264,9 @@ Params: `cron`, `interval` (ms), `once` (ISO timestamp)
 
 ---
 
-### `search` — BM25 ranked discovery
+### `search` — BM25-ranked discovery
 
-Tìm kiếm agents/teams/workflows với BM25 ranking:
+Search agents/teams/workflows with BM25 ranking:
 
 ```json
 {
@@ -271,7 +277,7 @@ Tìm kiếm agents/teams/workflows với BM25 ranking:
 
 ---
 
-### `status` — Trạng thái run
+### `status` — Run status
 
 ```json
 {
@@ -280,13 +286,13 @@ Tìm kiếm agents/teams/workflows với BM25 ranking:
 }
 ```
 
-Output gồm: manifest, tasks, agents, timing, usage totals.
+Output includes: manifest, tasks, agents, timing, usage totals.
 
 ---
 
-### `summary` — Tổng kết run
+### `summary` — Run summary
 
-Đọc summary:
+Read summary:
 
 ```json
 {
@@ -295,7 +301,7 @@ Output gồm: manifest, tasks, agents, timing, usage totals.
 }
 ```
 
-Ghi summary:
+Write summary:
 
 ```json
 {
@@ -307,7 +313,7 @@ Ghi summary:
 
 ---
 
-### `cancel` — Hủy run
+### `cancel` — Cancel a run
 
 ```json
 {
@@ -316,11 +322,11 @@ Ghi summary:
 }
 ```
 
-Hủy tất cả queued/running tasks. Running child processes nhận SIGTERM.
+Cancels all queued/running tasks. Running child processes receive SIGTERM.
 
 ---
 
-### `resume` — Tiếp tục run
+### `resume` — Resume a run
 
 ```json
 {
@@ -329,11 +335,11 @@ Hủy tất cả queued/running tasks. Running child processes nhận SIGTERM.
 }
 ```
 
-Re-queue failed/cancelled/skipped tasks. Tasks đã completed không bị ảnh hưởng.
+Re-queues failed/cancelled/skipped tasks. Already-completed tasks are unaffected.
 
 ---
 
-### `list` — Liệt kê tài nguyên
+### `list` — List resources
 
 ```json
 {
@@ -341,11 +347,11 @@ Re-queue failed/cancelled/skipped tasks. Tasks đã completed không bị ảnh
 }
 ```
 
-Hiển thị: teams, agents, workflows đã discover, và recent runs.
+Displays: discovered teams, agents, workflows, and recent runs.
 
 ---
 
-### `get` — Xem chi tiết tài nguyên
+### `get` — Inspect resource details
 
 ```json
 {
@@ -392,7 +398,7 @@ Append-only JSONL events: task.started, task.completed, run.blocked, etc.
 
 ---
 
-### `cleanup` — Xóa worktrees
+### `cleanup` — Delete worktrees
 
 ```json
 {
@@ -401,11 +407,11 @@ Append-only JSONL events: task.started, task.completed, run.blocked, etc.
 }
 ```
 
-Dirty worktrees được giữ lại trừ khi `force: true`.
+Dirty worktrees are kept unless `force: true`.
 
 ---
 
-### `forget` — Xóa run hoàn toàn
+### `forget` — Delete a run entirely
 
 ```json
 {
@@ -415,11 +421,11 @@ Dirty worktrees được giữ lại trừ khi `force: true`.
 }
 ```
 
-Xóa state + artifacts + worktrees. Cần `confirm: true`.
+Deletes state + artifacts + worktrees. Requires `confirm: true`.
 
 ---
 
-### `prune` — Xóa nhiều runs cũ
+### `prune` — Delete old runs
 
 ```json
 {
@@ -429,11 +435,11 @@ Xóa state + artifacts + worktrees. Cần `confirm: true`.
 }
 ```
 
-Giữ lại `keep` runs gần nhất, xóa phần còn lại.
+Keeps the `keep` most recent runs and deletes the rest.
 
 ---
 
-### `export` / `import` — Chia sẻ runs
+### `export` / `import` — Share runs
 
 Export:
 
@@ -473,9 +479,9 @@ List imports:
 
 ---
 
-### `create` — Tạo tài nguyên
+### `create` — Create resources
 
-Tạo agent:
+Create an agent:
 
 ```json
 {
@@ -495,7 +501,7 @@ Tạo agent:
 }
 ```
 
-Tạo team:
+Create a team:
 
 ```json
 {
@@ -515,7 +521,7 @@ Tạo team:
 }
 ```
 
-Tạo workflow:
+Create a workflow:
 
 ```json
 {
@@ -534,7 +540,7 @@ Tạo workflow:
 
 ---
 
-### `update` — Cập nhật tài nguyên
+### `update` — Update resources
 
 ```json
 {
@@ -547,11 +553,11 @@ Tạo workflow:
 }
 ```
 
-`updateReferences: true` sẽ tự động cập nhật tất cả team references trỏ đến tên cũ.
+`updateReferences: true` automatically updates all team references pointing to the old name.
 
 ---
 
-### `delete` — Xóa tài nguyên
+### `delete` — Delete resources
 
 ```json
 {
@@ -563,11 +569,11 @@ Tạo workflow:
 }
 ```
 
-Backup tự động trước khi xóa.
+Creates a backup automatically before deleting.
 
 ---
 
-### `validate` — Kiểm tra tài nguyên
+### `validate` — Validate resources
 
 ```json
 {
@@ -575,11 +581,11 @@ Backup tự động trước khi xóa.
 }
 ```
 
-Kiểm tra: agents, teams, workflows, references, model hints.
+Checks: agents, teams, workflows, references, model hints.
 
 ---
 
-### `doctor` — Chẩn đoán môi trường
+### `doctor` — Diagnose environment
 
 ```json
 {
@@ -587,7 +593,7 @@ Kiểm tra: agents, teams, workflows, references, model hints.
 }
 ```
 
-Kiểm tra: cwd, platform, Node.js, Pi version, git, state paths, config, resources, model/provider.
+Checks: cwd, platform, Node.js, Pi version, git, state paths, config, resources, model/provider.
 
 Smoke test child Pi (explicit):
 
@@ -600,9 +606,9 @@ Smoke test child Pi (explicit):
 
 ---
 
-### `api` — State interop nâng cao
+### `api` — Advanced state interop
 
-Safe API cho run/task/event/heartbeat/claim/mailbox operations:
+Safe API for run/task/event/heartbeat/claim/mailbox operations:
 
 ```text
 /team-api <runId> <operation> [key=value]
@@ -610,30 +616,30 @@ Safe API cho run/task/event/heartbeat/claim/mailbox operations:
 
 Operations:
 
-| Operation | Mô tả |
-|-----------|-------|
-| `read-manifest` | Đọc manifest |
-| `list-tasks` | Liệt kê tasks |
-| `read-task` | Đọc task (cần `taskId=`) |
-| `read-events` | Đọc event log |
-| `read-heartbeat` | Đọc heartbeat (cần `taskId=`) |
-| `write-heartbeat` | Ghi heartbeat (cần `taskId=`, `alive=`) |
-| `claim-task` | Claim task (cần `taskId=`, `owner=`) |
-| `release-task-claim` | Release claim |
-| `transition-task-status` | Chuyển task status |
-| `send-message` | Gửi mailbox message |
-| `read-mailbox` | Đọc mailbox |
-| `ack-message` | Acknowledge message |
-| `read-delivery` | Đọc delivery state |
-| `validate-mailbox` | Validate/sửa mailbox |
-| `approve-plan` | Approve plan (khi requirePlanApproval) |
-| `cancel-plan` | Cancel plan |
+| Operation | Description |
+|-----------|-------------|
+| `read-manifest` | Read the manifest |
+| `list-tasks` | List tasks |
+| `read-task` | Read a task (requires `taskId=`) |
+| `read-events` | Read the event log |
+| `read-heartbeat` | Read a heartbeat (requires `taskId=`) |
+| `write-heartbeat` | Write a heartbeat (requires `taskId=`, `alive=`) |
+| `claim-task` | Claim a task (requires `taskId=`, `owner=`) |
+| `release-task-claim` | Release a claim |
+| `transition-task-status` | Transition task status |
+| `send-message` | Send a mailbox message |
+| `read-mailbox` | Read the mailbox |
+| `ack-message` | Acknowledge a message |
+| `read-delivery` | Read delivery state |
+| `validate-mailbox` | Validate/repair mailbox |
+| `approve-plan` | Approve a plan (when requirePlanApproval) |
+| `cancel-plan` | Cancel a plan |
 
 ---
 
-### `config` — Cấu hình
+### `config` — Configuration
 
-Xem config hiện tại:
+View current config:
 
 ```json
 { "action": "config" }
@@ -659,7 +665,7 @@ Unset:
 
 ---
 
-### `init` — Khởi tạo project
+### `init` — Initialize project
 
 ```json
 { "action": "init" }

package/docs/architecture.md

@@ -2,7 +2,7 @@
 
 `pi-crew` is a Pi package for coordinated multi-agent work. It is intentionally durable-first: every run is represented on disk, every task has a state record, and child workers stream progress into JSONL/status files so foreground sessions, background jobs, dashboards, and later restarts all read the same source of truth.
 
-**Current version:** v0.5.22 — 38 rounds of code review hardening (see [CHANGELOG.md](../CHANGELOG.md)).
+**Current version:** v0.9.0 — 100+ rounds of code review hardening (see [CHANGELOG.md](../CHANGELOG.md)).
 
 ## Layers