derHaken/SuperAntigravity

# Architecture Design

## Overview

Design before you build. Architecture decisions are expensive to change.
Understand constraints, explore options, validate trade-offs, then decide.

## When to Use

- Starting a new system or significant new component
- Evaluating whether to build vs. use existing solutions
- Making decisions that will affect multiple parts of the system
- Choosing between fundamentally different structural approaches
- Designing APIs, data models, or service boundaries

# Brainstorming Ideas Into Designs

## Overview

Help turn ideas into fully formed designs and specs through natural collaborative dialogue.

Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design and get user approval.

<HARD-GATE>
Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it. This applies to EVERY project regardless of perceived simplicity.

Announce: "Design HARD-GATE: I will not write code or scaffold files until you approve this design."

An implementation action is: writing any file that will be part of the product (src/, lib/, app/), running npm init/create-*, generating scaffolding.

# Browser Agent

## Overview

Antigravity includes a built-in browser subagent that can autonomously interact with web applications.
The main agent delegates browser tasks to it — this skill governs when and how to do that correctly.

The browser agent is NOT a general-purpose web search tool. It is a UI interaction and verification tool.
Use it when you need to *act on* a web page, not just *read* information from it.

## Prerequisites

Before any browser task, verify:

# Confidence Check

## Overview

A quick self-assessment before implementation. If confidence is below threshold,
gather more information first. Don't build on shaky understanding.

## When to Use

- Before starting implementation of a feature
- When requirements feel ambiguous
- After reading existing code that you're about to modify
- When you're unsure about a technical approach

# Deep Research

## Overview

Systematic multi-source research before acting on unknowns. Never guess when you can verify.
Plan your searches, execute in parallel where possible, synthesize before concluding.

## When to Use

- Starting work on an unfamiliar library, framework, or API
- Validating a technical approach before committing
- Answering questions that require current information
- Comparing options or evaluating trade-offs
- Verifying security practices or compatibility

# Dependency Management

## Overview

Every dependency is a commitment -- to its maintenance, security surface, and upgrade path. Add deliberately, update strategically, audit regularly.

**Core principle:** Every dependency decision should be justified. Don't add what you can write. Don't ignore what you can update. Don't skip what you can audit.

## When to Use

- Adding a new package or library to a project
- Security audit warnings (npm audit, pip-audit, cargo audit, etc.)
- Batch dependency update time
- Major version upgrade decisions

# Dispatching Parallel Agents

## Overview

When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.

**Core principle:** Dispatch one agent per independent problem domain. Let them work concurrently.

## When to Use

```dot
digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];

# Executing Plans

## Overview

Load plan, review critically, execute tasks in batches, report for review between batches.

**Core principle:** Batch execution with checkpoints for architect review.

**Announce at start:** "I'm using the executing-plans skill to implement this plan. **REQUIRED:** Ensure Antigravity is set to **Fast Mode** for efficient execution."

## Step 0: Prerequisites

**STOP if:**
- (a) You are on main or master branch without explicit user instruction

# Finishing a Development Branch

## Overview

Guide completion of development work by presenting clear options and handling chosen workflow.

**Core principle:** Verify tests → Present options → Execute choice → Clean up.

**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."

## The Process

### Step 1: Verify Tests

# Performance Optimization

## Overview

Measure first, optimize second. Never optimize without data.
The bottleneck is almost never where you think it is.

## When to Use

- Code is measurably slow or resource-heavy
- Profiling has revealed specific bottlenecks
- Designing a system with known performance requirements
- Reviewing code for performance before production

# Code Review Reception

## Overview

Code review requires technical evaluation, not emotional performance.

**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.

## The Response Pattern

```
WHEN receiving code review feedback:

1. READ: Complete feedback without reacting

# Requesting Code Review

Dispatch a code-reviewer subagent to catch issues before they cascade.

**Core principle:** Review early, review often.

## When to Request Review

**Mandatory:**
- After each task in subagent-driven development
- After completing major feature
- Before merge to main

**Optional but valuable:**

# Security Review

## Overview

Security is not a feature — it's a property of the entire system.
Review security boundaries systematically, not ad-hoc.

## When to Use

- Authentication, authorization, session management code
- Any user input that touches storage, commands, or rendering
- Secrets, credentials, API keys in code or config
- Before a security-sensitive feature ships
- After any change to auth flows or data access controls

# Subagent-Driven Development

Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.

**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration

## When to Use

```dot
digraph when_to_use {
    "Have implementation plan?" [shape=diamond];
    "Tasks mostly independent?" [shape=diamond];
    "Stay in this session?" [shape=diamond];
    "subagent-driven-development" [shape=box];

# Systematic Debugging

## Overview

Random fixes waste time and create new bugs. Quick patches mask underlying issues.

**Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure.

**Violating the letter of this process is violating the spirit of debugging.**

## The Iron Law

```
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

# Test-Driven Development (TDD)

## Overview

Write the test first. Watch it fail. Write minimal code to pass.

**Core principle:** If you didn't watch the test fail, you don't know if it tests the right thing.

**Violating the letter of the rules is violating the spirit of the rules.**

## When to Use

**Always:**
- New features

# Using SuperAntigravity

## Overview

You have superantigravity installed. Before any action, check if a skill applies.
Skills are loaded automatically in Antigravity when the task matches the description.

<EXTREMELY-IMPORTANT>
If you think there is even a 1% chance a skill might apply to what you are doing,
you ABSOLUTELY MUST let Antigravity load and read it.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT.

This is not negotiable. This is not optional. You cannot rationalize your way out of this.

# Verification Before Completion

## Overview

Claiming work is complete without verification is dishonesty, not efficiency.

**Core principle:** Evidence before claims, always.

**Violating the letter of this rule is violating the spirit of this rule.**

## The Iron Law

```
NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

# Writing Plans

## Overview

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

**Announce at start:** "I'm using the writing-plans skill to create the implementation plan."

**Context:** This should be run in a dedicated worktree (created by brainstorming skill).

**Save plans to:** `docs/plans/YYYY-MM-DD-<feature-name>.md`

# Writing Skills

## Overview

**Writing skills IS Test-Driven Development applied to process documentation.**

**Personal skills live in `~/.gemini/antigravity/skills/`**

You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes).

**Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing.

**REQUIRED BACKGROUND:** You MUST understand test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation.