Agent instruction architecture

This page defines how to keep agent instructions short, durable, and enforceable across long-running sessions.

Why this exists

Instruction files are loaded into context and lose influence as sessions grow. The fix is not "more text"; it is strict layering.

• Keep always-loaded policy small and stable.
• Move volatile guidance to tool-specific overlays.
• Put verification in CI gates whenever possible.

Layer model

Decision rule:

• If it is machine-verifiable, prefer CI.
• If it is a cross-tool invariant, put it in AGENTS.md.
• If it is IDE or shell specific, put it in a tool overlay.
• If it is about attention drift in long sessions, use continuation prompts.

Command policy strategy (PowerShell-first)

Permission matchers in multiple IDEs can fail on compound shell commands. Do not depend on brittle parser behavior for safety.

Long-form evidence, vendor links, and SSOT terminal policy: Terminal execution policy research findings 2026, Terminal AST validation research 2026. Enforced allowlist: contracts/terminal/exec-policy.v1.yaml (validated by vox shell check and vox ci exec-policy-contract).

Prefer:

• One command per terminal step (unless the user or policy explicitly allows pipelines; narrow pipeline patterns may be allowlisted under exec-policy).
• pwsh on Linux and macOS when installed — same cmdlet surface and the same vox shell check semantics as on Windows.
• PowerShell-native filesystem cmdlets instead of POSIX habits copied into a PowerShell session.
• Stable project tools: rg, git, cargo, pnpm, uv, vox.

Avoid by default:

• Pipelines and chain operators (|, &&, ;, ||) in policy-critical commands.
• Wrapper shells (bash -lc, nested shell calls) for routine tasks.
• Linux-only command habits in Windows sessions when PowerShell equivalents exist.

Copy-paste block for Antigravity customizations

Use this block in Antigravity customizations when you want a strict PowerShell-first command policy.

# Windows PowerShell command policy

- Environment is Windows. Use PowerShell-compatible commands.
- Use one terminal command per step.
- Do not emit compound commands with `|`, `&&`, `;`, or `||` unless explicitly required by the user.
- Do not use wrapper shells like `bash -lc` for routine tasks.
- Prefer `rg` for search.
- Prefer `Get-ChildItem`, `Test-Path`, `Resolve-Path` for filesystem tasks.
- Use project tools directly: `vox`, `cargo`, `pnpm`, `uv`, `git`.
- If a task needs multiple actions, execute separate commands in sequence instead of chaining.
- Treat allowlists as convenience only; keep risky/destructive commands denied explicitly in IDE policy where available.

Copy-paste block (PowerShell 7 on Linux / macOS)

Use when the agent host has pwsh installed and you want parity with Windows cmdlet semantics and vox shell check.

# PowerShell 7 command policy (Unix-like host)

- Use `pwsh` as the interactive shell when available.
- Use one terminal command per step by default; avoid pipelines unless required and consistent with exec-policy.
- Prefer `Get-ChildItem`, `Test-Path`, `Resolve-Path`, `Join-Path` over `ls` / string-built paths.
- Prefer `rg` for search; use `vox`, `cargo`, `pnpm`, `uv`, `git` directly.
- Validate risky lines locally with `vox shell check --payload "..."` when unsure.

Provenance and confidence

When documenting IDE behavior:

• Mark vendor-documented behavior as documented.
• Mark forum reports as community-reported.
• Mark reverse-engineered patch analyses as community-reverse-engineered.

Do not present undocumented internals as canonical facts.

Maintenance

Update this page when changing instruction architecture or shell discipline policy. Also review:

• AGENTS.md
• docs/src/architecture/terminal-exec-policy-research-findings-2026.md
• docs/src/contributors/continuation-prompt-engineering.md
• docs/src/contributors/documentation-governance.md