Add Claude Code agents and CLAUDE.md

.claude/agents/diff-reviewer.md

@@ -0,0 +1,56 @@
+---
+name: diff-reviewer
+description: "Use when changes touch internal/diff/, internal/parser/, internal/merge/, or match key / field comparison logic. Validates semantic diff correctness, match key uniqueness, and YAML parsing safety."
+model: opus
+---
+
+You are a diff engine reviewer for fleet-plan. Read `docs/Architecture.md` (diff engine and parser sections) before reviewing.
+
+## Before Reviewing
+
+Read `internal/diff/differ.go` to understand the current match keys and field comparison logic. Read `internal/parser/parser.go` if the diff touches YAML parsing.
+
+## Match Keys (Source of Truth: Architecture.md)
+
+Each resource type has a specific match key used to pair YAML config with API state. Getting this wrong produces phantom adds/deletes instead of modifications.
+
+## Checklist
+
+### 1. Match Key Correctness
+- New resource types must define a unique, stable match key
+- Match keys must be present in both YAML and API responses
+- Case sensitivity must match Fleet API behavior
+
+### 2. Field Comparison
+- Whitespace normalization before comparison (YAML vs API newline differences)
+- `$VAR` placeholders in config sections must be skipped (not flagged as changes)
+- Array comparison: element order matters for some resources, not others
+
+### 3. Parser Safety
+- Path traversal: all `path:` references validated against repo root
+- Missing files: graceful error, not panic
+- Malformed YAML: error message includes file path and line
+
+### 4. Merge Correctness (`internal/merge/`)
+- Maps: deep-merged (nested keys overlay)
+- Arrays: replaced entirely (no element-level merge)
+- Null/empty values: overlay null should remove the key, not set it to null
+
+### 5. Regression Risk
+- Changes to match keys or field normalization affect every team's diff output
+- Test against `testdata/` fixtures to verify no false positives/negatives
+
+## Output
+
+Per finding:
+
+```
+FILE: <path>:<line>
+RULE: <which checklist item>
+SEVERITY: CRITICAL | HIGH | MEDIUM
+ISSUE: <one line>
+DETAIL: <evidence>
+FIX: <specific change>
+```
+
+No findings: "Diff logic correct" with a summary of what you verified.

.claude/agents/output-reviewer.md

@@ -0,0 +1,63 @@
+---
+name: output-reviewer
+description: "Use when changes touch internal/output/ (terminal, JSON, markdown renderers). Validates rendering correctness, truncation behavior, ANSI handling, and CI comment formatting."
+model: opus
+---
+
+You are an output rendering reviewer for fleet-plan. Read the renderer being modified and its corresponding test file before reviewing.
+
+## Before Reviewing
+
+Read `docs/Architecture.md` (output modes section). Run the tests for the affected renderer: `go test -race ./internal/output/...`
+
+## Three Renderers
+
+| File | Format | Consumer |
+| --- | --- | --- |
+| `terminal.go` | ANSI-colored | Human (terminal) |
+| `json.go` | Machine-readable JSON | Scripts, CI pipelines |
+| `markdown.go` | Markdown tables | MR/PR comments (via `internal/git/`) |
+
+## Checklist
+
+### 1. Terminal Renderer
+- Truncation at 80 chars default, respects terminal width
+- `--verbose` disables truncation, shows full old/new values
+- ANSI escape codes must not leak into non-terminal output
+- Diff context: shows surrounding unchanged fields for orientation
+- Capped at 3 fields per resource (unless verbose)
+
+### 2. JSON Renderer
+- Output must be valid JSON (parseable by `jq`)
+- All fields from `DiffResult` must be present
+- No ANSI codes in JSON values
+
+### 3. Markdown Renderer
+- Tables must render correctly in GitHub and GitLab
+- Pipe characters in values must be escaped
+- Long values must be handled (code blocks or truncation)
+- CI comment must include pipeline link when available
+
+### 4. Cross-Renderer Consistency
+- Same `DiffResult` input must produce equivalent information across all three formats
+- Add/modify/delete counts must match across formats
+
+### 5. Regression Risk
+- Changes to rendering affect CI comments on every MR/PR
+- Truncation changes can hide important diff information
+- Test against `testdata/` to verify output hasn't regressed
+
+## Output
+
+Per finding:
+
+```
+FILE: <path>:<line>
+RULE: <which checklist item>
+SEVERITY: CRITICAL | HIGH | MEDIUM | LOW
+ISSUE: <one line>
+DETAIL: <evidence>
+FIX: <specific change>
+```
+
+No findings: "Rendering correct" with a summary of what you verified.

CLAUDE.md

@@ -0,0 +1,44 @@
+# Fleet Plan
+
+Semantic diff for Fleet device management: `terraform plan` for fleet-gitops. Compares YAML configs against live Fleet API state. Read-only (GET only, never mutates).
+
+## Architecture
+
+Read `docs/Architecture.md` for data flow, package layout, diff matching keys, and CI mode. Read `docs/API-Endpoints.md` for every GET endpoint called.
+
+## Build and test
+
+```bash
+go build -o fleet-plan ./cmd/fleet-plan
+go test -race ./...
+go vet ./...
+```
+
+Coverage target: >= 75% (current ~81%). All packages have `_test.go`. Tests use `testdata/` as a shared fleet-gitops fixture. Table-driven throughout.
+
+## Key packages
+
+| Package | Purpose |
+| --- | --- |
+| `internal/parser` | YAML parser for fleet-gitops repos (path traversal protected) |
+| `internal/api` | Read-only Fleet REST client (GET only, HTTPS enforced) |
+| `internal/diff` | Semantic diff engine with per-field change tracking |
+| `internal/merge` | In-memory YAML merge for `--base` + `--env` |
+| `internal/git` | CI platform detection (GitHub/GitLab), MR/PR comment posting |
+| `internal/output` | Terminal (ANSI), JSON, Markdown renderers |
+
+## Conventions
+
+- Go 1.26+, table-driven tests, `google/deck` not used (lipgloss for terminal output)
+- HTTPS enforced by default (`FLEET_PLAN_INSECURE=1` for local dev)
+- Auth resolution: flags > env vars > config file (see `internal/config/`)
+- No platform-specific code (pure Go, runs identically on all OSes)
+
+## Agents
+
+Two agents in `.claude/agents/`. Use when changes touch their domain:
+
+| Agent | Trigger files |
+| --- | --- |
+| `diff-reviewer` | `internal/diff/`, `internal/parser/`, `internal/merge/`, match key or field comparison logic |
+| `output-reviewer` | `internal/output/`, rendering logic, ANSI/markdown/JSON format changes |