AI Cost Gate

Classify AI-assisted tasks by **size and risk** before editing the repo. Classification drives which [execution mode](./ai-execution-protocol.md) is required.

Purpose

Classify AI-assisted tasks by size and risk before editing the repo. Classification drives which execution mode is required.

Levels

S — Small

May proceed directly after confirming scope (single concern, no architecture drift).

Traits:

One file or a few lines in one module.
No contract, routing, API, DB, or permission changes.
No new package boundaries.

Examples:

Fix button copy or i18n key in en.ts
Adjust a token-backed style in one component
Fix an obvious typo or type error
Add a one-line guard in an existing handler

M — Medium

Short plan, then patch (still one session, one concern).

Traits:

Roughly 2–8 files in one app or package.
Local UI or mock data behavior change.
No cross-package contract changes.

Examples:

Add a tab to an existing os-apps screen
Adjust window titlebar interaction in one component
Extend App Store catalog rows without new runtime apps

L — Large

Task split required before coding. One slice per user confirmation.

Traits:

Multiple modules or packages.
State, routing, lifecycle, performance, or observability impact.
Likely multiple PRs.

Default L areas in Prox OS:

window manager
virtual desktops / Spaces
fullscreen route semantics
app registry composition
micro-app / iframe host behavior
packages/os-ui public API
packages/app-contract types
apps/api-worker routes
packages/db schema (when active)
auth / permissions (when implemented)
Cloudflare / Neon / R2 deployment wiring

Examples:

Extract more apps into packages/os-apps
Add MSW-backed API mocks for one domain
New system app with registry + UI + docs

XL — Extra Large

RFC first. Do not start implementation until the user accepts an RFC or explicitly names Phase 1 of an approved plan.

Traits:

Architecture or platform boundary change.
API + DB + UI together.
Monorepo-wide migration or multi-repo split.
User prompt implies unbounded scope ("refactor everything", "update all docs", "while you're at it").

Default XL areas:

window manager rewrite
new backend platform (auth + API + storage together)
app contract redesign
monorepo extraction across many apps
multi-repo split
docs-wide architecture rewrite without a plan

Examples:

Greenfield auth and permission model
Replace Spaces model and routing semantics
Full micro-frontend runtime with federation

Trigger Words

If the user message includes any of the following (any language), run Triage Mode at minimum:

English: refactor, migrate, extract, architecture, redesign, rewrite, all apps, including but not limited to, optimize while here, performance overhaul, routing, state management, database, API, auth, permissions, upload, storage, R2, Neon, Cloudflare Workers, window manager, virtual desktop, fullscreen, app contract, micro app, monorepo, rewrite all docs.

Other languages: Treat equivalent phrases the same (full rewrite, architecture change, migration, extract modules, update all documentation, scope expansion while here).

Expansion phrases: "also", "while you're at it", "and update all related docs", "in passing".

RFC Heuristics

Prefer an RFC when any apply:

Touches more than one package with new contracts.
Changes long-lived architecture boundaries.
Involves API, DB, auth, or permissions.
Affects window manager or app contract semantics.
Requires multiple PRs or >30 minutes of focused work.
Likely >10 files changed without a written split.

Estimated Effort (guidance only)

Level	Typical effort	Typical files
S	Minutes	1–2
M	Under 1 hour	2–8
L	Hours to days	8–15 per slice
XL	Days+	RFC + multiple slices

AI Cost Gate

On this page