AI Execution Protocol

Purpose

Define execution modes for AI-assisted work in the Prox OS monorepo. Modes prevent oversized vibe-coding sessions from burning context, time, and credits on unbounded refactors.

Canonical companions:

• cost-gate.md — S / M / L / XL classification
• task-splitting-protocol.md — slice rules
• prompt-templates.md — copy-paste user prompts
• ../rfcs/README.md — RFC workflow
• ../adr/README.md — ADR workflow

AGENTS.md enforces this at the repository level.

When to Enter Triage First

Enter Triage Mode (Mode 0) before editing implementation files when:

• The user has not said "go ahead", "proceed", or named a specific slice.
• The task touches architecture, migration, API, database, auth, permissions, window manager, Spaces, app contract, monorepo layout, or docs-wide rewrites.
• cost-gate.md trigger words appear in any language.

Mode 0: Preflight / Triage

Purpose: Assess cost and risk. Do not modify code unless the user explicitly asked for a direct patch on an S task.

Required output:

Task Level: S / M / L / XL
Estimated Scope:
Likely Files / Packages:
Risk Areas:
Needs RFC: Yes / No
Needs Task Split: Yes / No
Recommended First Slice:
Blocked Questions:
Proceed / Wait:

Rules:

If the user says "analyze only", "direction first", or "do not change code", stay in Triage or Plan.

Mode 1: RFC

Purpose: Design cross-cutting or long-lived changes before code.

Triggers: See ../rfcs/README.md.

RFC must include: Status, Owner, Created, Related Packages, Context, Goals, Non-goals, Current Architecture, Proposal, Alternatives, Risks, Migration Plan, Task Breakdown, Acceptance Criteria, Implementation Notes.

Rule: Do not open implementation PRs for XL work without an Accepted RFC (or explicit user waiver documented in chat).

Mode 2: Plan

Purpose: Turn an RFC or large request into ordered slices.

Required phases:

Phase 1: Minimal Safe Change
Phase 2: Core Implementation
Phase 3: Integration
Phase 4: Verification
Phase 5: Docs Sync

Each phase must specify:

Goal
Allowed Files
Forbidden Changes
Expected Diff Size
Validation Command
Rollback Strategy

Mode 3: Patch

Purpose: Execute one approved slice.

Default limits:

Max files changed: 8
Max packages touched: 2
No architecture rewrite
No unrelated cleanup
No opportunistic refactor
No docs-wide rewrite
Stop if scope expands

If limits are insufficient, stop and output:

Scope expansion detected.
Reason:
New files/packages needed:
Recommended next slice:
Waiting for user confirmation.

Mode 4: Verify

Purpose: Validate an existing change without adding features.

Allowed:

• Run or recommend pnpm typecheck, pnpm lint, pnpm arch:check, pnpm check:cjk, targeted builds/tests.
• Fix blocking compile/type errors introduced by the slice.
• Check acceptance criteria from RFC or slice definition.

Forbidden:

• New features, redesigns, scope expansion, unrelated doc rewrites.

Output format:

Verification Summary
Passed
Failed
Fixed
Remaining Risks
Recommended Next Step

Mode 5: Docs Sync

Purpose: Update documentation for a completed implementation.

Rules:

• Only docs tied to the change.
• No unrelated chapter rewrites.
• Record RFC deviations in Implementation Notes.
• Run pnpm docs:sync when the public docs site must reflect docs/ changes.

Prox OS-Specific Guardrails

These areas inherit default risk from cost-gate.md:

• State: Zustand for local OS/window/Space state; TanStack Query for remote data — see ../architecture/state-model.md.
• UI boundary: packages/os-ui has no business state, API, i18n, Query, or Zustand.
• Apps: No deep imports from apps/os-shell/src/shell/** or window-manager/** in packages/os-apps.
• Registry: New apps update registry.ts, types, renderers, icons — Cmd+K picks up registry via commandPaletteApps.ts.

Related Documents

• context-pack.md
• ../architecture/core-architecture-thinking.md
• agent-rules.md