Guardian

Protect your project architecture from AI agents and accidental restructuring.

Guardian is a VS Code extension that acts as a protective middleware between coding agents (GitHub Copilot, Cursor, Cline, Aider, etc.) and your file system. It enforces a user-defined architecture configuration so that AI agents cannot arbitrarily restructure, move, delete, or create files/folders in ways that violate the project's intended architecture.

Features

• Protected Paths — Prevent deletion, renaming, or moving files out of critical directories
• Locked Files — Lock specific files or glob patterns against deletion/renaming
• Folder Structure Enforcement — Block forbidden folder names, prevent new top-level directories
• Naming Conventions — Enforce PascalCase, camelCase, kebab-case, or custom patterns
• Boundary Rules — Prevent architectural boundary violations in imports (e.g., Core cannot import from Infrastructure)
• Multiple Enforcement Modes — Block, Warn, Ask, or Log violations
• Structure Snapshots — Capture and compare directory structure baselines
• Configuration Wizard — Interactive webview for generating .guardian.json

Getting Started

1. Install the extension
2. Open a project in VS Code
3. Run Guardian: Initialize Configuration from the Command Palette (Cmd+Shift+P)
4. Edit the generated .guardian.json to customize your rules
5. The guardian activates automatically and watches for violations

Configuration (.guardian.json)

Place a .guardian.json file in your project root:

{
  "version": "1.0",
  "projectName": "MyApp",
  "rules": {
    "protectedPaths": [
      {
        "path": "src/core",
        "rules": {
          "noDelete": true,
          "noRename": true,
          "noMoveOut": true,
          "allowedFileTypes": [".ts", ".py"],
          "maxDepth": 3
        }
      }
    ],
    "lockedFiles": ["src/core/interfaces/*.ts", "docker-compose.yml"],
    "folderStructure": {
      "enforceExisting": true,
      "allowNewTopLevel": false,
      "forbiddenFolderNames": ["temp", "tmp", "scratch", "old", "backup"]
    },
    "namingConventions": {
      "files": {
        "src/core/**": "PascalCase",
        "src/api/**": "camelCase"
      },
      "folders": "kebab-case"
    },
    "boundaryRules": [
      {
        "description": "Core must not import from Infrastructure",
        "from": "src/core/**",
        "cannotImport": ["src/infrastructure/**"]
      }
    ]
  },
  "enforcement": "warn",
  "notifications": true
}

Enforcement Modes

Commands

How It Works

Guardian uses VS Code's workspace file system events (onDidCreateFiles, onDidDeleteFiles, onDidRenameFiles) to intercept changes in real-time. When a file operation matches a rule violation, the configured enforcement action is taken.

For boundary rules, the extension also watches for file saves and analyzes import statements to detect cross-boundary dependencies.

Compatibility

Works in VS Code, VS Code Insiders, and Cursor.

License

MIT