Step by step cho thành viên mới

Cài — hai lệnh

Cần Node.js 22.19.0 trở lên. Không cần cài Pi Coding Agent trước: piagent-setup tự cài đúng bản host mà release hiện tại đang pin. Chạy nó ngay trong thư mục project — nó cài Pi package, khởi tạo .pi/, cài MCP baseline cùng subagents, rồi chạy doctor. Thêm --no-mcp, --no-subagents, --no-herdr hoặc --global-only để bỏ bớt.

npm install -g @piagent/platform
piagent-setup

Vì chạy từ package đã cài, source ghi vào .pi/settings.json là npm:@piagent/platform@<version> — giá trị này có nghĩa như nhau trên máy đồng đội, nên commit được cho cả team.

Dùng Herdr thì cài Herdr trước: piagent-setup tự cài luôn Herdr Pi integration khi thấy herdr trên PATH, còn không thì bỏ qua kèm cảnh báo — cài Herdr sau phải chạy lại piagent-setup --global-only.

brew install herdr                            # macOS
curl -fsSL https://herdr.dev/install.sh | sh  # macOS hoặc Linux

Bản curl chạy script tải về lúc cài; muốn kiểm tra được thì dùng brew hoặc tải từ GitHub releases. Herdr stable hỗ trợ macOS và Linux, Windows mới ở mức preview.

Rollout pin từng bước, update, rollback, và channel latest cho máy cá nhân nằm trong release & install policy.

Mở repo dự án

Chạy Pi từ thư mục repo. Với repo đã tin cậy, dùng wrapper trusted-run khi cần tự động hoá có kiểm soát.

cd /path/to/project
pi

Cần nhiều agent chạy song song thì gõ herdr thay cho pi, mỗi pane một vai: implement, review read-only, verify, notes. Herdr chỉ điều phối terminal và session — nó không phải security boundary, gate vẫn nằm ở Pi extension và OAuth vẫn login trong Pi. Cách dựng pane: Herdr workflow.

Onboard context

Chạy một lần ở repo mới để ghi context, verify matrix và protected areas vào .pi/. /onboard mở menu/status; run mới launch workflow đọc project.

/onboard
/onboard run

Chọn profile + tech

Dùng /profile setup để mở select option: chọn profile trước, rồi chọn tech theo role. Fullstack sẽ chọn frontend, backend và database.

/profile setup
/profile tech setup fullstack

Chọn permission

Scout thì read-only, code bình thường thì workspace-write, automation tin cậy thì full-access có guard.

/permission status
/permission workspace-write

Chạy workflow

Dùng command đúng mục tiêu để agent không phải diễn giải quá dài. Task nào nặng context thì dùng fresh session.

/workflow task Implement the requested bounded change.
/workflow review current diff
/fresh task Implement the requested bounded change.

Verify trước khi handoff

Final gate chỉ tin kết quả command đã chạy thật, exit 0, và khớp verify plan. Sau khi pin hoặc nâng version, chạy doctor trên project:

piagent-doctor

Người phát triển chính platform còn có npm run verify trong source repo; chi tiết ở CONTRIBUTING.

Gỡ cài đặt khi không dùng nữa

piagent-uninstall mặc định chỉ in ra sẽ gỡ những gì rồi thoát; phải thêm --apply nó mới thực hiện, vì nó sửa Pi settings mà công cụ khác cũng ghi vào. Mặc định chỉ gỡ Pi package của platform; add-on, Pi host và state trong project đều là opt-in.

piagent-uninstall
piagent-uninstall --apply

Add-on, Pi host, state trong project và helper npm-global đều tách riêng và là opt-in — piagent-uninstall --help liệt kê đủ. Nó gỡ theo những gì đang đăng ký trong Pi settings chứ không theo những gì bản hiện tại cài, nên package do release cũ đăng ký vẫn ra được.