intent-layer

What this skill does

# Intent Layer

> **TL;DR**: Create CLAUDE.md/AGENTS.md files that help AI agents navigate your codebase like senior engineers. Run `detect_state.sh` first to see what's needed.

Hierarchical AGENTS.md infrastructure so agents navigate codebases like senior engineers.

---

## Sub-Skills

This skill includes specialized sub-skills that are **automatically invoked** when appropriate:

| Sub-Skill | Location | Auto-Invoke When |
|-----------|----------|------------------|
| `git-history` | `git-history/SKILL.md` | Creating nodes for existing code (extracts pitfalls from commits) |
| `pr-review-mining` | `pr-review-mining/SKILL.md` | Creating nodes for existing code (extracts pitfalls from PR discussions) |
| `pr-review` | `pr-review/SKILL.md` | Reviewing PRs that touch Intent Layer nodes |

### git-history (Auto-Invoked During Setup)

When creating nodes for directories with git history, **automatically run git-history analysis** to pre-populate:
- **Pitfalls** from bug fix commits
- **Anti-patterns** from revert commits
- **Architecture Decisions** from refactor commits
- **Contracts** from breaking change commits

```
Trigger: Creating AGENTS.md for directory with >50 commits
Action: Run git-history analysis before writing node
```

### pr-review-mining (Auto-Invoked During Setup)

When creating nodes for directories with merged PRs, **automatically run PR mining** to pre-populate:
- **Pitfalls** from PR Risks sections and review warnings
- **Contracts** from Breaking Changes sections
- **Architecture Decisions** from Why sections and Alternatives Considered
- **Anti-patterns** from rejected approaches in reviews

```
Trigger: Creating AGENTS.md for directory with merged PRs
Action: Run pr-review-mining alongside git-history, merge findings
```

### pr-review (Auto-Invoked for PRs)

When reviewing PRs that modify code covered by Intent Layer:
- Verify contracts are respected
- Check pitfalls are avoided
- Flag potential Intent Layer updates needed

```
Trigger: PR touches files under an AGENTS.md
Action: Run pr-review with --ai-generated if applicable
```

### learning-loop (Auto-Invoked on Error Discovery)

When you discover a non-obvious gotcha during any work (not just Intent Layer setup):
- Find the nearest AGENTS.md to where the issue occurred
- Append to its Pitfalls section
- Keep the Intent Layer alive with real lessons

```
Trigger: Fix error caused by non-obvious behavior (API format, config quirk, etc.)
Action: Append pitfall to nearest AGENTS.md
Format:
  ### Short descriptive title
  **Problem**: What assumption failed
  **Symptom**: Error message or unexpected behavior
  **Solution**: Correct approach with code reference
```

**Example**: After fixing `'list' object has no attribute 'get'` because Claude CLI output format varies:
```markdown
### Claude CLI JSON output format varies

**Problem**: `claude --output-format json` can return dict or list
**Symptom**: `'list' object has no attribute 'get'`
**Solution**: Check `isinstance(data, list)` before `.get()`. See `lib/claude_runner.py:parse_claude_output()`
```

---

## Quick Start

### Step 0: Check State

```bash
scripts/detect_state.sh /path/to/project
```

| State | Action |
|-------|--------|
| `none` | Create root file (continue below) |
| `partial` | Add Intent Layer section to existing root |
| `complete` | Use `intent-layer-maintenance` skill instead |

### Step 1: Measure

```bash
# Auto-discover all candidate directories
scripts/estimate_all_candidates.sh /path/to/project

# Or analyze structure first
scripts/analyze_structure.sh /path/to/project
```

### Step 2: Create Root Node

Choose CLAUDE.md (Anthropic) or AGENTS.md (cross-tool). Pick template by size:
- **Small** (<50k tokens): `references/templates.md` → Small Project
- **Medium** (50-150k): `references/templates.md` → Medium Project
- **Large** (>150k/monorepo): `references/templates.md` → Large Project

### Step 3: Create Child Nodes (if needed)

| Signal | Action |
|--------|--------|
| Directory >20k tokens | Create `AGENTS.md` |
| Responsibility shift | Create `AGENTS.md` |
| Cross-cutting concern | Document at nearest common ancestor |

Use child template from `references/templates.md`.

### Step 4: Validate

```bash
scripts/validate_node.sh CLAUDE.md
scripts/validate_node.sh path/to/AGENTS.md
```

Checks: token count <4k, required sections, no absolute paths, no TODOs.

### Step 5: Cross-Tool Compatibility

```bash
ln -s CLAUDE.md AGENTS.md  # If CLAUDE.md is primary
```

---

## Interactive Wizard

Step-by-step guided setup with prompts at each decision point.

### Step 1: Detect State

Run `scripts/detect_state.sh`, then based on result:

| State | Action |
|-------|--------|
| `none` | Ask user: "Create CLAUDE.md or AGENTS.md as root?" |
| `partial` | Ask user: "What's the one-line TL;DR for this project?" |
| `complete` | Redirect to `intent-layer-maintenance` skill |

### Step 2: Measure & Decide

Run `scripts/estimate_all_candidates.sh`, then:
- Present candidates table to user
- Ask: "Which directories should get their own AGENTS.md?"

### Step 3: Mine History (Auto-Invoked) — HIGHEST VALUE STEP

**Before creating each node**, automatically analyze both git history AND PR discussions using the mining scripts. Git-mined pitfalls are consistently the most valuable content in any node. Pitfalls discovered from real bugs (commit fixes, reverts, migrations) are far more useful than pitfalls guessed from reading code.

```bash
# Git commit analysis (extracts pitfalls, anti-patterns, decisions, contracts)
${CLAUDE_PLUGIN_ROOT}/scripts/mine_git_history.sh [directory]

# GitHub PR analysis (requires gh CLI)
${CLAUDE_PLUGIN_ROOT}/scripts/mine_pr_reviews.sh --limit 50

# Check for stale nodes (during maintenance)
${CLAUDE_PLUGIN_ROOT}/scripts/detect_staleness.sh --code-changes [directory]
```

**mine_git_history.sh** extracts from commits:
1. Bug fixes → Pre-populate Pitfalls
2. Reverts → Pre-populate Anti-patterns
3. Refactors → Pre-populate Architecture Decisions
4. Breaking changes → Pre-populate Contracts

**mine_pr_reviews.sh** extracts from PRs:
1. Risks sections → Pre-populate Pitfalls
2. Review warnings → Pre-populate Pitfalls
3. Breaking Changes → Pre-populate Contracts
4. Why/Alternatives → Pre-populate Architecture Decisions

Present merged findings to user: "History suggests these pitfalls: [list]. Include them?"

### Step 4: Create Nodes

For root node:
- Ask user about project purpose
- Select template by size (Small/Medium/Large from `references/templates.md`)
- **Include git-history findings** in appropriate sections

For each child node:
- Ask user about directory's responsibility
- Use child template from `references/templates.md`
- **Include git-history findings** for that directory

### Step 4b: Add Pre-flight Checks

For directories with history of mistakes or complex operations:

**Ask**: "What operations in this directory have caused problems before?"

For each risky operation identified:
1. Ask: "What would you check before doing [operation]?"
2. Convert answer to verifiable check format
3. Add to Pre-flight Checks section

**Mine from history**:
```bash
# Find reverts and fixes that suggest missing checks
${CLAUDE_PLUGIN_ROOT}/scripts/mine_git_history.sh [directory] | grep -i "fix\|revert"
```

Present findings: "These commits suggest potential checks: [list]. Add any?"

### Step 5: Validate

Run `scripts/validate_node.sh` on all created nodes:
- Show validation results
- Offer to fix warnings/errors

### Step 6: Symlink

Ask user: "Create symlink for cross-tool compatibility? (AGENTS.md → CLAUDE.md)"

If yes: `ln -s CLAUDE.md AGENTS.md`

---

## Parallel Setup (Large Codebases)

For codebases >200k tokens, use parallel subagents to dramatically speed up exploration.

### When to Use Parallel Mode

| Codebase Size | Approach |
|---------------|----------|
| <100k tokens | Sequential (standard workflow) |
| 100-500k tokens | Parallel exploration, sequential synthesis |
| >500k tokens | F