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.
Adaptive runtime
Piagent now separates runtime decisions from Pi wiring
The harness keeps the model choice intact, but every task gets a smaller, cited context plan, durable task journal, and explicit recovery decision.
Context planner
runtime/context/adaptive-planner.ts chooses budget, retrieval lane, code inclusion, and a plan receipt from phase, context pressure, model capability, and thinking level.
Task journal
extensions/task-journal.js records start, progress, mutation, verifier, and completion checkpoints. Resume trusts the task contract first; retention compaction preserves hash anchors.
Repository memory
extensions/repository-memory.js stores only cited, expiring facts and rejects raw prompts, outputs, OAuth material, API keys, and secrets. Hints use only unused context-plan budget.
Model capability
runtime/model/capabilities.ts reads model family, context window, and thinking level as budget signals without switching providers or requiring API keys.
Verification intelligence
extensions/verification-intelligence.js classifies failures and chooses a targeted verifier from task scope; mixed frontend/backend scope uses the full source verifier.
Execution backend
extensions/execution-backend.js keeps local Pi OAuth as owner and blocks mutation when a requested experimental adapter is unavailable.
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 |
| Task journal and checkpoints | Runtime | .pi/piagent-state/task-journal/ | No |
| Repository memory facts | Runtime | .pi/piagent-state/repository-memory/ | No |
| Session history | Pi | Pi session store | No |
| Shared instructions | Project | AGENTS.md, project docs | Yes |