Mandrel: A GitHub-Native Governance Framework for AI Coding Assistants

Mandrel is a GitHub-native governance framework for AI coding assistants. Its core goal is to ensure code quality, architectural consistency, and unified professional standards while maintaining the efficiency of AI-driven development. Key mechanisms include:

1. An Epic-Centric workflow that uses GitHub Issues, Labels, and Projects V2 as the Single Source of Truth (SSOT)
2. A two-command simplified SDLC critical path (/epic-plan from idea to planning, /epic-deliver from development to delivery)
3. An automated validation system based on quality gates (linting, testing, type checking, maintainability index, etc.)
4. Performance telemetry and observability support to facilitate continuous optimization

With the widespread application of LLMs in software development, teams face a core challenge: how to ensure code quality, architectural consistency, and professional standards while AI coding assistants generate code efficiently? Traditional processes treat AI as a simple completion tool, lacking systematic governance mechanisms. Mandrel was born to address this. It is not a collection of prompts but a complete governance framework. Through structured instructions, role setting, skill definition, and SDLC workflows, it establishes a repeatable, verifiable, and scalable collaboration model for AI assistants.

The core design of Mandrel is to use GitHub as the Single Source of Truth:

• Epic-Centric Organization: All planning, execution, and status management exist natively on the GitHub platform
• Decentralized Decision-Making: No local files are needed; key information is tracked via GitHub Issues and Projects
• Traceability: The complete chain from original idea to final delivery is recorded on GitHub This design aligns with modern development trends, using the collaboration platform itself as governance infrastructure.

Mandrel compresses the SDLC critical path with two commands:

1. /epic-plan: Convert original ideas into clear requirements → Create GitHub Epic → Automatically generate PRD, technical specifications, and a four-layer ticket structure (Epic→Story→Task→Subtask)
2. /epic-deliver: Wave-like parallel development (Agent sub-agents execute Stories) → git worktree isolation to avoid conflicts → Execute quality gates (lint/test/typecheck/MI/CRAP) → Generate retrospective report → Create PR (merged after manual review; does not auto-merge to main branch)

Mandrel establishes a complete quality gate system to ensure code health:

• Multi-Layer Validation: Linting (style), testing (automated tests), type checking, Maintainability Index (MI), CRAP (change risk)
• Baseline Management: Per-Epic baseline snapshot → Only refresh baselines for changed files when a Story is closed → Set thresholds to prevent quality regression (MI drop ≤1.5, CRAP jump ≤5)
• Coding-Time Tools: npm run quality:preview (MI/CRAP changes for diff files), npm run quality:watch (auto-check on file changes), pre-commit hooks (pre-submission gates)

Highlights of Mandrel's technical architecture:

• Concurrency Control and Module Hygiene: Bounded concurrency (controlled via concurrentMap), centralized HTTP client, branch name protection
• Reliability Enhancement on Closure: Baseline parsing optimization (based on Epic ref instead of main), safe deletion check (git merge-base to verify reachability), baseline ownership tracking (attributed to the Story causing the difference)

Applicable scenarios for Mandrel:

1. Large-scale AI-assisted development (multiple developers collaborating with AI assistants)
2. Code quality-sensitive projects (finance, healthcare, etc.)
3. Remote distributed teams (using GitHub native features for asynchronous collaboration)
4. Continuous delivery practices (automated validation + rapid iteration) Value proposition: Maintain code quality and architectural consistency while enjoying the efficiency gains from AI.

Mandrel represents the evolutionary direction of AI-assisted development governance: from treating AI as a tool to treating it as a collaborative participant that requires governance. By using GitHub as governance infrastructure and establishing quality gates and observability mechanisms, it provides teams with a feasible path to balance efficiency and quality. Core insight: The value of AI coding assistants lies not only in generation speed but also in the maintainability and verifiability of code. Only by establishing a systematic governance framework can we truly unlock the potential of AI in software development.