Tiered Governance System

AI Development with Multi-Level Guardrails

Grabby introduces a revolutionary tiered governance system where rules cascade from organization-wide policies down to individual features. System contracts, project rulesets, and feature-level constraints work together to keep AI-assisted development safe, predictable, and auditable.

Explore the Tiered System See Developer Workflow Full Documentation

Tiered System Agent Architecture Governance Rulesets Complexity Tiers Workflow Integration Live Metrics

Core Innovation

The Three-Tier Governance Architecture

Grabby's most powerful feature is its cascading rule system. Rules flow from top to bottom, with each tier able to add constraints but never remove protections from above.

Tier 1 System-Level Contracts

Scope: Apply to ALL projects across your organization. Stored in ~/.grabby/contracts/ on the developer's machine. These define non-negotiable standards that every project must follow.

Security Standards (SYS-001) Code Quality Rules (SYS-002) Dependency Policies Audit Requirements

Tier 2 Project-Level Rulesets

Scope: Apply to a specific repository. Stored in docs/RULESET_*.md files. These extend system rules with project-specific patterns, technology choices, and team conventions.

RULESET_CORE RULESET_DB_SAFETY RULESET_API_COMPAT RULESET_FE_DEPS RULESET_GIT_WORKFLOW

Tier 3 Feature-Level Contracts

Scope: Apply to a single feature or change. Stored in contracts/*.fc.md. These define the specific objective, allowed files, dependencies, and completion criteria for one unit of work.

FC-001.fc.md BUG-202.fc.md GRAB-GIT-101.fc.md

How Rules Cascade

When AI generates code for a feature, Grabby merges all three tiers into a single enforcement context. System rules provide the floor (minimum security, quality). Project rulesets add technology-specific constraints. Feature contracts scope the exact files and changes allowed. The AI can only operate within the intersection of all three.

Visual Guide

Rule Cascade Flow

Rules flow downward, constraints accumulate. Each layer adds protection without removing what's above.

Intelligent Orchestration

Seven-Agent Pipeline Architecture

Grabby doesn't just have one AI persona. It orchestrates seven specialized agents, each owning a specific stage of the development lifecycle. Work flows through explicit handoffs with governance gates between stages.

🔍

Analyst

Structures raw requests into clear intake artifacts

📐

Architect

Turns requests into bounded feature contracts

✓

Validator

Reviews contracts critically before work starts

🗺️

Planner

Converts contracts into execution plans

💻

Developer

Executes the approved plan inside scope

🧪

Test Engineer

Owns verification and test coverage

📋

Auditor

Verifies completion against contract

Automatic Stage-Aware Routing

Grabby routes work to the correct agent based on artifact state, not just keywords. A draft contract goes to the Validator. An approved plan goes to the Developer. Completed work goes to the Auditor. You can override routing, but you can't skip governance gates.

Domain-Specific Governance

Five Specialized Rulesets

Each ruleset governs a specific domain. They're versioned, auditable, and automatically enforced during validation and execution.

📋 RULESET_CORE

TypeScript strict mode required
80%+ test coverage
No console.log in production
Functions under 50 lines
Forbidden: eval(), @ts-ignore

🗄️ RULESET_DB_SAFETY

Schema changes require contract
Data Impact checklist required
Rollback plan for destructive ops
CI blocks without DB artifacts
No live DB in automated runs

🔌 RULESET_API_COMPAT

Breaking changes need approval
Prefer additive changes
Explicit deprecation before removal
Version markers in OpenAPI/GraphQL
Migration guidance for FE callers

📦 RULESET_FE_DEPS

npm audit must pass
No high/critical vulnerabilities
Lockfile changes require review
Bundle size impact tracked
License compatibility checked

🔀 RULESET_GIT_WORKFLOW

Never force-push by default
Branch names include contract ID
No auto-resolve conflicts
Preflight checks before push
MR/PR tied to artifacts

Risk Assessment

Automatic Complexity Scoring

Every contract is automatically scored for complexity on a 1-10 scale. High-complexity work gets additional scrutiny and may require breakdown before execution.

Trivial
1-2

Simple
3-4

Moderate
5-6

Complex
7-8

Very Complex
9-10

Scoring Factors

Factor	Weight	Example
Scope breadth	Max 3 pts	Number of scope items
File changes	Max 2 pts	Creates + modifications
Dependencies	Max 1.5 pts	New packages added
Security surface	Max 2 pts	Auth, payments, data
Integration depth	Max 1.5 pts	APIs, external services

Verification Tiers

Risk-Based Verification Depth

When riskTieredVerification is enabled, Grabby adjusts verification depth based on detected risk level.

Basic Verification

For low-risk, trivial changes. Unit tests pass, lint clean, basic audit checklist.

Standard Verification

Default tier. Full test coverage check, integration tests, security checklist review.

High-Risk Verification

For auth, payments, data changes. Extended security review, rollback validation, stakeholder sign-off.

Auto-Detected Risk Patterns

auth/login/password payment/billing database/migration delete/drop breaking change

Practical Integration

How Grabby Fits Into Your Daily Workflow

Grabby integrates at every stage of development. Here's how a feature flows from idea to production.

Intake

Describe what you need in plain language. Grabby interviews you and creates a structured contract.

Plan

Review the generated plan. See exactly which files will change before any code is written.

Approve

Human checkpoint. You approve the plan, then AI can execute. Scope is locked.

Execute

AI writes code within the approved boundaries. Guard rails prevent scope creep.

Ship

Audit confirms completion. Tests pass. PR template generated. Feature is archived.

Command Flow

CLI Commands by Stage

# Stage 1: Intake (choose one) grabby ticket "add user avatars" # Draft a ticket grabby task "add user avatars" # Interview + contract grabby orchestrate "add user avatars" # Full automation # Stage 2: Validate & Plan grabby validate FC-123.fc.md grabby plan FC-123.fc.md grabby backlog FC-123.fc.md # Stage 3: Approve (human gate) grabby approve FC-123.fc.md # Stage 4: Execute grabby execute FC-123.fc.md grabby guard FC-123.fc.md # Pre-commit check # Stage 5: Complete grabby audit FC-123.fc.md grabby feature:close FC-123

Artifacts Generated

What Grabby Creates

Artifact	Purpose
`FC-123.fc.md`	Feature contract (scope, files, criteria)
`FC-123.brief.md`	Developer-facing summary
`FC-123.plan.yaml`	Execution plan with file sequence
`FC-123.backlog.yaml`	Agile breakdown (epic/task/subtask)
`FC-123.prompt.md`	LLM instruction bundle
`FC-123.audit.md`	Completion verification
`FC-123.session.json`	Machine-readable session data

Traceability Guarantee

Every artifact is linked by ID. From a PR, you can trace back to the contract, plan, and original request. From a feature, you can see all changes made. Complete audit trail.

Complete Workflow Diagram

End-to-End Feature Lifecycle

Live Project Data

Verified Statistics from This Repository

All metrics below come from actual project data and can be verified using the commands shown.

Industry Benchmarks

How This Project Compares

Metrics compared against DORA, State of DevOps, and McKinsey Digital research.

Metric

Poor

Avg

Here

Feature completion

<60%

75%

100%

Test-linked changes

<40%

55%

70.9%

Avg scope size

>15

8-15

4.1

Delivery Velocity

14-Day Completion Trend

Verification Commands

Confirm Every Statistic

All data on this page is verifiable. Run these commands to see the source.

# Feature tracking data cat .grabby/features.index.json # Count total features grabby features:list # Active contracts grabby list # Complexity analysis grabby validate contracts/FC-123.fc.md

# Git release tags git tag --sort=-version:refname # Ruleset versions cat docs/RULESET_CORE.md | head -1 # System contracts ls ~/.grabby/contracts/ # Version info grabby --version

Data snapshot: -

Common Questions

Understanding the Tiered System

Can project rules override system-level security requirements?

No. Rules cascade downward and accumulate. A project can add stricter requirements (e.g., "95% test coverage" instead of the system default of 80%), but it cannot remove or weaken security protections defined at the system level. This is by design.

What happens if a feature contract violates project rulesets?

The Validator agent catches the violation during grabby validate. The contract cannot proceed to planning or execution until the violation is resolved. Common violations include touching restricted directories or missing required sections.

How do I add organization-wide rules?

System-level contracts are stored in ~/.grabby/contracts/ on each developer's machine. You can create defaults with grabby system:create or manually add .fc.md files. Use your configuration management tools to distribute system contracts across your organization.

Can different projects have different rulesets?

Yes. Each project has its own docs/RULESET_*.md files. A frontend project might have strict FE dependency rules while a backend service focuses on API compatibility. The system-level contracts provide a common baseline; projects customize from there.

What if I need to bypass a rule for a legitimate reason?

Grabby supports explicit overrides documented in the feature contract. Add an "Override Rationale" section explaining why the bypass is necessary. This creates an audit trail. However, some system-level security rules may be marked as non-overridable by your organization.