@piagent/platform 1.0.0

package/docs/auto-delegation-policy.md

@@ -0,0 +1,192 @@
+# Solo-first orchestration policy
+
+Mục tiêu: user không phải nhớ `/run`, `/parallel`, `/chain` cho workflow hằng ngày, nhưng platform cũng không tự biến mọi task thành swarm tốn token. Khi anh gõ `/task`, `/be-to-fe`, `/platform-improve`, `/plan`, hoặc `/review`, parent agent đọc `piagent_orchestration_policy`, giữ mặc định **solo-first**, rồi chỉ dùng subagents nếu việc đó giúp giảm nhiễu context, tăng tốc read-heavy work, hoặc tăng chất lượng review.
+
+Kiểm tra policy hiện tại trong Pi:
+
+```text
+/piagent-orchestration
+```
+
+Slash command này chỉ hiện status compact, không gửi follow-up cho model.
+
+## Kết luận thực tế
+
+Subagent không nên hiểu là “luôn tự sinh khi task lớn”. Hành vi đúng là:
+
+1. Parent agent đánh giá task có phần việc độc lập không.
+2. Nếu có và `pi-subagents`/subagent tool khả dụng, parent có thể tự spawn subagent.
+3. Nếu không có tool/package, parent tiếp tục single-agent và ghi rõ `Subagents: unavailable/not used`.
+4. User vẫn có thể gọi command trực tiếp khi muốn ép orchestration cụ thể.
+5. Parallel read-only có thể dùng cho scout/review; parallel writers không phải default và cần approval + isolation.
+
+Nếu bundled skill `pi-subagents` có trong skill list của parent, parent nên dùng skill đó cho orchestration patterns thay vì tự đoán syntax. Skill này là parent-only; child subagents không nhận nó.
+
+## Policy mặc định
+
+| Setting | Default |
+|---|---|
+| Mode | `solo-first` |
+| Max concurrent subagents | `2` |
+| Review lenses | `correctness`, `tests`, `scope` |
+| Field Guide | `.pi/memory/MEMORY.md`, advisory, explicit-write only |
+| Writer policy | Một writer cho một write set. |
+
+Model role guidance:
+
+- planner: model mạnh nhất hợp lý cho decomposition, architecture, risk, acceptance criteria;
+- worker: model nhanh/ổn định cho bounded implementation đã có plan;
+- reviewer: model/thinking decorrelated với worker khi review quan trọng;
+- watchdog/oracle: model mạnh chỉ cho final risk/security/release/high-impact.
+
+## Khi nào parent nên tự spawn
+
+Parent nên tự spawn subagents khi có ít nhất một điều kiện:
+
+- cần scout nhiều vùng source độc lập;
+- cần map BE contract read-only trong khi FE implementation là write target;
+- cần đọc external source docs/repo và repo hiện tại song song;
+- cần external research có nguồn dẫn, và `pi-web-access`/web tools đang available;
+- cần tạo context handoff trước task lớn (`context-builder`);
+- cần review nhiều góc độc lập: correctness, tests, security, scope drift;
+- task có từ 3 touchpoint trở lên;
+- task medium/high-risk nhưng có phần audit read-only trước khi edit;
+- context có nguy cơ phình to nếu parent tự đọc toàn bộ log/spec/source.
+
+## Khi nào không nên tự spawn
+
+Không spawn nếu:
+
+- task nhỏ, một file, verify đơn giản;
+- requirement chưa rõ và cần hỏi user trước;
+- chỉ có một write target nhỏ;
+- subagent tool/package chưa available;
+- repo dirty hoặc write set có nguy cơ overlap mà chưa phân tách được;
+- task high-risk cần human gate trước khi edit;
+- muốn spawn nhiều writer song song nhưng không có worktree isolation/approval.
+
+## Default agent mapping
+
+| Need | Agent | Mode |
+|---|---|---|
+| Map unfamiliar repo/module/spec | `piagent-scout` | read-only |
+| Build implementation plan | `piagent-planner` | read-only |
+| Implement approved bounded change | `piagent-worker` | single writer |
+| Review current diff | `piagent-reviewer` | review-first |
+| Challenge architecture/risk | `piagent-oracle` | read-only |
+| External docs/web research | builtin `researcher` | read-only; requires web tools |
+| Large context handoff | builtin `context-builder` or `piagent-scout` | writes handoff artifact only |
+
+Default rule: parallel read-only is OK; parallel writers are not default.
+
+## Workflow policy
+
+### `/task`
+
+Parent should:
+
+1. load piagent context/profile/memory/project context;
+2. load `piagent_orchestration_policy`;
+3. create a compact task tree/workPlan and review lenses in `piagent_task_start`;
+4. decide whether subagents are useful enough to justify extra token cost;
+5. if useful, spawn bounded read-only scout/planner/reviewer before or after implementation;
+6. keep implementation single-writer unless user explicitly approves otherwise;
+7. summarize subagent outputs into task contract/context manifest/final response.
+
+### `/be-to-fe`
+
+Recommended auto-delegation:
+
+- `piagent-scout`: map backend contract read-only;
+- `piagent-scout`: map frontend touchpoints read-only;
+- `piagent-planner`: produce FE implementation plan;
+- parent or `piagent-worker`: implement FE only;
+- `piagent-reviewer`: review diff and verify coverage.
+
+### `/platform-improve`
+
+Recommended auto-delegation:
+
+- `piagent-scout`: inspect current platform source/docs;
+- builtin `researcher`: inspect official docs/web evidence when `pi-web-access` is installed;
+- builtin `context-builder`: create handoff context/meta-prompt for large platform changes;
+- `piagent-scout`: inspect official docs/external source repo targeted evidence;
+- `piagent-planner`: produce implementation matrix;
+- parent or `piagent-worker`: implement bounded changes;
+- `piagent-reviewer`: review docs/runtime behavior.
+
+### `/review`
+
+Recommended auto-delegation:
+
+- select explicit review lenses first;
+- optional parallel `piagent-reviewer` for correctness;
+- optional parallel `piagent-reviewer` for tests/verification;
+- optional parallel `piagent-reviewer` for scope/protected-path drift;
+- optional `piagent-oracle` for architecture/high-risk concerns.
+
+If the user explicitly asks for a review loop, use `/review-loop` or an equivalent parent-controlled loop with max rounds. Do not blindly apply all reviewer suggestions.
+
+## Prompt examples parent may use internally
+
+Single scout:
+
+```text
+Use piagent-scout to map the target module read-only. Return files, ownership, invariants, and likely change points only.
+```
+
+Parallel scout:
+
+```text
+Run parallel piagent-scout agents: one maps backend contract read-only, one maps frontend touchpoints read-only. Wait for both and summarize the contract-to-FE map.
+```
+
+Parallel review:
+
+```text
+Run parallel piagent-reviewer agents for correctness, tests/verification, and scope/protected-path drift. Wait for all and summarize findings by severity.
+```
+
+Tool syntax fallback:
+
+```text
+subagent({ agent: "piagent-scout", task: "Map target area read-only. Return concise findings.", context: "fresh" })
+```
+
+## Reporting requirement
+
+Final response should include one line:
+
+```text
+Subagents: <not used / unavailable / used: piagent-scout, piagent-reviewer>
+```
+
+If not used, give the reason briefly:
+
+- `task was tiny`;
+- `requirements unresolved`;
+- `subagent tool unavailable`;
+- `write set overlap risk`;
+- `human gate required first`.
+
+## Token rule
+
+Subagents can reduce parent context pollution, but total token usage can increase because each child does its own model/tool work. Use them for parallelizable read-heavy work and review quality, not as a blanket token-saving switch.
+
+## Package shortcuts worth using
+
+| Shortcut | Use when |
+|---|---|
+| `/parallel-review` | Need distinct review angles; add `autofix` only when user permits fixes. |
+| `/review-loop` | Need worker/reviewer/fix loop until clean or capped. |
+| `/parallel-research` | Need external evidence + local code context. |
+| `/parallel-context-build` | Need context/meta-prompt handoff before a large plan. |
+| `/parallel-handoff-plan` | Need research + context-builder + implementation handoff. |
+| `/gather-context-and-clarify` | Need scout/research first, then ask only meaningful questions. |
+| `/parallel-cleanup` | Need post-implementation cleanup review. |
+
+See `docs/subagent-orchestration-capabilities.md`.
+
+## Official docs
+
+- Pi pi-subagents package: https://pi.dev/packages/pi-subagents

package/docs/capability-packs.md

@@ -0,0 +1,234 @@
+# Capability packs
+
+## Tổng quan
+
+Capability pack là đơn vị khai báo tài nguyên dùng chung của Pi Agent Platform. Pack không thực thi code từ manifest. Manifest chỉ mô tả:
+
+- danh tính, phiên bản, owner và lifecycle;
+- artifact được cung cấp;
+- dependency phiên bản chính xác;
+- capability, path, network và external action cần thiết;
+- profile activation;
+- eval scenario bắt buộc.
+
+Core package chịu trách nhiệm validate, resolve và tạo bằng chứng integrity. Project profile luôn là nguồn cấp quyền cuối cùng.
+
+## Thành phần
+
+```text
+packs/<name>/
+├─ pack.json
+└─ recipes/
+   └─ <recipe>.json
+
+catalog/
+└─ capabilities.json
+
+.pi/
+├─ piagent-profile.json
+└─ piagent-profile.lock.json
+```
+
+| Thành phần | Vai trò |
+|---|---|
+| `pack.json` | Manifest có schema, owner, version, artifact, dependency và permission. |
+| Capability recipe | Step graph khai báo mode, dependency, timeout, retry, output và gate. |
+| Catalog | Index deterministic của toàn bộ pack và artifact digest. |
+| Project profile | Chọn pack và cấp quyền owner/lifecycle/network/action. |
+| Profile lock | Kết quả resolve có profile digest, pack digest và effective permissions. |
+
+## Lệnh vận hành
+
+Kiểm tra catalog hiện tại:
+
+```bash
+piagent-capabilities catalog --check
+```
+
+Tạo lại catalog sau thay đổi được phê duyệt:
+
+```bash
+piagent-capabilities catalog --write
+```
+
+Resolve profile ra stdout:
+
+```bash
+piagent-capabilities resolve \
+  --profile adapters/generic/profile.json
+```
+
+Tạo lock bên cạnh profile project:
+
+```bash
+piagent-capabilities resolve \
+  --profile /path/to/project/.pi/piagent-profile.json \
+  --output /path/to/project/.pi/piagent-profile.lock.json \
+  --package-source npm:@your-scope/platform@x.y.z
+```
+
+Cập nhật profile và lock theo đường fail-closed:
+
+```bash
+piagent-capabilities apply-profile \
+  --profile adapters/generic/profile.json \
+  --target /path/to/project/.pi/piagent-profile.json \
+  --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z \
+  --force
+```
+
+Kiểm tra profile và lock:
+
+```bash
+piagent-capabilities doctor \
+  --profile /path/to/project/.pi/piagent-profile.json \
+  --lock /path/to/project/.pi/piagent-profile.lock.json \
+  --package-source npm:@your-scope/platform@x.y.z
+```
+
+Kiểm tra external action proposal dạng dry-run:
+
+```bash
+piagent-capabilities validate-action --file proposal.json
+```
+
+`scripts/init-project.sh` tự tạo `piagent-profile.lock.json` sau khi áp dụng profile.
+
+## Profile selection
+
+```json
+{
+  "capabilityPacks": [
+    {
+      "name": "engineering-base",
+      "version": "0.1.1"
+    }
+  ],
+  "capabilityPolicy": {
+    "allowedOwners": [
+      "platform-maintainers"
+    ],
+    "allowedLifecycles": [
+      "experimental"
+    ],
+    "allowedFilesystemRead": [
+      "**/*"
+    ],
+    "allowedFilesystemWrite": [
+      "**/*"
+    ],
+    "allowedNetworkDomains": [],
+    "allowedExternalActions": []
+  }
+}
+```
+
+Pack không thể cấp thêm quyền cho chính nó:
+
+- capability phải có trong `mcpCapabilities` của profile;
+- owner và lifecycle phải được profile cho phép;
+- filesystem read/write scope phải exact-match grant tương ứng của profile;
+- built-in path-like tool và tool có định danh `fs`/`filesystem` bị giới hạn theo filesystem scope đã resolve; đường dẫn thoát khỏi repository hoặc đi qua symlink bị từ chối. Tool khác tiếp tục qua tool registry. Base-policy protected path luôn có ưu tiên deny cao hơn; shell command vẫn chịu shell protected-path và exec-policy gate;
+- network domain phải exact-match allowlist;
+- external action phải exact-match allowlist;
+- task contract và runtime policy vẫn có thể thu hẹp thêm quyền.
+
+## Security properties
+
+### Input boundary
+
+- Chỉ nhận JSON với field đã khai báo.
+- Reject key nguy hiểm và nesting trên 32 cấp.
+- Giới hạn manifest 256 KiB và artifact 2 MiB.
+- Artifact path phải là đường dẫn tương đối trong repository.
+- Reject absolute path, parent traversal, backslash và symlink.
+- Protected-path matching không phân biệt hoa/thường; runtime canonicalize đường dẫn hiện hữu để chặn alias hoặc symlink trỏ vào vùng được bảo vệ.
+
+### Integrity
+
+- Manifest và artifact dùng SHA-256 digest.
+- Catalog và lock dùng canonical key order.
+- Artifact ID là duy nhất trên toàn catalog để liên kết recipe không mơ hồ.
+- Không có timestamp trong generated contract.
+- Doctor phát hiện catalog hoặc lock stale.
+- Generated output dùng temporary file cùng thư mục, `fsync`, rồi atomic rename.
+- Lock gắn với declared package-source identifier, package version, catalog và digest của các runtime enforcement file đang cài. Đây là integrity binding của runtime quan sát được, không phải chứng minh nguồn gốc cryptographic của package archive.
+- Optional runtime package được cài bằng exact version; installer đối chiếu registry integrity với digest đã phê duyệt trước khi cài.
+- Khi cập nhật profile, lock được ghi trước; nếu profile không thể ghi thì lock được rollback. Process interruption tạo trạng thái mismatch fail-closed thay vì áp dụng profile thiếu lock.
+
+### Permission boundary
+
+- Resolver chỉ chấp nhận permission là tập con của profile grant.
+- Lock ghi lại `protectedPaths`, `shellProtectedPaths`, `readOnlyPaths` và filesystem scope do pack yêu cầu.
+- Network và external action mặc định rỗng.
+- Action proposal bắt buộc `riskLane=high-risk`, `dryRun=true`, `containsSecrets=false`.
+- Proposal dùng canonical UTC timestamp, chưa hết hạn, có hiệu lực tối đa 24 giờ và không chứa raw payload hay credential.
+- `validate-action` chỉ kiểm tra contract, thời hạn và secret indicator; không authorize action, không đối chiếu requested permission với profile/lock và không đọc artifact để xác minh digest/size.
+- External action vẫn cần human confirmation và executor riêng trước khi có side effect.
+
+## Lifecycle
+
+| Trạng thái | Ý nghĩa |
+|---|---|
+| `experimental` | Đang pilot, profile phải opt-in rõ. |
+| `stable` | Contract và eval đã đủ cho use case công bố. |
+| `deprecated` | Vẫn resolve được khi profile cho phép, nhưng cần kế hoạch thay thế. |
+
+Điều kiện promote lên `stable`:
+
+1. Schema và doctor pass.
+2. Không có dependency cycle hoặc permission không được cấp.
+3. Eval scenario bắt buộc pass trên project pilot.
+4. Security review không còn Critical/High.
+5. Artifact contract và compatibility note đã được duyệt.
+
+## Thêm capability pack
+
+1. Tạo `packs/<name>/pack.json` theo `schemas/capability-pack.schema.json`.
+2. Khai owner, exact version, lifecycle và permission tối thiểu.
+3. Khai artifact ID duy nhất, artifact path hiện hữu; không dùng symlink.
+4. Thêm recipe/eval nếu pack có workflow hoặc invariant riêng.
+5. Chạy `npm test` và `npm run capabilities:catalog`.
+6. Chạy `npm run verify` trước handoff.
+
+## Capability source (pack ngoài platform)
+
+Project dùng được pack không thuộc repo này mà không cần fork. Khai trong `.pi/piagent-profile.json`:
+
+```json
+{
+  "capabilitySources": [
+    { "name": "team", "path": ".pi/packs" },
+    { "name": "acme", "source": "npm:@acme/piagent-packs@1.2.3" }
+  ]
+}
+```
+
+Mỗi entry khai đúng một trong hai:
+
+- `path` — thư mục nằm trong project. Không cần network, không cần publish.
+- `source` — npm hoặc git ở version/tag/commit chính xác. Range (`^1.2.3`, `latest`, `main`) bị từ chối vì lock mất ý nghĩa nếu code đổi mà lock không đổi.
+
+Thư mục nguồn phải chứa `packs/`, nằm trong project, và không chứa symlink.
+
+### Vendor
+
+`source` được fetch bằng một lệnh riêng, chạy có chủ đích:
+
+```bash
+piagent-capabilities vendor --profile .pi/piagent-profile.json
+```
+
+Lệnh này ghi vào `.pi/capability-vendor/<name>/` và in digest để review trước khi commit. Đây là chỗ duy nhất chạm network. Resolve và guard chỉ đọc thứ đã có trên đĩa, nên pack không đổi được giữa lúc review và lúc chạy. Nguồn khai mà chưa vendor thì resolve fail — không im lặng chạy với ít pack hơn profile yêu cầu.
+
+### Vẫn deny by default
+
+Khai source không cấp quyền gì. Pack ngoài vẫn phải qua `capabilityPolicy` như pack nội bộ: owner lạ bị từ chối chứ không phải cảnh báo, và `allowedOwners` phải liệt kê owner đó trước. Lock ghi cả `origin` và `source` của từng pack, nên pack đổi nguồn là thay thế chứ không phải update.
+
+## Giới hạn hiện tại
+
+- Catalog là local file, chưa có remote discovery service. Catalog chỉ chứa pack của platform; pack ngoài xuất hiện trong lock của project.
+- Lock là preflight và integrity contract; runtime guard xác minh lại trước mỗi tool call đối với profile hiện hành. `PIAGENT_PROFILE` trusted override và legacy profile chưa khai `capabilityPacks` nằm ngoài lock gate; khi lock lỗi chỉ nhóm recovery/read-only tool giới hạn được phép hoạt động.
+- Eval scenario mới có schema và validation; execution matrix được triển khai ở phase tiếp theo.
+- Recipe binding nội bộ và eval scenario ID được kiểm tra trong exact dependency graph; capability binding vẫn do runtime tool registry giải quyết.
+- External action proposal chỉ được validate; authorization, artifact byte verification và executor có credential không nằm trong phạm vi này.