🦌 Deerflow

Production-Grade Enforcement Framework

Enforce zero-tolerance quality standards. Ship code that actually works.

9-Gate Quality Pipeline · Workflow Engine · Skill Modules · CLI Tool Reference

Quick Start · How It Works · Quality Gates · Skill Modules · Problems Solved

---

🎯 The Problem

Modern software projects suffer from the same recurring quality issues. Whether you're a solo developer, a growing startup, or an established team — these 25 critical flaws keep shipping to production:

#	Flaw	Impact
1	Poor code quality	Bugs, crashes, maintenance nightmares
2	UI doesn't match specs	Wasted iterations, broken designs
3	Files lost during refactors	Missing code, broken functionality
4	Incomplete bug fixes	Partial solutions, recurring bugs
5	Mock/fake data in production	Unusable software, security risks
6	Infinite loops & hangs	Frozen applications, CPU waste
7	Unprofessional UI	Bad user experience, no adoption
8	Security vulnerabilities	OWASP Top 10, data breaches
9	Unverified assumptions	Non-existent APIs, wrong solutions
10	No type safety	Runtime errors, unpredictable behavior
11	Missing error handling	Crashes, data loss
12	No tests	Unverified code, regression risk
13	Hardcoded secrets	Credential leaks, security breaches
14	No input validation	Injection attacks, data corruption
15	Missing documentation	Unmaintainable codebase
16	No CI/CD	Manual processes, human error
17	No containerization	Deployment failures
18	No rate limiting	DoS vulnerability
19	No authentication	Unauthorized access
20	Circular dependencies	Build failures, runtime errors
21	Memory leaks	Degraded performance, crashes
22	No observability	Blind to production issues
23	Breaking changes	Unstable APIs, broken consumers
24	No database patterns	N+1 queries, data inconsistency
25	Non-standard commits	Unreadable git history

Every single one of these is solvable through enforcement.

✅ The Solution: Deerflow

Deerflow is a single repository you git clone that enforces production-grade standards through 3 layers:

Layer 1: Project Scaffold (Strict Configs)

• TypeScript strict mode (zero any, no implicit anything)
• ESLint with custom mock-data detection plugin
• Prettier for consistent formatting
• Vitest with 80% coverage thresholds
• Zod for runtime validation

Layer 2: Git Hooks (Husky)

• pre-commit: Secrets scan, mock data check, lint, type-check, tests
• commit-msg: Conventional Commits enforcement

Layer 3: CI/CD Pipeline (GitHub Actions)

• 5 parallel jobs: typecheck, lint, test+coverage, build, security
• Coverage threshold check (80%)
• npm audit + Trivy security scanning
• Secret detection in source code

🚀 Quick Start

git clone https://github.com/ntd25022006q/deerflow.git
cd deerflow

npm install
cp .env.example .env.local

make enforce      # Install enforcement tools
make quality-gate # Verify everything works
npm run dev       # Start development

⚙️ How It Works

Workflow Engine

The 8-phase pipeline that every contributor MUST follow:

┌─────────┐   ┌──────┐   ┌──────────┐   ┌───────────┐   ┌──────────┐   ┌──────┐   ┌──────────┐   ┌──────────────┐
│ ANALYZE │──▶│ PLAN │──▶│ SCAFFOLD │──▶│ IMPLEMENT │──▶│ VALIDATE │──▶│ TEST │──▶│ SECURITY │──▶│ QUALITY GATE │
└─────────┘   └──────┘   └──────────┘   └───────────┘   └──────────┘   └──────┘   └──────────┘   └──────────────┘
     │            │            │              │               │            │           │               │
  Read code   Write ADR   Use templates   Follow patterns   Type+Lint   ≥80%      OWASP+           9/9
  Understand  Design      Create files    Repository Pat.   Zero err   coverage   secrets          PASS

• ANALYZE: Read requirements, understand domain, identify patterns
• PLAN: Design solution, write DECISIONS.md entry
• SCAFFOLD: Create files from templates/
• IMPLEMENT: Write code following Repository Pattern
• VALIDATE: Type-check + lint on every changed file
• TEST: Write tests, achieve ≥80% coverage
• SECURITY: Scan for OWASP Top 10, secrets, vulnerabilities
• QUALITY GATE: All 9 gates must pass — DEPLOY BLOCKED if any fail

Each phase has built-in validation. Failures block progression. Max 3 retries before escalating.

Skill Modules

5 specialized modules that enforce specific quality domains:

Skill	Purpose	Key Checks
🔍 code-review	Code quality enforcement	Zero any, no mock data, proper patterns, no empty catches
🔒 security	OWASP Top 10 scanning	SQL injection, XSS, secrets, CORS, auth, npm audit
🧪 test	Test coverage validation	Missing tests, empty tests, weak assertions, coverage ≥80%
🎨 ui	UI/UX quality	Accessibility (WCAG 2.1), responsive design, design system
🔎 search	Verify before coding	API docs, security advisories, best practices, version checks

🛡️ Quality Gates

The 9 gates that ALL must pass before any code is accepted:

Gate	Check	Command	Blocking
1	Build	npm run build	✅ Yes
2	Lint	eslint . --max-warnings=0	✅ Yes
3	Type Check	tsc --noEmit	✅ Yes
4	Test + Coverage	vitest run --coverage (≥80%)	✅ Yes
5	Security Audit	npm audit --audit-level=moderate	✅ Yes
6	Docker Build	docker build .	✅ Yes
7	Smoke Test	Health endpoint check	✅ Yes
8	Format Check	prettier --check .	✅ Yes
9	Secret Detection	Regex scan for hardcoded secrets	✅ Yes

Result: JSON report at .agent/reports/quality-report.json Exit code: 0 = DEPLOY APPROVED, 1 = DEPLOY BLOCKED

📁 Project Structure

deerflow/
├── .github/workflows/     # CI/CD pipelines
│   ├── ci.yml             # Main CI (typecheck, lint, test, build, security)
│   └── release.yml        # Release pipeline with changelog
├── .husky/                # Git hooks
│   ├── pre-commit         # Secrets + mock + lint + type-check + tests
│   └── commit-msg         # Conventional Commits enforcement
├── deerflow/              # 🦌 Core Framework
│   ├── workflow.ts        # Workflow Engine (8 phases)
│   ├── skills/            # Skill Modules
│   │   ├── code-review.skill.ts
│   │   ├── security.skill.ts
│   │   ├── test.skill.ts
│   │   ├── ui.skill.ts
│   │   └── search.skill.ts
│   └── index.ts           # Framework entry point
├── scripts/
│   └── quality-gate.sh    # 9-gate quality check script
├── src/                   # Application source code
│   ├── services/          # Business logic
│   ├── controllers/       # Request handlers
│   ├── routes/            # API route definitions
│   ├── models/            # Domain entities & schemas
│   ├── middleware/         # Auth, validation, error handling
│   ├── utils/             # Helper functions
│   ├── types/             # Shared TypeScript types
│   └── config/            # Configuration management
├── templates/             # Code templates (copy & rename)
│   ├── service.template.ts  # Repository Pattern template
│   ├── route.template.ts    # API route with validation + auth
│   └── component.template.ts # React component with a11y
├── tests/                 # Test files
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── e2e/               # End-to-end tests
├── docker/                # Docker configuration
│   └── nginx.conf         # Nginx reverse proxy config
├── AGENT_RULES.md         # 🚨 12 Mandatory Rules for contributors
├── DECISIONS.md           # Architecture Decision Records
├── CODEOWNERS             # Code ownership rules
├── cli-tools.json        # CLI tool reference (NOT MCP servers)
├── docker-compose.yml     # Dev environment (app + postgres + redis + nginx)
├── Dockerfile             # Multi-stage build (deps → builder → runner)
├── Makefile               # Central command hub
├── package.json           # Dependencies & scripts
├── tsconfig.json          # Strict TypeScript config
├── eslint.config.js      # ESLint flat config + custom mock detection
├── .prettierrc            # Code formatting rules
└── vitest.config.ts       # Test config with 80% coverage threshold

🗺️ Problems → Solutions Map

Problem	Deerflow Solution	Enforcement
Poor code quality	Repository Pattern templates + strict TypeScript	ESLint + type-check
UI mismatches	UI Skill (accessibility + responsive checks)	ui.skill.ts
Files lost during refactors	Full file read rule (Rule #7)	AGENT_RULES.md
Incomplete fixes	Quality Gate blocks until ALL pass	quality-gate.sh
Mock/fake data	Custom ESLint plugin detects mock patterns	eslint.config.js + pre-commit
Infinite loops	Performance lint rules	lint:perf
Unprofessional UI	UI Skill + design system consistency	ui.skill.ts
Security flaws	Security Skill (OWASP Top 10 scanner)	security.skill.ts + CI
Unverified assumptions	Search Skill (verify APIs before use)	search.skill.ts + Rule #10
No type safety	TypeScript strict mode + zero any rule	tsconfig.json + ESLint
Missing error handling	Route template with typed error handling	route.template.ts
No tests	Test Skill + 80% coverage threshold	vitest.config.ts
Hardcoded secrets	Secret detection in pre-commit + CI	.husky/pre-commit + CI
No input validation	Zod schemas in all templates	route.template.ts
No CI/CD	GitHub Actions with 5 parallel jobs	.github/workflows/
No Docker	Multi-stage Dockerfile + compose	Dockerfile + Gate 6
No rate limiting	Nginx config with rate limiting	docker/nginx.conf
No authentication	Route template with auth checks	route.template.ts
Circular dependencies	ESLint import/no-cycle rule	eslint.config.js
Memory leaks	Performance lint + review skill	code-review.skill.ts
Non-standard commits	Conventional Commits enforcement	.husky/commit-msg

🛠️ Available Commands

# Quality & Enforcement
make enforce          # Install all enforcement tools
make quality-gate     # Run all 9 quality gates
make verify           # Verify rules compliance
make fix              # Auto-fix lint and format issues

# Development
npm run dev           # Start development server
npm run build         # Build for production
npm run start         # Run production build

# Testing
make test             # Run all tests with coverage
make test:unit        # Run unit tests
make test:integration # Run integration tests
make test:e2e         # Run e2e tests

# Code Quality
make lint             # Run linter
make lint:fix         # Fix lint issues
make type-check       # TypeScript type checking
make format           # Format code with Prettier
make format:check     # Check formatting without fixing

# Security
make security         # Run security audit

# Docker
make docker:build     # Build Docker image
make docker:up        # Start all services
make docker:down      # Stop all services

# Release
make release:patch    # Bump patch version (1.0.x)
make release:minor    # Bump minor version (1.x.0)
make release:major    # Bump major version (x.0.0)

# Utilities
make clean            # Remove build artifacts
make fresh            # Clean install from scratch
make help             # Show all available commands

🔌 CLI Tool Reference

Deerflow includes a reference configuration for CLI tools commonly used in development. These are standard CLI tools invoked via subprocess, NOT MCP (Model Context Protocol) servers. MCP servers require JSON-RPC 2.0 over stdio or HTTP/SSE — see https://modelcontextprotocol.io for the MCP specification.

Tool	Purpose
Docker	Build, run, manage containers and services
PostgreSQL	Execute queries, run migrations, inspect schema
Redis	Cache operations, pub/sub, health checks
Git	Commits, branches, tags, diffs
Vitest	Run unit/integration/e2e tests with coverage
NPM Audit	Audit, secret scanning, OWASP checks
ESLint	Lint, format, type-check code

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🦌 Clone it. Quality is non-negotiable.

⬆ Back to Top