intent-guard-core
Advanced tools
Prevent AI coding assistants from breaking your architecture. Validates AI-generated code against layer boundaries, protected regions, and dependency rules.
Prevent AI from Breaking Your Architecture
Validate AI-generated code against architectural rules. Enforce layer boundaries, protect critical code, and catch violations before they reach your codebase.
📚 Read the Full Documentation | 🚀 Quick Start Guide
Works with Cursor, GitHub Copilot, Windsurf, and any AI coding assistant
Intent-Guard is an architectural validation tool for AI-assisted coding. It validates AI-generated code against rules you define, preventing violations before they reach your codebase.
The Problem: AI coding assistants (Cursor, GitHub Copilot, Windsurf) don't understand your project's architecture. They import database code into UI components, modify protected payment logic, and violate layer boundaries.
The Solution: Intent-Guard validates AI-generated code against architectural rules. If AI breaks your architecture, validation fails and the AI self-corrects.
Works with: Any JavaScript/TypeScript project (React, Next.js, Vue, Angular, Express, Nest.js, and more).
Intent-Guard is 100% framework-agnostic. It analyzes your source code structure (imports, exports, dependencies) - not framework-specific features.
React • Next.js • Vue.js • Nuxt.js • Angular • Svelte • SvelteKit • Solid.js • Remix • Astro • Qwik • Preact • Vanilla JS/TS
Express.js • Fastify • Nest.js • Koa • Hapi • Adonis.js • Serverless Functions • AWS Lambda • Node.js
Webpack • Vite • Rollup • esbuild • Turbopack • Parcel • SWC • Babel
Turborepo • Nx • Lerna • pnpm Workspaces • Yarn Workspaces • npm Workspaces
Intent-Guard validates source code structure, not runtime behavior:
✅ Checks: import/export statements, module dependencies, file organization
❌ Doesn't check: Component props, API responses, business logic
Example: Whether you use React hooks, Vue composables, or Express middleware - Intent-Guard ensures they import from the correct architectural layers.
Define architectural rules:
.intentguard/ folder).intentguard/ at monorepo root)AI coding assistants are powerful, but they don't understand your project's architecture:
❌ AI violates layer boundaries
Your AI assistant imports database.ts directly into your UI component, bypassing your service layer.
❌ AI duplicates logic across modules
The AI recreates authentication logic in 3 different places instead of using your existing AuthService.
❌ AI modifies protected code
The AI "helpfully" refactors your critical payment processing logic without understanding the implications.
❌ AI adds banned dependencies
The AI suggests moment.js when your team has standardized on date-fns.
Intent-Guard validates BEFORE the code reaches your codebase.
--diff mode for speed)rules-for command┌─────────────────┐
│ You Define │
│ Architecture │──┐
│ Rules (YAML) │ │
└─────────────────┘ │
│
┌─────────────────┐ │ ┌──────────────────┐
│ AI Generates │ │ │ Intent-Guard │
│ Code │──┼───▶│ Validates │
└─────────────────┘ │ └──────────────────┘
│ │
┌─────────────────┐ │ ▼
│ AI Reads │ │ ┌──────────────────┐
│ Rules (JITC) │◀─┘ │ ✅ Pass / ❌ Fail│
└─────────────────┘ └──────────────────┘
Flow:
.intentguard/intent.config.yaml# npm
npm install --save-dev intent-guard-core
# yarn
yarn add --dev intent-guard-core
# pnpm
pnpm add -D intent-guard-core
Requirements: Node.js >= 16.0.0
npx intent-guard init
This creates:
.intentguard/
├── intent.config.yaml # Your architectural rules
└── .gitignore # Excludes memory.json from git
💡 New to Intent-Guard or have a large codebase?
Skip the manual setup! Use our AI-Powered Configuration Generator to automatically create yourintent.config.yamlby analyzing your project structure. Just copy the prompt, paste it into your AI assistant, and get a production-ready config in minutes! 🚀
Edit .intentguard/intent.config.yaml:
version: "1.0.0"
architecture:
layers:
- name: domain
path: src/domain/**
canImportFrom: [] # Domain is isolated
- name: application
path: src/application/**
canImportFrom: [domain]
- name: infrastructure
path: src/infrastructure/**
canImportFrom: [domain, application]
# Validate entire codebase
npx intent-guard validate
# Validate only changed files (faster)
npx intent-guard validate --diff
✅ Success:
🔍 Intent-Guard Validation Report
✅ No violations found!
Analyzed 42 files
❌ Failure:
🔍 Intent-Guard Validation Report
src/domain/user.ts
❌ Layer "domain" cannot import from layer "infrastructure" [layer-boundary]
at src/domain/user.ts:3
💡 Allowed imports: (none)
Summary:
❌ 1 error(s)
📁 42 file(s) analyzed
For easier usage, add Intent-Guard to your package.json scripts:
{
"scripts": {
"validate": "intent-guard validate",
"validate:diff": "intent-guard validate --diff",
"validate:ci": "intent-guard validate --format json",
"precommit": "intent-guard validate --diff"
}
}
Now you can run:
npm run validate # Validate entire codebase
npm run validate:diff # Validate only changed files
npm run validate:ci # JSON output for CI/CD
Prevent violations from being committed:
# Install husky
npm install --save-dev husky
# Initialize husky
npx husky init
# Add pre-commit hook
echo "npm run validate:diff" > .husky/pre-commit
Now Intent-Guard runs automatically before every commit!
Use Intent-Guard if:
Don't use if:
| Tool | Purpose | What It Validates |
|---|---|---|
| ESLint | Code style | Syntax, formatting, best practices |
| TypeScript | Type safety | Types, interfaces, null safety |
| Intent-Guard | Architecture | Layer boundaries, protected code |
Best Practice: Use Intent-Guard together with ESLint and TypeScript. They solve different problems.
Creating the perfect intent.config.yaml can be time-consuming, especially if you're new to Intent-Guard or working with a large codebase. Use this AI prompt to automatically generate your configuration based on your project structure.
Run the init command to create the .intentguard directory:
npx intent-guard init
Copy the prompt below and paste it into your AI assistant (Cursor, GitHub Copilot, Claude, ChatGPT, etc.)
Let AI analyze your project and generate a tailored configuration
Review and adjust the generated config as needed
You are an expert software architect helping me set up Intent-Guard for my project.
CONTEXT:
Intent-Guard is an architectural validation tool that enforces boundaries in AI-assisted coding. It prevents AI from breaking architectural rules by validating code against a YAML configuration file.
YOUR TASK:
1. Analyze my project structure and codebase
2. Identify the architectural patterns and layers
3. Generate a comprehensive `.intentguard/intent.config.yaml` file
ANALYSIS STEPS:
Step 1: PROJECT DISCOVERY
- Scan the project directory structure
- Identify the framework/stack (React, Next.js, Express, Vue, Angular, etc.)
- Locate source code directories (src/, app/, packages/, etc.)
- Identify key architectural folders (components, services, utils, domain, infrastructure, etc.)
- Check package.json for dependencies and project type
Step 2: ARCHITECTURAL PATTERN RECOGNITION
Identify which architectural pattern(s) are used:
- Layered Architecture (UI → Services → Data)
- Clean Architecture (Domain-centric with dependency inversion)
- Feature-based (Modules organized by feature)
- Monorepo (Multiple packages with cross-dependencies)
- MVC/MVVM pattern
- Hexagonal Architecture
- Microservices structure
Step 3: LAYER IDENTIFICATION
For each identified layer/module:
- Name: Clear, descriptive layer name
- Path: Glob pattern matching files in this layer
- Dependencies: What other layers can this import from?
- Rationale: Why this boundary exists
Step 4: CRITICAL CODE PROTECTION
Identify files/directories that should be protected from AI modification:
- Authentication/authorization logic
- Payment processing
- Security configurations (API keys, secrets)
- Database migrations
- Core business logic
- Third-party integrations
- Configuration files
Step 5: DEPENDENCY ANALYSIS
Check for:
- Deprecated packages that should be banned (moment, request, etc.)
- Large packages with better alternatives (lodash → lodash-es)
- Packages that violate team standards
- Type packages in wrong dependency section
CONFIGURATION REQUIREMENTS:
1. LAYERS SECTION:
- Define clear, logical layers based on actual project structure
- Ensure dependency flow makes sense (no circular dependencies)
- Use descriptive names (not "layer1", "layer2")
- Include glob patterns that match actual file paths
- Add comments explaining each layer's purpose
2. PROTECTED REGIONS:
- Identify security-critical code
- Identify business-critical code
- Identify compliance-critical code
- Provide clear reasons for protection
- Set aiMutable: false for critical areas
3. BANNED DEPENDENCIES:
- List deprecated packages
- Suggest modern alternatives
- Explain why each is banned
- Consider bundle size, maintenance, security
4. DOCUMENTATION:
- Add YAML comments explaining the architecture
- Document the dependency flow
- Explain any non-obvious rules
- Include examples where helpful
OUTPUT FORMAT:
Generate a complete `.intentguard/intent.config.yaml` file with:
- Proper YAML syntax
- Comprehensive comments
- All sections filled based on analysis
- Ready to use without modification (but reviewable)
EXAMPLE STRUCTURE (adapt to my project):
version: "1.0.0"
# [Brief description of the architectural pattern used]
# Dependency Flow: [Layer A] → [Layer B] → [Layer C]
architecture:
layers:
# [Layer description]
- name: layer-name
path: src/path/**
canImportFrom: [other-layers]
# Comment: Why this layer exists and its boundaries
protectedRegions:
# [Protection category: Security/Business/Compliance]
- path: src/critical/**
reason: "Clear explanation of why this is protected"
aiMutable: false
bannedDependencies:
# [Category: Deprecated/Performance/Security]
- package: package-name
reason: "Why this is banned"
alternatives: [better-option-1, better-option-2]
IMPORTANT GUIDELINES:
✅ DO:
- Analyze actual project structure, don't assume
- Create realistic, enforceable boundaries
- Use glob patterns that match real paths
- Provide clear, actionable reasons
- Consider the project's specific needs
- Add helpful comments throughout
- Make it production-ready
❌ DON'T:
- Create overly restrictive rules that block legitimate code
- Use generic layer names without context
- Add rules that don't match the actual architecture
- Forget to explain WHY rules exist
- Create circular dependencies
- Over-complicate for simple projects
ADDITIONAL CONTEXT:
- Framework: [Auto-detect or ask me]
- Project Type: [Frontend/Backend/Fullstack/Monorepo]
- Team Size: [Infer from project complexity]
- Architectural Style: [Detect from structure]
START ANALYSIS NOW:
Please analyze my project and generate the complete intent.config.yaml file.
Before running the prompt:
package.json file in your project rootAfter AI generates the config:
npx intent-guard validate to see if there are existing violationsFor complex projects:
This advanced prompt instructs AI to:
🔍 Deep Project Analysis
🧠 Intelligent Layer Detection
🛡️ Security-First Approach
📦 Dependency Optimization
📝 Production-Ready Output
The generated config is a starting point, not the final version:
# 1. Generate config with AI prompt
# 2. Test it
npx intent-guard validate
# 3. See what violations exist
# 4. Decide: Fix code or adjust rules?
# 5. Iterate until you have the right balance
Remember: Intent-Guard enforces the architecture YOU define. The AI prompt helps you define it faster, but you're still in control.
GitHub Actions Example:
# .github/workflows/validate.yml
name: Validate Architecture
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: '18'
- run: npm ci
- run: npm run validate
GitLab CI Example:
# .gitlab-ci.yml
validate:
stage: test
script:
- npm ci
- npm run validate
Using lint-staged for faster validation:
// package.json
{
"lint-staged": {
"*.{ts,tsx,js,jsx}": [
"intent-guard validate --diff"
]
}
}
Add a task to .vscode/tasks.json:
{
"version": "2.0.0",
"tasks": [
{
"label": "Validate Architecture",
"type": "shell",
"command": "npx intent-guard validate --diff",
"problemMatcher": [],
"presentation": {
"reveal": "always",
"panel": "new"
}
}
]
}
Run with: Cmd/Ctrl + Shift + P → "Run Task" → "Validate Architecture"
The .intentguard/intent.config.yaml file is your architectural contract.
version: "1.0.0"
# Define your architectural layers
architecture:
layers:
- name: presentation # Layer name
path: src/ui/** # Files in this layer
canImportFrom: [domain] # What this layer can import
cannotImportFrom: [] # Explicit bans (optional)
# Protect critical files from AI modification
protectedRegions:
- path: src/config/secrets.ts
reason: "Contains API keys"
aiMutable: false # AI cannot modify this file
# Ban specific npm packages
bannedDependencies:
- package: moment
reason: "Use date-fns instead"
alternatives: [date-fns]
When you use the rules-for command, AI assistants can query Intent-Guard to understand what imports are allowed for a specific file:
npx intent-guard rules-for src/domain/user.ts
Output (JSON):
{
"file": "src/domain/user.ts",
"layer": "domain",
"canImportFrom": [],
"isProtected": false,
"bannedDependencies": [...]
}
AI reads this and self-corrects before generating code.
initPurpose: Initialize Intent-Guard in your project
npx intent-guard init
What it does:
.intentguard/ directoryintent.config.yaml.gitignore to exclude memory.jsonvalidatePurpose: Validate your codebase against architectural rules
# Validate entire codebase
npx intent-guard validate
# Validate only changed files (git diff)
npx intent-guard validate --diff
# Output as JSON
npx intent-guard validate --format json
# Reset architectural baseline
npx intent-guard validate --baseline
Options:
--diff: Only validate files changed since last commit (50-100x faster)--format <json|text>: Output format (default: text)--baseline: Reset the architectural memory baselineWhen to use:
rules-for <file>Purpose: Get architectural rules for a specific file (AI context)
npx intent-guard rules-for src/domain/user.ts
Output (JSON):
{
"file": "src/domain/user.ts",
"layer": "domain",
"canImportFrom": [],
"isProtected": false,
"bannedDependencies": []
}
When to use:
# 1. Ask Intent-Guard for context about the file
npx intent-guard rules-for <file-path>
# 2. Generate code that respects the architectural rules
# 3. Validate changes to ensure no rules were broken
npx intent-guard validate --diff
# 4. If validation fails, fix the violations
I need to add a new feature to src/application/auth-service.ts.
First, check the architectural rules:
npx intent-guard rules-for src/application/auth-service.ts
Then write the code following those rules.
After writing, validate:
npx intent-guard validate --diff
AI generates code → Intent-Guard validates → AI sees errors → AI fixes → Repeat until ✅
This creates a self-correcting AI that respects your architecture.
Problem: Intent-Guard can't find .intentguard/intent.config.yaml
Solution:
# Make sure you're in the project root
cd /path/to/your/project
# Initialize if not done
npx intent-guard init
# Verify file exists
ls .intentguard/intent.config.yaml
Problem: You're using --diff in a non-git project
Solution:
# Option 1: Initialize git
git init
# Option 2: Use full validation (slower)
npx intent-guard validate
Problem: Your code violates layer boundaries
Solution:
intent.config.yaml to see allowed importsrules-for to see what's allowed:
npx intent-guard rules-for src/your-file.ts
Problem: AI modified code inside // #protected-start ... // #protected-end
Solution:
# Revert the protected block changes
git checkout HEAD -- path/to/file.ts
# Or remove protection if intentional:
# Edit intent.config.yaml and set aiMutable: true
For large codebases (1000+ files):
Always use --diff mode during development:
npm run validate:diff # 50-100x faster
Use full validation only in CI:
{
"scripts": {
"validate": "intent-guard validate", // CI only
"validate:dev": "intent-guard validate --diff" // Development
}
}
Exclude generated files in .intentguard/intent.config.yaml:
# Add to your config (future feature)
exclude:
- "**/*.generated.ts"
- "**/dist/**"
- "**/node_modules/**"
For complex projects, use descriptive layer names:
architecture:
layers:
# Frontend layers
- name: ui-components
path: src/components/**
canImportFrom: [ui-hooks, shared-types]
- name: ui-hooks
path: src/hooks/**
canImportFrom: [api-client, shared-types]
# Backend layers
- name: api-routes
path: src/routes/**
canImportFrom: [business-logic, database]
- name: business-logic
path: src/services/**
canImportFrom: [database, shared-types]
- name: database
path: src/db/**
canImportFrom: [shared-types]
# Shared
- name: shared-types
path: src/types/**
canImportFrom: []
protectedRegions:
- path: src/config/**
reason: "Environment configuration - requires security review"
aiMutable: false
- path: src/payments/**
reason: "Payment processing - critical business logic"
aiMutable: false
- path: src/auth/**
reason: "Authentication - security sensitive"
aiMutable: false
bannedDependencies:
- package: moment
reason: "Deprecated and large bundle size"
alternatives: [date-fns, dayjs]
- package: request
reason: "Deprecated - no longer maintained"
alternatives: [axios, node-fetch, got]
- package: lodash
reason: "Use lodash-es for tree-shaking"
alternatives: [lodash-es]
- pattern: "^@types/.*"
reason: "Types should be in devDependencies"
alternatives: []
Protect specific code blocks from AI modification:
// src/config/api-keys.ts
export const PUBLIC_KEY = "pk_live_...";
// #protected-start
export const SECRET_KEY = "sk_live_...";
export const WEBHOOK_SECRET = "whsec_...";
// #protected-end
AI can modify the file, but cannot change the protected block.
Intent-Guard automatically tracks your architectural health:
# First run: Creates baseline
npx intent-guard validate
# ℹ Initialized new architectural memory
# ✅ No violations found!
# Later: New violations appear
npx intent-guard validate
# 🚨 ARCHITECTURAL DRIFT DETECTED
# Errors increased from 0 to 3
# Fix the new errors or run with --baseline to accept the new state
Ratchet System: If you fix violations, the baseline automatically improves.
Problem: AI imports database code directly into React components
Solution:
architecture:
layers:
- name: ui
path: src/components/**
canImportFrom: [hooks, utils] # No database access
Problem: Domain logic depends on infrastructure
Solution:
architecture:
layers:
- name: domain
path: src/domain/**
canImportFrom: [] # Pure business logic
- name: infrastructure
path: src/infrastructure/**
canImportFrom: [domain] # Depends on domain, not vice versa
Problem: AI refactors payment processing logic
Solution:
protectedRegions:
- path: src/payments/**
reason: "Payment logic requires security review"
aiMutable: false
Problem: AI suggests old dependencies
Solution:
bannedDependencies:
- package: request
reason: "Deprecated - use axios or fetch"
alternatives: [axios, node-fetch]
Don't try to define your entire architecture on day one:
# Week 1: Start with basic layers
architecture:
layers:
- name: frontend
path: src/frontend/**
canImportFrom: [shared]
- name: backend
path: src/backend/**
canImportFrom: [shared]
- name: shared
path: src/shared/**
canImportFrom: []
Then refine over time as you understand your architecture better.
❌ Bad:
- name: layer1
path: src/a/**
✅ Good:
- name: presentation-layer
path: src/ui/**
Add comments to your intent.config.yaml:
# Clean Architecture Pattern
# Flow: UI → Application → Domain ← Infrastructure
architecture:
layers:
- name: ui
path: src/ui/**
canImportFrom: [application, domain]
# UI can use application services and domain models
- name: application
path: src/application/**
canImportFrom: [domain]
# Application orchestrates domain logic
- name: domain
path: src/domain/**
canImportFrom: []
# Domain is isolated - pure business logic
- name: infrastructure
path: src/infrastructure/**
canImportFrom: [domain, application]
# Infrastructure implements interfaces defined in domain
Identify and protect your most critical files immediately:
protectedRegions:
# Security-critical
- path: src/auth/**
reason: "Authentication logic - security review required"
aiMutable: false
# Business-critical
- path: src/billing/**
reason: "Payment processing - financial impact"
aiMutable: false
# Compliance-critical
- path: src/gdpr/**
reason: "GDPR compliance logic - legal review required"
aiMutable: false
--diff Mode in DevelopmentAlways use --diff during active development:
{
"scripts": {
"dev:validate": "intent-guard validate --diff",
"ci:validate": "intent-guard validate"
}
}
Run dev:validate while coding, ci:validate in CI/CD.
Intent-Guard complements (doesn't replace) other tools:
{
"scripts": {
"lint": "eslint src",
"type-check": "tsc --noEmit",
"test": "jest",
"validate": "intent-guard validate --diff",
"check-all": "npm run lint && npm run type-check && npm run validate && npm run test"
}
}
Check your architectural health:
# View current baseline
cat .intentguard/memory.json
# If you've fixed violations, verify improvement
npm run validate
# ✨ Architectural baseline improved!
# Errors reduced from 5 to 2
# .intentguard/intent.config.yaml
version: "1.0.0"
architecture:
layers:
- name: pages
path: src/pages/**
canImportFrom: [components, hooks, lib, types]
- name: components
path: src/components/**
canImportFrom: [hooks, lib, types]
- name: hooks
path: src/hooks/**
canImportFrom: [lib, types]
- name: lib
path: src/lib/**
canImportFrom: [types]
- name: types
path: src/types/**
canImportFrom: []
protectedRegions:
- path: src/lib/auth/**
reason: "Authentication logic"
aiMutable: false
bannedDependencies:
- package: moment
reason: "Use date-fns for smaller bundle"
alternatives: [date-fns]
version: "1.0.0"
architecture:
layers:
- name: routes
path: src/routes/**
canImportFrom: [controllers, middleware, types]
- name: controllers
path: src/controllers/**
canImportFrom: [services, types]
- name: services
path: src/services/**
canImportFrom: [repositories, types]
- name: repositories
path: src/repositories/**
canImportFrom: [database, types]
- name: database
path: src/database/**
canImportFrom: [types]
- name: middleware
path: src/middleware/**
canImportFrom: [types]
- name: types
path: src/types/**
canImportFrom: []
protectedRegions:
- path: src/database/migrations/**
reason: "Database migrations - require review"
aiMutable: false
version: "1.0.0"
architecture:
layers:
# App layer
- name: app
path: packages/app/src/**
canImportFrom: [ui-kit, shared-utils, shared-types]
# UI Kit (design system)
- name: ui-kit
path: packages/ui-kit/src/**
canImportFrom: [shared-types]
# Shared utilities
- name: shared-utils
path: packages/shared/utils/**
canImportFrom: [shared-types]
# Shared types
- name: shared-types
path: packages/shared/types/**
canImportFrom: []
bannedDependencies:
- pattern: "^lodash$"
reason: "Use lodash-es for tree-shaking"
alternatives: [lodash-es]
Be aware:
--diff mode: Non-git projects must validate all filesWhat may change:
Intent-Guard is not for everyone. Skip it if:
Use Intent-Guard when:
Future ideas (no promises, no timelines):
Want to influence the roadmap? Share your ideas in Discussions
A: No. ESLint checks for syntax and style errors. Intent-Guard checks for architectural violations (e.g., "Domain layer importing Infrastructure"). Use both together.
A: Currently, Intent-Guard validates file structures and imports for JavaScript/TypeScript projects only. Support for other languages is planned.
A: Yes! You can define a global architecture in the root, or specific rules for each package.
A: No. Intent-Guard runs locally on your machine. Your code never leaves your computer.
We welcome feedback, questions, and contributions!
Report a bug with reproduction steps and your configuration.
Request a feature describing the problem you're trying to solve.
If Intent-Guard helps your team, consider sponsoring the project to support ongoing development and documentation.
Contributions are welcome! Here's how:
npm run lint and npm run formatSee CONTRIBUTING.md for detailed guidelines.
Proprietary License - See LICENSE file for details.
Summary: You may use this package in your applications, but you cannot redistribute, republish, or create derivative works. See the full license for complete terms.
Built with:
Made with ❤️ for developers building with AI
⭐ Star on GitHub | 📦 View on npm | 💬 Discussions | ☕ Buy Me A Coffee
FAQs
Prevent AI coding assistants from breaking your architecture. Validates AI-generated code against layer boundaries, protected regions, and dependency rules.
We found that intent-guard-core demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OpenAI rotated macOS signing certificates after a malicious Axios package reached its CI pipeline in a broader software supply chain attack.
Security News
Open source is under attack because of how much value it creates. It has been the foundation of every major software innovation for the last three decades. This is not the time to walk away from it.
Security News
Socket CEO Feross Aboukhadijeh breaks down how North Korea hijacked Axios and what it means for the future of software supply chain security.