[docs] Define agent platform instruction layers

[mmabrouk]

Context

Agent-owned instructions currently travel through different SDK, runner, and harness paths. Ownership, persistence, invalidation, and native-session continuity therefore vary between Pi, Claude, and Codex.

Changes

This docs-only design defines one internal platformInstructions contract for SDK-owned text and a separate runner-owned runtime layer. It documents native delivery per harness, the required Codex late-runtime overlay, deterministic composition, lifecycle and continuity digests, Pi operator-file precedence, and a two-phase rollout that avoids mixed-version prompt loss.

Tests / notes

• git diff --check -- docs/design/agent-platform-instructions
• Independent interface and minimality reviews completed with no blocker, high, or medium findings.
• Implementation remains gated on executable Pi precedence and Codex developer-instruction spikes.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agenta-documentation	Ready	Preview	Aug 29, 2026 9:18am

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mmabrouk]

🤖 The AI agent says: Please review three decisions before implementation: (1) SDK-owned platformInstructions stays separate from author fields, (2) changed prompt inputs rebuild every harness and an effective direct-instruction digest guards native continuity, and (3) Codex keeps late runner facts in a fenced AGENTS.md overlay because daemon config freezes before Daytona mounts. Implementation starts with executable Pi precedence and Codex developer-instruction spikes.