ARC Protocol v2.1 (Technical Preview)

   █████╗ ██████╗  ██████╗ 
  ██╔══██╗██╔══██╗██╔════╝ 
  ███████║██████╔╝██║      
  ██╔══██║██╔══██╗██║      
  ██║  ██║██║  ██║╚██████╗ 
  ╚═╝  ╚═╝╚═╝  ╚═╝ ╚═════╝ 
   ANALYZE. RUN. CONFIRM.

🧩 What is ARC?

ARC is a system that prevents AI-assisted coding from becoming sloppy. In simpler terms: it's a local development workflow that lets multiple AI agents work together to build a project without losing the "big picture."

Most AI tools just "wing it" by looking at one file at a time and hoping for the best. ARC is different. It’s a coordination layer that forces the AI to work like a pro. It breaks the job down: it Analyzes your whole codebase, Runs the task using specialized "expert" agents (like a Researcher, a Coder, and an Auditor), and Confirms that everything actually works before it calls it a day.

It’s not magic—it’s just a strict set of guardrails that keep your AI focused and your code clean.

Why I Built This: I'm a developer, not a "Prompt Engineer." I got tired of AI writing code that broke two days later because it forgot my file structure.

Other tools try to be "Magic Employees" that run your whole company. ARC is different. It's a Managed Context Protocol. It forces the AI to check CONTRACTS.md before it commits a single line of code. No magic. Just guardrails.

⚡ Quick Start

1. Installation

You need Python 3.10+ (for the Core Logic) and Node.js 18+ (for the Gemini Auth Bridge). No API Key required (we use your Google account).

# 1. Initialize the environment
python3 setup_arc.py

# 2. Login to Gemini (One time only)
npm install -g @google/generative-ai
gemini login

# 3. Connect your IDE
# Copy the config from docs/INTEGRATIONS.md to your MCP settings.

👉 Comprehensive Integrations Guide

💡 A Quick Tip on Slash-Commands: Don't reach for your terminal when you see things like /arc-new or /arc-plan. These aren't shell scripts; they're trigger phrases for your AI.

Just type them into your chat sidebar (in Claude, Windsurf, or Antigravity) once you've connected ARC. Your AI sees the slash-command, grabs the right tool from the protocol, and starts the automation for you.

🏎️ Tutorial: Build a To-Do App in 5 Minutes

See it in action. Open your AI editor (Claude/Windsurf/Antigravity) and type:

1. "Initialize a new project. Run /arc-new."
   • AI asks: "What are we building?"
   • You say: "A simple Python CLI To-Do app."
2. "Okay, let's build Phase 1. Run /arc-plan."
   • AI acts: It reads PROJECT.md, checks for existing code (none), and drafts a plan: "Create file todo.py, Add add_task function..."
3. "Looks good. Run /arc-execute."
   • AI acts: It spawns background agents. You watch the dashboard.
     • Research-Agent checks argparse docs.
     • Build-Agent writes the .py file.
     • Audit-Agent checks for PEP8 violations.
4. "Verify it works. Run /arc-verify."
   • AI acts: It runs the script and confirms tasks can be added.

Result: You end up with a working app driven entirely through the ARC workflow, with all changes written and verified on disk.

📖 How to Use

🆕 Starting a New Project

Don't write code yet. Let the ARC process structure it for you.

1. Initialize: /arc-new
2. Plan the work: /arc-plan
3. Build it: /arc-execute

👉 Read the full "New Project" Guide

🏢 Working on an Existing Codebase

Don't let the AI guess your architecture. Map it first.

1. Scan the files: /arc-map
2. This generates a CODEBASE_MAP.md that teaches the agents your style.
3. Then proceed with planning.

👉 Read the full "Existing Project" Guide

🤖 The Workflow Commands

We use specific trigger words to switch modes.

• /arc-discuss: Brainstorm before you build.
• /arc-quick: Fast, one-off tasks.
• /arc-verify: Make sure it actually works.

👉 See all Workflow Commands

📂 Documentation

• How It Works (Deep Dive): The internal mechanics of MCP and Gemini.
• Contracts & Rules: How we enforce code quality.
• The Toolbox: The "Power Tools" behind the scenes (Enforcer, Cartographer, etc.).

Open Source. MIT License.

🚀 Quick Start

# 1. Initialize the environment
python3 setup_arc.py

# 2. Login to Gemini (One time only)
npm install -g @google/generative-ai
gemini login

# 3. Connect your IDE
# Copy the config from docs/INTEGRATIONS.md to your MCP settings.