🧠 Antigravity Cortex

The intelligent .agents kit that makes AI coding agents actually think before they code.

Quick Start

One command. Zero config. Instant intelligence.

# Navigate to your project and run:
npx antigravity-cortex

That's it. The .agents/ directory is now installed in your project. Open VS Code with Gemini and start coding smarter.

What is this?

Antigravity Cortex is a structured .agents kit -- a collection of rules, workflows, and skills that transform how AI coding agents behave. Instead of blindly generating code, your AI agent will:

• 🤔 Ask before coding (Socratic Gate)
• 📋 Plan before implementing (structured workflows)
• 🔍 Review its own work (multi-lens self-check)
• 🛡️ Follow security practices (OWASP-aware)
• ✅ Verify before claiming done (mandatory exit gates)

Why?

Most AI coding agents suffer from:

Installation

Option 1: npx (Recommended)

The fastest way to get started. No global install needed.

cd your-project
npx antigravity-cortex

This will copy the .agents/ directory into your project with all rules, workflows, and skills.

Already have .agents/? Use --force to overwrite:

npx antigravity-cortex --force

Option 2: npm Global Install

Install once, use everywhere:

npm install -g antigravity-cortex

# Then in any project:
cd your-project
antigravity-cortex

Option 3: Git Clone

For contributors or those who want to inspect the source:

git clone https://github.com/nvtphong/antigravity-cortex.git
cp -r antigravity-cortex/.agents /path/to/your/project/

Prerequisites

• IDE: VS Code or Cursor (or any editor with Gemini integration)
• AI Agent: Gemini Code Assist (Antigravity) -- the .agents structure is natively supported by Google Gemini's agent system
• No extra extensions needed -- Gemini automatically detects the .agents/ directory in your project root

Note: This kit is built exclusively for Antigravity (Gemini). Other AI agents (Copilot, Cursor AI, etc.) may not fully support the .agents/ structure.

Usage Guide

How It Works -- The 3-Layer System

Cortex operates on 3 layers that work together automatically:

📦 Your Request
  |
  +-- 🔒 Rules (always active, invisible)
  |     Agent automatically asks questions, follows clean code standards,
  |     validates its own work -- you don't need to do anything.
  |
  +-- ⚡ Workflows (you trigger with /commands)
  |     Type a slash command to activate a structured workflow.
  |     e.g. /cook, /debug, /fix, /plan
  |
  +-- 📚 Skills (auto-loaded by keywords)
        Agent detects keywords in your request and loads
        relevant domain knowledge behind the scenes.

Using Workflows (Slash Commands)

Type a /command followed by your task description in the chat. The agent will follow a structured, multi-step process:

🍳 /cook -- Build a Feature

The main implementation workflow. Research -> Plan -> Code -> Test -> Self-review -> Done.

/cook add dark mode toggle to the settings page
/cook implement user avatar upload with image cropping
/cook create a REST API endpoint for order history

What happens when you type /cook add dark mode toggle:

1. Classify -- Agent detects "moderate complexity" (multi-file)
2. Socratic Gate -- Agent asks: "CSS-only or save preference to DB? Which pages should support dark mode?"
3. Research -- Agent scans your codebase for existing theme/CSS patterns
4. Plan -- Agent creates an implementation plan and asks for your approval
5. Implement -- Agent writes the code, following your existing patterns
6. Self-Review -- Agent checks for security issues, edge cases, performance
7. Verify -- Agent runs build/tests and confirms everything works

🐛 /debug -- Investigate a Bug

For when you don't know why something is broken. Systematic investigation, not random guesses.

/debug login returns 500 error after upgrading auth library
/debug images don't load on the product page in production
/debug memory usage spikes every 30 minutes

What happens: Agent traces the error backwards through the call stack, generates competing hypotheses, tests each one, and only fixes when the root cause is confirmed.

🔧 /fix -- Fix a Known Issue

For when you know what's broken and just need it fixed. Faster than /debug.

/fix TypeError: Cannot read property 'map' of undefined in UserList.tsx
/fix missing import for useState in Dashboard component
/fix --test                        (run tests, fix all failures)
/fix --ci                          (read CI logs, fix pipeline errors)

Rule of thumb: Can you describe the fix in one sentence? -> Use /fix. Need to investigate? -> Use /debug.

📐 /plan -- Design Before Building

Creates a detailed implementation plan without writing code. Perfect for complex features.

/plan migrate from REST to GraphQL
/plan add multi-tenant support to the database layer
/plan --hard redesign the authentication system    (includes red-team review)

What happens with --hard: After planning, the agent adopts 3 hostile personas (Security Adversary, Assumption Destroyer, Scope Critic) and tries to tear apart its own plan. Catches flaws before a single line of code is written.

🔍 /scout -- Explore the Codebase

Find files fast. Use before starting any feature work.

/scout authentication logic
/scout database migration files
/scout "error handling patterns"
/scout payment module --edge-cases     (find potential edge cases too)

Other Workflows

Understanding Flags

Flags modify how a workflow runs. Here's what each one means:

How Skills Work (Automatic)

Skills are loaded automatically -- you don't need to do anything special. The agent detects keywords in your request and loads the relevant domain knowledge.

Example: If you type "Add a REST API endpoint with JWT authentication", the agent automatically loads both api-patterns and security-audit skills. You don't need to tell it.

How Rules Work (Invisible)

Rules are always active -- they shape the agent's behavior on every single request, without you needing to do anything.

Architecture

.agents/
+-- rules/          <- Always active behavioral constraints (9 rules)
|   +-- README.md                     Priority & conflict resolution
|   +-- task-lifecycle.md             6-phase pipeline orchestrator
|   +-- socratic-gate.md              Ask before coding
|   +-- development-rules.md          Request classification, core principles
|   +-- output-calibration.md         Auto-calibrate response depth
|   +-- skill-routing.md              Auto-load skills by keyword
|   +-- clean-code.md                 Naming, functions, anti-patterns
|   +-- error-recovery.md             SCDFV loop -- diagnose, don't retry
|   +-- self-check.md                 5-point mandatory exit verification
|   +-- documentation-management.md   Post-task docs updates
|
+-- workflows/      <- On-demand slash commands (14 workflows)
|   +-- cook.md       /cook       Feature implementation pipeline
|   +-- debug.md      /debug      Root-cause-first debugging
|   +-- fix.md        /fix        Auto-complexity issue resolution
|   +-- plan.md       /plan       Technical planning + red-team
|   +-- review.md     /review     Multi-lens code review
|   +-- scout.md      /scout      Fast codebase exploration
|   +-- test.md       /test       Test generation & execution
|   +-- brainstorm.md /brainstorm Structured ideation
|   +-- design.md     /design     UI/UX design workflow
|   +-- docs.md       /docs       Documentation management
|   +-- explain.md    /explain    Mermaid diagrams + visual explanations
|   +-- git.md        /git        Conventional commits
|   +-- init.md       /init       Project bootstrapper
|   +-- watzup.md     /watzup     Quick project status
|
+-- skills/         <- Domain knowledge loaded on-demand (18 skills)
    +-- accessibility/            WCAG, ARIA, keyboard nav, a11y testing
    +-- api-patterns/             REST, auth, pagination, versioning
    +-- code-review/              Checklists, OWASP, anti-patterns
    +-- css-architecture/         Design tokens, responsive, animations
    +-- database-design/          Schema, indexes, query optimization
    +-- devops/                   Docker, CI/CD, deployment patterns
    +-- git-patterns/             Branching, conflict resolution, rebase
    +-- nextjs-patterns/          App Router, RSC, data fetching
    +-- performance-optimization/ Core Web Vitals, bundle analysis
    +-- problem-solving/          5 techniques for breaking through
    +-- react-best-practices/     Components, hooks, state, structure
    +-- refactoring/              5 core patterns, safety protocol
    +-- security-audit/           OWASP Top 10 deep reference
    +-- sequential-thinking/      Structured problem decomposition
    +-- technical-writing/        README, changelog, API docs, ADRs
    +-- testing-patterns/         Test pyramid, AAA, mocking
    +-- typescript-patterns/      Generics, narrowing, Zod, branded types
    +-- ui-ux-design/             Design systems, color, typography, UX

Three-Layer Design

Key Features

🤔 Socratic Gate

Every complex request must pass through strategic questioning before implementation. Prevents wasted work from misunderstood requirements.

You: "Add authentication to the app"

❌ Without Cortex: Agent immediately starts coding JWT auth
✅ With Cortex: 
   "Before I implement authentication, let me clarify:
    1. What auth method? (email/password, OAuth, SSO?)
    2. What roles/permissions are needed? (admin, user, guest?)
    3. Should sessions persist? (remember me, token expiry?)
    
    This ensures I build exactly what you need."

✅ Self-Check Protocol

5-point mandatory verification before any task is marked complete:

1. Goal met? 2. All files edited? 3. Code works? 4. No errors? 5. Nothing forgotten?

🔴 Red-Team Review

The /plan --hard workflow includes adversarial review from 3 hostile personas:

• 🔴 Security Adversary
• 🟠 Assumption Destroyer
• 🟡 Scope & Complexity Critic

📊 Context Efficiency

Built-in token awareness -- the kit includes guidance on efficient context window usage to avoid overflowing the AI's working memory.

Choosing the Right Workflow

Not sure which command to use? Here's a decision guide:

                    What do you need?
                         |
            +------------+------------+
            ▼            ▼            ▼
       Build new     Fix something   Understand
       feature       broken          codebase
            |            |            |
            ▼            |            ▼
         /cook           |          /scout
                    +----+----+     /explain
                    ▼         ▼
              Know the    Don't know
              cause?      the cause?
                |            |
                ▼            ▼
              /fix        /debug

Contributing

See CONTRIBUTING.md for guidelines on adding new workflows, skills, and rules.

License

MIT

Made with 🧠 by developers who got tired of AI agents that don't think.