Composition
piagent-guard.ts chỉ giữ wiring, registration order và shared runtime state. File này không được tiếp tục chứa feature algorithm.
Kiến trúc repo
Repo này không nhét business logic vào core. Core chỉ giữ policy, prompts, guard, skills và scripts dùng lại được.
Chiều dependency được enforce bằng code.
architecture/layers.json là rule máy đọc; npm run architecture:check chặn dependency ngược và file vượt budget.
Runtime adapters
packages/piagent-core/runtime quản lý Pi hook, command, tool, session UI, usage, log compaction và workflow input routing.
Core services
Policy, task, context và state trả về structured decision. Core service không import runtime adapter hay Pi composition root.
Integrations
mcp/, capabilities/ và security/ có ownership riêng; không nhúng task workflow vào integration.
Entrypoints
scripts/ parse CLI argument rồi gọi use case. Metric, policy và state transition không được duplicate trong CLI.
Product assets
prompts/, skills/, subagents/, adapters/, packs/ và schemas/ là declarative assets.
Ownership
Một state chỉ có một source of truth
Project profile và lock có thể commit. Task evidence, telemetry, trace, capture và session history là local state. Derived index phải có policy digest và rebuild được.
| State | Owner | Vị trí | Commit |
|---|---|---|---|
| Project profile + lock | Project | .pi/piagent-profile*.json | Có |
| Task, trace, telemetry, capture | Runtime | .pi/piagent-state/ | Không |
| Session history | Pi | Pi session store | Không |
| Shared instructions | Project | AGENTS.md, project docs | Có |