Upgrade Protocol Quick Reference
The step-by-step process for converting friction into permanent brain improvements.
The Core Loop
Every pass through this loop reduces future effort.
Step 1: Detect the Trigger
The upgrade protocol starts when one of three triggers fires:
Repetition Trigger
Condition: You explain the same thing for the 2nd or 3rd time.
Output: A new Rule — a persistent constraint the agent always follows.
Example: You keep telling the agent to use TypeScript strict mode → becomes a rule.
Manual Labor Trigger
Condition: A multi-step sequence requires high context and is repeated.
Output: A new Skill or Workflow — a reusable procedure.
Example: Deploying always requires the same 5 steps → becomes a skill.
Unwritten Law Trigger
Condition: You correct a preference or convention.
Output: An immediate Rule update — codify the preference now.
Example: "No, always use named exports, not default exports" → becomes a rule.
Step 2: Propose the Upgrade
When a trigger fires, the agent presents the upgrade in this mandatory format:
🧠 Brain Upgrade Proposed
Observation: [what pattern you detected]
Suggestion: [the rule, skill, or workflow to create]
Benefit: [how this reduces future friction]
Action: "Shall I create this now?"Human-in-the-Loop
Step 3: Implement the Upgrade
Once approved, the agent creates the appropriate file in your .agent/ directory.
If the output is a Rule:
.agent/rules/api-error-handling/RULE.md
---
name: api-error-handling
description: Standardizes error handling in API routes. Apply when creating or modifying API endpoints.
globs: ["**/api/**/*.ts", "**/routes/**/*.ts"]
---
# API Error Handling
## Rules
- Always wrap async handlers in try/catch
- Return structured error responses: { error: string, code: number }
- Log errors with context (endpoint, params, user)
- Never expose internal error messages to clients
- Use appropriate HTTP status codes (400 for validation, 401 for auth, 500 for server)If the output is a Skill:
.agent/skills/create-api-endpoint/SKILL.md
---
name: create-api-endpoint
description: Step-by-step procedure for creating a new API endpoint with proper error handling, validation, and tests.
---
# Create API Endpoint
## Steps
1. Define the route and HTTP method
2. Add input validation (schema or manual)
3. Implement the business logic
4. Add error handling per the api-error-handling rule
5. Write at least one happy-path and one error-path test
6. Update API documentation if it existsStep 4: Verify It Works
After creating the upgrade, test that the agent actually follows it:
Ask the agent to perform a task that should trigger the new rule or skill
Verify the output matches the expected behavior
If the agent ignores the rule, revise the wording — rules that use concrete examples work better than abstract principles
Quick Decision Guide
Repeated explanation → Create a Rule (passive constraint)
Multi-step process → Create a Skill (action-oriented procedure)
Complex orchestration → Create a Workflow (multi-skill sequence)
Preference correction → Update an existing Rule immediately
This template was last reviewed in April 2026 against the official Antigravity rules & workflows docs. Spot something out of date? Let us know.