pi-crew 0.1.51 → 0.2.0

package/docs/actions-reference.md

@@ -0,0 +1,595 @@
+# 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`.
+
+## 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 |
+| `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 |
+| `events` | Đọc event log | Debug/audit |
+| `artifacts` | List run artifacts | Xem outputs |
+| `worktrees` | List run worktree metadata | Kiểm tra worktrees |
+| `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 |
+
+---
+
+## Chi tiết từng Action
+
+### `recommend` — Gợi ý định hướng
+
+Khi chưa biết dùng team/workflow nào, gọi `recommend` để nhận phân tích + đề xuất:
+
+```json
+{
+  "action": "recommend",
+  "goal": "Refactor auth flow and add tests"
+}
+```
+
+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
+
+---
+
+### `run` — Thực thi workflow
+
+Đây là action chính. Tạo run manifest, task graph, và thực thi.
+
+#### Cú pháp cơ bản
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Investigate failing tests and propose a fix"
+}
+```
+
+#### Chọn 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 |
+| `review` | Code review + security review |
+| `research` | Nghiên cứu và viết tài liệu |
+
+#### Chạy bất đồng bộ (async)
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Implement user settings screen",
+  "async": true
+}
+```
+
+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.
+
+#### Worktree isolation
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Add API endpoint and tests",
+  "workspaceMode": "worktree"
+}
+```
+
+Mỗi task chạy trong git worktree riêng — an toàn cho codebase chính. Yêu cầu repo clean.
+
+#### Override model
+
+```json
+{
+  "action": "run",
+  "team": "default",
+  "goal": "Quick exploration",
+  "model": "gpt-4o-mini"
+}
+```
+
+#### Override config cho run
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Refactor auth",
+  "config": {
+    "runtime": { "requirePlanApproval": true },
+    "limits": { "maxConcurrentWorkers": 4 }
+  }
+}
+```
+
+#### Plan approval gate
+
+Yêu cầu explicit approve sau khi planner tạo plan, trước khi executor chạy:
+
+```json
+{
+  "action": "run",
+  "team": "implementation",
+  "goal": "Major refactor",
+  "config": {
+    "runtime": { "requirePlanApproval": true }
+  }
+}
+```
+
+Approve:
+
+```json
+{
+  "action": "api",
+  "runId": "team_...",
+  "config": { "operation": "approve-plan" }
+}
+```
+
+Cancel plan:
+
+```json
+{
+  "action": "api",
+  "runId": "team_...",
+  "config": { "operation": "cancel-plan" }
+}
+```
+
+---
+
+### `plan` — Preview workflow
+
+Giống `run` nhưng **không spawn workers**. Xem trước task graph sẽ tạo:
+
+```json
+{
+  "action": "plan",
+  "team": "implementation",
+  "goal": "Add authentication module"
+}
+```
+
+---
+
+### `status` — Trạng thái run
+
+```json
+{
+  "action": "status",
+  "runId": "team_..."
+}
+```
+
+Output gồm: manifest, tasks, agents, timing, usage totals.
+
+---
+
+### `summary` — Tổng kết run
+
+Đọc summary:
+
+```json
+{
+  "action": "summary",
+  "runId": "team_..."
+}
+```
+
+Ghi summary:
+
+```json
+{
+  "action": "summary",
+  "runId": "team_...",
+  "message": "Implemented auth with tests. All passing."
+}
+```
+
+---
+
+### `cancel` — Hủy run
+
+```json
+{
+  "action": "cancel",
+  "runId": "team_..."
+}
+```
+
+Hủy tất cả queued/running tasks. Running child processes nhận SIGTERM.
+
+---
+
+### `resume` — Tiếp tục run
+
+```json
+{
+  "action": "resume",
+  "runId": "team_..."
+}
+```
+
+Re-queue failed/cancelled/skipped tasks. Tasks đã completed không bị ảnh hưởng.
+
+---
+
+### `list` — Liệt kê tài nguyên
+
+```json
+{
+  "action": "list"
+}
+```
+
+Hiển thị: teams, agents, workflows đã discover, và recent runs.
+
+---
+
+### `get` — Xem chi tiết tài nguyên
+
+```json
+{
+  "action": "get",
+  "resource": "agent",
+  "agent": "executor"
+}
+```
+
+---
+
+### `events` — Event log
+
+```json
+{
+  "action": "events",
+  "runId": "team_..."
+}
+```
+
+Append-only JSONL events: task.started, task.completed, run.blocked, etc.
+
+---
+
+### `artifacts` — Run outputs
+
+```json
+{
+  "action": "artifacts",
+  "runId": "team_..."
+}
+```
+
+---
+
+### `worktrees` — Worktree metadata
+
+```json
+{
+  "action": "worktrees",
+  "runId": "team_..."
+}
+```
+
+---
+
+### `cleanup` — Xóa worktrees
+
+```json
+{
+  "action": "cleanup",
+  "runId": "team_..."
+}
+```
+
+Dirty worktrees được giữ lại trừ khi `force: true`.
+
+---
+
+### `forget` — Xóa run hoàn toàn
+
+```json
+{
+  "action": "forget",
+  "runId": "team_...",
+  "confirm": true
+}
+```
+
+Xóa state + artifacts + worktrees. Cần `confirm: true`.
+
+---
+
+### `prune` — Xóa nhiều runs cũ
+
+```json
+{
+  "action": "prune",
+  "confirm": true,
+  "keep": 10
+}
+```
+
+Giữ lại `keep` runs gần nhất, xóa phần còn lại.
+
+---
+
+### `export` / `import` — Chia sẻ runs
+
+Export:
+
+```json
+{
+  "action": "export",
+  "runId": "team_..."
+}
+```
+
+Import:
+
+```json
+{
+  "action": "import",
+  "path": "/path/to/run-export.json"
+}
+```
+
+User-global import:
+
+```json
+{
+  "action": "import",
+  "path": "/path/to/run-export.json",
+  "scope": "user"
+}
+```
+
+List imports:
+
+```json
+{
+  "action": "imports"
+}
+```
+
+---
+
+### `create` — Tạo tài nguyên
+
+Tạo agent:
+
+```json
+{
+  "action": "create",
+  "resource": "agent",
+  "config": {
+    "scope": "project",
+    "name": "api-reviewer",
+    "description": "Reviews backend API changes",
+    "systemPrompt": "You review backend API changes for correctness and compatibility.",
+    "triggers": ["api", "endpoint", "contract"],
+    "useWhen": ["backend API change", "OpenAPI contract update"],
+    "avoidWhen": ["documentation-only edits"],
+    "cost": "cheap",
+    "category": "backend"
+  }
+}
+```
+
+Tạo team:
+
+```json
+{
+  "action": "create",
+  "resource": "team",
+  "config": {
+    "name": "backend-team",
+    "description": "Backend implementation team",
+    "scope": "project",
+    "defaultWorkflow": "default",
+    "roles": [
+      { "name": "explorer", "agent": "explorer" },
+      { "name": "executor", "agent": "executor" },
+      { "name": "verifier", "agent": "verifier" }
+    ]
+  }
+}
+```
+
+Tạo workflow:
+
+```json
+{
+  "action": "create",
+  "resource": "workflow",
+  "config": {
+    "name": "quick-review",
+    "scope": "user",
+    "steps": [
+      { "id": "review", "role": "reviewer", "prompt": "Review: {goal}" },
+      { "id": "verify", "role": "verifier", "dependsOn": "review", "verify": true, "prompt": "Verify the review findings." }
+    ]
+  }
+}
+```
+
+---
+
+### `update` — Cập nhật tài nguyên
+
+```json
+{
+  "action": "update",
+  "resource": "agent",
+  "agent": "worker",
+  "scope": "project",
+  "updateReferences": true,
+  "config": { "name": "better-worker", "description": "Improved worker agent" }
+}
+```
+
+`updateReferences: true` sẽ tự động cập nhật tất cả team references trỏ đến tên cũ.
+
+---
+
+### `delete` — Xóa tài nguyên
+
+```json
+{
+  "action": "delete",
+  "resource": "team",
+  "team": "backend-team",
+  "scope": "project",
+  "confirm": true
+}
+```
+
+Backup tự động trước khi xóa.
+
+---
+
+### `validate` — Kiểm tra tài nguyên
+
+```json
+{
+  "action": "validate"
+}
+```
+
+Kiểm tra: agents, teams, workflows, references, model hints.
+
+---
+
+### `doctor` — Chẩn đoán môi trường
+
+```json
+{
+  "action": "doctor"
+}
+```
+
+Kiểm tra: cwd, platform, Node.js, Pi version, git, state paths, config, resources, model/provider.
+
+Smoke test child Pi (explicit):
+
+```json
+{
+  "action": "doctor",
+  "config": { "smokeChildPi": true }
+}
+```
+
+---
+
+### `api` — State interop nâng cao
+
+Safe API cho run/task/event/heartbeat/claim/mailbox operations:
+
+```text
+/team-api <runId> <operation> [key=value]
+```
+
+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 |
+
+---
+
+### `config` — Cấu hình
+
+Xem config hiện tại:
+
+```json
+{ "action": "config" }
+```
+
+Update user config:
+
+```json
+{
+  "action": "config",
+  "config": { "asyncByDefault": true }
+}
+```
+
+Unset:
+
+```json
+{
+  "action": "config",
+  "config": { "autonomous.preferAsyncForLongTasks": "unset" }
+}
+```
+
+---
+
+### `init` — Khởi tạo project
+
+```json
+{ "action": "init" }
+```
+
+Copy builtins:
+
+```json
+{ "action": "init", "config": { "copyBuiltins": true, "overwrite": true } }
+```
+
+---
+
+### `autonomy` — Delegation settings
+
+```json
+{ "action": "autonomy" }
+```
+
+Profiles: `manual`, `suggested`, `assisted`, `aggressive`.