🚀 Get Shit Done

A spec-driven, context-engineered development methodology

Note: This repository (zeative/gsd-antigravity.git) is a custom adaptation built for Zeative Labs, originating from zeative/gsd-antigravity.

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.

❌ Without GSD

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

✅ With GSD

"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

| | | |---|---| | 🧑‍💻 Solo developers | Using AI coding assistants and need consistency | | 👥 Small teams | Who want structure without enterprise overhead | | 😤 Anyone | Tired of AI generating inconsistent garbage |

⚡ Getting Started

Command Line / Terminal

# 1. Navigate to your project directory
cd your-project

# 2. Initialize GSD 
npx gsd-ag@latest

Then run `/new-project` and follow the prompts.

> [!TIP]
> You can also use `/install` from a clean project to automate the installation above.

---

## 🔄 How It Works

```mermaid
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

| Step | Command | Output | |:----:|---------|--------| | 1 | /new-project | Deep questioning → SPEC.md (finalized) | | 2 | /discuss-phase N | Clarify scope → CONTEXT.md | | 3 | /plan N | Technical discovery → PLAN.md with XML tasks | | 4 | /execute N | Wave-based execution → Atomic commits | | 5 | /verify N | Must-haves check → Evidence captured | | 6 | Repeat | Next phase or /complete-milestone |

🧩 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:

| File | Role | Icon | |------|------|:----:| | SPEC.md | Project vision, always loaded | 🎯 | | ARCHITECTURE.md | System understanding | 🏗️ | | ROADMAP.md | Where you're going, what's done | 🗺️ | | STATE.md | Decisions, blockers, memory across sessions | 💾 | | PLAN.md | Atomic tasks with XML structure | 📐 | | SUMMARY.md | What happened, what changed | 📝 |

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

🏷️ 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 executor gets fresh context. Your main session stays fast.

🔗 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:

| Change Type | Evidence Required | |:---:|:---:| | 🌐 API endpoint | curl output | | 🖥️ UI change | Screenshot | | 🏗️ Build | Command output | | 🧪 Tests | Test results |

🎮 Commands (26 Total)

[!NOTE] Slash commands are typed directly as chat messages (e.g. send /plan 1). They are not IDE autocomplete features — if your editor shows "nothing found" when pressing /, that's normal. Just type the full command and send it.

🔵 Core Workflow

| Command | Purpose | |---------|---------| | /map | 🏗️ Analyze codebase → ARCHITECTURE.md | | /plan [N] | 📐 Create PLAN.md for phase N | | /execute [N] | ⚙️ Wave-based execution with atomic commits | | /verify [N] | ✅ Must-haves validation with proof | | /quick [desc] | ⚡ Fast ad-hoc tasks with tracking | | /debug [desc] | 🐛 Systematic debugging (3-strike rule) |

Pro Tip: Use the --auto flag with /plan or /execute to automatically chain into the next logical workflow without waiting for user input.

🟢 Project Setup

| Command | Purpose | |---------|---------| | /install | 📦 Install GSD from GitHub | | /new-project | 🆕 Deep questioning → SPEC.md | | /new-milestone | 🏁 Create milestone with phases | | /complete-milestone | 🎉 Archive completed milestone | | /audit-milestone | 🔍 Review milestone quality |

🟠 Phase Management

| Command | Purpose | |---------|---------| | /add-phase | ➕ Add phase to end of roadmap | | /insert-phase | 📌 Insert phase (renumbers) | | /remove-phase | ➖ Remove phase (safety checks) | | /discuss-phase | 💬 Clarify scope before planning | | /research-phase | 🔬 Deep technical research | | /list-phase-assumptions | 📋 Surface planning assumptions | | /plan-milestone-gaps | 🔧 Create gap closure plans |

🟣 Navigation & State

| Command | Purpose | |---------|---------| | /progress | 📊 Show current position | | /pause | ⏸️ Save state for session handoff | | /resume | ▶️ Restore from last session | | /add-todo | 📝 Quick capture idea | | /check-todos | 📋 List pending items |

🔴 Utilities

| Command | Purpose | |---------|---------| | /help | ❓ Show all available commands | | /health | 🩺 Validate directory and state integrity | | /web-search | 🌐 Search the web for decisions | | /whats-new | 📢 Show recent GSD changes | | /update | ⬆️ Update GSD to latest version |

💡 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

[!IMPORTANT] GSD forces planning before coding. The AI can't write code until SPEC.md says FINALIZED. This prevents building the wrong thing.

🔒 Core Rules

| | Rule | Why It Matters | |:---:|------|----------------| | 🔒 | Planning Lock | No code until SPEC.md is FINALIZED — prevents building wrong thing | | 💾 | State Persistence | Update STATE.md after every task — memory across sessions | | 🧹 | Context Hygiene | 3 failures → state dump → fresh session — prevents circular debugging | | ✅ | Empirical Validation | Proof required — no "it should work" |

🌍 Cross-Platform Support

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

| Platform | Instructions | |:--------:|:------------:| | 🪟 Windows | Use PowerShell blocks | | 🐧 Linux / Mac | Use Bash blocks (may require jq) |

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 .gsd/PROJECT_RULES.md — the single source of truth.

Optional Adapters

Model-specific enhancements (optional, never required):

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

Model Selection by Phase

| Phase | Recommended | Why | |:-----:|:-----------:|-----| | 📋 Planning | Reasoning models | Complex decisions | | ⚙️ Implementation | Fast models | Iteration speed | | 🐛 Debugging | Reasoning models | Hypothesis testing | | 🔍 Review | Long-context models | Full diff analysis |

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

PowerShell:

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

Bash:

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

No installation required — falls back to built-in tools (Select-String / grep).

Workflow

1. Define question — What are you looking for?
2. Search first — .\.gsd\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

| Skill | Purpose | |-------|---------| | 📊 token-budget | Track and manage token usage | | 🗜️ context-compressor | Compress context for efficiency | | 🔍 context-fetch | Search-first loading | | 🩺 context-health-monitor | Detect quality degradation |

Budget Thresholds

| Usage | Status | Action | |:-----:|:------:|--------| | 0–50% | 🟢 OK | Proceed normally | | 50–70% | 🟡 Warning | Compress, use outlines | | 70%+ | 🔴 Critical | State dump required |

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

📁 File Structure

📂 .agent/
├── 📂 workflows/            # 25 slash commands
└── 📂 skills/               # 11 agent specializations

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

📂 .gsd/
├── 📄 PROJECT_RULES.md          # ← Canonical rules (model-agnostic)
├── 📄 GSD-STYLE.md              # Complete style guide
├── 📄 model_capabilities.yaml   # Optional capability registry
├── 📄 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
    └── 📄 search_repo.ps1/.sh   # Search wrapper
    ├── 📄 setup_search.ps1/.sh  # Search tool setup

📚 Documentation

| Resource | Description | |----------|-------------| | PROJECT_RULES.md | Canonical model-agnostic rules | | GSD-STYLE.md | Complete style and conventions guide | | Model Selection Playbook | Model selection guidance | | Runbook | Operational procedures | | Token Optimization Guide | Token efficiency strategies | | Examples | Usage walkthroughs and quick reference | | Templates | Document templates for plans, verification |

🧠 Philosophy

Adapted from zeative/gsd-antigravity for Google Antigravity