GitHub - orban/intent-layer: Custom skills for Claude Code CLI

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

Compression > Verbosity - Target 100:1 compression. 200k tokens of code → 2k token node.
Contracts > Comments - Document invariants and constraints, not obvious code behavior.
Pitfalls > Patterns - What catches people matters more than standard patterns.
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 edits
`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 failures
Stop prompt	Stop	LLM evaluates session for learnings to capture

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

# Detect which nodes need review after changes
./scripts/detect_changes.sh main HEAD

# Generate pain point capture template
./scripts/capture_pain_points.sh pain_points.md

# Run maintenance workflow
# In Claude Code: /intent-layer-maintenance /path/to/project

Onboarding

# Generate orientation overview
./scripts/generate_orientation.sh /path/to/project

# Or use the skill interactively
# In Claude Code: /intent-layer-onboarding /path/to/project

Plugin Structure

intent-layer-plugin/
├── .claude-plugin/
│   └── plugin.json          # Plugin manifest
├── skills/                   # Slash-command skills
│   ├── intent-layer/
│   ├── intent-layer-maintenance/
│   ├── intent-layer-onboarding/
│   └── intent-layer-query/
├── agents/                   # Specialized subagents
│   ├── explorer.md
│   ├── validator.md
│   └── auditor.md
├── hooks/
│   └── hooks.json            # PostToolUse hook config
├── scripts/                  # Shared bash scripts
└── references/               # Templates and guides

Script Features

All scripts support:

-h / --help for usage information
set -euo pipefail for robust error handling
Cross-platform compatibility (macOS + Linux)
Detailed error messages with remediation hints
Consistent exclusion of generated directories (node_modules, dist, etc.)

When to Use

intent-layer

Good for:

New projects that will be touched by AI agents
Existing codebases where agents struggle to navigate
Monorepos with complex subsystem boundaries
Codebases with non-obvious contracts or invariants

Not good for:

Tiny scripts or single-file projects
Projects that change so rapidly the docs would be stale immediately
Codebases you won't use AI agents on

intent-layer-maintenance

Good for:

Quarterly reviews of existing Intent Layers
Post-incident updates (adding pitfalls, updating contracts)
Post-refactor updates (moving entry points, changing boundaries)
When agents consistently get confused about something

Not good for:

Initial setup (use intent-layer first)
Minor cosmetic changes that don't affect behavior

CI Integration

The plugin includes detect_staleness.sh for automated staleness checks in CI pipelines. The script exits with code 2 when stale nodes are found, making it easy to fail builds or create warnings.

GitHub Actions

# .github/workflows/intent-layer.yml
name: Intent Layer Check

on:
  pull_request:
  push:
    branches: [main]

jobs:
  staleness:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Needed for git history analysis

      - name: Check Intent Layer staleness
        run: |
          ./scripts/detect_staleness.sh --code-changes --threshold 30
        continue-on-error: true  # Warning only, or remove for hard fail

GitLab CI

# .gitlab-ci.yml
intent-layer:check:
  stage: test
  script:
    - ./scripts/detect_staleness.sh --code-changes
  allow_failure: true  # Warning only
  only:
    - merge_requests

Exit Codes

Code	Meaning
0	No stale nodes found
1	Error (invalid path, etc.)
2	Stale nodes found

Useful Options

--code-changes: Flag nodes where code changed more recently than the node
--threshold N: Days since node update to consider stale (default: 90)
--quiet: Output only paths (useful for scripting)

PR Review Integration

For PR-specific checks, use review_pr.sh which validates changes against Intent Layer contracts:

- name: Review PR against Intent Layer
  if: github.event_name == 'pull_request'
  run: |
    ./scripts/review_pr.sh origin/${{ github.base_ref }} HEAD