Composition
piagent-guard.ts owns wiring, registration order, and shared runtime state. Feature algorithms do not belong in this file.
Repository architecture
Core contains reusable policy and runtime infrastructure, while project-specific business logic stays in the project that owns it.
Dependency direction is enforced by code.
architecture/layers.json is machine-readable policy. npm run architecture:check blocks reverse dependencies and files that exceed their size budget.
Runtime adapters
packages/piagent-core/runtime owns Pi hooks, commands, tools, session UI, usage, log compaction, and workflow input routing.
Core services
Policy, task, context, and state modules return structured decisions. Core services do not import runtime adapters or the Pi composition root.
Integrations
mcp/, capabilities/, and security/ have explicit ownership and do not embed task workflow logic.
Entrypoints
scripts/ parses CLI arguments and calls use cases. Metrics, policy, and state transitions are not duplicated in CLI code.
Product assets
prompts/, skills/, subagents/, adapters/, packs/, and schemas/ are declarative assets.
Ownership
Each state has one source of truth
Project profiles and locks may be committed. Task evidence, telemetry, traces, captures, and session history are local state. Derived indexes carry a policy digest and remain rebuildable.
| State | Owner | Location | Committed |
|---|---|---|---|
| Project profile and lock | Project | .pi/piagent-profile*.json | Yes |
| Task, trace, telemetry, capture | Runtime | .pi/piagent-state/ | No |
| Session history | Pi | Pi session store | No |
| Shared instructions | Project | AGENTS.md, project docs | Yes |