convez.ai
AgenteDevOps & InfraestruturaAvançado
ai-godfather

AI Project Governance Framework

ai-godfather/ai-project-governance

Governança modular para projetos com IA: 16 papéis + gates de qualidade

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework de governança IA para times de desenvolvimento que utilizam assistentes de código. Fornece 16 papéis especializados, workflow enforcement com quality gates e validação em 15 dimensões para prevenir erros de codificação assistida por IA.

Instalação

$npx convez-ai ai-godfather/ai-project-governance

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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Enforçar qualidade em projetos com Claude/GPT/Cursor
  • Implementar gates de validação antes de deployment
  • Estruturar workflows TDD com suporte a testes
  • Auditar código gerado por IA em 15 dimensões
  • Documentar padrões de projeto e guardrails de IA

Veredito

Framework robusto e bem-documentado para times que querem governança séria em projetos AI-assisted. Exige instalação manual e adoção disciplinada do workflow, não é plug-and-play. Valor real em organizações que codificam com IA sistematicamente.

README

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

AI Project Governance

Version: 2.0.0
Author: God_FatherAI (https://x.com/God_FatherAI)
Status: Framework Complete (v2.0.0)
License: MIT

A project-agnostic AI governance framework for software development teams using AI coding assistants (Claude, GPT, Cursor, etc.).

What's New in v2.0.0

FeatureDescription
16 RolesAdded AUDITOR, TDD_GUIDE, UI_BROWSER_INSPECTOR
Two-Phase PLANNERUser approval gate between plan and task generation
Quality Gate (AUDITOR)15-dimension audit before implementation
TDD SupportOptional RED phase test creation before implementation
Documentation GateBlocking validation for missing docs (FP-069)
Cursor Rules6 enforcement templates for .cursor/rules/
Workflow DefinitionsExecutable workflow specs in core/workflows/
Modular RolesFolder-per-role structure with OUTPUT_RULES
20 New FPsFP-050 to FP-069 (Data Semantic + Process patterns)

📜 License

This project is licensed under the MIT License.

See the LICENSE file in the project root for full license text.

What This Means

ActionStatus
View source code✅ Permitted
Use in production✅ Permitted
Use commercially✅ Permitted
Use internally in organization✅ Permitted
Modify or fork✅ Permitted
Redistribute✅ Permitted (with attribution)

Attribution Required: Please credit God_FatherAI (https://x.com/God_FatherAI) when using this framework. | Train AI models | ❌ Prohibited |

For questions or support:

Author: God_FatherAI
Contact: https://x.com/God_FatherAI

See LICENSE for full license terms.


This Repo IS / IS NOT

✅ This repo IS❌ This repo IS NOT
A framework you install into your projectA library you import or run directly
A set of governance artifacts (rules, workflows, guards)A code generator or AI tool
A process contract for AI-assisted developmentA replacement for human architects or decision-makers
Installed once, then lives in your repoA service or SaaS you connect to

Key point: You clone this repo, run the bootstrap script, and governance artifacts are copied into YOUR project. You do not "run" this repo — you install from it.


Terminology

TermDefinition
FrameworkThis repository — the source of governance artifacts
Governance artifactsFiles installed into your project (.ai/, .cursorrules, AGENTS.md, etc.)
Workflow systemThe set of 16 roles + guards living in .ai/ after installation
ValidationFirst-pass code review by VALIDATOR (static analysis, FP checks)
InspectionUI/data anomaly detection by UI_INSPECTOR, DATA_SEMANTIC_VALIDATOR
VerificationConfirming fixes resolved issues (RE_VALIDATOR)
Quality GateAUDITOR verification between PLANNER and IMPLEMENTER (v2.0)
TDD CHECKMandatory test verification before implementation (v2.0)
@workflowA command issued in IDE/agent chat (Cursor), NOT a shell command

Purpose

This framework provides:

  • 16 specialized AI roles with strict boundaries (v2.0: +AUDITOR, +TDD_GUIDE, +UI_BROWSER_INSPECTOR)
  • Two-Phase PLANNER with user approval gate (v2.0)
  • Quality Gate (AUDITOR) with 15-dimension audit (v2.0)
  • TDD Support with RED phase test creation (v2.0)
  • Workflow contracts for validation, fixing, and documentation
  • Pre-execution guards preventing common failure modes
  • 109 failure patterns (v2.0: +20 new FP-050 to FP-069)
  • Error traceability from symptom to root cause
  • Documentation governance with blocking gate (v2.0)
  • Cursor rules enforcement layer (v2.0)
  • Task management with Task Magic system
  • Bootstrap tooling for new projects starting from zero

Core Principles

PrincipleRule
Code is TruthCode > Snapshot > Docs > Plans
No GuessingAgents verify with evidence, never assume
Scope LockEach role has strict, non-negotiable boundaries
Failure PatternsKnown failures (109 FPs) inform all decisions
DeterminismWorkflows are repeatable and auditable
Safe RemovalFramework can be removed cleanly without breaking your code

When NOT to Use This Framework

Do NOT adopt this framework if:

  • ❌ No process owner — no one will enforce changelog/validation discipline
  • ❌ No CI/CD or PR review — governance requires observable workflow
  • ❌ Hackathon / throwaway code — overhead exceeds value
  • ❌ Solo dev with no future team — simpler approaches suffice
  • ❌ Unwilling to follow role boundaries — framework will be bypassed, creating false confidence
  • ❌ No Cursor IDE — MDC workflow commands require Cursor (or compatible agent)
  • ❌ Expecting AI to make architectural decisions — framework enforces process, not judgment

If any of the above apply, consider a lighter approach or delay adoption until conditions change.


Scope Boundaries

This framework DOES:

  • ✅ Enforce a structured development process
  • ✅ Prevent common AI failure modes (109 documented patterns)
  • ✅ Require evidence-based claims (file paths, logs)
  • ✅ Block undocumented dangerous operations
  • ✅ Track compliance and decision history

This framework DOES NOT:

  • ❌ Generate code for you
  • ❌ Replace human architects or decision-makers
  • ❌ Make business or technical decisions
  • ❌ Guarantee bug-free code (it reduces risk, not eliminates it)
  • ❌ Work without human oversight and enforcement

Roles Overview

#RolePurposeModeNew in v2.0
1EMERGENCY_ERRORProduction incidentsOrchestrator—
2PLANNERFeature planning (Two-Phase)Read-OnlyEnhanced
3AUDITORQuality Gate (15 dimensions)Read-OnlyNEW
4TDD_GUIDERED phase test creationWrite (tests)NEW
5IMPLEMENTERCode execution (TDD CHECK)Write (scoped)Enhanced
6VALIDATORFirst-pass validationRead-OnlyEnhanced
7UI_INSPECTORVisual anomaliesRead-Only—
8DATA_SEMANTIC_VALIDATORData integrityRead-Only—
9UI_BROWSER_VALIDATORRuntime verification (v3.0)ExecutionEnhanced
10UI_BROWSER_INSPECTORE2E test generationRead+ExecuteNEW
11FIXATORIssue remediationWrite (scoped)—
12RE_VALIDATORFix verificationRead-Only—
13ARCHITECTADR creationRead-Only—
14CODE_DOCUMENTATORTechnical docsWrite (docs)—
15USER_DOCUMENTATORUser docsWrite (docs)—
16DOC_GUARDDoc governanceAdvisory—

v2.0 Execution Order

PLANNER (Phase 1) → [USER APPROVAL] → PLANNER (Phase 2)
              ↓
          [AUDITOR] ◄── Quality Gate (NEW)
              ↓
         [TDD_GUIDE] ◄── Optional RED phase (NEW)
              ↓
         IMPLEMENTER ◄── TDD CHECK mandatory
              ↓
          VALIDATOR ◄── Documentation Gate (NEW)
              ↓
     FIXATOR → RE_VALIDATOR (if BLOCK)

Installation

Happy Path (Recommended)

⚠️ Run all commands from your project root directory. Script paths can be absolute, but CWD must be your target project.

# 1. Clone the governance framework
git clone https://github.com/yourorg/ai-project-governance.git /tmp/governance

# 2. Navigate to YOUR project (target repo)
cd /path/to/your-project

# 3. Create configuration file
cat > governance.config.yaml << 'EOF'
project:
  name: "my-project"
  display_name: "My Project"
stack:
  language: "typescript"
EOF

# 4. Run bootstrap with config (auto-replaces placeholders)
/tmp/governance/bootstrap/scripts/init.sh --config=./governance.config.yaml

# 5. Validate installation (strict mode recommended)
/tmp/governance/bootstrap/scripts/validate.sh --strict

# 6. Commit governance artifacts
git add .ai/ .cursor/ .cursorrules AGENTS.md docs/ governance.config.yaml
git commit -m "chore: initialize AI project governance v1.0.0"

# 7. Clean up
rm -rf /tmp/governance

Advanced Path (Higher Drift Risk)

For manual installation or customized setups, see docs/guides/INSTALLATION.md.

⚠️ Manual placeholder replacement is error-prone. Prefer --config approach.

Common Mistakes

MistakeConsequencePrevention
Running init.sh from wrong directoryArtifacts installed in wrong repoAlways cd to target project first
Forgetting --configPlaceholders remain ({{PROJECT_NAME}})Use validate.sh --strict to catch
macOS vs Linux sed -iSyntax error or no replacementUse --config or see INSTALLATION.md
Missing .cursor/rules/.task-magic/@workflow commands not recognizedRe-run init or copy manually
Not committing governance artifactsTeam doesn't have rulesCommit immediately after validate
Using --force on existing projectYour custom rules are lost foreverUse --migrate instead (creates backup)
Skipping backup merge reviewCustom rules not preservedAlways check .governance-backup-*/

Migrating from Existing Configuration

If your project already has .cursorrules, AGENTS.md, or .cursor/rules/:

# RECOMMENDED: Backup existing files, then install
/tmp/governance/bootstrap/scripts/init.sh --migrate --config=./governance.config.yaml

# This will:
# 1. Create backup in .governance-backup-YYYYMMDD-HHMMSS/
# 2. Install governance framework
# 3. Show warnings about files that need manual merge

After migration, manually merge your custom rules:

FileHow to Merge
.cursorrulesAdd your custom [PROJECT-SPECIFIC RULES] section at the end of new file
AGENTS.mdAdd project-specific sections (Key Rules, Patterns) to new file
.cursor/rules/*.mdcKeep custom MDC files alongside new .task-magic/ files

⚠️ Never blindly replace — review the backup and merge intentionally.

Detailed Guides

GuideDescription
docs/guides/QUICK_START.md5-minute getting started
docs/guides/INSTALLATION.mdFull installation options
docs/guides/MIGRATION.mdMigrating from existing config
bootstrap/BOOTSTRAP_FLOW.md7-phase detailed flow

Installed Artifacts

After bootstrap, these files/folders are added to YOUR project:

ArtifactPurposeCommitted?
.ai/Workflow system, guards, plans, changelogs✅ Yes
.cursor/rules/.task-magic/MDC workflow files for Cursor✅ Yes
.cursorrulesSupreme rules (highest authority)✅ Yes
AGENTS.mdAI agent quick-reference✅ Yes
docs/AI_PLANNER_GUARDRAILS.md31 absolute prohibitions✅ Yes
docs-FINAL/Documentation navigation layer✅ Yes
governance.config.yamlProject configuration✅ Yes

Installation Mapping

How framework repo maps to your project:

Framework Repo→Your Project
core/workflow/*→.ai/_WORKFLOW/*
core/runtime/*→.ai/runtime/*
core/roles/*→.ai/roles/*
core/workflows/*→.ai/workflows/*
adapters/cursorrules/*.cursorrules→.cursorrules
adapters/cursor-rules/*.mdc→.cursor/rules/
adapters/agents/*.AGENTS.md→AGENTS.md
adapters/task-magic/*.mdc→.cursor/rules/.task-magic/
bootstrap/templates/docs/*→docs/
bootstrap/scripts/*→(not copied — used at install time)

Configuration

Create governance.config.yaml in your project root:

project:
  name: "my-project"
  display_name: "My Project"

stack:
  language: "typescript"
  framework: "express"
  database: "postgresql"
  cloud: "gcp"

governance:
  frozen_period_days: 14
  max_tasks_per_turn: 3

categories:
  features: [ADMIN, USER, API, INFRA]

See docs/guides/CONFIGURATION.md for all options.


Usage

Workflow Commands

⚠️ @workflow is an IDE/agent chat command (Cursor), NOT a shell command.
Type it in Cursor's AI chat, not in terminal.

# Plan a feature (Two-Phase)
@workflow PLANNER
# → Creates plan → Waits for approval → Generates tasks

# Audit tasks before implementation (NEW v2.0)
@workflow AUDITOR FEATURE_001

# Create failing tests (Optional, NEW v2.0)
@workflow TDD_GUIDE TASK_ID

# Implement from plan
@workflow IMPLEMENTER FEATURE_001

# Validate implementation
@workflow VALIDATOR
@workflow UI_INSPECTOR
@workflow DATA_SEMANTIC_VALIDATOR
@workflow UI_BROWSER_VALIDATOR

# Generate E2E tests (NEW v2.0)
@workflow UI_BROWSER_INSPECTOR FEATURE_001

# Fix issues
@workflow FIXATOR

# Verify fixes
@workflow RE_VALIDATOR

Production Incidents

@workflow EMERGENCY_ERROR https://app.example.com/error

Documentation

@workflow CODE_DOCUMENTATOR MODULE_NAME
@workflow USER_DOCUMENTATOR CREATE --route="/dashboard"
@workflow DOC_GUARD

Required Workflows by Change Type

Not every change requires full validation chain:

Change TypeRequired Workflows (v2.0)
New featurePLANNER → AUDITOR → [TDD_GUIDE] → IMPLEMENTER → VALIDATOR → [FIXATOR → RE_VALIDATOR]
UI changes+ UI_INSPECTOR, DATA_SEMANTIC_VALIDATOR, UI_BROWSER_VALIDATOR
Backend onlyAUDITOR → IMPLEMENTER → VALIDATOR
Bug fixVALIDATOR → FIXATOR → RE_VALIDATOR
Production incidentEMERGENCY_ERROR → (if BLOCK) FIXATOR → RE_VALIDATOR
DocumentationCODE_DOCUMENTATOR or USER_DOCUMENTATOR
New job / dangerous op+ DOC_GUARD (hard blocker if docs missing)
E2E test generationUI_BROWSER_INSPECTOR → UI_BROWSER_VALIDATOR

Directory Structure

After installation, your project will have:

your-project/
├── .ai/
│   ├── _WORKFLOW/          # Workflow system
│   ├── runtime/            # Runtime guards
│   ├── workflows/          # MDC workflow files
│   ├── roles/              # Role definitions
│   ├── prompts/            # Prompt templates
│   ├── plans/              # Feature plans
│   ├── tasks/              # Task files
│   ├── CHANGELOGS/         # State snapshots
│   ├── COMPLIANCE/         # Metrics
│   ├── DECISIONS/          # History indexes
│   └── _PLANS_VALIDATIONS/ # Validation reports
├── .cursor/
│   └── rules/              # Cursor-specific rules
├── docs-FINAL/             # Navigation layer
├── docs/
│   └── AI_PLANNER_GUARDRAILS.md
├── .cursorrules            # Supreme rules
├── AGENTS.md               # Agent definitions
└── governance.config.yaml  # Configuration

Governance Levels

The framework supports three levels of adoption:

Non-Negotiables (ALL Levels)

Even at Minimal level, these rules are mandatory:

  • ✅ Hierarchy of truth: Code > Snapshot > Docs > Plans
  • ✅ Role boundaries: Only IMPLEMENTER writes code; validators don't fix
  • ✅ No guessing: Claims require file path / log evidence
  • ✅ Changelog discipline: Commits require changelog entries

Level 1: Minimal

  • Core workflow roles (PLANNER, IMPLEMENTER, VALIDATOR)
  • Basic .cursorrules
  • Simple AGENTS.md

Best for: Small projects, proof-of-concepts

Level 2: Standard

  • All 16 roles
  • Full workflow system
  • Documentation governance
  • Task Magic system

Best for: Production applications, team projects

Level 3: Enterprise

  • Everything in Standard
  • Custom failure patterns
  • ADR enforcement
  • Compliance tracking
  • Job observer (SRE)

Best for: Large codebases, regulated industries


AI Agent Contract

Mandatory Reading Order (in target repo)

When an AI agent starts working on a governed project, it MUST read in this order:

  1. .cursorrules — Supreme law
  2. AGENTS.md — Role definitions and quick reference
  3. .ai/_WORKFLOW/04_EXECUTION_ORDER.md — Workflow sequence
  4. .ai/_WORKFLOW/09_ENFORCEMENT.md — Compliance rules
  5. .ai/runtime/workflow-guard.md — Pre-execution validation
  6. Latest .ai/CHANGELOGS/*.snapshot.md — Current system state

DO / DO NOT (AI Agents)

✅ DO❌ DO NOT
Respect .cursorrules as supreme lawEdit .ai/_WORKFLOW/ files (framework-managed)
Follow role boundaries strictlyAct outside your assigned role
Cite file paths as evidenceMake claims without evidence
Read latest changelog before workAssume system state from memory
Refuse work if prerequisites missingGuess when plan is ambiguous
Mark unknown information as UNKNOWNInvent missing data

Evidence-First Rule

All AI claims must be backed by:

  • File paths (e.g., server/routers.ts:42)
  • Log evidence (e.g., error message, stack trace)
  • Explicit source reference

Claims without evidence must be marked UNKNOWN or ASSUMPTION.


Why This Prevents AI Lying

The framework enforces truthfulness through multiple mechanisms:

MechanismHow It Works
Hierarchy of TruthCode > Snapshot > Docs > Plans — agents cannot claim something contradicting code
Workflow GuardsPre-execution checks block roles from running without prerequisites
Origin-Layer ClassificationEvery issue is traced to source (FEATURE_PLAN, IMPLEMENTATION, etc.)
DOC_GUARD Hard BlockersNew jobs / dangerous ops require documentation — no silent additions
Refusal ConditionsRoles MUST refuse if conditions not met (e.g., FIXATOR refuses FEATURE_PLAN errors)
Changelog EnforcementCommits without changelog = system state UNKNOWN = blocker

Safety Contract

If you skip required workflows or guards, the output is non-compliant and outside governance.
Treat it as unverified work that may contain errors, hallucinations, or undocumented changes.


Safe Removal

The framework is designed to be safely removable:

# Remove AI governance
rm -rf .ai/
rm -rf .cursor/rules/.task-magic/
rm .cursorrules
rm AGENTS.md
rm governance.config.yaml

# Optionally keep documentation
# rm -rf docs-FINAL/
# rm docs/AI_*.md

What remains:

  • Your actual code (untouched)
  • Documentation you chose to keep
  • Git history of governance-related commits

Upgrading

# Download new version
git clone https://github.com/yourorg/ai-project-governance.git /tmp/gov-new

# Run upgrade script (from your project root)
cd /path/to/your-project
/tmp/gov-new/bootstrap/scripts/upgrade.sh --from=v1.0.0 --to=v1.1.0

The upgrade will:

  1. Backup current governance
  2. Update core files (.ai/_WORKFLOW/, .ai/runtime/)
  3. Preserve customizations (.cursorrules, AGENTS.md, config)
  4. Validate upgrade

Framework Origin

This framework was extracted and generalized from a production system (HyperXAdvisor) with:

  • 80+ production incidents documented as failure patterns
  • 2000+ tasks executed through the workflow
  • 50+ feature plans validated
  • 8 months of real-world usage

The extraction preserved all learned patterns while removing project-specific details.


Key Files Reference

LocationPurpose
adapters/cursorrules/.cursorrules templates
adapters/cursor-rules/Cursor enforcement rules (6 MDC files)
adapters/agents/AGENTS.md templates
core/workflows/Executable workflow specifications
core/workflow/03_ROLES.mdAll 16 role definitions
core/workflow/09_ENFORCEMENT.mdCompliance rules
core/runtime/workflow-guard.mdPre-execution validation
bootstrap/templates/docs/AI_PLANNER_GUARDRAILS.md31 absolute prohibitions
docs/guides/User guides

Support


Acknowledgments

  • Built with insights from 80+ production incidents
  • Inspired by enterprise governance patterns
  • Designed for AI-assisted development workflows

Version History

VersionDateChanges
2.0.02026-01-31Added AUDITOR, TDD_GUIDE, UI_BROWSER_INSPECTOR; Two-Phase PLANNER; Documentation Gate; Cursor Rules; Modular Roles; FP-050 to FP-069
1.0.02026-01-01Initial release

Legal

Copyright (c) 2026 God_FatherAI.

This project is licensed under the MIT License. See LICENSE and NOTICE.md.

Free to use, modify, and distribute with attribution.


Questions or feedback?

Contact: https://x.com/God_FatherAI

Ver o original no GitHub

Bom para

Relacionados