Raven v3.0

AI-native engineering discipline for Claude Code · GitHub Copilot · OpenAI Codex
61 domain skills · 10 always-on guard agents · 9 always-on hooks · CVE scanning · secret detection · audit logs · Obsidian session memory
Works for individual developers and engineering teams

v3.0 · Full Documentation · MIT License · Built by Giggso

## Performance Token cost is a first-class design constraint. Skills load once on invocation and remain in the context window for the entire session — smaller skills mean every subsequent message is cheaper. | Optimisation | Before | After | Saving | |---|---|---|---| | Andie (v5.2 → v6.3) | ~9,955 tok | ~3,103 tok | **−6,852 tok** | | db-router (pure routing table) | ~3,034 tok | ~474 tok | **−2,560 tok** | | ui-router | ~2,987 tok | ~1,424 tok | **−1,564 tok** | | agent-chaining | ~3,046 tok | ~1,361 tok | **−1,686 tok** | | **Total skill footprint** | **~22,321 tok** | **~9,523 tok** | **−57%** | | `raven-skill-reminder` hook | ~71 tok × every message | ~10 tok × first message only | **−61 tok/msg** | | Obsidian → `session-start` continuity | cold start each session | last session summary injected | **context carry** | In a 20-message session using Andie + 1 specialist: **~53% fewer context-tokens** compared to v3.0. ## The Problem Raven Solves **Raven is the discipline layer between your AI assistant and your codebase.** It doesn't slow you down. It makes sure what ships is actually good. ## What Raven Does ### 🧠 Andie — Your AI Architect (v6.3) Every session starts with **Andie**, Raven's orchestration layer. Andie isn't a chatbot — it's a structured expert system that: - **Detects your domain automatically** — Oracle ERP, Salesforce, AWS GenAI, Agentic AI, SAP, Kubernetes, Data Engineering, Security, and more - **Loads a Specialist Triad for that domain** — every problem gets three experts: 🏢 Functional (business/process) · ⚙️ Technical (implementation/code) · 📊 Data (flows/schema/pipelines). Each one surfaces their domain's corner cases - **Generates domain-specific questions** — not generic prompts. An Oracle O2C engagement gets O2C questions. An AWS ML project gets ML questions. Shown to you before asking, adjustable, one at a time - **Proposes before proceeding** — every tech recommendation, framework pick, and team suggestion is a PROPOSAL (accept / modify / reject). Nothing proceeds without your explicit confirmation. This is HITL as a first-class design principle, not an afterthought - **Runs OODA continuously** — Observe / Orient / Decide / Act fires after every round in every mode. When orientation shifts the picture, a PROPOSAL is issued before anything changes direction - **Picks the right thinking mode** — Deep (expert explanation), Kaizen (improvement cycles), War (crisis triage), Drama (multi-stakeholder debate). Shows you what each mode would produce *for your specific problem* before you commit to one - **200-word cap per generation** — Andie moves at human pace. One idea per round, fully absorbed before the next - **Feynman recap after every round** — "📌 Here is what we learnt:" — 100–150 word summary combining domain, technical, and data insights ### 🛡️ 10 Guard Agents — Always On Guard agents run silently in the background. They don't interrupt typing. They fire at the right moments — before a commit, after a file save, before a tool executes. | Guard Agent | What it protects | |---|---| | **manifest-checker** | Verifies Raven is properly configured before any work starts | | **stack-validator** | Catches wrong-stack libraries before they get merged. Warns during coding, hard blocks at commit | | **style-enforcer** | Enforces your team's code style. Advises during coding, blocks at commit | | **architecture-guard** | Ensures architecture decisions are documented. No diagram = warn now, block in 24h | | **db-guard** | Catches inline SQL in non-SQL files, missing ERDs, broken migration numbering | | **skill-guard** | Prevents skills from reading secrets, modifying settings, or acting outside their scope | | **claude-mem** | Writes structured session memory to `.raven/memory/`. Surfaces open questions at next session start | | **guard-git-watch** | Hard blocks any unexpected read of `.env`, SSH keys, or secrets files | | **odoo-guard** | Odoo-specific: catches hardcoded DB IDs, raw SQL in ORM context, broken module structure | | **salesforce-guard** | Salesforce-specific: catches SOQL/DML inside loops, missing bulk patterns, hardcoded IDs | ### 🔒 Commit-Time Gates Before any `git commit` lands, Raven runs a full gate: - **Secret scan** — checks every staged file for API keys, tokens, passwords, private keys. Hard blocks if found. No exceptions. - **CVE scan** — checks every library you've added against known vulnerabilities. CVSS > 7 = hard block. Unknown libraries go through an approval flow. - **Style check** — enforces your configured style rules across changed files - **Architecture check** — ensures any significant changes are reflected in architecture docs Secrets in staged files → hard block commit CVE critical (CVSS >7) → hard block commit Force push to main → hard block >100 rows deleted → approval flow required Schema drop detected → hard block + escalate Port 0.0.0.0 opened → hard block + escalate ### 📦 46 Domain Skills Skills activate only when your work matches their domain — ~100 tokens each, never loaded all at once. **Orchestration** **Frontend & Design Thin Router** *(auto-detects framework, design tool default: claude-design/stitch)* **Cloud Platforms** **Data & Streaming** **Infrastructure & DevOps** **Frameworks & APIs** **AI & ML** **Enterprise Platforms** **Oracle** **Engineering Practice** **Tooling** ### 🪝 9 Always-On Hooks — Fire Without Being Asked Unlike skills (which activate on domain match), hooks fire automatically at specific lifecycle events. You cannot forget to run them. | Event | Hook | Type | What it does | |---|---|---|---| | `SessionStart` | `session-start.py` | Context | Detects brownfield/greenfield · discovers available models · writes `.model.env` if missing | | `PreToolUse` any tool | `tool-guard.py` | **BLOCK** | Blocks restricted actions (rm -rf, sudo, etc.) | | `PreToolUse` Bash | `schema-guard.py` | **BLOCK** | Stops DROP TABLE / TRUNCATE / DELETE without WHERE before execution | | `UserPromptSubmit` | `cve-prompt-guard.py` | Warn | Detects install intent (`pip install`, `npm install`, etc.) — injects CVE reminder before Claude responds | | `PostToolUse` Write/Edit | `secret-scan.py` | Async warn | Scans every written file for secrets immediately — not just at commit | | `PostToolUse` any tool | `audit-log.py` | Async | Encrypted audit entry for every tool use | | `PreCompact` | `token-guard.py` | Warn | Token budget warnings at 25/50/75/90% | | `Stop` | `session-gate.py` | Async | Git status + recent commits + open observations at session end | | `Stop` | `obsidian-log.py` | Async | Three-layer session log → Obsidian vault: AI summary + files touched + git state | **INTEGRITY hooks** (BLOCK type) fire before execution and stop dangerous actions. **CONTEXT hooks** (Warn/Async) inform without blocking — so they never kill adoption. ### 🔄 Version Check — Every Session Raven checks its own version against the latest release every time a session opens: - **Up to date** → silent, no interruption - **1–2 releases behind** → version banner in session opener: "Update available — say 'update raven' to sync" - **3+ releases behind** → **auto-syncs automatically**, no action needed. You see a banner and it's done. This means teams on shared codebases never silently drift onto old versions. ## Who It's For **Enterprise IT** — need MDM deployment, MCP governance, model routing, and org-level risk dashboards? See [Raven Enterprise](https://github.com/giggsoinc/raven-enterprise). ## Install ### Quickest — Plugin (no terminal needed) 1. Download [`raven-plugin-v3.3.0.zip`](plugin/raven-plugin-v3.3.0.zip) 2. Open Claude Desktop → Settings → Extensions → Add plugin 3. Upload the ZIP 4. Done — 61 skills and 10 guard agents load automatically ### Individual Developer **macOS / Linux:** curl -fsSL https://raw.githubusercontent.com/giggsoinc/raven/main/install.sh | bash **Windows:** iwr https://raw.githubusercontent.com/giggsoinc/raven/main/install.ps1 | iex ### Enterprise For MDM deployment (Jamf, Intune, GPO), MCP governance, model routing, and Hub — see [Raven Enterprise](https://github.com/giggsoinc/raven-enterprise). ## How It Feels in Practice **You're adding a new AWS Lambda function:** Raven detects AWS. `aws-specialist` loads. When you `import requests`, the CVE check runs. At commit, secret scan checks your staged files. Style enforcer validates naming. Architecture guard checks if this is a significant new component that needs a decision record. **You ask Andie to help design a Salesforce order management flow:** Andie detects Salesforce domain. Loads: SF Domain Expert + SF Dev (LWC/APEX/Flow) + SF Agentforce + Data Cloud Architect. Generates 8 Salesforce-specific questions. Shows them to you before asking. After your answers, proposes the architecture as a PROPOSAL — you accept, modify, or push back before anything is designed. OODA runs after each round and flags if the approach needs to shift. **A CVE is found in a library you just added:** Pre-commit hook fires. CVSS score shown. If > 7, commit hard-blocked. You see the alternative. If it's a known false positive or approved dependency, the approval flow is triggered with one command: `git commit -m "feat: X [GUARD:ALLOW-CVE]"`. **It's 2am and production is down:** You open Claude Code. Andie detects "production down" signal. War mode fires. No framework discussion, no diagram selection. Triage block in 10 seconds. OODA at T+0 gives you the first action. Incident log builds automatically. One command transitions to Kaizen when you're stable. ## Companion Repos | Repo | For | Does | |---|---|---| | [giggsoinc/raven](https://github.com/giggsoinc/raven) | Claude Code · Codex · Copilot | This repo — full install, plugin ZIP, all skills | | [giggsoinc/raven-codex](https://github.com/giggsoinc/raven-codex) | Codex / Copilot users | Plugin-only version | | [giggsoinc/raven-guard](https://github.com/giggsoinc/raven-guard) | DevOps / architects | Production-grade guard layer | | [giggsoinc/raven-enterprise](https://github.com/giggsoinc/raven-enterprise) | Enterprise IT | Superset — Hub, MCP guard, dynamic model routing, org risk | | [giggsoinc/andie](https://github.com/giggsoinc/andie) | All AI platforms | Andie v6.3 standalone — works on ChatGPT, Gemini, Manus, Perplexity too | ## License MIT — [Giggso](https://giggso.com) [HOW-TO-USE.md](HOW-TO-USE.md) · [CLAUDE.md](CLAUDE.md) · [plugin/README.md](plugin/README.md)