@piagent/platform 1.0.0

package/docs/subagents-and-multiagent.md

@@ -0,0 +1,346 @@
+# Subagents và multi-agent workflow
+
+## Kết luận
+
+Pi core không có subagents built-in. Theo design của Pi, subagents là extension/package. Platform này dùng `pi-subagents` làm subagent runtime vì nó hỗ trợ:
+
+- child Pi sessions riêng context;
+- foreground/background runs;
+- `/run`, `/parallel`, `/chain`;
+- builtin agents `scout`, `planner`, `worker`, `reviewer`, `oracle`, `researcher`, `context-builder`, `delegate`;
+- custom package agents từ `packages/piagent-core/subagents`;
+- status/fleet/cost/doctor commands;
+- bounded recursion/concurrency;
+- optional worktree isolation cho parallel writers.
+- prompt shortcuts như `/parallel-review`, `/review-loop`, `/parallel-research`, `/parallel-context-build`;
+- native supervisor channel (`contact_supervisor` / `subagent_supervisor`);
+- acceptance gates, output files, forked context, watchdog, model profiles, and lifecycle artifacts.
+
+Từ `v0.3.7`, `scripts/setup.sh` mặc định cài `pi-subagents` và chạy config preset `safe`.
+
+Workflow prompts của platform dùng **solo-first orchestration policy**: khi anh chạy `/task`, `/be-to-fe`, `/platform-improve`, `/plan`, hoặc `/review`, parent agent đọc `piagent_orchestration_policy`, lập task tree/review lenses, rồi mới cân nhắc subagent cho phần việc độc lập. Anh không bắt buộc phải gọi `/run` nếu chỉ muốn task hoàn chỉnh, và platform cũng không spawn swarm khi task nhỏ.
+
+Kiểm tra nhanh policy trong Pi:
+
+```text
+/piagent-orchestration
+```
+
+Guard extension vẫn load trong subagent process. Bash verify results do not stay in process-local memory only; they are appended to `.pi/piagent-state/observed-bash.jsonl`. Because parent and child share the same project cwd, parent can validate an exact verify command that a guarded worker subagent ran.
+
+Xem chi tiết: `docs/auto-delegation-policy.md`.
+
+Capability notes chi tiết: `docs/subagent-orchestration-capabilities.md`.
+
+## Install/setup
+
+Một lệnh setup đầy đủ:
+
+```bash
+bash /path/to/piagent/scripts/setup.sh . \
+  --profile auto \
+  --package-source git:github.com/Vt-mmm/piagent@vX.Y.Z \
+  --mcp-preset core \
+  --subagents-preset safe
+```
+
+Nếu chỉ cài global:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent
+pi install npm:pi-subagents@0.35.1
+bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
+```
+
+Nếu package đã cài nhưng muốn re-apply config:
+
+```bash
+piagent-subagents --preset safe
+# hoặc nếu chưa link npm bin:
+bash /path/to/piagent/scripts/configure-subagents.sh --preset safe
+```
+
+## Safe preset
+
+`safe` ghi vào:
+
+```text
+~/.pi/agent/extensions/subagent/config.json
+```
+
+Nội dung chính:
+
+- `toolDescriptionMode: compact` để giảm prompt/token;
+- `asyncByDefault: false` để không tự chạy background nếu không yêu cầu;
+- `waitTool.enabled: true` để parent có thể đợi async runs khi workflow cần kết quả;
+- `intercomBridge.mode: always` để child có thể hỏi parent qua `contact_supervisor`;
+- `singleRunOutputBaseDir` và `defaultSessionDir` stable trong `~/.pi/agent`;
+- `worktreeBaseDir` stable cho parallel writer khi được explicit bật;
+- `scheduledRuns.enabled: false` để không lộ surface schedule nếu user không yêu cầu;
+- `parallel.concurrency: 3`;
+- `parallel.maxTasks: 6`;
+- `maxSubagentDepth: 1`;
+- `maxSubagentSpawnsPerSession: 32`;
+- async completion batching bật.
+
+Không ép `subagents.modelScope` mặc định. Anh chọn model parent bằng `/model`; builtin subagents sẽ inherit model nếu không override. Nếu muốn ép chỉ provider:
+
+```bash
+bash /path/to/piagent/scripts/configure-subagents.sh --preset safe --model-scope piagent
+```
+
+## Kiểm tra trong Pi
+
+Sau khi mở session mới hoặc `/reload`:
+
+```text
+/subagents-doctor
+/subagents-models
+/subagents
+/subagents-fleet
+/subagent-cost
+```
+
+`/subagents-doctor` là lệnh đầu tiên nên chạy nếu không thấy tool/agent.
+
+Optional research support:
+
+```bash
+pi install npm:pi-web-access@0.13.0
+# hoặc
+bash /path/to/piagent/scripts/setup.sh . --with-web-access
+```
+
+`researcher` builtin cần web/search/fetch tools từ package này. Không bật mặc định để tránh tăng tool surface cho team không cần web research.
+
+Giải nghĩa nhanh:
+
+| Command | Nghĩa đơn giản | Khi dùng |
+|---|---|---|
+| `/subagents-doctor` | Health check subagent | Kiểm package/config/agent files/runtime readiness. |
+| `/subagents-models` | Bản đồ model/thinking của subagents | Xem agent nào inherit model parent, agent nào override. |
+| `/subagents` | Catalog/admin agents | Xem builtin agents và `piagent-*` agents. |
+| `/subagents-fleet` | Dashboard đội child sessions | Follow background/parallel runs, xem active/done/result. |
+| `/subagent-cost` | Token/cost subagents | Xem usage của child runs nếu package/provider expose stats. |
+| `/run` | Chạy một agent | Dùng cho scout/planner/worker/reviewer riêng context. |
+| `/parallel` | Chạy nhiều agent độc lập | Tốt cho read-only scout/review/test-gap analysis. |
+| `/chain` | Chạy tuần tự | Output agent trước làm input agent sau qua `{previous}`. |
+
+Nếu cần bản tổng hợp cho team mới:
+
+```text
+/piagent-commands subagents
+```
+
+## Gọi subagent tự nhiên
+
+Không bắt buộc nhớ exact tool call. Có thể prompt tự nhiên:
+
+```text
+Use scout to map the auth flow, then summarize likely change targets.
+Ask oracle to challenge this plan before we edit code.
+Use reviewer to review the current diff for correctness and tests.
+Run parallel reviewers: correctness, tests, and unnecessary complexity.
+Have worker implement this approved plan, then run reviewer.
+Run a review loop on this change until reviewers stop finding fixes worth doing, max 3 rounds.
+Run parallel research: external docs, local code context, and practical tradeoffs.
+```
+
+Với workflow platform, còn có thể chỉ gọi:
+
+```text
+/task Implement <task lớn>.
+```
+
+Parent agent sẽ tự quyết định:
+
+- không spawn nếu task nhỏ;
+- spawn bounded `piagent-scout` nếu cần map source/spec;
+- spawn bounded `piagent-planner` nếu cần plan medium/high-risk;
+- spawn bounded `piagent-reviewer` trước final nếu diff không nhỏ;
+- dùng builtin `researcher` nếu task cần external evidence và web tools available;
+- dùng builtin `context-builder` nếu task lớn cần handoff context;
+- dùng review lenses (`correctness`, `tests`, `scope`, optional `security/docs/release/package`) thay vì gọi review swarm chung chung;
+- ghi trong final `Subagents: used/not used and why`.
+
+## Package prompt shortcuts nên biết
+
+| Prompt | Dùng khi nào |
+|---|---|
+| `/parallel-review` | Review nhiều góc nhìn độc lập; thêm `autofix` nếu muốn áp fix đáng làm. |
+| `/review-loop` | Worker/reviewer/fix loop đến khi sạch hoặc hết max rounds. |
+| `/parallel-research` | External research + local scout + tradeoff. Cần `pi-web-access` cho web researcher. |
+| `/parallel-context-build` | Tạo `context.md`/meta-prompt handoff cho task lớn. |
+| `/parallel-handoff-plan` | Research + context-builder + implementation handoff plan. |
+| `/gather-context-and-clarify` | Đọc/scout trước rồi chỉ hỏi câu clarification thật sự cần. |
+| `/parallel-cleanup` | Cleanup review sau implementation; có thể thêm `autofix`. |
+
+## Gọi bằng slash command
+
+Single agent:
+
+```text
+/run scout "Map the auth flow and identify entry points."
+/run piagent-scout "Map FE routes related to listing search. Read-only."
+/run piagent-planner "Create implementation plan from context.md."
+/run piagent-worker "Implement the approved plan. Do not touch backend."
+/run piagent-reviewer "Review current diff against the task and verify evidence."
+/run piagent-oracle "Challenge this architecture choice before implementation."
+```
+
+Parallel:
+
+```text
+/parallel piagent-reviewer "Review correctness" -> piagent-reviewer "Review tests" -> piagent-reviewer "Review scope drift"
+```
+
+Chain:
+
+```text
+/chain piagent-scout "Scout the target area" -> piagent-planner "Plan from {previous}" -> piagent-worker "Implement from {previous}" -> piagent-reviewer "Review the implementation"
+```
+
+Background:
+
+```text
+/run piagent-scout "Map this module" --bg
+/subagents-fleet
+```
+
+## Gọi bằng tool syntax
+
+Khi muốn chính xác:
+
+```text
+subagent({ agent: "piagent-scout", task: "Map the auth flow. Read-only.", context: "fresh" })
+```
+
+Background:
+
+```text
+subagent({ agent: "piagent-reviewer", task: "Review current diff", async: true })
+subagent({ action: "status" })
+```
+
+Status/control:
+
+```text
+subagent({ action: "status" })
+subagent({ action: "status", view: "fleet" })
+subagent({ action: "status", id: "<run-id>", view: "transcript" })
+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." })
+subagent_supervisor({ action: "pending" })
+subagent_supervisor({ action: "reply", replyTo: "<request-id>", message: "Approved path A." })
+```
+
+Output/file controls:
+
+```text
+/run scout[output=context.md,outputMode=file-only] "Map target area"
+/chain scout[output=context.md,as=context] "Scan" -> planner[reads=context.md] "Plan from {outputs.context}"
+```
+
+Use `outputMode=file-only` khi report dài để parent không bị nhồi full output vào context.
+
+## Piagent subagents
+
+Platform package exposes these package-level agents:
+
+| Agent | Role | Write? |
+|---|---|---|
+| `piagent-scout` | bounded repo mapping | no |
+| `piagent-planner` | implementation plan + verify gates | no |
+| `piagent-worker` | single-writer implementation | yes |
+| `piagent-reviewer` | review diff/policy/tests/scope | review-first, edit only if asked |
+| `piagent-oracle` | second opinion/risk challenge | no |
+
+Default rule:
+
+- Use `piagent-scout` before touching unfamiliar code.
+- Use `piagent-planner` before medium/high-risk changes.
+- Use `piagent-worker` only for approved, bounded write tasks.
+- Use `piagent-reviewer` before final handoff.
+- Use `piagent-oracle` when architecture/product/risk is uncertain.
+
+## Worktree isolation
+
+Parallel implementation writers can clobber each other in one checkout. Only use `worktree: true` when:
+
+- current repo is a Git repo;
+- working tree is clean;
+- write sets do not overlap;
+- parent will review/merge outputs.
+
+Example:
+
+```text
+subagent({
+  tasks: [
+    { agent: "piagent-worker", task: "Implement feature A" },
+    { agent: "piagent-worker", task: "Implement feature B" }
+  ],
+  worktree: true
+})
+```
+
+For normal solo/internal workflow, prefer one `piagent-worker` plus parallel read-only reviewers.
+
+## Watchdog opt-in
+
+Watchdog không phải `reviewer`. Nó là adversarial review ở boundary `agent_end`, chỉ chạy khi có repo edits. Không bật mặc định vì tốn thêm model pass.
+
+Session-only high-risk run:
+
+```text
+/subagents-watchdog recommend-model
+/subagents-watchdog session model recommended
+/subagents-watchdog on
+```
+
+Persistent project/user config chỉ dùng khi team đã đồng ý cost/latency.
+
+## Model profiles
+
+Khi team có nhiều provider/quota:
+
+```text
+/subagents-refresh-provider-models openai-codex
+/subagents-generate-profiles openai-codex
+/subagents-load-profile openai-codex.quota
+/subagents-check-profile openai-codex.quota
+```
+
+Model scope platform vẫn có thể enforce bằng:
+
+```bash
+piagent-subagents --preset safe --model-scope piagent
+```
+
+## Cost/token controls
+
+Use:
+
+```text
+/subagent-cost
+/piagent-usage
+/session
+```
+
+Recommended token policy:
+
+- default `safe` preset;
+- do not set `asyncByDefault` unless anh intentionally wants background-heavy workflow;
+- keep `/piagent-orchestration` at `solo-first` unless team has a measured reason to change it;
+- one writer at a time;
+- parallel reviewers/scouts are OK;
+- use `piagent-scout`/`piagent-planner` to compress context before handing off to `piagent-worker`;
+- run `/subagents-fleet` to inspect background runs instead of asking parent model to recall everything.
+
+## Nguồn
+
+- Pi usage docs: https://pi.dev/docs/latest/usage
+- Pi SDK docs: https://pi.dev/docs/latest/sdk
+- pi-subagents package: https://pi.dev/packages/pi-subagents
+- pi-subagents GitHub: https://github.com/nicobailon/pi-subagents

package/docs/task-implementation-contract.md

@@ -0,0 +1,200 @@
+# Task Implementation Contract
+
+## Mục tiêu
+
+Đây là contract tối thiểu để Pi implement task không khác gì một CLI agent nghiêm túc: có scope, context, guard, verify, trace.
+
+## Contract fields
+
+| Field | Required | Ý nghĩa |
+|---|---:|---|
+| `taskId` | yes | ID ổn định cho task. |
+| `summary` | yes | Một câu mô tả outcome. |
+| `riskLane` | yes | `tiny`, `normal`, hoặc `high-risk`. |
+| `expectedOutput` | yes | Artifact/behavior cụ thể. |
+| `acceptanceCriteria` | yes | Điều kiện pass/fail. |
+| `scope` | yes | File/module được phép đụng. |
+| `outOfScope` | yes | Cái không làm. |
+| `protectedPaths` | yes | Vùng cấm từ profile/policy. |
+| `requiredContext` | yes | Context bắt buộc đọc. |
+| `contextManifest` | yes | Bằng chứng context đã dùng. |
+| `memoryCitations` | no | Memory file dùng làm advisory context, nếu có. |
+| `mcpCapabilities` | no | Tool/MCP được phép. |
+| `verifyCommands` | yes | Command phải chạy trước DONE. |
+| `workPlan` | no | Task tree compact: step, role, mode, trạng thái, dependency. |
+| `reviewLenses` | no | Góc review rõ ràng, mặc định `correctness`, `tests`, `scope`. |
+| `orchestration` | no | Snapshot solo-first policy khi task bắt đầu: mode, subagent stance, Field Guide, model-role guidance. |
+| `verifyEvidence` | yes before done | Observed command result. Passing gate requires exact match with `verifyCommands`. |
+| `changedFiles` | yes before done | File đã sửa. |
+| `trace` | yes before done | Handoff/audit record. |
+
+## JSON example
+
+```json
+{
+  "taskId": "TASK-0001",
+  "summary": "Fix listing filter reset behavior",
+  "riskLane": "normal",
+  "expectedOutput": "Filter reset returns listing page to default query and preserves route owner.",
+  "acceptanceCriteria": [
+    "Reset button clears selected filters",
+    "URL query returns to canonical default",
+    "No protected paths are modified"
+  ],
+  "scope": [
+    "src/features/listings/**"
+  ],
+  "outOfScope": [
+    "backend API changes",
+    "database changes"
+  ],
+  "protectedPaths": [
+    "backend/**"
+  ],
+  "requiredContext": [
+    "AGENTS.md",
+    ".pi/project-context.md",
+    "docs/frontend/structure-guide.md"
+  ],
+  "contextManifest": [
+    {
+      "path": "AGENTS.md",
+      "reason": "root rules"
+    }
+  ],
+  "memoryCitations": [],
+  "mcpCapabilities": [
+    "filesystem-readonly",
+    "browser"
+  ],
+  "verifyCommands": [
+    "npm run test"
+  ],
+  "workPlan": [
+    {
+      "id": "plan",
+      "title": "Confirm scope and verify gate before editing.",
+      "role": "parent",
+      "mode": "read-only",
+      "status": "done"
+    },
+    {
+      "id": "implement",
+      "title": "Apply the bounded source change.",
+      "role": "piagent-worker",
+      "mode": "single-writer",
+      "status": "pending",
+      "dependsOn": [
+        "plan"
+      ]
+    }
+  ],
+  "reviewLenses": [
+    "correctness",
+    "tests",
+    "scope"
+  ],
+  "orchestration": {
+    "mode": "solo-first",
+    "subagents": "not-used",
+    "reason": "Task starts in solo-first mode; use bounded subagents only for independent scout, planning, or review work.",
+    "fieldGuidePath": ".pi/memory/MEMORY.md",
+    "modelRoles": {
+      "planner": "Use the strongest available model for decomposition, architecture, risk, and acceptance criteria.",
+      "worker": "Use the fastest reliable model for a bounded, already-planned single write set.",
+      "reviewer": "Use a model or thinking setting decorrelated from the worker when review quality matters.",
+      "watchdog": "Use a strong model only for final risk review, security, release, or high-impact changes."
+    }
+  },
+  "verifyEvidence": [
+    {
+      "command": "npm run test",
+      "exitCode": 0,
+      "summary": "Unit test suite passed.",
+      "observed": true,
+      "matchedProfileCommand": true
+    }
+  ],
+  "changedFiles": [],
+  "trace": {
+    "outcome": "pending"
+  }
+}
+```
+
+## Prompt contract
+
+Pi task prompt phải bắt buộc:
+
+```text
+Use piagent_context first.
+Use piagent_orchestration_policy; default to solo-first, create a compact task tree, and choose review lenses before spawning subagents.
+Use piagent_context_index_status/search as advisory navigation when available; verify cited files before editing.
+Use piagent_memory_status and search memory when relevant; memory is advisory only.
+Read .pi/project-context.md; if it is pending, stop and request /onboard-project.
+Create a Task Implementation Contract with piagent_task_start.
+Check large context with piagent_context_budget.
+Check complex/high-impact shell with piagent_exec_policy_check.
+Check non-piagent tools with piagent_tool_policy_check.
+Do not edit before scope + verify command are known.
+Before final, run the exact verify command from task.verifyCommands through Pi bash, record observed verify evidence, and trace.
+Call piagent_task_gate_check before DONE.
+If verify cannot run, final outcome is blocked/partial, not done.
+```
+
+## Enforcement levels
+
+| Level | Cách enforce | Độ tin cậy |
+|---|---|---:|
+| Prompt only | prompt nhắc model | Thấp |
+| Profile + prompt | profile có rule, prompt đọc profile | Trung bình |
+| Extension guard | tool_call block protected/destructive | Khá |
+| Runtime task tools | task_start/context_record/verify_record/trace | Cao |
+| Runtime quality tools | exec_policy/context_budget/tool_policy/task_gate | Cao |
+| Final gate | trace completion block khi `finalGate=enforce`; hard assistant stop-hook khi Pi API hỗ trợ | Cao nhất |
+
+Hiện platform đang ở mức “P3-baseline runtime policy”:
+
+- `piagent_task_start`
+- `piagent_exec_policy_check`
+- `piagent_context_budget`
+- `piagent_context_index_status`
+- `piagent_context_index_search`
+- `piagent_context_index_record`
+- `piagent_tool_policy_check`
+- `piagent_context_record`
+- `piagent_verify_record`
+- `piagent_trace_record`
+- `piagent_task_gate_check`
+- local task/trace/observed-bash state trong `.pi/piagent-state/`
+- session trace qua Pi custom entry `piagent-task-trace`
+
+`piagent_trace_record` có thể block completion nếu profile bật `finalGate=enforce`. Nếu Pi runtime chưa expose hard final assistant stop hook, agent vẫn phải gọi `piagent_task_gate_check` và final phải nêu gate result.
+
+## Verify evidence rules
+
+`piagent_verify_record` is not a free-form self-report. It accepts evidence only when the same normalized command was observed through a Pi `bash` `tool_result` after `task.createdAt`.
+
+Observed bash results are persisted to:
+
+```text
+.pi/piagent-state/observed-bash.jsonl
+```
+
+This lets parent agents validate verify commands executed by guarded subagent processes in the same cwd.
+
+Final-gate pass requires:
+
+- `observed=true`;
+- `matchedProfileCommand=true`;
+- `exitCode=0`.
+
+Exact command identity matters. If the task profile says `npm test`, record `npm test`. `npm  test`, `npm test 2>&1`, `npm test || true`, `true`, and `echo ok` are different commands and will not satisfy the passing gate unless explicitly present in `task.verifyCommands`.
+
+## Named implementation recipes
+
+- `/platform-improve`: dùng cho task cải tiến setup, docs, prompt, MCP, model, memory, runtime policy, hoặc subagent workflow của platform.
+- `/be-to-fe`: dùng cho task scout BE contract read-only rồi implement FE.
+- `/memory-policy`: dùng cho task kiểm tra/ghi nhớ explicit project memory.
+
+Hai recipe này vẫn phải tạo/giữ Task Implementation Contract khi có source writes.