convez.ai
SkillSegurançaAvançado
giggsoinc

Raven — Disciplina de Engenharia Nativa para IA

giggsoinc/raven

Guardrails e orquestração IA para código seguro e estruturado antes do ship

Ver no GitHub
BomPluginScore · de 0 a 100

Framework que impõe pensamento estratégico, estrutura escalável e segurança na origem do código antes de ser commitado. Fornece 61 skills especializados, 10 guardrails com detecção de segredos e CVEs, além de orquestração inteligente com dois modos: Andie (plan-first com crítico) e Andie-Jr (debug em brownfield). Totalmente local, sem telemetria, MIT.

Instalação

$npx convez-ai giggsoinc/raven

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
5
Forks
5
Acompanhando
1
Saúde
57%
Último commit
há 2 dias
Versão
v4.1.0
Issues abertas
1
Contribuidores
2

Casos de uso

  • Triagem automática de bugs com root cause analysis em 2 rodadas
  • Decisões arquiteturais com revisão 3-ângulos (negócio, técnica, dados)
  • Bloqueio em commit-time de secrets, CVEs críticas e edições não planejadas
  • Roteamento determinístico para 61 especialistas por domínio (FastAPI, Postgres, K8s, Terraform, AWS/GCP/Azure, etc)

Veredito

Ferramenta madura e rigorosa para equipes que priorizam segurança e qualidade arquitetural em workflows de IA coding. Overhead desnecessário para features triviais, mas essencial em brownfield e decisões críticas — o bloqueio em commit-time de secrets/CVEs é valor real que reduz risco operacional.

README

A tradução para o português deste README ainda está na fila.

Raven v4.1.0

AI codes fast. Raven enforces Discipline — Strategic Thinking, Scalable Structure, Security at Source.

How, in simple terms:

  • Strategic Thinking — before Raven lets the AI touch your code, it makes a plan, attacks that plan from three angles (business, technical, data — plus a critic), and waits for your go. Bugs aren't guessed at: a 2-round triage finds the root cause first.
  • Scalable Structure — every prompt is routed to the right expert automatically. 61 specialists, one per domain, picked by deterministic rules — and you always see a one-line note saying who's handling it and why. Works the same on one repo or a hundred.
  • Security at Source — guards run on your machine, at the moment code is written and committed: secrets are blocked, vulnerable libraries are blocked, and edits are blocked until the thinking actually happened. Not a report after the damage — a gate before it.

All local. Zero telemetry. MIT.

Install (Claude Code plugin marketplace)

/plugin marketplace add giggsoinc/raven
/plugin install raven@raven

Then restart your session. You should see the Raven greeting:

🪶 Raven ✅  |  {your-project}  |  {stack}
   Andie is your discipline layer. What are you working on?

Quick start

You typeWhat happens
why is auth failing since yesterday?routed to andie-jr — 2-round triage: root cause → fix → audit note
should we use Postgres or Mongo here?routed to andie — one mode card, 3-angle review, you approve each step
/andie or /andie-jrforce the route explicitly
git commit with a staged API keyhard block at the pre-commit gate, with the line that triggered it
rename this variablerouted nowhere — trivial edits skip the ceremony

What's included

  • 2 orchestrators — Andie (plan-first, one hard gate, critic voice) and Andie-Jr (brownfield debug, max 2 rounds)
  • Deterministic routers — repo-state + intent routing with visible one-line toasters; never routes silently
  • 61 domain skills — FastAPI, Postgres, K8s, Terraform, Salesforce, Odoo, Oracle, AWS/GCP/Azure, and more, loaded only when your work matches
  • Local guards — secret scan + CVE check (CVSS >7 blocks) at every commit; optional edit gate (raven-skill-gate, shadow/soft/hard modes); style and architecture checks
  • Cost-aware model routing — prompts classified to the cheapest adequate tier; secret-laden context forced to a local model
  • Audit + memory — JSONL audit logs, session notes, token dashboard — all on local disk

When to Use Raven — Use Case Table

ScenarioRavenPlain ClaudeNotes
Brownfield bug — "Why is auth timing out?"✅ Faster❌2-round triage beats open-ended; forces root cause before fix.
Architecture decision — "Should we migrate to Postgres?"✅ Better❌Triad (Functional/Tech/Data) catches angles one perspective misses.
Commit-time security — prevent secrets/CVEs shipping✅ Hard-block❌Pattern-based detection; reduces risk, not foolproof.
Routine feature work — "Build me a login form"❌ Slower✅ FasterRaven adds ceremony; plain Claude is direct.
Quick lookup — "What's the CloudRun pricing?"❌ Overkill✅ DirectNo decision needed; Raven's routing overhead is wasted.

Andie + Andie-Jr: The Decision Duo

Andie (Architecture, Design, Strategy)

Runs a Drama panel debate when your decision has tradeoffs:

  • Functional Lead — business/domain owner perspective
  • Technical Lead — system/implementation owner perspective
  • Data Lead — metrics/integration owner perspective

Each panelist argues their angle. You steer the debate. Final output: decision + rationale + rejected alternatives + risks.

Andie-Jr (Brownfield Triage)

For broken systems: problem → diagnosis → fix → audit.

  • Round 1: 2 clarifying questions that isolate the root cause.
  • Round 2: Root-cause explanation + fix + verification steps + audit note.

Not for greenfield builds; only for existing systems showing symptoms (errors, timeouts, regressions).

Routing Table

ScenarioRouteHow
Brownfield bug ("why is X broken?")andie-jrRepo >1 commit + symptom language detected
Greenfield or architecture ("should we...?")AndieRepo ≤1 commit OR Drama-mode intent
Data question ("what is...?", "list...", "show...")DirectNo change verbs (build, fix, create); no routing overhead
Force path (/andie, /andie-jr)ExplicitUser typed the skill name — routing wins always

How Raven Works — The Full Stack

Architecture Overview

UserPromptSubmit (every message)
  ↓
triage-router.py [deterministic repo-state]
  ├─ Brownfield (>1 commit) → andie-jr
  ├─ Greenfield (≤1 commit) → Andie
  ├─ Data question (read/list/explain, no change verbs) → direct
  └─ Force path (/andie, /andie-jr) → always wins
  ↓
[Specialist runs, edit/commit allowed]
  ↓
PostToolUse: secret-scan.py (after Write/Edit)
  ├─ AWS keys, OpenAI keys, GitHub tokens, SSH, bearer tokens → WARN
  └─ Send intent to audit log (`.raven/audit/YYYY-MM-DD.log`)
  ↓
Pre-commit hook (.git/hooks/pre-commit)
  ├─ secret-scan.py → HARD BLOCK if secrets staged
  ├─ cve-check.py (new imports) → HARD BLOCK if CVSS >7
  ├─ style-enforcer (line count, type hints, docstrings) → HARD BLOCK if violated
  ├─ architecture-guard (doc alignment) → WARN now, block in 24h
  ├─ db-guard (inline SQL, missing ERDs, migration order) → WARN
  └─ notify.py (SMTP + Slack) → send pass/fail summary + audit
  ↓
Commit lands (or blocked + approval flow starts)

7 Guard Agents — What They Check

GuardFiresDetectsAction
manifest-checkerSessionStartMissing .raven/manifest.jsonHard stop with setup guide
secret-guardPostToolUse + pre-commitAWS keys, tokens, SSH, PII in staged filesWarn on edit / hard block on commit
cve-checkNew import X statementLibrary vulnerabilities (CVSS >7)Warn during coding / hard block at commit
stack-validatorImport detected + not in approved listUnapproved libraries (Polars vs Pandas, etc.)Warn / block at commit
style-enforcerFile editLine count >200, missing type hints, no docstringsAdvise / block at commit
architecture-guardNew file createdMissing .raven/architecture.md documentationWarn / hard block after 24h grace
db-guardFile edit (SQL, migrations)Inline SQL in non-SQL files, missing ERDs, broken migration numberingWarn in audit log

Notifications (SMTP + Slack)

Fires from pre-commit hook on success or block:

  • Commit pass: Confirmation email + Slack (to recipients in .raven/manifest.secrets.json)
  • Commit blocked: Alert with violation count + Slack
  • Override used: Log to audit trail + email
  • Token warning: 75% / 90% thresholds

Tokenomics — What Raven Costs Per Message

Rule: enforcement runs in Python hooks, outside the model — it costs zero tokens. Gates, guards, scanners, audit logs, and the pre-commit pipeline never enter Claude's context. Only the thin advisory layer does:

LayerFrequencyTokens
Hooks: skill gate, secret scan, CVE, pre-commit, token guardevery tool call / commit0
Skill-reminder + router toasters (context injection)per message~100
Session boot (greeting + transparency banner)once per session~500
Specialist SKILL.md load (when a skill actually runs)once per session~1–2k
Violation messages (block/warn)only on violation~50

Steady-state: ~2% overhead on a typical session — and the model router (0-token hook) claws that back by tiering simple prompts to cheaper models and routing secret-laden context to a free local model. Full breakdown, including where Raven saves tokens: docs/TOKENOMICS.md · diagrams: business view · technical view.


Features by Version

Raven v4.1.0 (Current) — Privacy + Routing Hardening

New:

  • Privacy hardening: Changelog cleared from manifest, personal emails replaced with org email across all registries.
  • Critical routing fix: Deterministic repo-state logic replaces regex classification. Brownfield →andie-jr, greenfield → Andie, data questions → direct. Fixes misclassification of debug as new-work.

Maintained from v4.0:

  • Andie Drama mode (3-panelist debate on tradeoffs)
  • Andie-jr fast triage (2-round root-cause flow)
  • 61 domain skills (ML, Salesforce, Odoo, K8s, Terraform, etc.)
  • Commit-time secret + CVE scanning
  • Cross-session memory (.raven/memory/)
  • SMTP + Slack notifications

Raven v4.0.0 — Honesty Pass + First Release

  • Rewritten README: no false claims, honest ROI section, per-persona messaging.
  • Verified 61 skills (corrected from earlier miscount).
  • CLAUDE.md per-turn discipline contract at top; Raven/Lucky gate; real hook names.
  • First onboarding in Andie: brownfield self-detect vs greenfield setup (≤2 questions).
  • /andie + /andie-jr force-path commands; plugin now bundles 12 commands.
  • notify.py: real SMTP + Slack wired into pre-commit.
  • install-claudemd.py: append-only CLAUDE.md installer (never deletes user content).
  • Session-start transparency banner.

Previous Versions

See CHANGELOG.md for v3.x and earlier.

Upgrade Path

  • v4.0 → v4.1: Drop-in replacement. Run /raven-sync to sync manifests; no config changes needed.
  • v3.x → v4.0+: Not backward-compatible. See migration guide in CONTRIBUTING.md.

Other Install Paths

Claude Desktop (ZIP): download raven-plugin-v4.1.0.zip → Settings → Extensions → Add plugin → drop the ZIP → restart.

From source:

git clone https://github.com/giggsoinc/raven.git
cd raven && bash plugin/make-plugin.sh   # builds plugin/raven-plugin-v4.1.0.zip

Contributing

Raven is MIT licensed. Contributions welcome. See CONTRIBUTING.md for:

  • How to add a skill
  • How to write a guard agent
  • Style standards (Giggso code style — type hints, docstrings, logging, ≤200 LOC per file)
  • Pre-commit hook requirements

Raven Enterprise

This repo is the free tier — everything runs local, MIT-licensed, complete as-is.

Raven Enterprise (paid, sold separately) adds what teams and compliance departments need on top: Hub dashboards across developers and repos, per-developer token attribution and chargeback, compliance/audit reporting, centralized policy sync, and commercial support.

→ giggso.com


Support & Issues


Raven v4.1.0 — Governance for AI coding at the speed of thought.

Ver o original no GitHub

Bom para

Relacionados