intent-layer

Intent Layer Plugin

Claude Code plugin for creating and maintaining Intent Layer infrastructure.

Philosophy

Intent Layers solve a fundamental problem: AI agents reading raw code lack the tribal knowledge that experienced engineers have.

Senior engineers know:

• Where to start for common tasks
• What patterns are expected
• What invariants must never be violated
• What pitfalls to avoid

Intent Layers compress this knowledge into high-signal AGENTS.md/CLAUDE.md files that give agents the same intuition—without reading thousands of lines of code.

Core Principles

1. Compression > Verbosity - Target 100:1 compression. 200k tokens of code → 2k token node.
2. Contracts > Comments - Document invariants and constraints, not obvious code behavior.
3. Pitfalls > Patterns - What catches people matters more than standard patterns.
4. Progressive Disclosure - Start minimal, agents drill down when needed.

Installation

From GitHub (recommended)

# Add the marketplace
/plugin marketplace add orban/intent-layer

# Install the plugin
/plugin install intent-layer@orban

Or using the CLI:

claude plugin marketplace add orban/intent-layer
claude plugin install intent-layer@orban

From local directory

# Clone the repository
git clone https://github.com/orban/intent-layer.git

# Install from local path
claude plugin install ./intent-layer

Components

Skills

Interactive workflows invoked via slash commands:

Skill	Purpose	Command
intent-layer	Set up new Intent Layer infrastructure	/intent-layer
intent-layer-maintenance	Maintain existing Intent Layers	/intent-layer-maintenance
intent-layer-onboarding	Orient new developers using Intent Layer	/intent-layer-onboarding
intent-layer-query	Query Intent Layer for answers	/intent-layer-query
review-mistakes	Interactive review of pending mistake reports	/review-mistakes

Agents

Specialized subagents that Claude invokes automatically when appropriate:

Agent	Purpose
explorer	Analyze directories and propose AGENTS.md content
validator	Deep validation that nodes accurately reflect codebase
auditor	Find drift between nodes and current code state

Hooks

Automatic event handlers that keep the Intent Layer active during development:

Hook	Event	Purpose
post-edit-check	PostToolUse	Remind about Intent Layer coverage after Edit/Write/NotebookEdit
pre-edit-check	PreToolUse	Inject pitfalls before edits, warn about uncovered dirs
inject-learnings	SessionStart	Inject recent learnings, suggest setup if no Intent Layer
capture-tool-failure	PostToolUseFailure	Auto-create skeleton mistake reports on Edit/Write/NotebookEdit/file-modifying Bash failures
Stop prompt	Stop	LLM evaluates session for learnings to capture

Canonical hook-slot taxonomy lives in hooks/hooks.json for config and hooks/AGENTS.md for payload contracts. matcher values are tool names within a slot, not extra hook events.

Learning Loop

The plugin implements a continuous, mostly-automated learning loop:

Agent makes mistake → PostToolUseFailure auto-creates skeleton
                              ↓
                      Skeleton in .intent-layer/mistakes/pending/
                              ↓
                      Stop hook evaluates: enrich or discard?
                              ↓
                      Next session: Agent offers interactive review
                      or user runs /review-mistakes
                              ↓
                      User decides: Accept / Reject / Discard
                              ↓ (on accept)
                      Auto-integrated via lib/integrate_pitfall.sh
                      Pitfall added to covering AGENTS.md
                              ↓
                      Next session: SessionStart injects learnings
                              ↓
                      PreToolUse injects relevant pitfalls before edits

Interactive review: When pending reports exist, the agent offers to walk you through them conversationally. You can also explicitly run /review-mistakes to start a review session.

Supporting scripts:

Script	Purpose
lib/integrate_pitfall.sh	Auto-add pitfalls to covering AGENTS.md
scripts/capture_mistake.sh	Manual capture (if auto-capture missed something)
scripts/review_mistakes.sh	Terminal-based review (alternative to agent)

Usage

Initial Setup

# Check if Intent Layer exists
./scripts/detect_state.sh /path/to/project

# Analyze token distribution
./scripts/estimate_all_candidates.sh /path/to/project

# Create nodes using the skill
# Then in Claude Code: /intent-layer /path/to/project

Maintenance