Module 1: SDLC Productivity 75 min¶

Your first real Antigravity CLI session. This module covers the core daily-driver workflows — understanding code, refactoring, generating tests, and reviewing changes — plus how to extend the CLI with plugins for your team's toolchain.

1.0 — First Interactive Session 5 min¶

Launch Antigravity CLI in your workshop project directory:

cd agy-cli-field-workshop
agy

You'll land in the interactive prompt. Try:

> What files are in this project and what does each one do?

Observe how agy reads your workspace — it indexes the git repo, reads file contents, and responds with context. This is automatic: no config, no prompts to write first.

1.1 — Code Understanding 10 min¶

Pattern: Explain Before You Touch — understand the code before changing it.

Exercise: Map an Unfamiliar Codebase¶

# -i seeds the session with an initial prompt and stays interactive
agy -i "Give me a high-level architecture overview of this project. What are the main components and how do they connect?"

Then follow up interactively:

> Which file handles the entry point?
> What external dependencies does this project have?
> Are there any obvious code smells or tech debt?

1.2 — Refactoring 10 min¶

Pattern: Propose, Review, Apply — never apply changes you haven't read.

Exercise: Targeted Refactor¶

agy

> I want to refactor the error handling in this project. First, show me all the places where errors are currently caught or returned — don't change anything yet.

Review the findings. Then:

> Now propose a refactored version of [specific function] using a consistent error handling pattern. Show me the diff before applying.

Only apply after you've read the proposed change.

Permissions Model¶

agy has a 3-level permissions model that controls how it handles tool approvals:

Use the /permissions slash command to view or change the current level. You can also set fine-grained rules in settings.json:

{
  "permissions": {
    "allow": ["command(git)", "read_file"],
    "deny": ["command(rm -rf)"]
  }
}

📖 Full details: Permissions docs · Strict Mode docs

1.3 — Test Generation 10 min¶

Pattern: Test What Exists — generate tests for real code, not hypotheticals.

Exercise: Generate Unit Tests¶

agy

> Look at [specific function or file]. Generate a comprehensive unit test suite for it. Include happy path, edge cases, and error conditions. Use the testing framework already in this project.

Then:

> Run the tests and fix any that fail.

1.4 — Code Review 10 min¶

Pattern: Pre-Commit Review — use agy as a senior reviewer before every push.

Exercise: Review Your Changes¶

# Stage some changes (or use an existing branch)
git add -p

# Start agy and review what's staged
agy

> Review my staged changes for: (1) correctness, (2) security issues, (3) missing test coverage, (4) anything that would block a PR. Be direct — don't soften findings.

Headless Variant (for scripting)¶

# Review changes non-interactively — useful in pre-commit hooks or CI
git diff --cached | agy --print "Review these changes. Flag any bugs, security issues, or missing tests. Output as markdown."

1.5 — Project Context with AGENTS.md 5 min¶

Pattern: Persistent Context — tell agy once, it remembers every session.

agy reads context files at session start. Create one at the project root:

cat > AGENTS.md << 'EOF'
# Project Context

This is a Node.js REST API built with Express and TypeScript.

## Key Conventions
- Language: TypeScript (strict mode, no `any`)
- Testing: Jest with 80% coverage minimum; run `npm test` to validate
- Style: ESLint + Prettier; run `npm run lint` before committing
- DO NOT modify `src/db/migrations/` — those are append-only
- DO NOT use `console.log` in production code; use the `logger` utility

## Architecture
Three-layer: `routes/` → `services/` → `repositories/`. All DB access goes through the repository layer. External HTTP calls go through `src/clients/`.

## Common Commands
- `npm run dev` — start local dev server on :3000
- `npm test` — run full test suite
- `npm run db:migrate` — apply pending DB migrations
EOF

Now start a new session:

agy --print "What do you know about this project?"

agy will incorporate your AGENTS.md into every subsequent session automatically.

Additional Context Sources¶

Beyond AGENTS.md, agy also loads:

• .agents/rules.md (or .agents/rules/*.md) — project-level rules injected as system prompt directives. Use these for hard requirements like "never delete migration files" or "always use TypeScript strict mode."
• .gemini/ — for Gemini CLI compatibility, agy reads .gemini/ directories alongside .agents/.
• ~/.gemini/config/rules.md — global rules applied to all sessions.

📖 Full details: Rules & Workflows docs

Sample Agent Definitions (in samples/agents/)¶

1.6 — Interactive Navigation 5 min¶

Pattern: Terminal Fluency — know the shortcuts that make agy sessions fast. 📖 Full reference: Using Antigravity CLI

Key Slash Commands¶

📖 Full slash command reference: CLI Features

Quick Tips¶

📖 Full keybindings reference: Using Antigravity CLI

1.7 — Extend with Plugins 15 min¶

Pattern: Bring Your Toolchain — plugins add skills, MCP servers, agents, and rules to agy. Install once, available in every session.

Antigravity CLI's plugin system does something unique: it can import plugins you've already installed in Gemini CLI — without reinstalling or reconfiguring. Your existing investment carries over.

See What's Active¶

agy plugin list

Shows each plugin's name, source, import date, and components (skills, commands, mcpServers, agents).

Import from Gemini CLI¶

agy plugin import gemini

agy scans your local Gemini CLI installation, discovers all installed plugins, and stages their components into ~/.gemini/antigravity/. Output:

  [ok]    code-review
          ✔ skills      : 3 processed
          ✔ commands    : 2 processed
          - mcpServers  : skipped (not found)
  [ok]    gemini-deep-research
          ✔ commands    : 1 processed
          ✔ mcpServers  : 1 processed
  [skip]  superpowers (already imported)

agy plugin import gemini --force

What Gets Imported¶

Enable / Disable Per-Project¶

Not every plugin is appropriate for every codebase:

# Disable for this project
agy plugin disable gemini-deep-research

# Re-enable
agy plugin enable gemini-deep-research

Plugin Locations¶

Building a Custom Plugin¶

A valid agy plugin needs a plugin.json manifest:

my-plugin/
├── plugin.json          ← required
├── mcp_config.json      ← MCP server definitions (optional)
├── hooks.json           ← hook event handlers (optional)
├── skills/              ← SKILL.md files (optional)
│   └── my-skill/
│       └── SKILL.md
├── agents/              ← subagent definitions (optional)
└── rules/               ← rules files (optional)
    └── my-rules.md

{
  "name": "my-plugin",
  "version": "1.0.0",
  "description": "My custom agy plugin",
  "components": ["skills"]
}

Validate it before shipping:

agy plugin validate ./my-plugin
# ✔ Plugin manifest is valid

📖 Full reference: Plugins · Migration guide

Module 1 Exercises¶

Next Module¶

→ Module 2: Legacy Codebase Modernization — strict mode, agent self-onboarding, subagents, and /rewind as your safety net.