🛡️ Cerber Core — CI Contract Guard for GitHub Actions

Detects workflow/config drift across repos and enforces a single source of truth via CERBER.md.

> AI doesn't break your project. Lack of a contract does.

![npm version](https://www.npmjs.com/package/cerber-core)
![License: MIT](https://opensource.org/licenses/MIT)
![GitHub](https://github.com/Agaslez/cerber-core)
![Discord](https://discord.gg/V8G5qw5D)

---

What is Cerber Core?

Cerber enforces your project roadmap as executable contract (CERBER.md). Write rules once, get automatic validation on every commit + CI run.

$3

✅ Contract guard — Validates your CERBER.md rules are enforced
✅ Drift detector — Catches when CI config/workflow changes break protection
✅ Works WITH existing tools — Doesn't replace ESLint/Prettier/tests. Ensures they stay required.

❌ Not a linter — Use ESLint for code style
❌ Not a test runner — Use Jest/Vitest for unit tests
❌ Not a deployment tool — Use your existing CD pipeline

Think of it as: Policy-as-code layer that prevents your other tools from being bypassed.

Why? (The CI Drift Problem)

- ✅ AI agents follow your roadmap → Agent pastes code matching CERBER.md
- ❌ Human bypasses rules → Commit sneaks through, CI green but wrong
- ❌ CI config drifts → Workflow changes, gates disappear, protection gone

Solution: Guardian blocks bad commits before they reach CI. CI re-validates and protects itself from tampering.

---

🏆 Proof: Used in Production

Cerber protects real SaaS applications. See it in action:

Eliksir Platform CI Pipelines:
- 🎨 Frontend: Guardian Schema Check + tests ✅
- ⚙️ Backend: Quality Gate + deploy checks ✅

These aren't demo projects - live production systems serving real users, protected by Cerber since day one.

📖 Full case study: How Cerber prevented 47 production bugs

---

💬 Community (Discord)

Join the Cerber Core Discord for support, feedback, and CI/Doctor showcases:
👉 https://discord.gg/V8G5qw5D

- Questions: ask in #general
- Feedback / bugs: #feedback (bugs can also go to GitHub Issues)
- Proofs: post your CI runs / doctor output in #showcase

---

🚀 Quick Start (60 seconds)

bash

1. Install

npm i -D cerber-core



2. Generate contract template

npx cerber init



3. Edit CERBER.md (use AI assistant or manual)

→ Define your roadmap, tech stack, protected assets



4. Generate hooks + CI workflow

npx cerber init



5. Verify setup

npx cerber doctor



6. Commit and push

git add .

git commit -m "feat: add Cerber protection"

git push





That's it. Guardian now blocks bad commits. CI re-validates and protects itself.



---



What Cerber Checks



$3

- ❌ Secrets in code (API keys, tokens)

- ❌ Forbidden patterns (eval, console.log in prod)

- ❌ Missing required imports

- ❌ Protected file deletions

- ✅ Schema validation (if enabled)



$3

- ❌ Workflow tampering (job ID changes)

- ❌ Missing required checks

- ❌ Contract violations

- ✅ Re-runs Guardian validation



📍 TODAY: CI contract guard + workflow drift detection  

🚀 ROADMAP: Post-deploy health gates (experimental in v1.1, production-ready in v2.0)



$3

- ❌ Missing CERBER.md

- ❌ Missing schema (strict mode)

- ❌ Missing pre-commit hook

- ❌ Missing CI workflow

- ✅ Override state validation



---



⚖️ Stability Policy



Cerber is a devtool — we don't break pipelines:



- CLI flags + exit codes: Follow SemVer. Breaking changes = major version bump.

- JSON output: Versioned schema (e.g.,

{"version": "1.0", ...}

). New fields = minor, changed fields = major.

- CI workflow templates: Generated files are yours to customize. Updates = opt-in via

cerber init --force

.



Current stability: v1.1.11 is production-ready for CI contract guard use case. See production proof.



---



Example: CI Drift Detected

bash

$ npx cerber doctor



[Cerber Doctor] Setup Validation



[OK] All checks passed!



Configuration:

  Mode: dev

  Guardian: enabled

  Health: enabled

  CI: github

  Override: DISABLED



[READY] Ready to commit!



⭐ If Cerber helped you, star the repo: https://github.com/Agaslez/cerber-core

💬 Join Discord for feedback/support: https://discord.gg/V8G5qw5D





When drift detected:

bash

$ npx cerber doctor



[Cerber Doctor] Setup Validation



[FAIL] Issues found:



[!] .github/workflows/cerber.yml

    GitHub workflow not found



Next Steps:



1. Re-run initialization to generate missing files:

   npx cerber init



Help: https://github.com/Agaslez/cerber-core/discussions





---



How to Use Cerber (Full Workflow)



Cerber is simple: write rules once in

CERBER.md

, enforce on every commit + CI run.



📍 TODAY: Pre-commit Guardian + CI workflow drift detection  

🚀 ROADMAP: Post-deploy health gates (experimental)



Roadmap → CERBER.md contract → enforced automatically on every commit/push.



$3

bash

npm i -D cerber-core

$3

bash

npx cerber init





If CERBER.md did not exist, Cerber creates a template and stops.  

Now YOU fill the contract (ideally with an AI assistant).



$3



Take your project roadmap + repo structure and paste it into ChatGPT/Claude/Cursor with the Cerber Contract Translator prompt (see below).



Then:

- Paste the generated contract into

CERBER.md



- Run init again to generate hooks/workflows/templates:

bash

  npx cerber init

$3

bash

npx cerber doctor





Exit codes:

-

 ✅ All checks pass

-

 ❌ Missing CERBER.md

-

 ❌ Missing schema (strict mode)

-

 ❌ Missing hook/workflow



$3



-

git commit

 → Guardian validates staged changes (blocks violations)

-

git push

 → GitHub Actions validates again in CI



---



💬 Feedback & Support



Having issues? Want to share your setup?



- 💬 Discord: https://discord.gg/V8G5qw5D (fastest support)

- 🐛 GitHub Issues: Report bugs

- 💡 GitHub Discussions: Ask questions, share ideas

- 📖 Case Studies: See Cerber in production



Show your CI runs in Discord

#showcase!





---



Cerber Contract Translator (Copy/Paste Prompt)



> Use this to generate a production-ready

CERBER.md

 from your roadmap.  

> Cerber does NOT design your architecture. It enforces what you write.



PROMPT:



You are a "Cerber Contract Translator". Convert my roadmap + repo structure into a

CERBER.md

 contract.



RULES:

- Do NOT invent architecture or rules.

- Only translate what I explicitly provide.

- If something is missing, ask up to 10 questions in a

QUESTIONS

 section and leave placeholders.

- Output must be a complete

CERBER.md

 with:

  1) CERBER_CONTRACT (YAML)

  2) ROADMAP_AS_LAW (milestones)

  3) AI_AGENT_RULES (no guessing)

  4) PROTECTED_ASSETS

  5) CERBER_OVERRIDE (TTL safety fuse)

  6) QUESTIONS



INPUT I PROVIDE:

- Roadmap (what we are building, milestones, priorities)

- Repo structure (

tree -L 3

 or folder list)

- Tech stack + commands for smoke/e2e/build

- Integrations (Stripe/Ghost/Cloudinary/etc.)

- What files/paths are "protected" from deletion



Now generate

CERBER.md





---



For AI Agents (Copilot / Cursor / Windsurf / Claude / etc.)



Single rule:

CERBER.md

 is the ONLY source of truth.



$3



1) If

CERBER.md is missing:



   - Run

npx cerber init

 to generate template

   - STOP (user must provide contract content)



2) If

CERBER.md exists:



   - Read it first

   - Execute exactly what it says

   - Do NOT invent rules, do NOT infer architecture



3) Schema policy (important):

   - If

schema.mode: strict

 → DO NOT generate schema files

   - If

schema.mode: template_only

 → you may generate only the minimal template (NOT decisions)



4) Safety rules:

   - Never disable or rename CI job id:

cerber-ci



   - Never remove:

CERBER.md, .github/workflows/cerber.yml, scripts/cerber-guardian.mjs, .husky/pre-commit, .github/CODEOWNERS



   - Never bypass checks using

continue-on-error



   - Never use

cat < for TS/JS (corrupts ${}

 template literals)



If a required rule is not present in

CERBER.md → ASK USER or FAIL FAST.





---



🔗 Links



- Repository: https://github.com/Agaslez/cerber-core

- Releases: https://github.com/Agaslez/cerber-core/releases

- Security Policy: https://github.com/Agaslez/cerber-core/blob/main/SECURITY.md

- Discussions: https://github.com/Agaslez/cerber-core/discussions

- Full Documentation: docs/README_LONG.md



---



📋 Minimal CERBER.md Example

yaml

CERBER_CONTRACT

\

yaml

version: 1

mode: solo  # solo | dev | team



guardian:

  enabled: true

  schemaFile: BACKEND_SCHEMA.mjs



schema:

  enabled: true

  file: BACKEND_SCHEMA.mjs

  mode: strict  # Recommended: You create schema, Cerber never generates



health:

  enabled: true

  endpoint: /api/health



ci:

  provider: github

  branches: [main]

\





Schema modes:

-

strict

 (recommended) → You design architecture, Cerber guards it

-

template_only

 → Helper scaffold for beginners (NOT design decisions)



---



📚 Documentation



Quick Links:

- 📖 Full Documentation (Long README)

- 🛡️ Guardian API - Pre-commit validation

- 🔍 Cerber API - Runtime health checks

- ⚡ SOLO Layer - Automation for solo developers (666 LOC)

- 👥 TEAM Layer - Focus Mode + module system (1861 LOC)

- 🏗️ Architecture - System design philosophy

- 🔐 Security Policy - Supply-chain security, vulnerability reporting

- 🤝 Contributing - How to contribute



Workflows by Team Size:

- Solo Developer - 1 person, 15min setup

- Small Team (2-5) - Module system, 1-2h setup

- Growing Team (5-20) - Architecture governance



Examples:

- Frontend Schema (React)

- Backend Schema (Express)

- Health Checks

- SOLO Integration

- TEAM Integration



---



✨ Key Features



$3

- Schema-as-Code (architecture rules in version control)

- Fast feedback (<1s validation vs 5min CI wait)

- Required imports + forbidden patterns

- Architect approvals (traceable exceptions)



$3

- Detailed diagnostics (diagnosis + rootCause + fix)

- Severity levels (critical/error/warning)

- Component-based health checks

- Performance tracking



$3

- Auto-repair (format, deps, changelog)

- Performance budget enforcement

- Daily dashboard

- Dependency health checks



$3

- Focus Mode (500 LOC context vs 10K LOC for AI) ⭐

- Module boundaries enforcement

- Connection contracts between modules

- CERBER.md project mapping



---



🚨 Emergency Override



For P0 production hotfixes only, controlled safety fuse with strict TTL:

yaml

CERBER_OVERRIDE

enabled: true

reason: "P0 - Payment API down, emergency rollback"

expires: "2026-01-04T18:00:00Z"  # 6-hour TTL

approvedBy: "CTO Name"





What Override DOES:

- ✅ Allows pre-commit to pass WITH WARNING (audit trail logged)

- ✅ Can skip postDeploy gate if configured



What Override NEVER DOES:

- ❌ Disable

cerber-integrity

 job (self-protection always runs)

- ❌ Disable entire CI pipeline (build/test/lint must pass)

- ❌ Disable CODEOWNERS enforcement (team mode)



Use sparingly. After expiry, guardian proceeds with normal validation.



---



🤝 Contributing



Contributions welcome! Please read CONTRIBUTING.md first.

bash

git clone https://github.com/Agaslez/cerber-core.git

cd cerber-core

npm install

npm run build

npm test

``

---

📞 Support & Links

- 💬 Discord: Join community
- 🐛 Issues: GitHub Issues
- 💡 Discussions: GitHub Discussions
- 📖 Full Docs: docs/README_LONG.md
- 📚 Case Study: How Cerber prevented 47 bugs
- 🎭 Story: The team behind Cerber
- 🔐 Security: Report vulnerabilities to st.pitek@gmail.com
- ⭐ Repository: github.com/Agaslez/cerber-core

---

📄 License

MIT © 2026 Stefan Pitek

Free for commercial use. See LICENSE for details.

---

🌟 About

Founded by Agata Ślęzak, created and maintained by Stefan Pitek

- 📖 Read the full story: docs/STORY.md

Read the full story: docs/STORY.md

Support development: docs/SPONSORING.md

---

⭐ If Cerber saved you time, give it a star! ⭐

Made with 🛡️ by developers, for developers

🛡️ Cerber Core — CI Contract Guard for GitHub Actions

What is Cerber Core?

Cerber enforces your project roadmap as executable contract (CERBER.md). Write rules once, get automatic validation on every commit + CI run.

$3

Why? (The CI Drift Problem)

🏆 Proof: Used in Production

💬 Community (Discord)

🚀 Quick Start (60 seconds)

bash

1. Install

npm i -D cerber-core



2. Generate contract template

npx cerber init



3. Edit CERBER.md (use AI assistant or manual)

→ Define your roadmap, tech stack, protected assets



4. Generate hooks + CI workflow

npx cerber init



5. Verify setup

npx cerber doctor



6. Commit and push

git add .

git commit -m "feat: add Cerber protection"

git push





That's it. Guardian now blocks bad commits. CI re-validates and protects itself.



---



What Cerber Checks



$3

- ❌ Secrets in code (API keys, tokens)

- ❌ Forbidden patterns (eval, console.log in prod)

- ❌ Missing required imports

- ❌ Protected file deletions

- ✅ Schema validation (if enabled)



$3

- ❌ Workflow tampering (job ID changes)

- ❌ Missing required checks

- ❌ Contract violations

- ✅ Re-runs Guardian validation



📍 TODAY: CI contract guard + workflow drift detection  

🚀 ROADMAP: Post-deploy health gates (experimental in v1.1, production-ready in v2.0)



$3

- ❌ Missing CERBER.md

- ❌ Missing schema (strict mode)

- ❌ Missing pre-commit hook

- ❌ Missing CI workflow

- ✅ Override state validation



---



⚖️ Stability Policy



Cerber is a devtool — we don't break pipelines:



- CLI flags + exit codes: Follow SemVer. Breaking changes = major version bump.

- JSON output: Versioned schema (e.g.,

{"version": "1.0", ...}

). New fields = minor, changed fields = major.

- CI workflow templates: Generated files are yours to customize. Updates = opt-in via

cerber init --force

.



Current stability: v1.1.11 is production-ready for CI contract guard use case. See production proof.



---



Example: CI Drift Detected

bash

$ npx cerber doctor



[Cerber Doctor] Setup Validation



[OK] All checks passed!



Configuration:

  Mode: dev

  Guardian: enabled

  Health: enabled

  CI: github

  Override: DISABLED



[READY] Ready to commit!



⭐ If Cerber helped you, star the repo: https://github.com/Agaslez/cerber-core

💬 Join Discord for feedback/support: https://discord.gg/V8G5qw5D





When drift detected:

bash

$ npx cerber doctor



[Cerber Doctor] Setup Validation



[FAIL] Issues found:



[!] .github/workflows/cerber.yml

    GitHub workflow not found



Next Steps:



1. Re-run initialization to generate missing files:

   npx cerber init



Help: https://github.com/Agaslez/cerber-core/discussions





---



How to Use Cerber (Full Workflow)



Cerber is simple: write rules once in

CERBER.md

, enforce on every commit + CI run.



📍 TODAY: Pre-commit Guardian + CI workflow drift detection  

🚀 ROADMAP: Post-deploy health gates (experimental)



Roadmap → CERBER.md contract → enforced automatically on every commit/push.



$3

bash

npm i -D cerber-core

$3

bash

npx cerber init





If CERBER.md did not exist, Cerber creates a template and stops.  

Now YOU fill the contract (ideally with an AI assistant).



$3



Take your project roadmap + repo structure and paste it into ChatGPT/Claude/Cursor with the Cerber Contract Translator prompt (see below).



Then:

- Paste the generated contract into

CERBER.md



- Run init again to generate hooks/workflows/templates:

bash

  npx cerber init

$3

bash

npx cerber doctor





Exit codes:

-

 ✅ All checks pass

-

 ❌ Missing CERBER.md

-

 ❌ Missing schema (strict mode)

-

 ❌ Missing hook/workflow



$3



-

git commit

 → Guardian validates staged changes (blocks violations)

-

git push

 → GitHub Actions validates again in CI



---



💬 Feedback & Support



Having issues? Want to share your setup?



- 💬 Discord: https://discord.gg/V8G5qw5D (fastest support)

- 🐛 GitHub Issues: Report bugs

- 💡 GitHub Discussions: Ask questions, share ideas

- 📖 Case Studies: See Cerber in production



Show your CI runs in Discord

#showcase!





---



Cerber Contract Translator (Copy/Paste Prompt)



> Use this to generate a production-ready

CERBER.md

 from your roadmap.  

> Cerber does NOT design your architecture. It enforces what you write.



PROMPT:



You are a "Cerber Contract Translator". Convert my roadmap + repo structure into a

CERBER.md

 contract.



RULES:

- Do NOT invent architecture or rules.

- Only translate what I explicitly provide.

- If something is missing, ask up to 10 questions in a

QUESTIONS

 section and leave placeholders.

- Output must be a complete

CERBER.md

 with:

  1) CERBER_CONTRACT (YAML)

  2) ROADMAP_AS_LAW (milestones)

  3) AI_AGENT_RULES (no guessing)

  4) PROTECTED_ASSETS

  5) CERBER_OVERRIDE (TTL safety fuse)

  6) QUESTIONS



INPUT I PROVIDE:

- Roadmap (what we are building, milestones, priorities)

- Repo structure (

tree -L 3

 or folder list)

- Tech stack + commands for smoke/e2e/build

- Integrations (Stripe/Ghost/Cloudinary/etc.)

- What files/paths are "protected" from deletion



Now generate

CERBER.md





---



For AI Agents (Copilot / Cursor / Windsurf / Claude / etc.)



Single rule:

CERBER.md

 is the ONLY source of truth.



$3



1) If

CERBER.md is missing:



   - Run

npx cerber init

 to generate template

   - STOP (user must provide contract content)



2) If

CERBER.md exists:



   - Read it first

   - Execute exactly what it says

   - Do NOT invent rules, do NOT infer architecture



3) Schema policy (important):

   - If

schema.mode: strict

 → DO NOT generate schema files

   - If

schema.mode: template_only

 → you may generate only the minimal template (NOT decisions)



4) Safety rules:

   - Never disable or rename CI job id:

cerber-ci



   - Never remove:

CERBER.md, .github/workflows/cerber.yml, scripts/cerber-guardian.mjs, .husky/pre-commit, .github/CODEOWNERS



   - Never bypass checks using

continue-on-error



   - Never use

cat < for TS/JS (corrupts ${}

 template literals)



If a required rule is not present in

CERBER.md → ASK USER or FAIL FAST.





---



🔗 Links



- Repository: https://github.com/Agaslez/cerber-core

- Releases: https://github.com/Agaslez/cerber-core/releases

- Security Policy: https://github.com/Agaslez/cerber-core/blob/main/SECURITY.md

- Discussions: https://github.com/Agaslez/cerber-core/discussions

- Full Documentation: docs/README_LONG.md



---



📋 Minimal CERBER.md Example

yaml

CERBER_CONTRACT

\

yaml

version: 1

mode: solo  # solo | dev | team



guardian:

  enabled: true

  schemaFile: BACKEND_SCHEMA.mjs



schema:

  enabled: true

  file: BACKEND_SCHEMA.mjs

  mode: strict  # Recommended: You create schema, Cerber never generates



health:

  enabled: true

  endpoint: /api/health



ci:

  provider: github

  branches: [main]

\





Schema modes:

-

strict

 (recommended) → You design architecture, Cerber guards it

-

template_only

 → Helper scaffold for beginners (NOT design decisions)



---



📚 Documentation



Quick Links:

- 📖 Full Documentation (Long README)

- 🛡️ Guardian API - Pre-commit validation

- 🔍 Cerber API - Runtime health checks

- ⚡ SOLO Layer - Automation for solo developers (666 LOC)

- 👥 TEAM Layer - Focus Mode + module system (1861 LOC)

- 🏗️ Architecture - System design philosophy

- 🔐 Security Policy - Supply-chain security, vulnerability reporting

- 🤝 Contributing - How to contribute



Workflows by Team Size:

- Solo Developer - 1 person, 15min setup

- Small Team (2-5) - Module system, 1-2h setup

- Growing Team (5-20) - Architecture governance



Examples:

- Frontend Schema (React)

- Backend Schema (Express)

- Health Checks

- SOLO Integration

- TEAM Integration



---



✨ Key Features



$3

- Schema-as-Code (architecture rules in version control)

- Fast feedback (<1s validation vs 5min CI wait)

- Required imports + forbidden patterns

- Architect approvals (traceable exceptions)



$3

- Detailed diagnostics (diagnosis + rootCause + fix)

- Severity levels (critical/error/warning)

- Component-based health checks

- Performance tracking



$3

- Auto-repair (format, deps, changelog)

- Performance budget enforcement

- Daily dashboard

- Dependency health checks



$3

- Focus Mode (500 LOC context vs 10K LOC for AI) ⭐

- Module boundaries enforcement

- Connection contracts between modules

- CERBER.md project mapping



---



🚨 Emergency Override



For P0 production hotfixes only, controlled safety fuse with strict TTL:

yaml

CERBER_OVERRIDE

enabled: true

reason: "P0 - Payment API down, emergency rollback"

expires: "2026-01-04T18:00:00Z"  # 6-hour TTL

approvedBy: "CTO Name"





What Override DOES:

- ✅ Allows pre-commit to pass WITH WARNING (audit trail logged)

- ✅ Can skip postDeploy gate if configured



What Override NEVER DOES:

- ❌ Disable

cerber-integrity

 job (self-protection always runs)

- ❌ Disable entire CI pipeline (build/test/lint must pass)

- ❌ Disable CODEOWNERS enforcement (team mode)



Use sparingly. After expiry, guardian proceeds with normal validation.



---



🤝 Contributing



Contributions welcome! Please read CONTRIBUTING.md first.

bash

git clone https://github.com/Agaslez/cerber-core.git

cd cerber-core

npm install

npm run build

npm test

``

---

📞 Support & Links

📄 License

🌟 About

⭐ If Cerber saved you time, give it a star! ⭐

Made with 🛡️ by developers, for developers