README.md

Stop vibecoding. Start shipping.

Describe your idea → GSD extracts everything the AI needs → Watch it build correctly.

Getting Started · How It Works · Commands · Documentation

🧠 The Problem

Vibecoding has a bad reputation — and it deserves it.

You describe what you want, AI generates code, and you get inconsistent garbage that falls apart at scale.

GSD fixes that. It's the context engineering layer that makes AI coding reliable.

"Add a feature"
    → Inconsistent code
    → Bugs everywhere
    → Debug loop
    → Frustration

"Add a feature"
    → SPEC
    → Plan
    → Atomic execution
    → Verification
    → ✅ Done

No enterprise roleplay. No sprint ceremonies, story points, stakeholder syncs, or Jira workflows. Just an incredibly effective system for building cool stuff consistently.

👤 Who This Is For

⚡ Getting Started

Requirements: Antigravity 2.0+ for subagent delegation. GSD runs on 1.x too — every command works, but everything shares one context window and workflows will tell you so.

# Open your project
cd your-project

# Clone the GSD template
git clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template

# Copy to your project
Copy-Item -Recurse gsd-template\.agent .\
Copy-Item -Recurse gsd-template\.agents .\
Copy-Item -Recurse gsd-template\.gemini .\
Copy-Item -Recurse gsd-template\.gsd .\
Copy-Item -Recurse gsd-template\adapters .\
Copy-Item -Recurse gsd-template\docs .\
Copy-Item -Recurse gsd-template\scripts .\
Copy-Item -Force gsd-template\PROJECT_RULES.md .\
Copy-Item -Force gsd-template\GSD-STYLE.md .\
Copy-Item -Force gsd-template\model_capabilities.yaml .\

# Clean up
Remove-Item -Recurse -Force gsd-template

# Open your project
cd your-project

# Clone the GSD template
git clone https://github.com/toonight/get-shit-done-for-antigravity.git gsd-template

# Copy to your project
cp -r gsd-template/.agent ./
cp -r gsd-template/.agents ./
cp -r gsd-template/.gemini ./
cp -r gsd-template/.gsd ./
cp -r gsd-template/adapters ./
cp -r gsd-template/docs ./
cp -r gsd-template/scripts ./
cp gsd-template/PROJECT_RULES.md ./
cp gsd-template/GSD-STYLE.md ./
cp gsd-template/model_capabilities.yaml ./

# Clean up
rm -rf gsd-template

Then run /new-project and follow the prompts.

🔄 How It Works

graph LR
    A["🆕 /new-project"] --> B["📋 SPEC.md"]
    B --> C["💬 /discuss-phase"]
    C --> D["📐 /plan"]
    D --> E["⚙️ /execute"]
    E --> F["✅ /verify"]
    F --> G{"More\nphases?"}
    G -- Yes --> C
    G -- No --> H["🏁 /complete-milestone"]

    style A fill:#7B2D8E,color:#fff,stroke:none
    style B fill:#00C853,color:#fff,stroke:none
    style C fill:#2196F3,color:#fff,stroke:none
    style D fill:#FF6D00,color:#fff,stroke:none
    style E fill:#E91E63,color:#fff,stroke:none
    style F fill:#00C853,color:#fff,stroke:none
    style G fill:#FFC107,color:#000,stroke:none
    style H fill:#7B2D8E,color:#fff,stroke:none

🧩 Why It Works

📦 Context Engineering

The AI is incredibly powerful if you give it the context it needs. Most people don't. GSD handles it for you:

Size limits based on where AI quality degrades. Stay under, get consistent excellence.

🧬 Subagent Delegation

Context engineering only works if something actually protects the context. In GSD, that something is native Antigravity subagents: workflows orchestrate and route, subagents do the work — each on its own clean context window.

/execute 2
    │
    ├─ wave 1 ──► gsd-executor  (plan 1)  ──► SUMMARY.md ──┐
    │             gsd-executor  (plan 2)  ──► SUMMARY.md ──┤ compact
    │                                                       │ results
    └─ verify ──► gsd-verifier            ──► VERIFICATION ─┘ only

Subagents inherit no conversation history and return a compact result block — status, artifact paths, verdict. The artifacts land on disk; only the block reaches the orchestrator.

Requires Antigravity 2.0+ (invoke_subagent). On 1.x, workflows announce degraded mode and run inline — one plan per session, /pause between plans.

No Ultra plan required. GSD uses plain subagents, which are not plan-gated — only Multi-Agent Teamwork (/teamwork-preview, Agent Teams) is Ultra-exclusive, and GSD does not use it. Free and Pro tiers differ in rate limits and model access, not in access to delegation.

Protocol: subagent-delegation · Definitions: .agents/agents/

🏷️ XML Prompt Formatting

Every plan is structured XML optimized for AI execution:

<task type="auto">
  <name>Create login endpoint</name>
  <files>src/app/api/auth/login/route.ts</files>
  <action>
    Use jose for JWT (not jsonwebtoken - CommonJS issues).
    Validate credentials against users table.
    Return httpOnly cookie on success.
  </action>
  <verify>curl -X POST localhost:3000/api/auth/login returns 200 + Set-Cookie</verify>
  <done>Valid credentials return cookie, invalid return 401</done>
</task>

Precise instructions. No guessing. Verification built in.

🌊 Wave-Based Execution

Plans are grouped into waves based on dependencies:

graph TD
    subgraph W1["🌊 Wave 1 — Foundation"]
        T1["Task A"] & T2["Task B"] & T3["Task C"]
    end
    subgraph W2["🌊 Wave 2 — Integration"]
        T4["Task D"] & T5["Task E"]
    end
    subgraph W3["🌊 Wave 3 — Polish"]
        T6["Task F"]
    end

    W1 --> W2 --> W3

    style W1 fill:#E3F2FD,stroke:#2196F3,color:#000
    style W2 fill:#FFF3E0,stroke:#FF6D00,color:#000
    style W3 fill:#F3E5F5,stroke:#7B2D8E,color:#000
    style T1 fill:#2196F3,color:#fff,stroke:none
    style T2 fill:#2196F3,color:#fff,stroke:none
    style T3 fill:#2196F3,color:#fff,stroke:none
    style T4 fill:#FF6D00,color:#fff,stroke:none
    style T5 fill:#FF6D00,color:#fff,stroke:none
    style T6 fill:#7B2D8E,color:#fff,stroke:none

Each plan runs in its own gsd-executor subagent, so each executor gets fresh context and your main session stays fast. Plans sharing a wave run in isolated git worktrees (branch mode) and merge when the wave closes.

🔗 Atomic Git Commits

Each task gets its own commit immediately after completion:

abc123f feat(phase-1): create login endpoint
def456g feat(phase-1): add password validation
hij789k feat(phase-1): implement JWT cookie handling

Why? Git bisect finds exact failing task · Each task independently revertable · Clear history for AI in future sessions

🔬 Empirical Verification

No "trust me, it works." Every verification produces evidence:

🎮 Commands (29 Total)

🔵 Core Workflow

🟢 Project Setup

🟠 Phase Management

🟡 Sprint

🟣 Navigation & State

🔴 Utilities

💡 Typical Session

/resume              # ← Load context from last session
/progress            # ← See where you left off
/discuss-phase 2     # ← Clarify requirements (optional)
/plan 2              # ← Plan next phase
/execute 2           # ← Implement with atomic commits
/verify 2            # ← Prove it works (screenshots, tests)
/pause               # ← Save state for later

🔒 Core Rules

🌍 Cross-Platform Support

All workflow files include dual syntax — both PowerShell and Bash commands.

Git commands (git add, git commit, git tag) are cross-platform and work identically everywhere.

🤖 Multi-Model Support

GSD is model-agnostic — use any LLM that works in your environment.

Canonical Rules

All rules live in PROJECT_RULES.md — the single source of truth.

Optional Adapters

Model-specific enhancements (optional, never required):

adapters/
├── CLAUDE.md     # Extended thinking, effort levels
├── GEMINI.md     # Flash vs Pro selection
└── GPT_OSS.md    # Function calling, context handling

Model Selection by Phase

See model-selection-playbook.md for detailed guidance.

🔍 Search-First Mode

Principle: Search before reading files completely.

Why?

• 🎯 Reduces context pollution
• ⚡ Faster codebase understanding
• 🚫 Prevents reading irrelevant code

.\scripts\setup_search.ps1          # Checks for ripgrep/fd
.\scripts\search_repo.ps1 "pattern" # Search wrapper

./scripts/setup_search.sh           # Checks for ripgrep/fd
./scripts/search_repo.sh "pattern"  # Search wrapper

Workflow

1. Define question — What are you looking for?
2. Search first — .\scripts\search_repo.ps1 "keyword"
3. Evaluate results — Which files matter?
4. Targeted read — Only read relevant sections

💰 Token Optimization

Principle: Minimize token consumption while maintaining quality.

Skills Available

Budget Thresholds

See token-optimization-guide.md for complete strategies.

📁 File Structure

📄 PROJECT_RULES.md          # ← Canonical rules (model-agnostic)
📄 GSD-STYLE.md              # Complete style guide

📂 .agent/
└── 📂 workflows/            # 27 slash commands

📂 .agents/
├── 📂 agents/               # 5 subagent definitions (invoke_subagent)
└── 📂 skills/               # 12 agent specializations (Agent Skills standard)

📂 .gemini/
└── 📄 GEMINI.md             # Gemini integration

📂 .gsd/
├── 📄 SPEC.md               # ← START HERE (finalize first)
├── 📄 ROADMAP.md            # Phases and progress
├── 📄 STATE.md              # Session memory
├── 📄 ARCHITECTURE.md       # System design (/map output)
├── 📄 STACK.md              # Tech inventory
├── 📄 DECISIONS.md          # Architecture Decision Records
├── 📄 JOURNAL.md            # Session log
├── 📄 TODO.md               # Quick capture
├── 📂 templates/            # Document templates
└── 📂 examples/             # Usage walkthroughs

📂 adapters/                 # Optional model-specific enhancements
├── 📄 CLAUDE.md
├── 📄 GEMINI.md
└── 📄 GPT_OSS.md

📂 docs/                     # Operational documentation
├── 📄 model-selection-playbook.md
└── 📄 runbook.md

📂 scripts/                  # Utility scripts
├── 📄 validate-*.ps1/.sh    # Structure validators
├── 📄 setup_search.ps1/.sh  # Search tool setup
└── 📄 search_repo.ps1/.sh   # Search wrapper

📄 model_capabilities.yaml   # Optional capability registry

🧪 Testing

Run validation scripts to verify GSD structure:

.\scripts\validate-all.ps1        # Run all validators
.\scripts\validate-workflows.ps1  # Workflows only
.\scripts\validate-skills.ps1     # Skills only
.\scripts\validate-agents.ps1     # Subagents only
.\scripts\validate-encoding.ps1   # Script encoding only

./scripts/validate-all.sh         # Run all validators
./scripts/validate-workflows.sh   # Workflows only
./scripts/validate-skills.sh      # Skills only
./scripts/validate-agents.sh      # Subagents only
./scripts/validate-encoding.sh    # Script encoding only

📚 Documentation

🧠 Philosophy