Skip to content

Repository files navigation

agent-setup-bundle

Turn your AI coding assistant into a disciplined senior engineer without burning through frontier tokens.

Architecture: Two-Tier Multi-Agent Standard: agentskills.io MCP: FastMCP v1.0 License: MIT Platforms: Linux | macOS | Windows

agent-setup-bundle is a cross-platform engineering suite for AI coding assistants: Gemini CLI / Antigravity, Claude Code, Cursor IDE, and OpenAI Codex on Linux, macOS, and Windows.

It pairs frontier reasoning models (Gemini 3.7 Pro, Claude 3.7 Sonnet) with 16 strict operational rules, 39 modular skills following the agentskills.io standard, persistent memory via MemPalace, and an autonomous sub-worker bridge (chinese-worker). High-volume coding tasks (large scaffolds, unit test suites, docstrings, type refactors) are delegated to free, large-context models (MiniMax M3 with 1M context, NVIDIA Nemotron 550B MoE, Zhipu GLM-5.2) running in sandboxed Git worktrees with automated test validation.


Why this exists: standard assistant vs agent-setup-bundle

Problem Area Standard AI Assistant With agent-setup-bundle
Token spend Burns $10 to $30 per session using frontier models on repetitive boilerplate and syntax formatting. Delegates bulk code generation to free, million-token models in Git worktrees. Saves 78.3% of fresh tokens per line of code.
Speculation Guesses package versions, CLI flags, and root causes without checking documentation or runtime state. Zero Speculation Protocol: the agent must verify facts via live commands or web search before making claims.
Working tree safety Edits your active files directly. Leaves half-working changes and broken dependencies in place when it fails. Sandboxed Git worktrees with an automated test runner (--auto-test). Merges into your working tree only after tests pass.
Context degradation Dumps 500-line build logs and terminal dumps into prompt history, degrading attention and triggering hallucinations. Context Engineering Directive: automatically offloads tool outputs exceeding 100 lines or 5 KB to ./scratch/.
Session continuity Starts from scratch every time you restart your terminal or open a new chat. MemPalace Knowledge Graph: stores architectural decisions, schemas, and lessons in AAAK format across sessions.
Quality control Declares a task complete as soon as the file write finishes, without running tests or reviewing code. Mandatory Phase 3 QA Gate: requires TDD test confirmation, TypeScript compilation (tsc --noEmit), and a 5-axis code review.

Quickstart

Option 1: 1-prompt autonomous setup

Paste this prompt directly into your AI coding assistant (Claude Code, Gemini CLI / Antigravity, Cursor Composer, or OpenAI Codex):

English:

Clone https://github.com/Gzyms69/agent-setup-bundle.git and install the full AI engineering operating system for me following AGENTS.md in the repo.

Polish:

Sklonuj https://github.com/Gzyms69/agent-setup-bundle.git i zainstaluj całe środowisko inżynieryjne według instrukcji w AGENTS.md.

Your assistant reads AGENTS.md, detects your operating system, runs the installer, validates suite integrity, and configures the environment.

Option 2: 1-command terminal installation

Run the installer directly in your terminal:

Linux and macOS (Bash):

git clone https://github.com/Gzyms69/agent-setup-bundle.git
cd agent-setup-bundle
chmod +x install.sh
./install.sh --all

Windows (PowerShell 5.1 / 7+):

git clone https://github.com/Gzyms69/agent-setup-bundle.git
cd agent-setup-bundle
powershell -ExecutionPolicy Bypass -File .\install.ps1 -All

Universal Python 3 (All operating systems):

git clone https://github.com/Gzyms69/agent-setup-bundle.git
cd agent-setup-bundle
python3 install.py --all

Selective installation flags:

  • --gemini / -Gemini: Install only Antigravity / Gemini CLI configuration (~/.gemini/).
  • --claude / -Claude: Install only Claude Code configuration (~/.claude/).
  • --cursor / -Cursor: Install only Cursor IDE rules (~/.cursor/rules/).
  • --codex / -Codex: Install only OpenAI Codex configuration (~/.codex/).

How the system works

When you give a task to an agent equipped with this bundle, execution flows through a disciplined 6-stage lifecycle:

flowchart TD
    subgraph Step1 ["1. Task initiation"]
        User["User prompt: /plan, new feature, bugfix, or refactor"]
    end

    subgraph Step2 ["2. Memory and cartography gate"]
        Recall["Query MemPalace (mempalace-recall): recall past decisions and schema"]
        Cartography["Phase 0 cartography (skill-codebase-onboarding): map entrypoints"]
        Recall --> Cartography
    end

    subgraph Step3 ["3. Spec-driven planning (Wait-for-GO)"]
        SpecDoc["Phase 1: generate technical specification and plan"]
        Approval{"Human review: explicit GO required"}
        SpecDoc --> Approval
    end

    subgraph Step4 ["4. Two-tier execution"]
        Brain["Tier 1 brain (Gemini 3.7 / Claude 3.7): core architecture and logic"]
        Worker["Tier 2 worker (chinese-worker / FastMCP): free models (MiniMax, Nemotron, GLM)"]
        Worktree["Isolated Git worktree (.git/worktrees_active/task-id)"]
        Brain -->|Scaffolding, tests, DTOs| Worker
        Worker --> Worktree
    end

    subgraph Step5 ["5. Automated quality loop"]
        TestLoop["Automated test runner (--auto-test): pytest, vitest, cargo"]
        TSGate["TypeScript safety gate (npx tsc --noEmit)"]
        ReviewGate["Phase 3: 5-axis code review (correctness, security, perf)"]
        Worktree --> TestLoop --> TSGate --> ReviewGate
    end

    subgraph Step6 ["6. Atomic merge and memory retention"]
        Merge["worker_merge_branch: merge verified diff into working tree"]
        Diary["mempalace_diary_write: record session facts to AAAK knowledge graph"]
        ReviewGate --> Merge --> Diary
    end

    Step1 --> Step2 --> Step3
    Approval -->|Approved GO| Step4
    Step4 --> Step5 --> Step6
Loading

The 6-stage lifecycle in detail:

  1. Task initiation: You submit a prompt (for example: /plan add Stripe webhook verification).
  2. Memory recall and cartography: Before reading or editing files, the agent queries MemPalace (mempalace-recall) to check past architecture records and database schemas. It then activates skill-codebase-onboarding to locate entrypoints and dependencies.
  3. Spec-driven planning (Wait-for-GO): The agent generates a structured implementation plan listing affected files, interface changes, and test commands. The agent is strictly forbidden from writing code until you review the plan and type GO.
  4. Two-tier execution: The frontier brain (Tier 1) designs domain logic and interfaces, delegating repetitive bulk work (scaffolds, DTOs, mock suites) to the FastMCP chinese-worker (Tier 2). The worker generates code inside an isolated Git worktree (.git/worktrees_active/<task-id>).
  5. Automated quality loop: The worktree runs test suites automatically (--auto-test, npx tsc --noEmit). If a test fails, the worker repairs the code in the worktree before reporting back. The Tier 1 model then conducts a 5-axis review (correctness, readability, architecture, security, performance).
  6. Atomic merge and memory retention: After you approve the diff, changes merge cleanly into your working tree. The agent records key lessons, schema updates, and architecture records to MemPalace, maintaining continuity for future sessions.

Concrete example

Step What you see in chat What the agent does behind the scenes
1. Prompt Implement S3 file upload handler with validation Activates skill-codebase-onboarding and mempalace-recall. Inspects storage configuration without guessing.
2. Plan Agent creates plan.md and halts. Analyzes dependencies, defines input validation schemas, specifies test cases, and waits for approval.
3. Approval You type GO. Agent switches to Act phase and calls worker_run_task via chinese-worker FastMCP.
4. Grunt work Zero token clutter in your chat. MiniMax M3 generates the S3 upload handler, DTOs, and input validation inside a sandboxed Git worktree.
5. Verification 12 tests passed, tsc clean Worktree runs tests automatically. Agent reviews diff against OWASP Top 10 guidelines and checks for memory leaks.
6. Completion Clean summary and diary entry. Changes merge into the working tree. Architectural decisions are saved to the MemPalace AAAK graph.

Two-tier sub-worker delegation engine

Frontier models are effective at domain architecture, but using them to generate 2,000 lines of boilerplate or repetitive test fixtures burns budget quickly.

agent-setup-bundle routes bulk coding tasks to specialized, free models through a local FastMCP server (scripts/worker_mcp.py):

flowchart TD
    subgraph Tier1 ["Tier 1: Frontier reasoning brain"]
        Gemini["Gemini 3.7 Pro / Antigravity CLI"]
        Claude["Claude 3.7 Sonnet / Claude Code"]
        Cursor["Cursor IDE / Composer"]
        Codex["OpenAI Codex CLI"]
        SpecGate["Spec-driven planning and 5-axis code review"]
        Gemini & Claude & Cursor & Codex --> SpecGate
    end

    subgraph Tier2 ["Tier 2: FastMCP sub-worker bridge (chinese-worker)"]
        Router["Task router (keyword and task affinity)"]
        SkillsInj["Dynamic skill injector (--read skills/*/SKILL.md)"]
        WorktreeMgr["Git worktree sandbox (.git/worktrees_active/task-id)"]
        AiderEngine["Aider headless engine (diff mode)"]
        SelfHealing["Automated test loop (--auto-test)"]
    end

    subgraph Models ["Free model pool"]
        M3["MiniMax M3 (1M context, 65k output): large scaffolding"]
        N550["NVIDIA Nemotron 550B MoE: low-level systems and algorithms"]
        GLM5["Zhipu GLM-5.2: bug fixes and refactoring"]
        NLight["Nemotron 3.5 Lightning: fast TDD unit test suites"]
        GLM4["Zhipu GLM-4-Flash PAAS: direct API fallback"]
    end

    SpecGate -->|MCP tool: worker_run_task / worker_generate_tests| Router
    Router --> WorktreeMgr --> AiderEngine
    Router --> SkillsInj --> AiderEngine
    Router --> M3 & N550 & GLM5 & NLight & GLM4
    M3 & N550 & GLM5 & NLight & GLM4 --> AiderEngine
    AiderEngine --> SelfHealing
    SelfHealing -->|Clean report: 3-line status| SpecGate
    SpecGate -->|Approved merge| Merge["worker_merge_branch"]
Loading

Free model pool and task affinity

Model Profile Target Model Identifier Context / Output Best Suited For
minimax-m3 openrouter/minimax/minimax-m3:free 1,048,576 / 65,536 Large scaffolding, multi-file boilerplates, fullstack components.
nemotron-550b openrouter/nvidia/nemotron-3-ultra-550b-a55b:free 1,000,000 / 65,536 Low-level systems (C/C++, Rust, Assembly), binary layouts, math algorithms.
glm-5.2 openrouter/z-ai/glm-5.2:free 256,000 / 65,536 Bug fixing, refactoring, documentation generation, diff precision.
nemotron-lightning openrouter/nvidia/nemotron-3.5-lightning:free 1,000,000 / 65,536 Fast TDD unit test suite creation (pytest, vitest, cargo test).
glm-4-flash openai/glm-4-flash 128,000 / 4,096 Direct BigModel PAAS fallback when free public endpoints queue.

FastMCP sub-worker tools:

  • worker_run_task: Runs an autonomous coding task in a dedicated Git worktree with skill injection and self-healing test loops.
  • worker_generate_tests: Generates unit tests with edge-case mocking for a specified target file.
  • worker_generate_docs: Generates docstrings, JSDoc, or markdown documentation without altering code behavior.
  • worker_batch_refactor: Applies multi-file refactoring or strict type safety upgrades.
  • worker_continue_task: Continues refining changes in an existing active worktree sandbox.
  • worker_get_diff: Returns the unified git diff generated by the worker for inspection.
  • worker_merge_branch: Merges the verified task worktree into your main branch and cleans up the sandbox.
  • worker_discard_branch: Deletes a rejected worktree sandbox.
  • worker_status: Lists active worktree sandboxes and recent execution logs.

Developer CLI companion (worker)

The installer provisions a terminal CLI symlink at ~/.local/bin/worker:

# Check worker health, installed packages, and API profiles
worker check

# Launch an interactive coding session using MiniMax M3
worker chat minimax-m3 --skills skill-frontend-architect src/App.tsx

# Run a task with automatic model routing and skill injection
worker run "Refactor database queries to use parameterized statements" --skills skill-backend-architect -f src/db.ts

Universal 4-phase pre-flight skill gate

Agents evaluate and load skills from skills/ (~/.agents/skills/) through a 4-phase gate before performing discovery or making code edits:

flowchart LR
    P0["Phase 0: Cartography gate"] --> P1["Phase 1: Planning and orchestration"]
    P1 --> P2["Phase 2: Domain specialists"]
    P2 --> P3["Phase 3: QA and review gate"]
Loading

Complete 39-skill catalog:

Phase 0: Cartography and memory

  • skill-codebase-onboarding: Mandatory first step for exploring or onboarding any unmapped repository.
  • spec-miner: Reverse engineers legacy, undocumented, or poorly structured repositories.
  • mempalace-recall: Queries the MemPalace knowledge graph before answering questions about past decisions, schemas, or team conventions.

Phase 1: Planning, context and orchestration

  • spec-driven-development: Activated for tasks expected to take over 15 minutes, touch more than 3 files, or when /plan is invoked.
  • skill-context-engineering: Attention budget curation, log offloading to ./scratch/, and context compaction.
  • skill-master-orchestrator: Multi-agent swarm coordination, Task DAG decomposition, and barrier synchronization.
  • mempalace-task: Creates, delegates, claims, and tracks tasks through the MemPalace logstream.
  • skill-monorepo-architect: Manages monorepo structures (PNPM, Turborepo, UV workspaces).
  • skill-plugin-architecture: Designs microkernel systems, dynamic toolkits, and plugin lifecycles.
  • skill-web-architecture: Defines full-stack web architectural standards, module boundaries, and API contracts.

Phase 2: Domain specialists

  • mempalace: Configuration and operation of MemPalace (local private palace or shared hub).
  • skill-frontend-architect: Next.js 15+ App Router, React Server Components (RSC), Client Island boundaries, WCAG 2.1/2.2 AA.
  • skill-design-engineering: Motion animations (motion.dev), CSS Subgrid, Container Queries, 21st.dev UI components.
  • skill-creative-design: Art direction, visual composition, Fontjoy typography scales, OKLCH color palettes.
  • skill-backend-architect: Database schemas, API contracts, query optimization (EXPLAIN ANALYZE), zero-downtime migrations.
  • skill-mcp-builder: Model Context Protocol server development (FastMCP, TypeScript SDK, stdio/SSE transports).
  • skill-low-level-programming: Low-level systems programming in C, C++, Rust, and Assembly (endianness, byte buffers).
  • c-cpp-systems: C and C++ memory safety, pointers, manual RAII, struct alignment, and sanitizers (ASan/UBSan).
  • wasm-emscripten: C and C++ to WebAssembly compilation, Emscripten runtime flags, and direct HEAP memory views.
  • retro-emulation-engineering: Console emulator architecture, hardware coprocessor simulation (CPU/RSP/RDP), frame timing.
  • skill-emulator-wasm: WebAssembly retro emulators, WebGL rendering, Web Audio sync, save states.
  • skill-ai-ml: LLM integrations (Gemini, OpenAI, Anthropic, Ollama), RAG pipelines, and vector databases.
  • skill-data-science: Exploratory data analysis, ingestion pipelines, Pandas/Polars dataframes, notebooks.
  • skill-data-analysis: Statistical methodology, hypothesis testing, anomaly detection, metric verification.
  • skill-graph-analytics: Graph databases (Neo4j), Cypher queries, topology analysis, Graph Data Science (GDS).
  • skill-graphics-webgl: 2D and 3D graphics, Three.js, WebGL shader optimization, Canvas rendering.
  • skill-stealth-scraping: Anti-bot evasion, stealth automation, TLS/JA3 fingerprints, reverse API engineering.
  • skill-osint-engineering: OSINT intelligence pipelines, entity relationship graphs, forensic analysis.
  • skill-system-diagnostics: Hardware, OS, and kernel diagnostics, dmesg/journalctl analysis, root-cause triage.
  • skill-devops-cloud: Docker containerization, CI/CD pipelines, Cloud Run checklists, Kubernetes.
  • skill-research: Technical literature research with multi-source verification and paper inspection.
  • skill-resume-tailor: Developer CV and resume tailoring (Google XYZ formula, Harvard Tech standard).
  • marketing-copywriting: Conversion copywriting, value propositions, CTA engineering, audience targeting.
  • avoid-ai-writing: Audit and rewriting protocol eliminating AI clichés, hollow intensifiers, and robotic cadence.
  • seo-optimization-and-audit: SEO audits, metadata validation, Core Web Vitals optimization.
  • skill-web-performance: Universal web performance engineering, Lighthouse 100/100, runtime tracing.

Phase 3: QA and verification gate

  • skill-qa-engineer: Mandatory Phase 3 QA Gate, TDD Red-Green discipline, TypeScript Safety Gate (tsc --noEmit).
  • skill-code-review: Systematic 5-axis review (Correctness, Readability, Architecture, Security OWASP Top 10, Performance).
  • doubt-driven-development: Adversarial verification gate challenging false assumptions before executing critical changes.

16 operational directives

The rules in rules/ (~/.agents/rules/) enforce deterministic behavior across every supported platform:

  1. Zero speculation (zero-speculation.md): Total ban on guessing hardware specs, package versions, API endpoints, or error causes. Verify facts via live commands or web search before making technical claims.
  2. Command verification (command-verification.md): Mandatory verification of CLI tool outcomes before proceeding to next steps.
  3. Environment integrity (env-integrity.md): Pre-flight environment audit before modifying codebase configuration.
  4. Error triage (error-triage.md): Strict diagnostic triage sequence: Documentation -> Web Search -> Source Code.
  5. Full log reporting (full-log-reporting.md): Prohibition of truncated logs when diagnosing failures.
  6. Problem isolation (problem-isolation.md): Surgical problem isolation without collateral mutations to unrelated files.
  7. Subagent economy (subagent-economy.md): Model routing economy (flash_lite -> flash -> pro) and delegation to FastMCP sub-workers.
  8. System identity (system-identity.md): Mandatory real-time hardware identity and operating system verification via live diagnostic commands.
  9. Systemic excellence (systemic-excellence.md): Prohibition of symptomatic patches, workarounds, or defensive error masking. Always fix the root cause.
  10. Context engineering (context-engineering.md): Offloading tool outputs exceeding 100 lines or 5 KB to ./scratch/ to protect attention.
  11. Modular architecture (modular-architecture.md): Clean and Hexagonal architecture boundaries. Prohibition of monolithic files exceeding 200 lines.
  12. Planning and document integrity (planning-and-document-integrity.md): Stateful planning lifecycle with an Iteration Delta and locked baseline facts.
  13. Session handoff (session-handoff.md): Lossless session transition via NEXT_SESSION_PLAN.md and clean handoff prompts.
  14. Skill orchestration (skill-orchestration.md): Universal 4-phase pre-flight skill gate activation protocol.
  15. MCP master playbook (mcp-master-playbook.md): Standardized Model Context Protocol tool invocation guidelines.
  16. MemPalace discovery (mempalace-discovery.md): Knowledge graph querying and memory retrieval protocol.

Model Context Protocol (MCP) server matrix

The bundle includes unified MCP configurations across Gemini CLI (config/mcp_config.json), Cursor (config/cursor_mcp.json), and Claude Code:

MCP Server Provider / Package Purpose
chinese-worker scripts/worker_mcp.py (FastMCP) High-throughput sub-worker delegation engine for bulk coding.
mempalace mempalace.mcp_server (Python) Long-term memory palace, AAAK knowledge graph and diary storage.
github @modelcontextprotocol/server-github@latest Remote GitHub API operations (pull requests, issues, code search, reviews).
chrome-devtools chrome-devtools-mcp@latest Headless Chrome browser automation and DOM inspection.
puppeteer @modelcontextprotocol/server-puppeteer@latest Web automation, end-to-end testing, and screenshot capture.
StitchMCP mcp-remote (Google Stitch) UI screen design generation and design system synchronization.
oracle-oci oracle.oci-api-mcp-server@latest (uvx) Oracle Cloud Infrastructure management.
lighthouse-mcp @danielsogl/lighthouse-mcp@latest Web performance, Core Web Vitals, and accessibility audits.
postgres @modelcontextprotocol/server-postgres@latest PostgreSQL schema introspection and query analysis.
sqlite mcp-server-sqlite (uvx) Local SQLite database inspection.
docker @hypnosis/docker-mcp-server@latest Container lifecycle management and log inspection.
firecrawl firecrawl-mcp@latest Web scraping, crawling, and clean Markdown extraction.
ast-grep ast-grep-server (uvx) Structural AST search and code pattern matching.

Empirical validation and token telemetry

This repository includes a longitudinal empirical study and a standalone CLI audit tool analyzing token consumption, cache hit ratios, and cost per line of code:

  • Case study document: docs/CASE_STUDY_TOKEN_ECONOMICS.md: 200-day study covering 30,120 generations across 5 architectural epochs. It documents an 83.4% reduction in fresh tokens per line of code and 1.77 billion tokens saved.
  • Audit tool CLI: tools/audit_token_economics.py: zero-dependency utility for analyzing local SQLite conversation telemetry, Antigravity Cockpit quotas, and Git commit churn.

Running the token audit CLI:

# Run a 30-day telemetry audit with Markdown summary
python3 tools/audit_token_economics.py --days 30

# Output structured JSON for automation or dashboards
python3 tools/audit_token_economics.py --days 14 --format json

# Generate a 7-day detailed report and save to file
python3 tools/audit_token_economics.py --days 7 --verbose --save report.md

Quality assurance and testing

Every component in this repository is tested by automated verification suites before deployment:

# 1. Master suite validator (checks all 16 rules, 39 skills, 4 platforms, and worker configs)
python3 scripts/validate_suite.py

# 2. Worker MCP and CLI unit test suite
python3 scripts/tests/test_worker.py

# 3. Sub-worker environment diagnostics
python3 scripts/worker_cli.py check

Directory topography

agent-setup-bundle/
├── AGENTS.md                        # Master repository blueprint and AI installer instructions
├── README.md                        # Master documentation and cross-platform guide
├── CAREER_KNOWLEDGE_BANK.md         # SSOT for career portfolios, metrics and STAR+R cases
├── PROMPT_FOR_AI.md                 # Universal bootstrap prompts
├── llms.txt                         # Semantic summary for web-enabled LLM agents
├── .env.example                     # Universal environment configuration template
├── install.sh                       # Native Bash installer (Linux and macOS)
├── install.ps1                      # Native PowerShell installer (Windows)
├── install.py                       # Universal Python 3 installer (all operating systems)
├── docs/
│   └── CASE_STUDY_TOKEN_ECONOMICS.md # 200-day empirical telemetry and token economics study
├── tools/
│   └── audit_token_economics.py      # Standalone CLI for auditing token consumption and LOC cost
├── core/                            # Platform manifests (CODEX.md, GEMINI.md, CLAUDE.md, cursor)
├── rules/                           # 16 Universal Operational Rules (~/.agents/rules/)
├── skills/                          # 39 Modular Skills (~/.agents/skills/)
├── templates/
│   ├── AGENTS.md                    # Project-level starter template
│   ├── CONVENTIONS.md               # Universal coding conventions for sub-workers
│   └── .aider.conf.yml.template     # Universal Aider configuration template
├── config/
│   ├── worker_profiles.json         # Sub-worker model routing profiles and context bounds
│   ├── .aider.model.settings.yml    # Aider model behavioral settings and diff formats
│   ├── .aider.model.metadata.json   # Aider token limit overrides (1M context / 65k output)
│   ├── mcp_config.json              # Gemini CLI MCP configuration template (13 servers)
│   ├── settings.json                # Gemini CLI general settings
│   ├── codex_config.toml            # OpenAI Codex configuration template
│   └── cursor_mcp.json              # Cursor IDE MCP configuration template
├── policies/                        # MCP tool planning policies
└── scripts/
    ├── worker_mcp.py                # FastMCP server for autonomous sub-worker delegation
    ├── worker_cli.py                # Developer CLI companion (worker)
    ├── tests/
    │   └── test_worker.py           # Unit test suite for sub-worker engine
    └── validate_suite.py            # Quality assurance test suite

License

MIT License. Maintained by Gzymson for deterministic AI pair programming.

About

Multi-platform AI Engineering Operating System: 16 core rules (PRAR, Context Engineering, /plan protocol), 36 skills (agentskills.io), and MCP integration for Codex, Gemini CLI, Claude Code & Cursor

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages