Skip to content

AGENTS.md

Latest commit

 

History

History
87 lines (61 loc) · 3.39 KB

AGENTS.md

File metadata and controls

87 lines (61 loc) · 3.39 KB

AGENTS.md — Zenith Project Agent Rules

One-stop reference for every AI agent working in this repo.

Project Identity

  • Name: Zenith (codename: VeriGen)
  • Event: HACKFEST 2026 · NMIT Bangalore
  • Track: Open Innovation
  • Problem: AI systems are vulnerable to prompt injection, CVEs, zero-day exploits.
  • Solution: Unified, automated, self-healing pipeline — detect threats AND prove patches.

Non-Negotiable Coding Rules

  1. Zero crashes during demo — Every module is imported lazily with try/except. If a module is missing, the CLI prints ⚠ SKIP [MODULE] and continues. Never let a ModuleNotFoundError reach the terminal.

  2. Docstrings everywhere — Every function and every file must have a docstring. No exceptions.

  3. ZenithPayload is the API — All inter-module data flows through shared/payload.py::ZenithPayload. Never use raw dicts as the main handoff between modules.

  4. No hardcoded secrets — All API keys from os.environ only. No .env file committed to git.

  5. Wrap ALL external calls — Any call to an external API (requests, OpenAI, Anthropic) must be in try/except. On failure, return a structured error dict, not a raised exception.

  6. Each module is independently runnable — Every module file must have an if __name__ == "__main__": block that runs a self-contained demo.

  7. Branch discipline —

    • main = integration-ready skeleton only
    • Dev branches: feat/dev1-ingress, feat/dev2-sast, feat/dev3-clash, feat/dev4-verify
    • Merge strategy: squash merge to main

Module Ownership

Module Owner File Branch
1 — Ingress + AI Shield Dev1 src/dev1_ingress/ingress.py feat/dev1-ingress
2 — SAST + CVE Scanner Dev2 src/dev2_sast/sast_runner.py feat/dev2-sast
3 — Red/Blue Clash Dev3 src/dev3_clash/clash_runner.py feat/dev3-clash
4 — Verify + Dashboard Dev4 src/dev4_verify/verify_runner.py feat/dev4-verify

Autonomous Loop Rules (Agent Behaviour)

  • 3-Strike Rule: After writing code, immediately write and run the test. If it fails, enter a self-correction loop (Analyse error → Fix → Re-test). Do this up to 3 times without asking permission.
  • 4th strike: Pause and ask the human for direction.
  • Breaking changes: If a fix requires modifying shared/payload.py or core_cli.py, PAUSE and ask first.
  • LSP discipline: Never guess types or import paths. Use the Language Server diagnostics to confirm.

Living Architecture Guide

After every file creation or modification, update ZENITH_ARCHITECTURE_GUIDE.md. For every block added, explain:

  • What it does (one sentence)
  • Why it's built this way (one sentence — the design decision)
  • How it connects to the bigger picture (one sentence)

This is the study guide for the pitch.

Tech Stack Quick Reference

Layer Tech
Language Python 3.11
Red Team AI Anthropic Claude 3.5 Sonnet
Blue Team AI OpenAI GPT-4o
SAST Semgrep (local CLI)
CVE DB OSV.dev (free API) + NVD NIST (optional key)
Testing pytest
Frontend Vanilla HTML + CSS + JS
Terminal output colorama

Environment Variables Required

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
NVD_API_KEY=...  (optional — OSV.dev works without it)