@piagent/platform 1.0.0

package/docs/package-architecture-notes.md

@@ -0,0 +1,101 @@
+# Package architecture notes
+
+## Mục tiêu
+
+Pi Agent Platform được đóng gói như một reusable Pi package để dùng cho nhiều project mà không kéo theo rule nghiệp vụ của một repo cụ thể.
+
+## Package shape
+
+```text
+packages/piagent-core/
+├─ capabilities/
+│  └─ capability-core.js
+├─ extensions/
+│  ├─ piagent-guard.ts      ← extension entry point
+│  ├─ guard-shell-analysis.ts
+│  ├─ guard-types.ts
+│  ├─ guard-io.js
+│  ├─ policy-core.js
+│  ├─ redaction-core.js
+│  └─ runtime-evidence.js
+├─ prompts/
+├─ skills/
+├─ subagents/
+├─ policies/
+└─ package.json
+```
+
+Root `package.json` expose:
+
+- `pi.extensions`
+- `pi.skills`
+- `pi.prompts`
+- `pi.subagents.agents`
+
+`pi.extensions` names `piagent-guard.ts` explicitly instead of globbing the
+directory. Pi loads every path the field matches and calls its default export as
+an extension factory, so a glob would sweep in the modules the guard imports —
+they export helpers, not a factory, and would fail to load. Anything added to
+`extensions/` is a library module until it is named in the manifest.
+
+Root CLI additionally exposes `piagent-capabilities` for catalog validation, profile resolution, lock verification, and dry-run action proposal validation.
+
+## Design decisions
+
+### 1. Prompts stay short
+
+Workflow prompts define phase, required tools, output contract, and verification. Project-specific detail lives in `.pi/piagent-profile.json`, `.pi/project-context.md`, memory, and required context files.
+
+### 2. Profile is the project adapter
+
+Profiles hold protected paths, required context, verify commands, MCP capabilities, and hard gates. This keeps the core package reusable across frontend, backend, fullstack, data, DevOps, mobile, and docs projects.
+
+### 3. Runtime state is local and auditable
+
+Task state is stored under `.pi/piagent-state/` and also mirrored into Pi session custom entries when possible. This gives a file-based audit trail without requiring a database.
+
+### 4. Source cache is read-only shared state
+
+`piagent-source-cache` stores user-provided external repositories in a stable local cache. Agents read targeted files from the cache and never edit it directly.
+
+### 5. Review guidance is project-local
+
+`templates/project/REVIEW_GUIDELINES.md` gives each project a place to define review rules without changing the package.
+
+### 6. Tool policy belongs in runtime
+
+Prompt instructions are not enough for safety. The extension layer provides exec policy, tool policy, protected path checks, context budget checks, and final gates.
+
+### 7. Benchmarking is scenario-based
+
+Token/cost/quality improvements must be measured on repeatable project scenarios, not assumed from setup shape.
+
+### 8. Capability selection is deterministic
+
+Capability packs declare exact dependencies, owners, lifecycle, artifacts, permissions, activation, and eval identifiers. Project profiles grant the allowed boundary. Resolver output is stored in `piagent-profile.lock.json` with profile, pack, and artifact digests.
+
+Manifest data never executes code. Invalid paths, symbolic links, dependency cycles, stale locks, and permission expansion fail validation.
+
+## Adopted capabilities
+
+| Capability | Implementation |
+|---|---|
+| Project onboarding | `/onboard-project` + `piagent_project_onboarding_record` |
+| Project context index | `/context-index` + `piagent_context_index_*` |
+| Profile switching | `/profile` + `piagent_profile_options` / `piagent_profile_apply` |
+| Explicit memory | `/memory-policy` + `piagent_memory_*` |
+| Task lifecycle | `/task` + task/context/verify/trace tools |
+| Platform workflow | `/platform-improve` |
+| Backend-readonly to frontend | `/be-to-fe` |
+| Source cache | `piagent-source-cache` + `piagent_source_checkout` |
+| Subagent roles | `piagent-scout`, `piagent-planner`, `piagent-worker`, `piagent-reviewer`, `piagent-oracle` |
+| Quality benchmark | `scripts/quality-benchmark.sh` |
+| Capability catalog | `packs/*/pack.json` + `catalog/capabilities.json` |
+| Capability resolver | `capability-core.js` + `piagent-capabilities` |
+
+## Deferred capabilities
+
+- Hard final assistant hook if Pi exposes a stable extension hook.
+- Project-specific worktree policy for parallel writer agents.
+- Optional stronger sandbox layer for strict enterprise environments.
+- Rich TUI dashboard for long-running usage and benchmark summaries.

package/docs/project-adapters.md

@@ -0,0 +1,174 @@
+# Project adapters
+
+## Mục tiêu
+
+Adapter mô tả project cho Pi core. Core không biết domain/project cụ thể trừ khi profile khai báo.
+
+## Profile schema hiện tại
+
+```json
+{
+  "schemaVersion": 1,
+  "projectId": "my-project",
+  "displayName": "My Project",
+  "mode": "web-frontend",
+  "permissionProfile": "workspace-write",
+  "rootMarkers": ["AGENTS.md", "package.json"],
+  "protectedPaths": [".git/**", "**/auth.json"],
+  "shellProtectedPaths": [".git/**", "**/auth.json"],
+  "readOnlyPaths": ["backend/**"],
+  "requiredContext": ["AGENTS.md", "docs/architecture.md"],
+  "taskModes": {
+    "readOnly": { "tools": ["read", "grep", "find", "ls"] },
+    "sourceWrite": { "requiresPlan": true, "requiresVerify": true }
+  },
+  "verifyCommands": {
+    "docsOnly": ["test -s README.md"],
+    "source": ["npm test"]
+  },
+  "mcpCapabilities": [
+    "filesystem-readonly",
+    "filesystem-write",
+    "shell",
+    "github",
+    "memory"
+  ],
+  "techStack": {
+    "provider": "context7",
+    "manifest": ".pi/tech-stack.json",
+    "contextDir": ".pi/tech-context",
+    "roles": {
+      "frontend": ["nextjs"],
+      "backend": ["nestjs"],
+      "database": ["prisma"]
+    }
+  },
+  "contextIndex": {
+    "enabled": true,
+    "path": ".pi/context-index.json",
+    "writePolicy": "onboarding-record",
+    "requireCitations": true,
+    "maxNodes": 120,
+    "maxEdges": 240,
+    "includeTechStack": true,
+    "includeMemoryPointers": true
+  },
+  "runtimePolicy": {
+    "execPolicy": "enforce",
+    "contextBudget": "enforce",
+    "toolRegistry": "advisory",
+    "finalGate": "enforce"
+  }
+}
+```
+
+Path policy fields have distinct meanings:
+
+- `protectedPaths`: block read/write path-tool access and protect these paths from shell parsing when `shellProtectedPaths` is omitted.
+- `readOnlyPaths`: allow `read`/`grep`/`find`/`ls`, but block `write`/`edit` and shell access.
+- `shellProtectedPaths`: block shell access only. Do not rely on this field to block write/edit; `profile-doctor` and `team-doctor` warn when a path is present only here.
+
+## Built-in adapters
+
+| Profile | Dùng cho | Verify mặc định |
+|---|---|---|
+| `generic` | Repo chưa có chuẩn riêng | README check hoặc message yêu cầu cấu hình verify |
+| `web-frontend` | Next/React/Vite frontend | type-check, lint, test, e2e nếu project khai báo |
+| `backend-api` | Node/Java/Python API | npm/maven/gradle/pytest tùy marker |
+| `be-readonly-fe` | BE là source of truth nhưng chỉ scout/read-only; FE là write target | FE type-check/lint/test/e2e theo layout phổ biến |
+| `fullstack` | Repo có FE + BE/monorepo | type-check, lint, test, e2e nếu có |
+| `node-typescript` | Node/TS library/tooling | npm type-check/lint/test nếu có |
+| `python` | Python app/library | `uv run pytest` |
+| `data` | ETL/dbt/DVC/notebook/data pipeline | pytest hoặc dbt compile nếu có |
+| `devops` | Docker/Terraform/K8s/GitHub Actions | diff check, compose/terraform validate nếu tool có |
+| `mobile` | React Native/Flutter | npm test / flutter test nếu tool có |
+| `docs` | Docs portal/manual | markdown diff check + test nếu project có |
+
+## Runtime profile selection
+
+Default UX không bắt buộc chạy bash để set profile. Sau global install, vào project chạy:
+
+```text
+/onboard-project
+```
+
+Nếu chưa có `.pi/piagent-profile.json`, onboarding nên dùng select-style setup: chọn profile trước, rồi chọn tech theo role. Native command là:
+
+```text
+/profile setup
+/profile tech setup fullstack
+```
+
+Nếu Pi host chưa expose select UI, command trả về card compact và lệnh deterministic, ví dụ:
+
+```text
+/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma
+```
+
+Kết quả ghi:
+
+- `.pi/piagent-profile.json`;
+- `.pi/piagent-profile.lock.json`;
+- `.pi/tech-stack.json`;
+- `.pi/tech-context/<tech>.json` placeholder.
+
+Sau khi agent đọc Context7 cho tech tương ứng, chỉ record snapshot ngắn bằng `piagent_profile_tech_context_record`; không lưu nguyên văn docs dài.
+
+`/onboard-project` cũng tạo `.pi/context-index.json`. Đây là advisory node/edge/citation map cho profile, tech, verify command, docs, risk và memory pointer; không dùng thay thế source hiện tại hoặc guard policy.
+
+Đổi profile sau này:
+
+```text
+/profile list
+/profile be-readonly-fe
+/profile tech setup
+```
+
+## Auto detect trong shell script
+
+`scripts/init-project.sh` và `scripts/setup.sh` vẫn hỗ trợ `--profile auto` cho case preseed/CI. Logic detect dựa trên marker:
+
+- mobile: `pubspec.yaml`, hoặc `android/` + `ios/`;
+- fullstack: package frontend + backend marker cùng tồn tại;
+- frontend: Next/React/Vite/Vue/Svelte/Astro marker;
+- backend: Nest/Express/Fastify/Hono/Prisma, Java Maven/Gradle, hoặc FastAPI/Flask/Django;
+- data: dbt/DVC/notebooks/data marker;
+- python: `pyproject.toml`;
+- node-typescript: `package.json` + `tsconfig.json`;
+- devops: Docker/compose/Terraform/K8s/Helm/GitHub Actions;
+- docs: docs portal markers;
+- fallback: `generic`.
+
+Auto detect là bootstrap convenience, không phải policy cuối cùng. Sau init, `.pi/piagent-profile.json` là source of truth của project.
+
+Mọi built-in adapter đều đưa `.pi/project-context.md` vào `requiredContext`. File này được tạo dạng placeholder khi init project, rồi được model thay bằng snapshot thật sau `/onboard-project`.
+
+## Khi nào cần custom profile
+
+Custom profile khi project có ít nhất một điểm sau:
+
+- verify command riêng;
+- protected path riêng;
+- context bắt buộc riêng;
+- tool/MCP capability riêng;
+- runtime policy riêng;
+- rule domain hoặc compliance riêng.
+
+Không sửa core extension chỉ để phục vụ một repo. Sửa `.pi/piagent-profile.json` của repo đó trước.
+
+## Adapter BE readonly → FE write
+
+Dùng `adapters/be-readonly-fe/profile.json` khi task pattern là:
+
+- đọc BE controller/DTO/schema/test để map contract;
+- không được sửa backend;
+- chỉ implement frontend;
+- nếu BE thiếu/gãy contract thì report gap.
+
+Không để `auto` tự chọn adapter này vì BE read-only là policy decision, không phải marker kỹ thuật.
+
+## Project-specific profiles
+
+Project-specific profiles should live in the target project repository, not in this public core repo.
+
+Use `examples/private/` locally if a maintainer needs private examples; that path is ignored by git.

package/docs/project-onboarding.md

@@ -0,0 +1,135 @@
+# Project onboarding snapshot
+
+## Mục tiêu
+
+Lần đầu gắn một project vào Pi Agent Platform, không nên nhảy thẳng vào `/task`.
+
+Luồng chuẩn là:
+
+```bash
+cd /path/to/project
+pi
+/login
+<select provider/model>
+/onboard-project
+```
+
+Sau khi `/onboard-project` chạy xong, project có file:
+
+```text
+.pi/piagent-profile.json
+.pi/piagent-profile.lock.json
+.pi/tech-stack.json
+.pi/tech-context/*.json
+.pi/project-context.md
+.pi/context-index.json
+.pi/memory/memory_summary.md
+.pi/memory/MEMORY.md
+```
+
+`/onboard-project` là nơi profile và tech stack được chọn. Ưu tiên select-style flow:
+
+```text
+/profile setup
+/profile tech setup fullstack
+```
+
+Nếu Pi host chưa có native select, command trả card compact và lệnh deterministic, ví dụ `/profile tech apply fullstack frontend=nextjs backend=nestjs database=prisma`. Không dùng model để giải thích dài từng lựa chọn trong daily UX.
+
+`.pi/project-context.md` là context snapshot để task sau không phải scout lại toàn bộ repo từ đầu.
+
+`.pi/context-index.json` là compact advisory index dạng node/edge/citation cho profile, tech stack, verify command, docs, risk, memory pointer và task handoff đã được duyệt. Nó giúp agent tìm đúng điểm vào repo nhanh hơn, nhưng không phải source of truth hoặc security boundary.
+
+Context index là Pi runtime state. Không đọc/ghi raw file này trong workflow thường ngày; dùng `/context-index`, `piagent_context_index_status`, `piagent_context_index_search`, `/onboard-project` hoặc `piagent_context_index_record` để runtime có thể kiểm soát path và sanitize dữ liệu advisory trước khi đưa vào model.
+
+Memory markdown là local/private mặc định và bị ignore bởi `.pi/.gitignore`. Chỉ commit memory nếu team quyết định opt-in sau khi review/redact.
+
+`.pi/memory/` là durable memory thủ công để giữ preference/decision/lesson ổn định giữa các session. Nó không thay thế snapshot hoặc source hiện tại.
+
+## Vì sao không để bash làm bước này
+
+Bash setup chỉ biết tạo template và detect marker. Nó không có model reasoning, không biết project purpose, module ownership, domain rule, hay risk boundary.
+
+`/onboard-project` phải chạy sau login/model selection để chính model sẽ dùng cho task đọc qua project, chọn/gợi ý profile, và tạo snapshot.
+
+## Profile selection
+
+Xem hoặc đổi profile trong Pi:
+
+```text
+/profile list
+/profile setup
+/profile tech setup
+/profile fullstack
+/profile be-readonly-fe
+```
+
+Khác biệt quan trọng:
+
+- `fullstack`: FE và BE đều có thể được sửa nếu task cho phép.
+- `be-readonly-fe`: BE chỉ scout/read-only; FE là write target.
+- `web-frontend`: chỉ FE.
+- `backend-api`: chỉ BE.
+- `generic`: baseline an toàn khi chưa rõ repo.
+
+## Phạm vi model cần đọc
+
+Không đọc toàn bộ source. Đọc theo lớp:
+
+1. `.pi/piagent-profile.json`
+2. `AGENTS.md`
+3. `.pi/project-context.md` hiện tại
+4. `.pi/context-index.json` nếu đã được generate
+5. `.pi/memory/memory_summary.md` nếu đã có và liên quan
+6. `README.md`
+7. package/build/runtime config
+8. docs/architecture/spec nếu có
+9. source directory map
+10. test/verify command definitions
+11. API/schema/migration markers nếu có
+
+Mục tiêu là hiểu cấu trúc và policy, không nhồi full repo vào context.
+
+## Artifact bắt buộc
+
+`.pi/project-context.md` nên có:
+
+- project purpose;
+- stack/runtime/package manager;
+- repository map;
+- source-of-truth docs;
+- domain/architecture notes;
+- verification matrix;
+- protected/high-risk areas;
+- MCP/tool policy;
+- memory policy;
+- update triggers.
+
+`piagent_project_onboarding_record` sẽ tự ghi thêm `.pi/context-index.json` khi tool có sẵn. Nếu cần kiểm tra nhanh, dùng:
+
+```text
+/context-index
+/context-index search <keyword>
+```
+
+## Khi nào regenerate
+
+Chạy lại:
+
+```text
+/onboard-project
+```
+
+khi có thay đổi lớn:
+
+- source layout đổi;
+- framework/runtime đổi;
+- verify command đổi;
+- API/schema/migration/auth/provider policy đổi;
+- project ownership hoặc domain rule đổi.
+
+## Relationship với `/task`
+
+`/task` sẽ yêu cầu đọc `.pi/project-context.md`. Nếu file còn trạng thái `Generated: not yet`, agent phải dừng và yêu cầu chạy `/onboard-project` trước.
+
+Đây là điểm khác với CLI thuần: context bootstrap trở thành một bước có artifact có thể review và tái dùng. `.pi/project-context.md` và `.pi/context-index.json` có thể commit cho team sau khi review; memory markdown thì private-by-default.

package/docs/publishing-for-teams.md

@@ -0,0 +1,64 @@
+# Publish cho team dùng
+
+## Mục tiêu
+
+Team khác có thể cài cùng một Pi platform mà không lấy secret của maintainer.
+
+## Cách phát hành
+
+### Git repo
+
+Dùng tag hoặc reviewed commit cho team/repo cần reproducible lock:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent@vX.Y.Z
+```
+
+Pin tag hoặc commit cho `.pi/settings.json` đã commit vào project. Luồng cài host, terminal helper, Pi package, update và rollback canonical nằm tại [release/install policy](release-install-policy.md).
+
+Moving latest chỉ dành cho máy cá nhân hoặc sandbox chấp nhận thay đổi không đồng bộ:
+
+```bash
+pi install git:github.com/Vt-mmm/piagent
+```
+
+### npm private package
+
+Dùng khi muốn version/publish chuẩn:
+
+```bash
+pi install npm:@your-scope/platform@x.y.z
+```
+
+### Local path
+
+Dùng khi dev platform trên một máy, không commit source này vào project team:
+
+```bash
+pi install /path/to/piagent
+```
+
+## Versioning
+
+- `0.1.x`: local/internal pilot.
+- `0.2.x`: có guard ổn định và docs team.
+- `1.0.0`: đủ security review, MCP registry, adapter schema versioned.
+
+## Không publish
+
+- `auth.json`
+- `.env`
+- session files
+- private token
+- project data dump
+
+## Team onboarding
+
+1. Install exact Pi host version declared by the target release.
+2. Install the pinned terminal helper and matching Pi package.
+3. Login OAuth provider.
+4. Run `pi` in the target project.
+5. Run `/onboard-project`.
+6. Choose/apply a profile inside Pi.
+
+Chi tiết: `docs/team-onboarding.md` và `docs/distribution-standard.md`.

package/docs/quality-benchmark.md

@@ -0,0 +1,74 @@
+# Quality benchmark guide
+
+## Vì sao cần benchmark
+
+Không nên claim tiết kiệm token/cost hoặc tăng chất lượng nếu chưa có số liệu theo cùng scenario. Token giảm khi:
+
+- project context đã được onboard;
+- profile giới hạn đúng scope;
+- memory explicit giảm scout lặp;
+- source cache giúp đọc targeted;
+- task gate bắt verify/trace;
+- tool policy chặn vòng lặp sai.
+
+Benchmark là bằng chứng để chọn agent surface, model, profile, và workflow preset cho từng loại task.
+
+## Ba scenario mặc định
+
+Khởi tạo:
+
+```bash
+bash scripts/quality-benchmark.sh /path/to/project --init
+```
+
+Script tạo:
+
+```text
+.pi/benchmarks/quality-scenarios.md
+```
+
+Scenario mặc định:
+
+1. `read-only-scout`
+2. `bounded-source-fix`
+3. `be-readonly-to-fe`
+
+## Ghi một lần chạy
+
+```bash
+bash scripts/quality-benchmark.sh /path/to/project --record \
+  --scenario read-only-scout \
+  --surface pi \
+  --result pass \
+  --tokens 8200 \
+  --duration 540 \
+  --notes "good plan, no edits"
+```
+
+Output:
+
+```text
+.pi/benchmarks/quality-runs.jsonl
+```
+
+## Tiêu chí so sánh
+
+| Metric | Ý nghĩa |
+|---|---|
+| `result` | `pass`, `fail`, hoặc `partial` theo verify và acceptance criteria. |
+| `surface` | Agent surface/workflow/model preset được dùng cho run. |
+| `tokens` | Tổng token do runtime/provider báo. |
+| `cost` | Cost nếu provider báo được. |
+| `durationSeconds` | Thời gian wall-clock. |
+| `notes` | Số lần sửa lại, missing context, wrong file, verify failure, hoặc quality observation. |
+
+## Quy tắc claim
+
+Chỉ claim một setup tốt hơn khi:
+
+- cùng task/spec;
+- cùng repo state;
+- cùng verify command;
+- ít nhất 3 lần chạy hoặc 3 scenario khác nhau;
+- pass rate không thấp hơn setup hiện tại;
+- token/cost giảm mà không tăng manual rework.