Gavel

AI architecture governance for repositories.

Stop AI context drift. Standardize how AI reasons about your codebase.

The Problem

When teams use AI-assisted development - creating tasks in Linear, pulling them via MCP, having Claude implement them - a hidden inconsistency emerges:

Same task. Same repo. Different AI context. Different outcomes.

Each developer's AI instance carries different memory, saved references, and architectural preferences. One developer may have stored references to software architecture books and engineering patterns. Another may have none. The AI becomes an untracked dependency.

The Solution

gavel turns AI context into versioned infrastructure. A single agent.config.json file in your repository defines:

• Architecture principles and layer boundaries
• Coding standards and forbidden patterns
• Domain knowledge and business rules
• Task execution expectations
• Testing requirements

This config is automatically injected into AI workflows via MCP, so every developer's AI operates from the same playbook.

Think of it as .editorconfig for AI - just like teams standardized formatting with Prettier and linting with ESLint, teams now need to standardize AI context.

Quick Start

Install

npm install -g gavelai

Initialize

cd your-repo
gavel init

This scaffolds an agent.config.json with auto-detected project info from package.json or composer.json.

Validate

gavel validate

Connect to Claude

Add to your MCP client config (Claude Desktop, Claude Code, Cursor, etc.):

{
  "mcpServers": {
    "gavel": {
      "command": "npx",
      "args": ["-y", "gavelai"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "gavel": {
      "command": "node",
      "args": ["/path/to/gavel/build/mcp/server.js"]
    }
  }
}

agent.config.json

The config file has 9 sections. All are required except domain and examples.

{
  "project": {
    "name": "my-app",
    "description": "SaaS platform for invoice management",
    "stack": { "backend": "Laravel 11", "frontend": "React 18", "database": "MySQL 8" }
  },

  "ai": {
    "principles": ["Favor composition over inheritance", "..."],
    "anti_patterns": ["God classes", "Business logic in controllers"],
    "forbidden_actions": ["Never commit secrets", "Never use raw SQL"]
  },

  "architecture": {
    "pattern": "layered",
    "layers": [
      {
        "name": "Controllers",
        "path": "app/Http/Controllers",
        "responsibility": "HTTP handling, delegation to services",
        "rules": ["No business logic", "Always use Form Requests"]
      },
      {
        "name": "Services",
        "path": "app/Services",
        "responsibility": "Business logic orchestration",
        "rules": ["No HTTP concerns", "Use repositories for data access"]
      }
    ],
    "dependency_rules": ["Controllers -> Services -> Repositories -> Models"]
  },

  "coding_standards": {
    "languages": {
      "typescript": { "strict_mode": true, "preferences": ["Use const over let"] },
      "php": { "style_guide": "PSR-12", "preferences": ["Use constructor promotion"] }
    }
  },

  "task_execution": {
    "required_steps": [
      "Understand the task and acceptance criteria",
      "Check for existing patterns in the codebase",
      "Plan before coding",
      "Write tests"
    ]
  },

  "testing": {
    "framework": { "backend": "Pest PHP", "frontend": "Vitest" },
    "requirements": { "services": "Unit tests required", "endpoints": "Integration tests required" }
  },

  "domain": {
    "glossary": { "Invoice": "A billing document with line items and a total" },
    "business_rules": ["All monetary values stored in cents"]
  },

  "paths": {
    "source": { "backend": "app/", "frontend": "resources/js/" },
    "ignore": ["vendor/", "node_modules/", "dist/"]
  },

  "examples": {
    "good_controller": {
      "description": "Thin controller that delegates to a service",
      "code": "class ProjectController { ... }"
    }
  }
}

See examples/ for complete configs for Laravel + React, Next.js + Prisma, and Express + MongoDB.

Config Inheritance

For monorepos or org-wide standards, configs can extend a base:

{
  "extends": "../base-config/agent.config.json",
  "project": { "name": "child-app", "..." : "..." }
}

Child configs deep-merge with the parent. Objects are merged recursively, arrays are concatenated and deduplicated, and child primitives override parent values.

CLI

gavel <command> [options]

| Command | Description | |---------------------------------------------|----------------------------------------------------------------------------------------------------| | init [path] | Scaffold agent.config.json with auto-detected project info | | validate [path] | Validate the config and print a summary. Exit code 1 on failure. | | validate-diff --base main | Validate a git diff against config rules (forbidden patterns, secrets, layer violations) | | scan [path] | Report discovered files grouped by extension, architecture layer, and source path | | context --title "..." --description "..." | Build a full task context and output as a prompt or JSON | | migrate [path] | Convert existing CLAUDE.md / .cursorrules / copilot-instructions.md into agent.config.json | | generate [path] --target claude-md | Generate CLAUDE.md or .cursorrules from agent.config.json |

Examples

# Initialize a new config
gavel init

# Validate and see improvement suggestions
gavel validate

# Check your branch's changes against the config
gavel validate-diff --base main

# See what the AI would get for a task
gavel context --title "Add user search" --description "Search users by name and email" --modules services

# Migrate from an existing CLAUDE.md
gavel migrate --dry-run

# Generate CLAUDE.md from the config (bridge to existing Claude workflows)
gavel generate --target claude-md

MCP Tools

When connected as an MCP server, gavel exposes 5 tools:

| Tool | Description | |--------------------------------|-------------------------------------------------------------------------------------------------------------------------| | get_repo_ai_config | Returns the full config and a human-readable rules summary | | build_task_context | Assembles config + task details + similar patterns + domain context + architecture rules into an injection-ready prompt | | find_similar_patterns | Searches the repo for files similar to a query using TF-IDF ranking | | validate_change_plan | Validates a proposed plan against architecture layers, ignore paths, and scope limits | | validate_diff_against_config | Checks a unified diff for forbidden patterns, hardcoded secrets, and dependency violations |

Workflow

The intended workflow with Linear + MCP:

1. PM creates task in Linear with full context
2. Developer pulls the task via Linear MCP
3. Claude calls build_task_context → gets architecture rules, similar code, domain knowledge
4. Claude calls validate_change_plan → catches violations before writing code
5. Claude implements the task with consistent, architecture-aligned output
6. Claude calls validate_diff_against_config → checks the result

CI/CD Integration

Add config validation to your pipeline:

# GitHub Actions
- name: Validate AI Config
  run: npx gavelai validate

- name: Validate Changes Against AI Config
  run: npx gavelai validate-diff --base ${{ github.event.pull_request.base.sha }}

Both commands return exit code 1 on errors, making them suitable for CI gates.

Migrating from CLAUDE.md

If your team already uses a CLAUDE.md, .cursorrules, or .github/copilot-instructions.md, the migrate command converts them:

# Preview what would be generated
gavel migrate --dry-run

# Create agent.config.json from existing files
gavel migrate

The migration tool parses your markdown and categorizes content into principles, anti-patterns, forbidden actions, coding preferences, testing rules, and domain knowledge. Review and refine the output after migration.

To go the other direction (generate CLAUDE.md from your config):

gavel generate --target claude-md

This is useful for teams transitioning incrementally - maintain agent.config.json as the source of truth and auto-generate CLAUDE.md for developers who haven't adopted the MCP workflow yet.

Current Status & Roadmap

This project is under active development. The core pipeline works end-to-end, but there are known limitations and clear areas for improvement. Contributions are welcome.

What works well

• Config schema and validation. The 9-section agent.config.json schema is comprehensive, Zod-validated, and catches misconfiguration early. Config inheritance enables monorepo and org-wide standards.
• Context assembly. Given a task description, the system correctly identifies relevant files, surfaces matching domain glossary terms and business rules, pulls architecture constraints for affected layers, and formats everything into a structured, injection-ready prompt.
• Pattern matching. TF-IDF ranking reliably surfaces the right files - an "invoice payment" task scores invoice-service.ts at 0.85 and ranks it first, with the widget service correctly ranked lower.
• Validation. Plan validation catches real issues (files in ignored directories, oversized changesets). Diff validation detects hardcoded secrets, forbidden type patterns (any), and dependency direction violations.
• CLI tooling. All commands work - init with auto-detection, validate with suggestions, scan with layer mapping, context building, migration, and generation.
• Bidirectional migration. Teams can migrate from CLAUDE.md / .cursorrules into agent.config.json, and generate them back out for developers who haven't adopted MCP yet.

Known limitations

• Pattern matching is lexical, not semantic. TF-IDF scores based on word overlap. It won't catch semantic similarity - "payment processing" won't match a file called billing-handler.ts unless they share tokens. An embedding-based approach would improve recall significantly.
• Diff validation is pattern-based, not AST-aware. It catches surface-level violations (:any types, hardcoded strings matching secret patterns) but cannot enforce structural rules like "no business logic in controllers." That would require parsing the AST and understanding what constitutes "business logic."
• Domain context matching has false positives. Keyword overlap between task descriptions and business rules can surface irrelevant rules. A task mentioning "users" might pull in a business rule about "users" that isn't actually related.
• No end-to-end MCP integration test. The server builds and the tools execute correctly in isolation, but there is no automated test that verifies a full stdio JSON-RPC round-trip with a real MCP client.
• The migrate command uses heuristics. Categorizing free-form markdown into structured config sections is inherently imprecise. The output should always be reviewed and refined by the team.

Roadmap

Contributions in any of these areas are especially welcome:

| Priority | Area | Description | |------------|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------| | High | Embedding-based pattern search | Replace or augment TF-IDF with local embeddings (e.g., transformers.js or an embedding API) for semantic code search | | High | AST-aware validation | Parse TypeScript/PHP ASTs to enforce structural rules (layer boundary imports, business logic placement) | | High | MCP integration tests | Automated tests that spin up the server and verify tool calls over stdio transport | | Medium | JSON Schema for IDE support | Generate a JSON Schema from the Zod definitions so editors provide autocomplete and inline validation for agent.config.json | | Medium | Smarter domain matching | Use TF-IDF or embeddings to match domain context to tasks instead of naive keyword overlap | | Medium | Config linter | Deeper static analysis of the config itself - detect contradictory rules, missing layer coverage, overly broad forbidden patterns | | Low | VS Code extension | Display config status, validate on save, show active architecture rules inline | | Low | Web dashboard | Visual editor for agent.config.json with team collaboration features | | Low | Multi-model testing | Verify the config and tools work with GPT-4, Gemini, and other models |

Project Structure

src/
├── schema/              # Zod schemas and TypeScript types
├── config/              # Config loading, validation, inheritance
├── scanner/             # Repo file scanning and TF-IDF pattern matching
├── context/             # Task context assembly, rules summarization, prompt formatting
├── mcp/                 # MCP server and tool registrations
│   └── tools/           # Individual MCP tool implementations
└── cli/                 # CLI commands
    └── commands/

Development

# Install dependencies
npm install

# Type-check
npm run lint

# Run tests
npm test

# Build
npm run build

# Watch mode
npm run dev

Contributing

Contributions are welcome. This project is early-stage and there are meaningful problems to solve at every level - from improving pattern matching accuracy to building editor integrations.

Before contributing:

1. Check the roadmap for high-priority areas
2. Open an issue to discuss your approach before starting large changes
3. Run npm test and npm run lint before submitting a PR

Getting started:

git clone <repo-url>
cd gavel
npm install
npm test          # 108 tests should pass
npm run lint      # Should show no type errors
npm run build     # Compiles to build/

The codebase is intentionally simple - TypeScript with Zod, no heavy frameworks. The architecture follows the same layered principles the tool itself enforces: schemas, config loading, scanning, context assembly, MCP tools, and CLI commands are cleanly separated.

License

MIT