{"id":49064514,"url":"https://github.com/arvarik/gemstack","last_synced_at":"2026-04-25T00:02:11.835Z","repository":{"id":352533534,"uuid":"1210785563","full_name":"arvarik/gemstack","owner":"arvarik","description":"Opinionated AI agent orchestration framework for Gemini CLI and Antigravity","archived":false,"fork":false,"pushed_at":"2026-04-20T02:13:17.000Z","size":441,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-20T04:11:23.025Z","etag":null,"topics":["agent","ai","antigravity","cli","gemini","llm","mcp","orchestration","software-engineering","workflow"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/gemstack/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arvarik.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-14T18:53:06.000Z","updated_at":"2026-04-20T02:21:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arvarik/gemstack","commit_stats":null,"previous_names":["arvarik/gemstack"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/arvarik/gemstack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fgemstack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fgemstack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fgemstack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fgemstack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arvarik","download_url":"https://codeload.github.com/arvarik/gemstack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arvarik%2Fgemstack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32245153,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T13:21:15.438Z","status":"ssl_error","status_checked_at":"2026-04-24T13:21:15.005Z","response_time":64,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","antigravity","cli","gemini","llm","mcp","orchestration","software-engineering","workflow"],"created_at":"2026-04-20T04:06:15.384Z","updated_at":"2026-04-25T00:02:11.829Z","avatar_url":"https://github.com/arvarik.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gemstack\n\n**Opinionated AI agent orchestration framework for [Gemini CLI](https://github.com/google-gemini/gemini-cli) and [Antigravity](https://github.com/google-gemini/antigravity).**\n\n[![PyPI](https://img.shields.io/pypi/v/gemstack?style=flat-square\u0026logo=pypi\u0026logoColor=white\u0026label=PyPI)](https://pypi.org/project/gemstack/)\n[![Python](https://img.shields.io/pypi/pyversions/gemstack?style=flat-square\u0026logo=python\u0026logoColor=white)](https://pypi.org/project/gemstack/)\n[![CI](https://img.shields.io/github/actions/workflow/status/arvarik/gemstack/ci.yml?style=flat-square\u0026logo=github\u0026label=CI)](https://github.com/arvarik/gemstack/actions/workflows/ci.yml)\n[![License](https://img.shields.io/github/license/arvarik/gemstack?style=flat-square)](LICENSE)\n[![Typed](https://img.shields.io/badge/typed-py.typed-blue?style=flat-square\u0026logo=python\u0026logoColor=white)](https://peps.python.org/pep-0561/)\n\n\u003e Gemstack gives your Gemini-powered agents architectural memory, topology-aware guardrails, and a 5-step lifecycle that forces them to *verify their own work* against your terminal — not just hallucinate a solution and tell you it's done.\n\u003e\n\u003e Built for **Gemini CLI** and **Google Antigravity**. Also works with Cursor, Claude Desktop, and Cline via [MCP](docs/mcp-server.md).\n\n![gemstack](docs/assets/screenshots/gemstack.png)\n\n![hero](docs/assets/screenshots/hero-terminal.png)\n\n---\n\n## The Problem\n\nEvery AI coding tool on the market today — Cursor, Copilot, Aider, Cline — is **bottom-up**. You highlight a file, say \"write this function,\" and the agent does its best. Here's what goes wrong at scale:\n\n- 🧠 **Architecture amnesia** — The agent forgets your tech stack, reinvents design patterns, and introduces conflicting libraries across sessions.\n- 🔁 **Silent rewrites** — It overwrites perfectly good files to suit new logic, mutating critical path variables without testing.\n- ✅ **Self-reported success** — It tells you \"Done!\" but never actually ran the test suite. You discover failures 3 commits later.\n- 🎭 **One-size-fits-all prompting** — A React SPA and a Go microservice get the same generic instructions. No guardrails for your specific topology.\n\n## The Solution\n\n**Gemstack is top-down.** It acts as the orchestrator *above* your editor, purpose-built for **Gemini CLI** and **Google Antigravity** — Google's agentic AI coding platforms. Gemstack gives your Gemini agent the exact context, constraints, and verification loops it needs to produce production-quality code.\n\n```\n┌───────────────────────────────────────────────────────────────┐\n│                          GEMSTACK                             │\n│                                                               │\n│   ┌──────────┐  ┌────────────┐  ┌─────────┐  ┌────────────┐   │\n│   │ Context  │  │  Topology  │  │  Phase  │  │ Autonomous │   │\n│   │ Compiler │─▶│ Guardrails │─▶│ Router  │─▶│  Executor  │   │\n│   └────┬─────┘  └────────────┘  └─────────┘  └─────┬──────┘   │\n│        │                                           │          │\n│   .agent/ files                        Terminal verification  │\n│   (ARCHITECTURE, STYLE,              (Exit Code 0 or retry)   │\n│    TESTING, STATUS)                                           │\n└───────────────────────────────────────────────────────────────┘\n          ↕                  ↕                    ↕\n     Gemini CLI         Antigravity      Cursor / Claude / Cline\n      (native)           (native)          (via MCP Server)\n```\n\nGemstack's workflows install as **slash commands** (`/architect`, `/step1-spec`, `/step3-build`, etc.) directly into Gemini CLI and Antigravity. When you type `/step3-build` in a new Antigravity conversation, the full compiled context — roles, phases, topology guardrails, and your project's `.agent/` files — is loaded automatically. For other AI IDEs, the built-in [MCP server](docs/mcp-server.md) provides the same capabilities.\n\n---\n\n## Key Features\n\n### 🏛️ Architectural Memory via `.agent/` Files\nDefine your entire project context **once** — tech stack, API contracts, database schemas, coding style, test strategy, and anti-patterns — in 5 structured markdown files. Every AI agent reads these before touching your code. No more repeating yourself across sessions.\n\n```bash\ngemstack init --ai    # AI analyzes your codebase and auto-populates .agent/\n```\n\n### 🔄 The 5-Step Verified Lifecycle\nEvery feature flows through **Spec → Trap → Build → Audit → Ship**, with each step running in a **fresh context window**. The Auditor can't be influenced by the Builder's justifications. Tests are written before code. This is how you crush hallucination.\n\n```\nStep 1: Spec  → Define the feature, lock API contracts    (Product Visionary + Architect)\nStep 2: Trap  → Write the failing test suite + task plan  (SDET + Planner)\nStep 3: Build → Implement until Exit Code 0               (Principal Engineer)\nStep 4: Audit → Fresh-eyes security \u0026 logic review        (Security Engineer)\nStep 5: Ship  → Integrate, merge, deploy, archive         (DevOps Engineer)\n```\n\n### 📐 Topology-Aware Guardrails\nInstead of generic prompts, Gemstack loads **domain-specific guardrails** based on your project's detected topology. A Next.js app with a Go backend gets different rules than a Python ML pipeline.\n\n| Topology | Example Guardrails |\n|----------|-------------------|\n| **Backend** | Deterministic test discipline, anti-mocking rules, N+1 query detection |\n| **Frontend** | Component state coverage matrix (empty/loading/success/error), hydration safety |\n| **ML/AI** | Evaluation-Driven Development, cost circuit breakers, prompt versioning |\n| **Infrastructure** | YAML validation, no-auto-apply policy, configuration drift detection |\n| **Library/SDK** | API surface snapshot diffing, semver enforcement, backward compatibility |\n\n### 🤖 Autonomous Execution with `gemstack run`\nGo beyond copy-pasting prompts. Gemstack compiles your full project context, calls Gemini, writes the results to disk, and tracks costs — all in a single command:\n\n```bash\ngemstack run step1-spec --feature \"Add user notifications\"   # Define the spec\ngemstack run step3-build --feature \"Add user notifications\"  # Build until tests pass\ngemstack run step4-audit --feature \"Add user notifications\"  # Fresh-context audit\n```\n\nEach execution includes: **per-project lockfile** (prevents concurrent corruption), **cost tracking** with configurable circuit breakers, **path traversal prevention** on AI-generated file writes, and **structured result summaries**.\n\n### 🔌 Native IDE Integration via MCP\nGemstack exposes your `.agent/` context to **any MCP-compatible agent** (Cursor, Claude Desktop, Gemini CLI, Cline) as a Model Context Protocol server — with read-only resources, actionable tools, and reusable prompt templates:\n\n```bash\ngemstack mcp serve                           # Start stdio server\ngemstack mcp register --cursor --claude-desktop  # Auto-register with your IDEs\n```\n\n**Exposed MCP tools:** `gemstack_status`, `gemstack_route`, `gemstack_compile`, `gemstack_check`, `gemstack_diff`, `gemstack_run`, `gemstack_costs`\n\n### 🧩 Extensible Plugin System\nAdd custom topologies, roles, validation checks, or intercept compilation events with the stable `pluggy`-based plugin API (backward-compatible through the 1.x series):\n\n```python\nfrom gemstack.plugins.hooks import hookimpl\n\nclass MobilePlugin:\n    @hookimpl\n    def gemstack_register_topologies(self):\n        return [{\"name\": \"mobile\", \"description\": \"iOS/Android\", \"content\": \"...\"}]\n\n    @hookimpl\n    def gemstack_post_init(self, project_root, profile):\n        (project_root / \".agent\" / \"MOBILE.md\").write_text(\"# Mobile Context\")\n```\n\n### 🔍 Context Drift Detection\nCatch when your codebase drifts from what's documented. Gemstack compares your actual dependencies, environment variables, and file references against your `.agent/` context:\n\n```bash\ngemstack diff    # Detect new deps, removed env vars, stale file refs\ngemstack check   # Validate .agent/ directory integrity\n```\n\n### 📊 28 CLI Commands Across 7 Categories\n\n| Category | Commands | Purpose |\n|----------|----------|---------|\n| **Setup** | `init`, `install`, `uninstall`, `doctor`, `config` | Project bootstrapping, CLI registration, environment validation |\n| **Workflow** | `status`, `route`, `start`, `phase`, `run` | Lifecycle management, autonomous execution |\n| **Context** | `compile`, `diff`, `export`, `snapshot`, `migrate` | Prompt compilation, drift detection, format exports |\n| **Analysis** | `check`, `compare`, `replay`, `matrix` | Validation, benchmarking, retrospectives, cross-project dashboards |\n| **Tooling** | `mcp`, `hook`, `worktree`, `ci`, `scaffold` | MCP server, git hooks, parallel worktrees, CI generation |\n| **ML/AI** | `prompt`, `eval` | Prompt template versioning, evaluation runner with holdout boundary |\n| **DX** | `tail`, `teach` | Live TUI dashboard, interactive tutorial |\n\n---\n\n## Quickstart\n\n```bash\n# 1. Install (with AI bootstrapping + MCP server support)\npipx install \"gemstack[ai,mcp]\"\n\n# 2. Initialize your project (AI auto-detects stack, topology, and commands)\ncd your-project/\ngemstack init --ai\n\n# 3. See your current lifecycle state\ngemstack status\n\n# 4. Get the recommended next action\ngemstack route\n\n# 5. Start a new feature lifecycle\ngemstack start \"Add user search\"\n\n# 6. Execute Step 1 autonomously via Gemini\ngemstack run step1-spec --feature \"Add user search\"\n```\n\n### Alternative Install Methods\n\n```bash\nuv tool install \"gemstack[all]\"          # uv (fastest)\npip install \"gemstack[all]\"              # Standard pip\npipx install gemstack                    # Minimal (no AI, no MCP)\n```\n\n---\n\n## How It Works: The Context Compiler\n\nThe **Context Compiler** is the engine that makes Gemstack work. When you run a workflow step, it performs **JIT (Just-In-Time) prompt assembly**:\n\n1. **Parses the workflow** — Extracts required roles and phases from the step definition\n2. **Loads role definitions** — Bundles expert personas (Architect, SDET, Security Engineer, etc.)\n3. **Loads phase instructions** — Attaches phase-specific behavioral rules (Ideate, Design, Build, etc.)\n4. **Applies topology guardrails** — Detects your project topology from `ARCHITECTURE.md` and injects domain-specific constraints\n5. **Compiles `.agent/` context** — Reads your project's architecture, style, testing, and status files\n6. **Includes relevant source files** — Pulls in files referenced in `STATUS.md`\n7. **Fires plugin hooks** — Lets plugins modify sections before/after compilation\n8. **Applies token budgeting** — Truncates lowest-priority sections first if you exceed your context window\n\n```bash\ngemstack compile step3-build                   # View the full compiled prompt\ngemstack compile step3-build --max-tokens 100000  # With token limits\n```\n\n---\n\n## Compatibility\n\n| | Supported |\n|---|-----------|\n| **Python** | 3.10, 3.11, 3.12, 3.13 |\n| **OS** | macOS, Linux, Windows (WSL) |\n| **AI Backend** | Google Gemini (via `google-genai`) |\n| **MCP Transport** | stdio, SSE |\n| **Project Languages** | TypeScript/JavaScript, Python, Go, Rust (auto-detected) |\n| **Package Managers** | npm, pnpm, yarn, bun, pip, uv, poetry, cargo, go mod |\n\n---\n\n## Documentation\n\n| | |\n|---|---|\n| 📚 [Getting Started](docs/getting-started.md) | Installation, initialization, and your first workflow |\n| ⚙️ [The `.agent/` Context System](docs/the-agent-context.md) | How the 5 context files drive AI behavior |\n| 🔄 [The 5-Step Lifecycle](docs/the-5-step-lifecycle.md) | Spec → Trap → Build → Audit → Ship in depth |\n| 📐 [Topology-Aware Guardrails](docs/topologies.md) | Domain-specific guardrails for every project type |\n| 🧠 [The Context Compiler](docs/context-compiler.md) | How JIT prompt assembly works |\n| 🤖 [Autonomous Execution](docs/autonomous-execution.md) | Deep dive on `gemstack run` — the autonomous executor |\n| 🔍 [Drift Detection](docs/drift-detection.md) | Catch when code and docs get out of sync |\n| 🔌 [MCP Server \u0026 IDE Integration](docs/mcp-server.md) | Connecting Gemstack to Cursor, Claude, and Cline |\n| 🧩 [Building Custom Plugins](docs/plugins.md) | Extending Gemstack with custom topologies, roles, and hooks |\n| 🔧 [Full CLI Reference](docs/cli-reference.md) | All 28 commands with usage and examples |\n| 🛠️ [Configuration \u0026 Integrations](docs/configuration-and-integrations.md) | Global config, API keys, and Gemini CLI integration |\n| 📖 [Example Walkthroughs](examples/) | End-to-end lifecycle examples for 6 project types |\n\n---\n\n## Project Links\n\n| | |\n|---|---|\n| 📋 [Changelog](CHANGELOG.md) | 🤝 [Contributing](CONTRIBUTING.md) |\n| 🔒 [Security Policy](SECURITY.md) | 📜 [Code of Conduct](CODE_OF_CONDUCT.md) |\n| 🐛 [Report a Bug](https://github.com/arvarik/gemstack/issues/new?template=bug_report.md) | 💡 [Request a Feature](https://github.com/arvarik/gemstack/issues/new?template=feature_request.md) |\n| ⚖️ [License — Apache 2.0](LICENSE) | 🎓 Run `gemstack teach` for an interactive tutorial |\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvarik%2Fgemstack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farvarik%2Fgemstack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farvarik%2Fgemstack/lists"}