From b5c1b9f77bf772b5095d13f295c748d66df96a90 Mon Sep 17 00:00:00 2001 From: mkorwel Date: Sun, 15 Mar 2026 12:13:11 -0700 Subject: [PATCH] docs(offload): move architectural rationale to user-facing documentation --- .gemini/skills/offload/README.md | 11 +++++++++++ .gemini/skills/offload/SKILL.md | 3 ++- MAINTAINER_ONBOARDING.md | 19 ++++++++++++++++++- 3 files changed, 31 insertions(+), 2 deletions(-) diff --git a/.gemini/skills/offload/README.md b/.gemini/skills/offload/README.md index 11951e6e6f..37d3f0e6a0 100644 --- a/.gemini/skills/offload/README.md +++ b/.gemini/skills/offload/README.md @@ -41,6 +41,17 @@ When you run `npm run offload fix`, the orchestrator provisions the remote environment and then launches a Gemini CLI session specifically powered by the `fix-pr` skill. +## Architecture: The Hybrid Powerhouse + +The offload system uses a **Hybrid VM + Docker** architecture designed for maximum performance and reliability: + +1. **The GCE VM (Raw Power)**: By running on high-performance Google Compute Engine instances, we offload heavy CPU and RAM tasks (like full project builds and massive test suites) from your local machine, keeping your primary workstation responsive. +2. **The Docker Container (Consistency & Resilience)**: + * **Source of Truth**: The `.gcp/Dockerfile.maintainer` defines the exact environment. If a tool is added there, every maintainer gets it instantly. + * **Zero Drift**: Containers are immutable. Every job starts in a fresh state, preventing the "OS rot" that typically affects persistent VMs. + * **Local-to-Remote Parity**: The same image can be run locally on your Mac or remotely in GCP, ensuring that "it works on my machine" translates 100% to the remote worker. + * **Safe Multi-tenancy**: Using Git Worktrees inside an isolated container environment allows multiple jobs to run in parallel without sharing state or polluting the host system. + ## Playbooks - **`review`** (default): Build, CI check, static analysis, and behavioral proofs. diff --git a/.gemini/skills/offload/SKILL.md b/.gemini/skills/offload/SKILL.md index 69fdf2d6f3..0284c789db 100644 --- a/.gemini/skills/offload/SKILL.md +++ b/.gemini/skills/offload/SKILL.md @@ -2,7 +2,8 @@ This skill provides a high-performance, parallelized workflow for offloading intensive developer tasks (PR reviews, fixing CI, preparing merges) to a remote workstation. It leverages a Node.js orchestration engine to run complex validation playbooks concurrently in a dedicated terminal window. -## Playbooks +## Performance Workflow + The `offload` skill supports the following specialized playbooks: diff --git a/MAINTAINER_ONBOARDING.md b/MAINTAINER_ONBOARDING.md index 89129f1880..3964fb142a 100644 --- a/MAINTAINER_ONBOARDING.md +++ b/MAINTAINER_ONBOARDING.md @@ -10,7 +10,24 @@ preflight) to a dedicated GCP worker. `gemini-cli-team-quota` project. 2. **GCloud CLI**: Authenticated locally (`gcloud auth login`). 3. **GitHub CLI**: Authenticated locally (`gh auth login`). -4. **iTerm2**: (Optional) For automated window popping on macOS. + +- **iTerm2**: (Optional) For automated window popping on macOS. + +## Architecture: Why this setup? + +The offload system uses a **Hybrid VM + Docker** architecture to balance raw +power with environmental stability: + +1. **GCE VM (Raw Power)**: High-performance machines handle the "heavy lifting" + (full project builds, exhaustive test suites), keeping your local primary + workstation responsive and cool. +2. **Docker (Consistency)**: All development tools (`node`, `gh`, `tsx`, + `vitest`) are managed via `.gcp/Dockerfile.maintainer`. This ensures every + maintainer works in an identical environment, eliminating "it works on my + machine" issues. +3. **Persistence + Isolation**: Tmux sessions on the host VM provide + persistence (surviving disconnects), while Git Worktrees and isolated Docker + runs ensure that multiple jobs don't interfere with each other. ## Setup Workflow