Workflow System and Turbo Annotations

Relevant source files

• Google/Antigravity/Fast Prompt.txt

This document describes Antigravity's workflow system, which enables the creation of reusable, step-by-step procedures stored as markdown files in the .agent/workflows/ directory. Workflows can include special // turbo and // turbo-all annotations that control automatic command execution through the SafeToAutoRun parameter of the run_command tool.

For information about Antigravity's broader architecture and tool ecosystem, see System Architecture and Identity. For details on the run_command tool itself, refer to the tool documentation in the Fast Prompt system.

Workflow File Structure

Antigravity workflows are markdown files stored in .agent/workflows/*.md with a specific YAML frontmatter format. Each workflow file combines metadata and procedural content:

File Format:

The structure separates the workflow's purpose (frontmatter) from its implementation (markdown body). The description field provides a concise, human-readable title that summarizes the workflow's objective.

Storage Location: Google/Antigravity/Fast Prompt.txt79

• All workflows reside in .agent/workflows/ directory
• Filenames should be descriptive and use lowercase with hyphens or underscores
• Absolute paths are required when creating new workflows

Workflow File Structure Diagram

Sources: Google/Antigravity/Fast Prompt.txt78-98

Turbo Annotations System

Turbo annotations are special comments (// turbo and // turbo-all) embedded in workflow markdown that control automatic command execution. These annotations modify the behavior of the run_command tool's SafeToAutoRun parameter, enabling workflows to execute without user confirmation when deemed safe.

Single-Step Turbo Annotation

The // turbo annotation applies to a single step only. When placed above a workflow step, it signals that the immediately following step involving run_command should execute automatically.

Syntax: Google/Antigravity/Fast Prompt.txt87-94

2. Make a folder called foo
// turbo
3. Make a folder called bar

In this example:

• Step 2: Uses normal judgment for SafeToAutoRun determination
• Step 3: Must set SafeToAutoRun: true due to // turbo annotation
• Subsequent steps: Revert to normal judgment

Behavior:

• Annotation only affects the next step that uses run_command
• Does not cascade to subsequent steps
• Agent must still evaluate step context and command safety

Global Turbo Annotation

The // turbo-all annotation applies to every step in the workflow. When present anywhere in the workflow file, it overrides normal safety checks for all run_command invocations.

Syntax: Google/Antigravity/Fast Prompt.txt95

---
description: Fully automated deployment
---
// turbo-all

1. Build application
2. Run tests
3. Deploy to server
4. Restart services

Behavior:

• Global scope: affects all steps regardless of position
• Placement: can appear anywhere in the workflow body
• Mandatory execution: Agent MUST set SafeToAutoRun: true for every run_command call
• Used for trusted, repeatable workflows where manual confirmation would be counterproductive

Turbo Annotation Decision Flow

Sources: Google/Antigravity/Fast Prompt.txt87-95

Command Automation Mechanism

Turbo annotations interface directly with the run_command tool's safety system. Understanding this integration clarifies how annotations translate to executable behavior.

run_command Tool Parameters

The run_command tool accepts these relevant parameters:

Parameter	Type	Purpose
CommandLine	string	The exact command to execute
Cwd	string	Current working directory
SafeToAutoRun	boolean	If true, executes without user approval
WaitMsBeforeAsync	number	Delay before backgrounding the command
waitForPreviousTools	boolean	Sequential vs parallel execution control

Key Mechanism: Google/Antigravity/Fast Prompt.txt87-95

• Normal workflow steps: Agent evaluates command safety and sets SafeToAutoRun accordingly
• // turbo step: Agent must set SafeToAutoRun: true
• // turbo-all workflow: Agent must set SafeToAutoRun: true for all commands

Integration Architecture

Sources: Google/Antigravity/Fast Prompt.txt78-98 Google/Antigravity/Fast Prompt.txt490-502

Workflow Invocation Methods

Antigravity supports multiple methods for invoking workflows, each suited to different interaction patterns.

Method 1: Slash Command Invocation

Workflows can be invoked using slash commands that map directly to filenames.

Mechanism: Google/Antigravity/Fast Prompt.txt96

/slash-command → .agent/workflows/slash-command.md

When the user types /deploy-app, the agent:

1. Detects the slash command pattern
2. Constructs the path: .agent/workflows/deploy-app.md
3. Uses view_file tool to read the workflow
4. Executes the steps sequentially

Implementation:

• Filename must match the slash command (excluding the / prefix)
• Agent automatically looks in .agent/workflows/ directory
• No explicit file path required from user

Method 2: Relevant Workflow Detection

The agent can proactively identify and suggest workflows that match the user's intent.

Mechanism: Google/Antigravity/Fast Prompt.txt96

If a workflow looks relevant, [...] use the view_file tool to read 
.agent/workflows/[filename].md

Example Scenario:

USER: I need to deploy the application to production
AGENT: I found a workflow for deployment. Let me check it.
AGENT: [calls view_file on .agent/workflows/deploy-production.md]
AGENT: This workflow includes steps for building, testing, and deploying...

The agent:

1. Analyzes user request
2. Searches .agent/workflows/ directory (using list_dir or find_by_name)
3. Reads relevant workflow(s)
4. Executes or proposes execution

Method 3: Explicit Workflow Creation

Users can request new workflows, triggering a creation process.

Mechanism: Google/Antigravity/Fast Prompt.txt86

You might be asked to create a new workflow. If so, create a new file in 
.agent/workflows/[filename].md (use absolute path) following the format 
described above. Be very specific with your instructions.

Workflow Invocation Pipeline

Sources: Google/Antigravity/Fast Prompt.txt78-98

Creating New Workflows

When creating workflows, the agent must follow specific requirements to ensure consistency and functionality.

Creation Requirements

Mandatory Elements: Google/Antigravity/Fast Prompt.txt86

1. Absolute path: Must use full path when writing file
2. YAML frontmatter: Must include description field
3. Specific instructions: Steps must be detailed and actionable

Format Template:

Best Practices for Workflow Content

Specificity Requirements:

• Include exact command syntax: npm run build not "build the project"
• Specify directory paths: cd /path/to/project not "navigate to project"
• Define success criteria: "Verify server responds with 200 OK"

Turbo Annotation Guidelines:

• Use // turbo for safe, idempotent operations (mkdir, file reads, status checks)
• Use // turbo-all for fully automated, tested workflows
• Avoid turbo annotations for destructive operations (rm, drop database)

Workflow Creation Example

Sources: Google/Antigravity/Fast Prompt.txt78-98

Workflow Execution Semantics

Understanding how workflows execute provides insight into their operational model.

Sequential Step Execution

Workflows execute steps in order, respecting dependencies and tool call patterns:

Step Processing:

1. Agent reads workflow file using view_file
2. Parses YAML frontmatter and markdown body
3. Processes steps sequentially (unless explicitly parallelized)
4. Evaluates turbo annotations before each run_command call
5. Waits for completion before proceeding (unless WaitMsBeforeAsync is set)

Interaction with waitForPreviousTools: While turbo annotations control SafeToAutoRun, the waitForPreviousTools parameter controls execution order:

• waitForPreviousTools: true → Sequential execution (wait for previous tools)
• waitForPreviousTools: false → Parallel execution (if tools are independent)

Error Handling and Recovery

Workflows do not inherently include error handling beyond what the run_command tool provides:

Agent Responsibilities:

• Monitor command_status for command failures
• Parse error output from executed commands
• Decide whether to continue, retry, or abort workflow
• Report failures to user with context from workflow step

Example Error Scenario:

Workflow Step 3: Deploy to server
Command: ssh deploy@server 'bash /deploy.sh'
Result: Connection timeout
Agent Action: Stop workflow, report failure, suggest debugging steps

Workflow Execution State Machine

Sources: Google/Antigravity/Fast Prompt.txt78-98 Google/Antigravity/Fast Prompt.txt490-502

Workflow System Design Rationale

The workflow system addresses several key requirements in agentic AI assistants:

Repeatability and Documentation

Problem: Complex multi-step procedures must be executed consistently across sessions.

Solution: Workflows persist procedures as files, enabling:

• Version control: Workflows can be committed to git
• Sharing: Team members access the same procedures
• Iteration: Workflows evolve based on lessons learned

Automation Control

Problem: Some steps are safe to automate, others require human oversight.

Solution: Turbo annotations provide fine-grained control:

• Single-step turbo: Selectively automate safe operations
• Global turbo-all: Fully automate trusted workflows
• No annotation: Agent evaluates each command individually

Discoverability

Problem: Users may not know what procedures are available.

Solution: Multiple invocation methods:

• Slash commands: Explicit, tab-completable invocation
• Relevance detection: Agent suggests applicable workflows
• Directory structure: .agent/workflows/ provides clear organization

Agent Guidance

Problem: Agents must handle complex procedures reliably.

Solution: Workflows provide:

• Structured instructions: Step-by-step guidance reduces errors
• Context preservation: Each step builds on previous results
• Clear specifications: "Be very specific with your instructions"

Workflow System Architecture Summary

Sources: Google/Antigravity/Fast Prompt.txt78-98 Google/Antigravity/Fast Prompt.txt490-502

Usage Recommendations

When to Create Workflows

Create workflows for:

• Deployment procedures: Multi-step deployments with testing and verification
• Environment setup: Reproducible development environment initialization
• Testing pipelines: Sequential test execution with result validation
• Data migrations: Database schema changes with backup and rollback steps
• Build processes: Complex build pipelines with conditional steps

When to Use Turbo Annotations

Use // turbo for:

• File system operations (mkdir, cp, mv)
• Status checks (git status, npm list)
• Read-only commands (cat, grep, find)
• Idempotent operations that can safely retry

Use // turbo-all for:

• Fully tested, stable workflows
• Workflows executed frequently by the team
• Automated CI/CD pipelines
• Known-safe operation sequences

Avoid turbo annotations for:

• Destructive operations (rm -rf, drop table)
• Network operations with side effects (API calls that modify data)
• Commands requiring user input
• Operations in production environments without proper safeguards

Sources: Google/Antigravity/Fast Prompt.txt78-98