# Command reference tiếng Việt
<!-- language: vi; english-index: docs-site/content/en/commands.html -->

> Nếu cần flow đầy đủ theo thứ tự dùng thật, đọc `docs/operator-manual-vietnamese.md`. File này chỉ là bảng tra cứu command.

File này là bảng tra cứu command chính cho Pi Agent Platform. Mục tiêu là khi anh/team mở Herdr, `cd` vào project, chạy `pi`, thì biết rõ lệnh nào dùng cho việc gì.

## Cách đọc command

Có 5 loại cần phân biệt:

| Loại | Gõ ở đâu | Ví dụ | Ý nghĩa |
|---|---|---|---|
| Runtime slash command | Bên trong Pi TUI | `/usage` | Extension chạy ngay, hiện kết quả/menu, **không gọi model follow-up**. |
| Workflow launcher | Bên trong Pi TUI | `/workflow task <request>` | Runtime command mở menu hoặc gửi workflow prompt rõ ràng cho agent. |
| Workflow alias | Bên trong Pi TUI | `/task <request>` | Alias cũ cho power user; vẫn cần agent turn. Team mới nên dùng `/workflow`. |
| Terminal command | Terminal đã có Bash | `piagent-mcp --preset core` | Cài, kiểm tra, hoặc cấu hình máy/project từ bên ngoài Pi. |
| Pi native/hotkey | Bên trong Pi TUI | `/model`, `Ctrl+L` | Điều khiển native Pi như model/session/MCP. |

Nếu không chắc một slash command có sẵn chưa, mở Pi và gõ `/` để xem danh sách command của session hiện tại. Command có thể khác nhau theo package đã install, provider đã login, và project trust.

## Native Pi vs PiAgent

PiAgent không chiếm các command native đang dùng của Pi. Những command này để Pi xử lý trực tiếp:

| Pi native | Vai trò |
|---|---|
| `/login` | Đăng nhập provider/OAuth. |
| `/model`, `Ctrl+L` | Chọn model/provider. |
| `/name` | Đặt tên session; Piagent nhận rename event để map Agent Watch/report. |
| `/session` | Xem session id/name/token/cost/context hiện tại. |
| `/resume` | Resume session cũ bằng UI/native flow. |
| `/compact` | Nén context bằng Pi native compaction. |
| `/mcp`, `/mcp-auth` | Kiểm tra/kết nối MCP live và OAuth. |

Command ngắn của PiAgent dùng cho workflow và guard local:

| PiAgent runtime | Vai trò |
|---|---|
| `/commands` | Menu/help command, không gọi model. |
| `/workflow` | Launcher task/scout/plan/review/git/onboard. |
| `/usage` | Usage live/history/preflight/compact/logs/efficiency. |
| `/context` | Smart index/rebuild/search/pack/impact/efficiency/preflight/compact. |
| `/permission` | Permission mode của session. |
| `/profile` | Profile và tech stack. |
| `/memory` | Project memory policy. |
| `/onboard` | Project onboarding/status/setup. |
| `/fresh` | Tạo session mới cho workflow. |
| `/piagent-inspector` | Menu quan sát file diff, command, safety và context của task/session. |

Riêng MCP governance vẫn giữ `/piagent-mcp` vì `/mcp` đã là command native của Pi.

## Flow hằng ngày ngắn nhất

Lần đầu trên một project:

```bash
cd /path/to/project
pi
```

Trong Pi:

```text
/login
/model
/commands
/onboard
/context index
/context rebuild
/memory
```

Các lần sau:

```bash
cd /path/to/project
pi
```

Trong Pi:

```text
/workflow task Implement <task cụ thể>.
```

Nếu chỉ scout/audit read-only:

```text
/workflow scout Scout payment FE mapping vs BE. Do not edit source.
```

Nếu session đang nặng hoặc Pi báo context overflow, dùng fresh workflow:

```text
/fresh scout <read-only request>
/fresh task <implementation request>
/fresh be-to-fe <BE-readonly/FE request>
```

Nếu task còn mơ hồ:

```text
/workflow discuss <ý tưởng hoặc yêu cầu thô>
/workflow plan <goal cần bóc tách>
```

## Nguyên tắc command/UX

Pi Agent dùng ít namespace nhưng mỗi namespace có subcommand/menu rõ:

- `/workflow` là cửa chính cho task/scout/review/git/onboard workflow. Workflow cần agent turn là cố ý và được nói rõ.
- `/usage` gom live usage, history/report hint, preflight, compact, logs, efficiency.
- Pi native `/name` đặt tên session theo task; Piagent nhận rename event để Agent Watch/report map đúng việc.
- `/fresh` mở session mới cho `task`, `scout`, hoặc `be-to-fe` khi phiên hiện tại đã nặng.
- `/context` gom architecture map, code index, search, context pack, test impact, efficiency, preflight và semantic compact.
- `/permission` gom permission status/read-only/workspace-write/full-access.
- `/profile` là namespace duy nhất cho profile và tech stack.
- `/commands` là runtime help/menu, không còn bắt agent đọc docs để giải thích.
- `/piagent-inspector` là một namespace quan sát duy nhất; mở menu để tránh sinh thêm command rời.
- Khi user cần chọn, ưu tiên select option. Khi UI select không khả dụng, trả exact command.
- Hành động rủi ro như stage rộng, push, PR write, deploy, publish, thay đổi database hoặc external-provider write vẫn cần xác nhận người vận hành.

## Command chính cho team

Các command này đến từ package `piagent-core`.

| Command | Dùng khi nào | Kết quả mong đợi |
|---|---|---|
| `/commands` | Không nhớ command. | Mở menu/help theo topic, không gọi model. |
| `/workflow` | Muốn chọn task/scout/review/git/onboard bằng menu. | Mở workflow picker. |
| `/workflow task <request>` | Requirement đã rõ và cần implement. | Launch task workflow cho agent. |
| `/workflow scout <request>` | Cần scout/audit read-only. | Launch scout workflow cho agent. |
| `/workflow be-to-fe <request>` | BE read-only, FE implementation. | Launch BE→FE workflow. |
| `/workflow discuss <idea>` | Task còn mơ hồ. | Launch clarify workflow, không sửa code. |
| `/workflow plan <goal>` | Cần plan trước khi sửa. | Launch plan workflow. |
| `/workflow review <target>` | Review diff/source. | Launch review workflow. |
| `/workflow commit [message]` | Diff đã review và muốn commit local. | Launch guarded commit workflow. |
| `/workflow pr [title]` | Branch đã commit và muốn chuẩn bị PR. | Launch guarded PR workflow. |
| `/workflow onboard [focus]` | First-read onboarding cần agent đọc project. | Launch onboarding workflow để ghi `.pi/project-context.md` và context index. |
| `/onboard` | First-run setup/status. | Mở menu onboarding: status, run, profile, setup. |
| `/profile` | Xem/áp profile và chọn tech. | Chạy ngay, không gọi model. |
| `/profile setup` | Chọn profile + tech bằng option. | Ghi profile/lock/tech manifest. |
| `/usage` | Xem live usage hoặc report hint. | Menu live/history/preflight/compact/logs/efficiency. |
| `/task-preflight` | Xem product preflight deterministic. | Intent/risk/scope/runtime/solver/phases/tools/helpers/backend/approval có schema/version. |
| `/piagent-status` | Xem product live status deterministic. | Task/phase/checkpoint/resume/recovery/helper/terminal receipt từ persisted evidence. |
| `/piagent-inspector` | Muốn xem Piagent đang làm gì, sửa file nào, diff bao nhiêu dòng, command nào fail/block và context còn bao nhiêu. | Mở menu `summary/files/commands/security/context/toggle`; read-only, không gọi model. |
| `/fresh task|scout|be-to-fe <request>` | Phiên hiện tại đã nặng hoặc muốn tách việc. | Mở session mới có tên và replay workflow prompt gọn. |
| `/context` | Xem index/search/pack/impact/efficiency/preflight/compact. | Menu context, không gọi model. |
| `/permission` | Xem/đổi quyền runtime. | Menu status/read-only/workspace-write/full-access. |
| `/memory` hoặc `/memory-policy` | Xem memory policy. | Chạy ngay, không gọi model. |
| `/model-options` | Xem hướng dẫn model/thinking. | Chạy ngay; chọn model vẫn dùng `/model` hoặc `Ctrl+L`. |
| `/piagent-mcp` | Xem/quản trị MCP trong Pi. | Menu MCP, không gọi model. |

`/piagent-inspector` không thêm bước bắt buộc vào workflow. Panel bốn dòng tự
hiện sát phía trên footer native từ lúc mở session. Khi có Task Contract, panel
dùng các file task đã quan sát; không có task thì dùng working-tree status. View `files` mới tính exact snapshot
delta so với task baseline. Gõ command không kèm option để mở menu, hoặc dùng
trực tiếp:

Panel dùng màu theo mức độ: file cyan, test magenta, dòng thêm xanh lá, dòng
xóa đỏ; command pass xanh lá, blocked vàng, failed và safety warning đỏ. Context
dưới 60% là xanh lá, từ 60% là vàng và từ 80% là đỏ. Có thể đặt `NO_COLOR=1`
nếu terminal cần output không màu.

```text
/piagent-inspector summary
/piagent-inspector files
/piagent-inspector commands
/piagent-inspector security
/piagent-inspector context
/piagent-inspector toggle
/piagent-inspector --json summary
```

`files` tách source/test và hiển thị `+/-`. Nếu task sửa một file đã dirty trước
khi task bắt đầu, scope được ghi `mixed-working-tree` thay vì nhận nhầm toàn bộ
line diff là do task hiện tại. `commands` tách requested/executed/passed/failed/
blocked. `security` chỉ hiện policy block, secret redaction và integrity warning
đã quan sát. `context` dùng exact usage theo turn/session mà Pi cung cấp; token
theo từng built-in tool call luôn ghi unavailable, không ước lượng.

Alias cũ vẫn giữ để không phá thói quen:

| Alias | Command chính |
|---|---|
| `/task <request>` | `/workflow task <request>` |
| `/scout <request>` | `/workflow scout <request>` |
| `/be-to-fe <request>` | `/workflow be-to-fe <request>` |
| `/commit [message]` | `/workflow commit [message]` |
| `/pr [title]` | `/workflow pr [title]` |
| `/setname <name>` | Pi native `/name <name>` |
| `/fresh-task <request>` | `/fresh task <request>` |
| `/fresh-scout <request>` | `/fresh scout <request>` |
| `/fresh-be-to-fe <request>` | `/fresh be-to-fe <request>` |
| `/context-index` | `/context index` |
| `/task-preflight` | `/context preflight` |
| `/permission-status`, `/read-only`, `/workspace-write`, `/full-access` | `/permission ...` |

Git flow của Pi cố ý không dùng namespace `/git-*`. Daily flow là nói tự nhiên hoặc đi qua `/workflow`:

```text
/workflow commit docs: update onboarding notes
/workflow pr Add guarded git workflow
```

Alias `/commit` và `/pr` vẫn chạy. Commit workflow chỉ tạo local commit. PR workflow có thể cần `git push` và GitHub write action, nên guard vẫn bắt agent xác nhận rõ branch/title/scope trước khi đẩy hoặc tạo PR. Các lệnh stage rộng như `git add .`, `git add -A`, `git add --all`, `git add -- .`, `git add :/` cũng bị đưa qua confirmation để tránh gom nhầm file riêng tư hoặc unrelated diff.

## Image/screenshot input

| Tình huống | Cách dùng | Kết quả |
|---|---|---|
| Chat box trả ra local path ảnh | `/workflow scout Check screenshot ~/Documents/team-screenshots/screenshot.png` | Platform attach ảnh nếu file ở trong project hoặc folder đã cấp bằng `additionalReadRoots`, rồi rewrite path thành `[image1]`. |
| Nhiều ảnh trong cùng prompt | Dán tối đa 4 path ảnh | Prompt có `[image1]`, `[image2]`, ... |
| Ảnh quá lớn | Dùng Pi `read` tool trên file ảnh hoặc resize ảnh trước | Tránh nhồi ảnh quá lớn vào chat input. |

Định dạng hỗ trợ: `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.bmp`. Giới hạn
mặc định: 4 ảnh/input, 8 MB/ảnh. Protected path, symlink đi khỏi readable root,
file ngoài capability read scope và file chỉ giả đuôi ảnh đều bị từ chối trước
khi bytes được attach.

Profile name nên biết:

| Profile | Dùng khi nào |
|---|---|
| `generic` | Repo chưa rõ cấu trúc. |
| `web-frontend` | Chỉ FE. |
| `backend-api` | Chỉ BE/API. |
| `be-readonly-fe` | BE đọc-only, FE là nơi sửa. |
| `fullstack` | FE và BE đều có thể sửa nếu task cho phép. |
| `node-typescript` | Tooling/lib Node TypeScript. |
| `python` | Python app/lib. |
| `data` | ETL, dbt, data pipeline, notebook. |
| `devops` | Docker, Terraform, K8s, CI/CD. |
| `mobile` | React Native/Flutter. |
| `docs` | Docs/manual/portal. |

Tech stack option theo profile:

| Profile | Role bắt buộc chọn | Ví dụ |
|---|---|---|
| `web-frontend` | Frontend + database optional | `frontend=nextjs database=none` |
| `backend-api` | Backend + database optional | `backend=nestjs database=prisma` |
| `fullstack` | Frontend + backend + database optional | `frontend=nextjs backend=nestjs database=prisma` |
| `be-readonly-fe` | Frontend + backend + database optional | `frontend=react-vite backend=fastapi database=postgres` |
| `mobile` | Mobile | `mobile=react-native` |
| `devops` | DevOps | `devops=docker` |
| `data` | Data + database optional | `data=dbt database=postgres` |
| `docs` | Docs | `docs=mintlify` |

Sau khi chọn tech, platform tạo `.pi/tech-stack.json` và các file `.pi/tech-context/<tech>.json`. `/onboard run` sẽ đưa các pointer này vào `.pi/context-index.json`. File context chỉ nên chứa tóm tắt ngắn/citation từ Context7, không lưu nguyên văn docs dài, token, session, hoặc secret.

## Đọc tài liệu ngoài project

Tài liệu tải về `~/Downloads` rồi kéo vào CLI thường không đọc được, vì mặc định agent chỉ làm việc trong project. Tool `piagent_document_read` mở đúng một khe: đọc **tài liệu**, **chỉ đọc**, trong các folder đã cấp trước.

| Thành phần | Giá trị |
|---|---|
| Tool | `piagent_document_read` |
| Input | `path` — absolute, `~/...`, hoặc relative theo project |
| Định dạng | `.md`, `.markdown`, `.txt`, `.text`, `.csv`, `.tsv`, `.json`, `.yaml`, `.yml`, `.pdf`, `.docx` |
| Giới hạn | 12 MB/file; 400.000 ký tự sau khi trích, dài hơn thì cắt và báo `truncated` |
| Cấp quyền | `additionalReadRoots` trong `.pi/piagent-profile.json`, hoặc biến môi trường `PIAGENT_ADDITIONAL_READ_ROOTS` |

Cấp folder cố định trong profile:

```json
{
  "additionalReadRoots": ["~/Downloads", "~/Documents/specs"]
}
```

Cấp tạm cho một session, ngăn cách bằng `:` giống `PATH`:

```bash
PIAGENT_ADDITIONAL_READ_ROOTS="$HOME/Downloads:$HOME/Documents/specs" pi
```

Sau đó nói thẳng path là được: `Đọc ~/Downloads/spec-v2.docx rồi tóm tắt yêu cầu`.

Bốn ràng buộc không đổi khi cấp thêm root:

- **Chỉ đọc.** Root được cấp không mở quyền ghi, xoá, hay chạy lệnh trong đó.
- **Chỉ tài liệu.** File nằm trong root được cấp nhưng sai đuôi — `.pem`, `.sh`, `.env` — vẫn bị từ chối.
- **`protectedPaths` luôn thắng.** Root được cấp không mở được path mà project đang bảo vệ.
- **Nội dung là dữ liệu, không phải lệnh.** Text trả về đã qua redaction và có header nói rõ đây là dữ liệu người dùng; câu lệnh viết trong tài liệu không được thi hành.

Cả hai kiểm tra — nằm trong root và đúng đuôi — đều chạy trên path đã canonical hoá. Nên symlink trong root mà trỏ ra ngoài bị chặn, và symlink tên `notes.md` trỏ vào `id_rsa` cũng bị chặn.

`.docx` đọc trực tiếp, không cần cài gì; text bị xoá bởi tracked change chưa accept sẽ không lẫn vào nội dung. `.pdf` cần `pdftotext` (macOS `brew install poppler`, Debian/Ubuntu `apt install poppler-utils`); thiếu binary thì tool báo thiếu chứ không trả tài liệu rỗng.

## Command native của Pi

Các command này thuộc Pi core hoặc package Pi chính. Tên/availability có thể phụ thuộc version Pi.

| Command/hotkey | Dịch nghĩa | Dùng khi nào | Ghi chú |
|---|---|---|---|
| `/login` | Đăng nhập provider | Lần đầu dùng model OpenAI Codex hoặc model Anthropic Claude. | OAuth/session lưu local trong Pi, không commit repo. |
| `/model` | Chọn model | Muốn chọn OpenAI provider bằng native selector. | Đây là flow chính, không phải hỏi agent tự chọn thay. |
| `Ctrl+L` | Mở model selector | Đổi model nhanh. | Tương đương UI selector của Pi. |
| `/scoped-models` | Chỉnh danh sách model cycle | Muốn `Ctrl+P` chỉ xoay quanh vài model hay dùng. | Global setup seed sẵn provider model families. |
| `Ctrl+P` | Cycle model | Đổi model trong scope nhanh. | Dùng sau khi đã setup `enabledModels`. |
| `Shift+Ctrl+P` | Cycle model ngược | Quay lại model trước trong scope. | Tiện khi test provider. |
| `Shift+Tab` | Đổi thinking level | Chọn effort như `medium`, `high`, `xhigh`, `max` nếu model hỗ trợ. | Model không hỗ trợ level nào thì Pi có thể clamp. |
| `/name <name>` | Đặt tên session | Đối chiếu task trong Agent Watch/report và tìm lại khi resume. | Piagent theo dõi sự kiện rename; `/setname` là alias tương thích. |
| `/session` | Xem session hiện tại | Cần session id/name/token/cost/context. | Dùng sau `pi --name` hoặc `/name` để kiểm tra tên. |
| `/resume` | Resume session | Khi tắt nhầm Pi hoặc muốn nối lại work cũ. | Dựa vào session list/id/name của Pi. |
| `/compact` | Nén context | Khi context usage cao trước task dài. | Chỉ dùng khi cần; đọc lại context quan trọng sau compact. |
| `/mcp` | Xem MCP | Kiểm tra server/tool MCP trong Pi. | Cần `pi-mcp-adapter` hoặc MCP config tương ứng. |
| `/mcp setup` | Setup/refresh MCP | Khi MCP chưa nhận config. | Tùy adapter/version. |
| `/mcp tools` | List MCP tools | Muốn biết server expose tool nào. | Dùng trước khi bảo agent gọi tool ngoài. |
| `/mcp reconnect` | Kết nối lại MCP | Khi server lỗi, token mới, hoặc config đổi. | Không thay thế việc export secret env. |
| `/mcp-auth figma` | OAuth Figma remote MCP | Chỉ dùng khi Piagent đã được duyệt trong Figma MCP Catalog. | Nếu bị từ chối client, dùng `figma-desktop`. |
| `/piagent-mcp` | Menu MCP | Không nhớ subcommand, hoặc muốn xem có việc gì cần làm. | Menu dựng theo project; không có select UI thì in thẳng bảng trạng thái. |
| `/piagent-mcp status` | Danh sách MCP server + state | Muốn biết server nào đang có, ở scope nào, sẵn sàng chưa. | Đọc config, không kiểm tra kết nối live — cái đó là `/mcp`. |
| `/piagent-mcp get <name>` | Chi tiết một server | Trước khi duyệt, hoặc khi không rõ scope nào đang có hiệu lực. | Giá trị credential bị mask; `${VAR}` in nguyên vì là tên biến. |
| `/piagent-mcp doctor` | Server nào chưa chạy được và thiếu gì | Sau khi cài, hoặc khi tool call MCP bị chặn. | Không probe Docker daemon; chạy `piagent-mcp doctor` ở terminal cho việc đó. |
| `/piagent-mcp approve <name>` | Duyệt server repo khai | Khi mở một repo có `.mcp.json`. | In định nghĩa ra trước khi ghi quyết định. Pin theo digest. |
| `/piagent-mcp reject <name>` | Từ chối | Không tin server repo khai. | `reset` để quên quyết định. |
| `/piagent-mcp enable\|disable <name>` | Bật/tắt server | Tắt tạm mà không mất định nghĩa. | Cần `/reload` để adapter nhận thay đổi. |

`/piagent-mcp` chạy thẳng trong session, không qua model. Thêm/xoá server và preset ở terminal: `piagent-mcp add|remove|--preset`.

## Command subagent

Các command này đến từ package `pi-subagents`. Tên hơi “package terminology”, nên bảng dưới dịch ra nghĩa thực tế.

Quan trọng: Piagent mặc định parent-direct và helpers `off`. Các lệnh dưới đây phần lớn là capability upstream để inspect/debug. Piagent config chặn builtin, worker, parallel, nested và retry; operator chỉ có thể opt-in một helper read-only context fresh, và runtime vẫn yêu cầu hai lane độc lập cùng projected net saving từ 30%.

| Command | Dịch nghĩa dễ hiểu | Dùng khi nào | Kết quả mong đợi |
|---|---|---|---|
| `/subagents-doctor` | Health check subagent | Khi mới setup, sau update, hoặc subagent không chạy. | Kiểm tra package, config, agent files, runtime readiness. |
| `/subagents-models` | Bản đồ model của subagent | Khi muốn biết mỗi agent đang inherit model nào hoặc override gì. | Hiện model/thinking/routing đang áp dụng cho subagents. |
| `/subagents` | Catalog/admin agents | Khi muốn xem agent nào có sẵn. | List builtin + piagent agents, có thể inspect metadata. |
| `/subagents-fleet` | Dashboard đội agent đang chạy | Khi có background/parallel subagents. | Hiện active/done runs, id, status, transcript/result nếu hỗ trợ. |
| `/subagent-cost` | Chi phí/token subagents | Khi muốn biết parent + child agents tiêu hao ra sao. | Hiện usage/cost theo runs nếu package/provider expose stats. |
| `/subagents-watchdog` | Giám sát run bị treo | Khi background agents có nguy cơ stuck/timeout. | Theo dõi/nhắc trạng thái tùy package. |
| `/subagents-watchdog recommend-model` | Gợi ý model watchdog | Khi muốn watchdog dùng model mạnh bổ sung với model chính. | Trả gợi ý model/thinking hiện tại. |
| `/subagents-watchdog on` | Bật watchdog | Khi muốn adversarial review ở cuối turn cho session/project. | Watchdog review repo edits ở `agent_end`; có thể tốn thêm token. |
| `/subagents-profiles` | List profiles | Khi team có nhiều provider/quota profile. | Hiện profiles trong `~/.pi/agent/profile/pi-subagents/`. |
| `/subagents-refresh-provider-models <provider>` | Refresh model catalog | Khi model registry/provider thay đổi. | Probe/cache catalog provider. |
| `/subagents-generate-profiles <provider>` | Sinh quota/quality profiles | Khi muốn profile model theo quota/chất lượng. | Tạo profile cho provider. |
| `/subagents-check-profile <name>` | Check profile | Khi profile/model có thể stale. | Re-check model availability/auth. |
| `/run <agent> "<task>"` | Chạy 1 subagent | Khi cần 1 scout/reviewer/planner riêng context. | Child session chạy task rồi trả summary về parent. |
| `/run <agent> "<task>" --bg` | Capability upstream | Piagent không bật async mặc định. | Không dùng trong governed default. |
| `/run <agent> "<task>" --fork` | Capability upstream | Inherit history trái policy context fresh. | Piagent từ chối. |
| `/parallel ...`, `/chain ...`, `/run-chain ...` | Capability upstream | Nhân số turn/context. | Piagent config giới hạn 1 và không dispatch parallel/chain. |
| `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`, `/parallel-handoff-plan` | Capability upstream | Tạo nhiều helper hoặc retry loop. | Piagent config không cho dùng. |
| `/gather-context-and-clarify` | Scout rồi hỏi đúng câu | Khi requirement chưa rõ nhưng cần đọc trước. | Trả clarification questions có evidence. |
| `/parallel-cleanup` | Cleanup review sau implement | Khi muốn rà cleanup đáng làm. | Có thể thêm `autofix`. |

Glossary:

| Từ | Nghĩa trong repo mình |
|---|---|
| `doctor` | Kiểm tra sức khỏe/setup, không sửa logic task. |
| `models` | Cho biết model/thinking từng subagent sẽ dùng. |
| `fleet` | “Đội” child sessions đang chạy hoặc vừa chạy xong. |
| `scout` | Agent đọc/map code read-only. |
| `planner` | Agent lập plan và verify gate, không sửa code. |
| `worker` | Metadata compatibility; bị Piagent disable. |
| `reviewer` | Agent review diff/test/scope. |
| `oracle` | Agent phản biện/risk challenge. |
| `researcher` | Builtin agent nghiên cứu web/docs có nguồn; cần `pi-web-access`. |
| `context-builder` | Builtin agent tạo context/meta-prompt handoff cho task lớn. |
| `chain` | Làm A rồi dùng kết quả A để làm B. |
| `parallel` | Làm nhiều nhánh độc lập cùng lúc. |
| `bg` | Background run, không block parent ngay. |
| `fork` | Capability upstream; Piagent cấm vì helper phải context fresh. |
| `watchdog` | Opt-in adversarial reviewer ở cuối turn; không phải `reviewer` subagent. |
| `worktree` | Checkout riêng cho parallel writers để tránh đè file nhau. |

Piagent subagents:

| Agent | Khi dùng | Write policy |
|---|---|---|
| `piagent-scout` | Map repo/module/spec trước khi sửa. | Read-only. |
| `piagent-planner` | Lập implementation plan. | Read-only. |
| `piagent-worker` | Compatibility metadata; bị Piagent config disable. | Không dispatch. |
| `piagent-reviewer` | Review diff, verify coverage, scope drift. | Review-first. |
| `piagent-oracle` | Challenge architecture/risk. | Read-only. |

## Exact subagent control syntax

Dùng khi muốn chính xác hơn slash command:

```text
subagent({ agent: "piagent-scout", task: "Map the auth flow. Read-only.", context: "fresh" })
```

Status:

```text
subagent({ action: "status" })
subagent({ action: "status", id: "<run-id>", view: "transcript" })
```

Điều khiển run:

```text
subagent({ action: "steer", id: "<run-id>", message: "Focus only on tests." })
subagent({ action: "stop", id: "<run-id>" })
subagent({ action: "resume", id: "<run-id>", message: "Continue after this clarification." })
```

Rule thực tế: dùng slash/natural prompt cho hầu hết task; dùng tool syntax khi cần debug run id hoặc steer/stop chính xác.

Một số option hữu ích:

```text
/run reviewer[model=anthropic/claude-sonnet-5:high] "Review this diff"
/run scout[output=context.md,outputMode=file-only] "Map auth flow"
subagent({ action: "status", view: "fleet" })
subagent({ action: "status", id: "<run-id>", view: "transcript", lines: 120 })
```

`outputMode=file-only` hữu ích khi child tạo report dài: parent chỉ nhận đường dẫn file, không bị nhồi full report vào context.

## Khi nào nên spawn subagent

Trong Piagent, helper chỉ được dispatch khi tất cả điều kiện sau đúng:

- operator đã bật `PIAGENT_HELPERS_MODE=on`;
- runtime chứng minh ít nhất hai lane độc lập;
- helper không cần chờ output tiếp theo của parent;
- handoff context fresh, không inherit history, tối đa 2.048 token;
- projected tổng token sau cả handoff/merge tiết kiệm ít nhất 30%.

Không nên spawn bừa khi:

- task nhỏ, một file, verify đơn giản;
- nhiều writer cùng sửa chung vùng source;
- requirement chưa rõ;
- cần quyết định product/architecture từ user;
- repo đang dirty mà chưa hiểu thay đổi của ai.

Default của platform là an toàn:

- `maxSubagentDepth: 1`: parent spawn child, child không fan-out tiếp.
- `parallel.concurrency: 1`: compatibility ceiling, không chạy song song.
- `asyncByDefault: false`: không tự chạy background nếu anh không yêu cầu.
- Tổng 1 read-only helper, 0 worker, 0 retry.

Nếu anh không bật gì thêm, `/workflow task` chạy parent-direct và không tạo model turn phụ. Alias `/task` giữ cùng policy.

## Prompt mẫu cho bài toán thật

### Platform/package improvement

```text
/workflow platform-improve Improve onboarding, model scope, MCP setup, and verification docs for team usage. Keep workflows public, project-agnostic, and verifiable.
```

Khi muốn tách rõ agents:

```text
Use piagent-scout to map current platform docs/scripts read-only.
Use piagent-scout to inspect relevant external source context read-only when the user provides it.
Then use piagent-planner to produce an implementation plan.
Only after plan is clear, use piagent-worker for implementation.
Use piagent-reviewer before final.
```

### BE spec lên FE, không sửa BE

```text
/profile be-readonly-fe
/workflow be-to-fe Implement FE support for <endpoint/spec>. Scout backend read-only, map contract, then edit frontend only.
```

Nếu muốn parallel read-only:

```text
Keep the parent direct. If helper mode was explicitly enabled and the runtime proves at least 30% net saving, run one fresh read-only piagent-scout for the single highest-value independent lane.
```

### Review trước khi ship

```text
/review current diff
```

Hoặc chia reviewer:

```text
/parallel piagent-reviewer "Review correctness and edge cases" -> piagent-reviewer "Review tests and verification gaps" -> piagent-reviewer "Review scope drift and protected paths"
```

## Terminal commands

Các lệnh này chạy ngoài Pi.

| Command | Dùng khi nào |
|---|---|
| `npm install -g --ignore-scripts @earendil-works/pi-coding-agent@0.84.1` | Cài Pi CLI tương thích với release hiện tại. |
| `npm install -g --ignore-scripts @piagent/platform@1.6.1` | Cài terminal helper `piagent-*` từ release tag hiện tại. |
| `pi install git:github.com/Vt-mmm/piagent@v1.6.1` | Cài pinned release khi cần reproducible team setup. |
| `pi install git:github.com/Vt-mmm/piagent` | Cài latest package platform cho máy cá nhân/sandbox. |
| `piagent-update --check` | Báo version hiện tại vs version sẽ lên cho cả ba thành phần; không cài gì. |
| `piagent-update` | Full update global một lệnh cho cả máy: Pi host → npm-global helper → Pi package, đúng thứ tự release yêu cầu. |
| `piagent-update --version X.Y.Z` | Update tới đúng một release thay vì latest; dùng cho rollout theo lô hoặc rollback. |
| `piagent-update --project <path>` | Bước phụ sau global update: migrate project cũ nếu có rồi chạy doctor strict-share cho project đó. |
| `piagent-update --npm-prefix ~/.pi/npm-global` | Ép updater cài host/helper vào npm global prefix của user; hữu ích khi `/usr/local/lib/node_modules` không ghi được. |
| `npm exec -y --package @piagent/platform@X.Y.Z -- piagent-update --version X.Y.Z --force` | Bootstrap/update global cho máy chưa có `piagent-update`; chạy từ Terminal, không cần mở Pi. |
| `PIAGENT_NO_UPDATE_CHECK=1` | Tắt notice "có bản mới" ở đầu session Pi. Mặc định bật, hỏi registry nhiều nhất một lần mỗi 24 giờ ở tiến trình nền. |
| Cài exact Pi host của release, rồi `npm install -g --ignore-scripts @piagent/platform@X.Y.Z` và `piagent-install --stable` | Sequence thủ công tương đương. Thứ tự bắt buộc: `piagent-install` fail nếu Pi host lệch bản pin và không tự cài host. Version pin của từng release nằm trong [release/install policy](release-install-policy.md). |
| Cài exact Pi host ghi trong release cũ, rồi helper `vPREVIOUS` và `piagent-install --stable` | Full rollback; đánh giá dependency risk của host cũ trước khi hạ version. |
| `piagent-install --stable --dry-run` | Preview Pi package matching với helper hiện tại; stable resolve tag → commit SHA. |
| `piagent-install --stable` | Cài Pi package matching với helper hiện tại bằng resolved commit SHA. |
| `piagent-install --version vX.Y.Z --resolve-tag` | Chỉ đổi Pi package; npm-global helper giữ nguyên version. |
| `piagent-install --version vX.Y.Z` | Chỉ đổi Pi package theo exact tag literal khi cần giữ behavior cũ. |
| `piagent-install --dev` | Theo moving source cho máy cá nhân/sandbox; không commit vào `.pi/settings.json`. |
| `pi update --extensions` | Refresh package đã cài; với pinned tag/commit, muốn nâng version thì chạy lại install bằng ref mới. |
| `pi list --approve` | Xem package Pi đã install. |
| `piagent-auto` | Mở Pi với project trust `--approve` cho lần chạy hiện tại; guard vẫn bật. |
| `piagent-auto --read-only -p "<task>"` | Auto-run scout/read-only; guard chặn shell/write/unknown tool. |
| `piagent-auto --full-access -p "<task>"` | Trusted automation style; không tắt protected paths/redaction/human gates. |
| `pi` rồi `/permission full-access <task>` | Một lệnh trong Pi để bật full-access cho session và giao task. Alias `/full-access <task>` vẫn chạy. |
| `pi --list-models` | Xem model Pi thấy được theo credentials hiện tại. |
| `piagent-install --with-mcp --with-subagents` | Cài global package + MCP + subagent baseline từ package bin. |
| `piagent-setup <project> --profile auto` | Setup đầy đủ cho một project khi muốn preseed bằng bin. |
| `piagent-init <project> --profile generic` | Init project files tối thiểu. |
| `piagent-models` | Xem catalog model seeded bởi platform. |
| `piagent-route --prompt "<task>" --json` | Tính capability/model/effort trước task từ authenticated catalog; không gọi model và không lưu raw prompt. |
| `piagent-route --prompt-file <file> --execute --yes -- --approve` | Explicit prelaunch adaptive task; giữ hard pin và fail closed nếu preflight/catalog không đủ. |
| `piagent-model-scope --preset full` | Re-apply full provider model scope. |
| `piagent-mcp --preset core --scope global --replace` | Apply the governed MCP core baseline: Context7, Chrome DevTools, GitHub. |
| `piagent-mcp --preset popular --scope global --replace` | Apply the governed MCP popular baseline: core + Playwright + Figma desktop. |
| `piagent-mcp --list` | List MCP presets. |
| `piagent-subagents --preset safe` | Re-apply subagent safe config. |
| `pi install npm:pi-web-access@0.17.0` | Cấp web/search/fetch tools cho builtin `researcher`; platform setup/update cài mặc định từ `v1.2.8`. |
| `piagent-setup <project> --no-web-access` | Setup project nhưng bỏ web access khi máy không được phép browse/fetch external source. |
| `piagent-usage /path/to/project` | Lấy exact usage của session mới nhất từ terminal khác. |
| `piagent-usage --history /path/to/project --days 7` | Tổng usage lịch sử của project, gồm session đã end. |
| `piagent-usage --history --all-projects --days 7 --csv` | Xuất usage tuần toàn máy để đưa vào report. |
| `piagent-doctor /path/to/project --strict-share` | Kiểm tra project có share/open-source được không. |
| `piagent-uninstall` | Báo cáo những gì sẽ được gỡ. Dry run, không đụng gì. |
| `piagent-uninstall --apply` | Gỡ Pi package của platform khỏi Pi settings global. |
| `piagent-uninstall --apply --with-addons --with-host` | Gỡ thêm pi-mcp-adapter, pi-subagents, pi-web-access và Pi host. |
| `piagent-uninstall --apply --project /path/to/project` | Gỡ thêm state của platform trong project: profile, lock, `piagent-state/`. |
| `piagent-benchmark` | Chạy smoke suite `core-v1`: paired Piagent/controlled `codex-cli` bằng Luna/medium, 24 session, hidden grader + scope + workflow + exact usage. |
| `piagent-benchmark --dry-run` | Validate suite và xem số model session, không gọi model. |
| `npm run benchmark:deep -- --dry-run` | Validate `deep-logic-v1`: 7 family difficulty large × 3 repeat × Piagent/`codex-cli` = 42 session, khóa Luna/medium và chưa dùng quota. |
| `npm run benchmark:deep` | Chạy paired deep-logic benchmark Luna/medium cho event/state, scheduler, policy, context graph, stream recovery, transactional config và temporal usage billing chính xác. |
| `piagent-benchmark --production --dry-run` | Xem ma trận production 18 family x 3 variant x 2 surface = 108 session, chưa dùng quota. |
| `piagent-benchmark --production --preflight-only` | Trước lượt trả phí, tự chạy/cache ba lane provider-free cùng exact source/tree/config/runner binding; lần đầu có long-horizon tối thiểu 30 phút, 0 provider call/model token. |
| `piagent-benchmark --production --surfaces piagent,codex-cli --model openai-codex/gpt-5.6-luna --thinking medium --piagent-treatment candidate` | Chạy production release gate đa domain/profile/lifecycle với controlled Codex; S12/S36/S72 chặn pooled fresh ratio >1.10, observed family >1.25 hoặc subagent vượt 1 attempt/5% traffic; S108 dùng upper-95 <=0.60. |
| `piagent-benchmark --piagent-treatment release-defaults\|local-safe\|candidate\|feature-off ...` | Pin treatment Piagent; chỉ surface `piagent` nhận feature env, manifest/resume/replay/report giữ nguyên treatment. |
| `piagent-benchmark --codex-mode native ...` | Đo UX Codex theo cấu hình operator; protocol gate fail closed nên report không được claim tiết kiệm token. |
| `piagent-benchmark --production --seed <value> ...` | Tái lập đúng generated variant của một production report riêng tư. |
| `piagent-benchmark --production --scenarios <id,id> --repeats 1 ...` | Chẩn đoán family/rubric đã chọn; không đủ điều kiện nhận production verdict. |
| `piagent-benchmark --production --infrastructure-retries 2 ...` | Diagnostic recovery run; retry chỉ áp lỗi process chết trước usage, được report đầy đủ và làm production claim fail. |
| `piagent-benchmark --production --retry-delay 60 ...` | Đặt backoff trước infrastructure retry; production mặc định 60 giây. |
| `bash scripts/verify-local.sh` | Verify repo platform trước khi commit/tag. |
| `bash scripts/verify-local.sh --offline` | Verify trong CI/máy sạch, bỏ qua local Pi model catalog. |
| `bash scripts/setup.sh <project> ...` | Preseed setup project; không bắt buộc cho daily flow. |
| `bash scripts/quality-benchmark.sh ...` | Legacy: ghi tay benchmark cho scenario project-specific. |

Trong output `piagent-install`, `currentRelease` là version của terminal helper đang chạy, không phải lời xác nhận rằng npm-global helper vừa được update. Checklist đầy đủ nằm tại [release/install policy](release-install-policy.md).

Khi đang develop chính repo `piagent`, có thể dùng npm scripts tương ứng:

| Command | Tương đương |
|---|---|
| `npm run verify` | `bash scripts/verify-local.sh` |
| `npm run setup -- <project>` | `bash scripts/setup.sh <project>` |
| `npm run install-global` | `bash scripts/install-global.sh` |
| `npm run init-project -- <project>` | `bash scripts/init-project.sh <project>` |
| `npm run doctor -- <project> --strict-share` | `bash scripts/team-doctor.sh <project> --strict-share` |
| `npm run benchmark -- ...` | `node scripts/benchmark-runner.mjs ...` |
| `npm run benchmark:webui-parity` | Gate provider-free cho 10 workflow, 32 Project Controls, contract/security, bảy deterministic UI-stability suite, Chromium flow và ba cỡ performance stress. |
| `npm run usage -- <project>` | `bash scripts/pi-session-stats.sh <project>` |
| `npm run usage -- --history <project> --days 7` | `bash scripts/pi-session-stats.sh --history <project> --days 7` |
| `npm run models` | `bash scripts/pi-model-catalog.sh` |
| `npm run model-scope -- --preset full` | `bash scripts/configure-model-scope.sh --preset full` |
| `npm run mcp -- --preset core --scope global --replace` | `node scripts/mcp-manage.mjs --preset core --scope global --replace` |
| `npm run subagents -- --preset safe` | `bash scripts/configure-subagents.sh --preset safe` |

## MCP command quick map

| Muốn làm gì | Gõ |
|---|---|
| Kiểm tra MCP trong Pi | `/mcp` |
| Xem tool MCP | `/mcp tools` |
| Reconnect sau khi đổi config/env | `/mcp reconnect` |
| Apply global Context7/Chrome/GitHub baseline | `piagent-mcp --preset core --scope global --replace` |
| Apply Figma/Playwright baseline | `piagent-mcp --preset popular --scope global --replace` |
| Xem preset | `piagent-mcp --list` |

Secret phải để trong env, không commit:

```bash
export CONTEXT7_API_KEY=ctx7sk_...
export GITHUB_PERSONAL_ACCESS_TOKEN=<github-token>
```

## Token/context command quick map

| Câu hỏi | Lệnh |
|---|---|
| Session này đang dùng model gì? | `/session` hoặc `/usage` |
| Đặt/đổi tên session đang mở? | `/name <task/session name>` |
| Tắt nhầm, mở lại session gần nhất? | `pi --continue` |
| Chọn lại session cũ theo tên/id? | `pi --resume` hoặc `pi --session <id-or-file>` |
| Context window đang còn bao nhiêu? | `/usage` |
| Output test/build dài bị nén thì xem ở đâu? | `/logs` |
| Exact token/cost từ terminal khác? | `piagent-usage /path/to/project` |
| Tổng token/cost các session cũ? | `piagent-usage --history /path/to/project --days 7` |
| CSV report cuối tuần toàn máy? | `piagent-usage --history --all-projects --days 7 --csv` |
| Subagents tốn bao nhiêu? | `/subagent-cost` |
| Có nên compact chưa? | Xem `contextUsage.percent`; trên 75% mới cân nhắc `/compact`. |

Không claim tiết kiệm token/cost nếu chưa có paired evidence cùng scenario. Dùng
`piagent-benchmark`; smoke suite chỉ cho phép verdict khi quality/reliability đạt
ít nhất `9/10`, safety/workflow đạt tuyệt đối, quality không giảm và có ít nhất
ba cặp cùng model với exact usage. Production gate giữ safety `10`, yêu cầu
quality/reliability/workflow và mọi category ít nhất `9.5`, đồng thời bắt từng
task cùng mọi category/profile/lifecycle/difficulty band lớn hơn `9.5`, đủ 18
paired family và cận trên 95% của token ratio không vượt baseline. Report vẫn
liệt kê từng workflow check bị hụt để ngưỡng tổng không che mất hành vi cần xem
lại.

## Source rule cho subagent/custom agent

Mental model chuẩn:

1. Parent Pi là coordinator: giữ requirement, quyết định, final output.
2. Subagent là child session: có context riêng, có thể dùng model/tool riêng hoặc inherit parent.
3. Child trả summary/result về parent; parent không nên bị nhồi toàn bộ log trung gian.
4. Dùng read-only subagents trước: scout, docs research, review, test-gap analysis.
5. Writer song song chỉ dùng khi có worktree isolation và write set không overlap.
6. Agent custom tốt phải có role hẹp, tool surface rõ, output contract rõ.

Đây là lý do platform mình có `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle` thay vì một agent tổng quát làm tất cả.

## Tài liệu chính

- Pi usage docs: https://pi.dev/docs/latest/usage
- Pi packages: https://pi.dev/packages
- pi-subagents package: https://pi.dev/packages/pi-subagents