👁️ ARGUS

Autonomous 3-Stage AI Code Reviewer & Architecture Guardian for GitHub Actions

🌐 Live Showcase Site • 📦 GitHub Marketplace • 🚀 Quick Start • 👨‍💻 Developer Website

---

📋 Table of Contents

• Overview & Core Features
• 3-Stage Evaluation Pipeline
• SpecKit Specification-Driven Architecture
• Universal AI Cloud Providers
• Quick Start Workflow Setup
• Action Inputs & Parameters
• AI Rate Limits & Plan Guidance
• Mythological Origins & Codebase Mapping
• Origins & History
• Contact & Support

---

🚀 Overview & Core Features

ARGUS is a production-grade, multi-provider AI code reviewer for GitHub Actions. Whenever a developer opens or updates a Pull Request, ARGUS executes an autonomous 3-stage review pipeline in seconds:

1. 🎨 Stage 1: Atlas (Visualizer) — Generates an interactive Mermaid.js flowchart (flowchart TD) mapping changed control flows.
2. 🏛️ Stage 2: Athena (Architect) — Cross-references code changes against rules in architecture.md to prevent architectural decay.
3. ⚡ Stage 3: Hermes (Debt Scanner) — Scans modified files line-by-line for hardcoded API keys (🔴 BLOCK), // TODO comments & empty stubs (🟡 WARN), and debug statements (🔵 INFO).

Key Production Engineering Features

• Zero CI Break Guarantee: Includes an offline static regex engine that completes PR reviews safely if cloud APIs hit rate limits or network blips.
• Smart Key Auto-Detection: Automatically detects key signatures (gsk_ ➔ Groq, nvapi- ➔ NVIDIA, sk-or- ➔ OpenRouter, AIza ➔ Gemini) with zero manual URL configuration.
• Lockfile Noise Filtering: Excludes package-lock.json, yarn.lock, pnpm-lock.yaml, .min.js, .map, and build output directories from AI review prompts.
• Large Diff Truncation: Intelligently truncates diffs at 80,000 characters to prevent API context window overflow.
• Single-Thread Idempotent Comments: Maintains a single executive scorecard comment per Pull Request thread to eliminate notification noise.

---

🎨 3-Stage Evaluation Pipeline

Stage	Persona	Primary Task	Output Artifact	Implementation
Stage 1	Atlas (Visualizer)	Generates visual topology flowcharts	flowchart TD Mermaid Diagram	skills/atlas.js
Stage 2	Athena (Architect)	Evaluates compliance against architecture.md	Architectural Compliance Matrix	skills/athena.js
Stage 3	Hermes (Debt Scanner)	Scans line-by-line for TODOs, stubs & secrets	Flagged Items Table (🔴 BLOCK, 🟡 WARN, 🔵 INFO)	skills/hermes.js

---

🛠️ SpecKit Specification-Driven Architecture

ARGUS was designed and built using SpecKit (Specification Driven Development). The project structure enforces formal design artifacts and agent governance:

• 🏛️ Agent Constitution: Core operating principles, input boundaries, and rule matrix (ARGUS-01 zero placeholders, ARGUS-02 spec compliance, ARGUS-03 structural flowcharts).
• 📐 Architecture Specification: Formal tech stack declaration, component layering, and module boundary rules.
• ⚙️ SpecKit Memory & Governance: Governance rules for automated code reviews.

---

🌐 Universal AI Cloud Providers

ARGUS is powered by Google Gemini natively by default, with universal support for any OpenAI-compatible AI cloud provider:

Key Prefix	Target AI Provider	Default REST Base URL	Default AI Model
AIza... / AQ...	Google Gemini (Default)	Native @google/genai	gemini-2.0-flash
gsk_...	Groq Cloud	https://api.groq.com/openai/v1	llama-3.3-70b-versatile
nvapi-...	NVIDIA NIM	https://integrate.api.nvidia.com/v1	meta/llama-3.3-70b-instruct
sk-or-...	OpenRouter	https://openrouter.ai/api/v1	google/gemini-2.0-flash-001
sk-...	OpenAI Direct	https://api.openai.com/v1	gpt-4o-mini

💡 Hybrid Priority Rule: Explicit workflow inputs (model, base-url) ALWAYS override defaults. If omitted, ARGUS auto-routes based on key prefix.

---

🚀 Quick Start Workflow Setup

Add the following workflow file to your repository under .github/workflows/argus.yml:

name: ARGUS AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

jobs:
  argus-review:
    name: ARGUS 3-Stage AI PR Review
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write

    steps:
      - name: Checkout Code
        uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'

      - name: Install Dependencies
        run: npm ci

      - name: Run ARGUS AI Reviewer
        uses: Crystal-Studio-Labs/Argus@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          gemini-api-key: ${{ secrets.GEMINI_API_KEY }}

Groq / NVIDIA / OpenRouter Workflow Example

      - name: Run ARGUS AI Reviewer (Groq / NVIDIA / OpenRouter)
        uses: Crystal-Studio-Labs/Argus@main
        with:
          github-token: ${{ secrets.GITHUB_TOKEN }}
          api-key: ${{ secrets.GROQ_API_KEY }} # Auto-routes to Groq Cloud (llama-3.3-70b-versatile)

---

⚙️ Action Inputs & Parameters

Input Key	Description	Required	Default Value
github-token	GitHub token for fetching diffs and posting PR comments	False	${{ github.token }}
gemini-api-key	Google Gemini API key (primary default engine)	False	None
groq-api-key	Groq Cloud API key (sub-second 70B inference)	False	None
api-key	Universal API key for Gemini or OpenAI-compatible providers	False	None
base-url	Custom REST endpoint URL for OpenAI-compatible providers	False	Auto-detected
model	AI model identifier string	False	gemini-2.0-flash

---

💡 AI Rate Limits & Plan Guidance

• Free Tier API Keys: Free tier keys (such as Google Gemini Free Tier with 15 Requests/Minute) may encounter rate limit pauses (HTTP 429) during rapid consecutive PR commits.
• Paid / Pro / Subscription Plans: Paid API keys or higher-tier subscription plans (Groq Cloud, NVIDIA NIM, OpenAI Pro, Gemini Pay-As-You-Go) operate with high/unlimited rate limits and zero error pauses.
• Zero CI Break Guarantee: If rate limit errors occur on Free Tier keys, ARGUS's built-in Fallback Static Analysis Engine automatically completes the PR evaluation using offline static regex parsing without crashing your CI build pipeline.

---

🏛️ Mythological Origins & Codebase Mapping

Symbol	Figure	Greek Name	Role in ARGUS	Code Mapping
👁️	Argus Panoptes	Ἄργος Πανόπτης	The 100-eyed giant who never slept. Orchestrates the 3-stage PR review pipeline.	index.js
🎨	Atlas	Ἄτλας	The Titan holding up the heavens. Maps structural topology using Mermaid.js flowcharts.	skills/atlas.js
🏛️	Athena	Ἀθηνᾶ	Goddess of wisdom & strategic order. Enforces architectural compliance against architecture.md.	skills/athena.js
⚡	Hermes	Ἑρμῆς	Swift messenger god. Scans modified files line-by-line for TODOs, stubs, and secrets.	skills/hermes.js

---

📜 Origins & History

ARGUS was originally created during the Deploy Or [Redacted] Hackathon (hosted by HowToAlgo & GDG KIIT) using SpecKit specification-driven development, and has evolved into an active, production-grade automated code review product engineered and maintained under Crystal Studio Labs.

---

📬 Contact & Support

ARGUS is developed and maintained by SahooShuvranshu and Crystal Studio Labs:

• 🌐 Developer Website: sahooshuvranshu.is-a.dev
• 🏢 Organization: Crystal Studio Labs
• 📦 GitHub Repository: Crystal-Studio-Labs/Argus
• 📬 Email Support: contact@sahooshuvranshu.is-a.dev