DOCSEARCHbyAlgolia
Submit Docs

SuperAntigravity Documentation

repository·main·Indexed 19 days ago

https://github.com/derhaken/superantigravity

An AI-assisted development workflow for the Google Antigravity IDE. It provides a structured pipeline of 19 skills, 16 slash commands (such as /brainstorm, /plan, and /implement), and 6 specialist agents to automate the software development lifecycle from design and TDD implementation to code review and Git operations.

Tokens
37.1K
Snippets
56
Records
146
Agent score
63%

What's inside SuperAntigravity

  1. How SuperAntigravity works

    main

    SuperAntigravity operates by bootstrapping itself into your Antigravity environment.

    1. Bootstrap: The installation adds a bootstrap block to your GEMINI.md file, which is always-on.
    2. Filesystem Structure: The system populates specific directories in your home folder:
      • Skills: ~/.gemini/antigravity/skills/
      • Workflows: ~/.gemini/antigravity/global_workflows/
      • Agents: ~/.gemini/antigravity/agents/
    3. Execution: During a session, the Agent reads GEMINI.md to identify available skills. Skills trigger automatically based on description matching, while slash commands are explicitly invoked via workflows.

  2. How to write good tests in TDD

    main

    To ensure TDD provides high confidence and documentation, follow these quality standards for your tests:

    • Minimalism: Each test should verify exactly one thing. If your test name contains the word "and" (e.g., test('validates email and domain')), split it into multiple tests.
    • Clarity: The test name should clearly describe the expected behavior, not just a generic label like test1.
    • Intent: The test should demonstrate the desired API and behavior of the code, rather than obscuring it.
    • Realism: Test real behavior using real code. Avoid testing mock behavior (e.g., checking if a mock was called) instead of checking the actual outcome of the logic. Use mocks only for external dependencies when unavoidable.

  3. How SuperAntigravity architecture works

    main

    SuperAntigravity operates on three layers within the Google Antigravity IDE, utilizing native extension mechanisms to provide different types of agent behaviors:

    1. Bootstrap Layer (~/.gemini/GEMINI.md): Always-on behavioral guidelines. It instructs the agent that it has skills installed and mandates that it must check them before taking action.
    2. Skills Layer (~/.gemini/antigravity/skills/*/SKILL.md): Semantically triggered, lazy-loaded workflow pipelines and specialist skills that the agent invokes automatically based on the task context.
    3. Workflows Layer (~/.gemini/antigravity/global_workflows/*.md): Explicit entry points triggered by the user via slash commands (e.g., /command).

  4. Use the dependency-management skill

    main

    The dependency-management skill is designed to guide decisions regarding project dependencies. You should invoke this skill when performing any of the following tasks:

    • Adding new packages: Evaluating whether to add a new library or package to a project.
    • Security Audits: Responding to security audit warnings (e.g., npm audit, pip-audit, cargo audit).
    • Updates: Managing batch dependency updates or making major version upgrade decisions.
    • Evaluation: Choosing between alternative libraries or questioning if a package is still maintained.
    • Conflict Resolution: Handling lockfile merge conflicts.

    Do NOT use this skill for:

    • Internal module or code organization (use refactoring instead).
    • Learning a single package's API (use research instead).

  5. Organize Skill files based on content complexity

    main

    Choose a directory structure based on the amount of reference material and code required for the skill:

    • Self-Contained Skill: Use a single directory containing only SKILL.md. Best when all content fits inline.
    • Skill with Reusable Tool: A directory containing SKILL.md and an external code file (e.g., example.ts). Use this when the skill provides a reusable helper or tool.
    • Skill with Heavy Reference: A directory containing SKILL.md plus multiple specialized documentation files (e.g., api-reference.md, xml-structure.md) and potentially a scripts/ folder for executable tools. Use this when the reference material is too large for a single file.
    ### Self-Contained Skill
defense-in-depth/
  SKILL.md    # Everything inline

### Skill with Reusable Tool
condition-based-waiting/
  SKILL.md    # Overview + patterns
  example.ts  # Working helpers to adapt

### Skill with Heavy Reference
pptx/
  SKILL.md       # Overview + workflows
  pptxgenjs.md   # 600 lines API reference
  ooxml.md       # 500 lines XML structure
  scripts/       # Executable tools

  6. How to create skills using TDD

    main

    Creating a skill in SuperAntigravity follows a Test-Driven Development (TDD) cycle applied to process documentation. Instead of writing documentation first, you use 'pressure scenarios' (tests) to verify the need for a skill.

    The RED-GREEN-REFACTOR Cycle for Skills

    1. RED (Test Fails): Run a baseline scenario (a task/pressure scenario with a subagent) BEFORE writing the skill. Observe the agent violating rules or failing to follow the desired pattern. Document the exact rationalizations the agent uses to justify its failure.
    2. GREEN (Test Passes): Write the SKILL.md document addressing those specific violations. Verify that the agent now complies with the skill when it is present.
    3. REFACTOR: Identify new loopholes or rationalizations the agent uses to bypass the skill. Update the documentation to plug these holes and re-verify compliance.
    ### TDD Mapping for Skills

| TDD Concept | Skill Creation |
|-------------|----------------|
| **Test case** | Pressure scenario with subagent |
| **Production code** | Skill document (SKILL.md) |
| **Test fails (RED)** | Agent violates rule without skill (baseline) |
| **Test passes (GREEN)** | Agent complies with skill present |
| **Refactor** | Close loopholes while maintaining compliance |
| **Write test first** | Run baseline scenario BEFORE writing skill |
| **Watch it fail** | Document exact rationalizations agent uses |
| **Minimal code** | Write skill addressing those specific violations |
| **Watch it pass** | Verify agent now complies |
| **Refactor cycle** | Find new rationalizations → plug → re-verify |

  7. Resolve open questions in architecture design

    main

    After providing a design, any remaining open questions must be assigned to one of three categories:

    • (user): Questions regarding business requirements, organizational constraints, or budget. Note: If a user-assigned question is blocking, the design cannot be finalized until answered.
    • (deep-research skill): Questions answerable by researching technical documentation, benchmarks, or compatibility.
    • (implementation discovery): Questions answerable only by building a spike or prototype; it is acceptable to proceed and revisit these later.

  8. Trace root cause in deep call stacks

    main

    When an error occurs deep within a call stack, use the Trace Data Flow technique:

    1. Start at the line where the error is thrown.
    2. Follow the call stack upward.
    3. Note each function's inputs and outputs.
    4. Continue until you find the point where the actual behavior diverges from the expected behavior.

    Goal: Identify where the 'bad value' originates and fix it at the source, not at the symptom.

  9. Required workflow skills for plan execution

    main

    The executing-plans skill is part of a larger workflow and relies on the following skills:

    • writing-plans: Used to create the initial plan that executing-plans will then execute.
    • finishing-a-development-branch: REQUIRED to be loaded after all tasks in the plan are completed and verified to finalize the development work.
    • systematic-debugging: To be loaded if a batch fails due to test failures.

  10. Pattern for Dispatching Parallel Agents

    main

    To successfully implement parallel dispatch, follow this four-step pattern:

    1. Identify Independent Domains: Group failures by what is broken (e.g., File A tests tool approval, File B tests batch completion). Ensure fixing one domain does not affect the others.
    2. Create Focused Agent Tasks: For each agent, define a Specific scope (one test file or subsystem), a Clear goal (make these tests pass), Constraints (e.g., "Don't change other code"), and an Expected output (a summary of findings and fixes).
    3. Dispatch in Parallel: Use the Task() command to trigger multiple investigations simultaneously.
    4. Review and Integrate: Once agents return, read each summary, verify that fixes do not conflict, run the full test suite, and integrate all changes.

  11. How skills work in SuperAntigravity

    main

    Skills are semantically triggered components that are loaded automatically by the Google Antigravity IDE when a user's task matches a skill's description.

    Key Concepts

    • Automatic Loading: The agent reads descriptions for all installed skills and loads the full content of matching ones before taking action.
    • Skill Priority:
      1. Process skills (e.g., brainstorming, systematic-debugging) are used first to determine how to approach a task.
      2. Implementation skills (e.g., architecture-design, deep-research) are used second to guide the actual execution.
    • Skill Types:
      • Rigid: Must be followed exactly (e.g., test-driven-development, systematic-debugging).
      • Flexible: Principles that should be adapted to the specific context (e.g., patterns).

    Mandatory Skill Check

    Users and agents must check for relevant skills before taking any action, including asking clarifying questions, exploring files, writing code, or debugging. If there is even a 1% chance a skill applies, it must be loaded.

  12. Pipeline Gates and Transitions

    main

    To move between stages in the SuperAntigravity pipeline, specific conditions (gates) must be met:

    1. Design → Plan: The user must explicitly approve the generated design document.
    2. Plan → Implement: A plan file must exist in docs/plans/ and all tasks must include exact file paths.
    3. Implement → Review: All tasks defined in the plan must be complete and all tests must be green (passing).
    4. Review → Ship: The code-reviewer agent must issue an APPROVED or APPROVED WITH SUGGESTIONS verdict.
    5. Ship: The verification-before-completion skill must pass and the finishing-a-development-branch skill must be executed.