# Local Config

> Defines the yellow-plugins.local.md per-project config file schema. Use when authoring commands that should accept per-project overrides for review pipeline behavior, reviewer set narrowing, depth controls, or focus-area filtering.

- Skill: `kinginyellows/local-config` (Agent Skill)
- Install (CLI): `npx skillmds@latest add kinginyellows/local-config`
- Raw SKILL.md: https://api.skillmd.com/api/skills/kinginyellows/local-config/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: kinginyellows (https://skillmd.com/u/kinginyellows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/kinginyellows/local-config

---


# yellow-plugins.local.md — per-project configuration

`yellow-plugins.local.md` is an **optional** per-project config file that
lets a project override defaults for yellow-plugins commands. Place it at
the repo root (next to `CLAUDE.md`). The file uses YAML frontmatter for
structured settings and an optional markdown body for human-readable
notes.

## What It Does

- Provides a single, discoverable location for per-project overrides to
  yellow-plugins command behavior.
- Doubles as the **rollback escape hatch** for the Wave 2 review-pipeline
  rewrite — projects experiencing high false-positive review noise can
  set `review_pipeline: legacy` and the pre-Wave-2 adaptive selection is
  used instead.
- Supports optional `reviewer_set.{include,exclude}` for narrowing or
  expanding the persona dispatch table without forking commands.

## When to Use

- A project wants to skip specific reviewer personas
  (`reviewer_set.exclude: [adversarial-reviewer]`)
- A project wants to force the legacy pipeline during the Wave 2
  dogfooding period (`review_pipeline: legacy`)
- A project wants to narrow review focus to specific areas
  (`focus_areas: [security, correctness]`)
- A project wants a custom `review_depth` regardless of diff size
  (`review_depth: large` to always invoke `adversarial-reviewer`)

When the file is **absent**, all commands use their built-in defaults.
The file is purely additive — no command behavior depends on its
existence.

## Usage

### File location and shape

```
<repo-root>/yellow-plugins.local.md
```

Frontmatter-only is the typical shape; a markdown body is optional and
used only by humans (commands ignore the body).

### Schema

```yaml
---
# review:pr / review:all behavior overrides (Wave 2 keys)
review_pipeline: persona | legacy        # default: persona (Wave 2 default)
review_depth: small | medium | large     # default: auto-detect from diff size
focus_areas: [security, correctness, ...]  # default: all areas
reviewer_set:
  include: [<agent-name>, ...]            # additional agents to spawn beyond defaults
  exclude: [<agent-name>, ...]            # agents to skip

# Wave 3 keys (documented; consumer adoption tracked per-key below)
stack: [ts, py, rust, go]                 # default: auto-detect from repo
agent_native_focus: true | false          # default: false
confidence_threshold: 0..100              # default: 75
resolve_pr:
  cluster_line_distance: 10               # default: 10 (positive integer)
---
```

**Consumer adoption status (Wave 3 keys):** the keys are valid frontmatter
today and parsers do not warn on them, but the commands that act on them
land in separate Wave 3 PRs:

| Key                    | Acted on by                        | Status |
|------------------------|------------------------------------|--------|
| `stack`                | `polyglot-reviewer`, `review:pr` Step 4 dispatch | Pending W3 polyglot scoping. Until then: documented but ignored. |
| `agent_native_focus`   | `review:pr` Step 4 dispatch (forces W3.5 reviewers) | Pending W3.5 (`agent-native-reviewers` branch). Until then: documented but ignored. |
| `confidence_threshold` | `review:pr` aggregation gate, `audit-synthesizer` | Pending W3.13b (`yellow-debt-confidence-calibration` branch). Until then: documented but ignored. |
| `resolve_pr.cluster_line_distance` | `review:resolve` Step 3d cluster threshold | Acted on by `review:resolve` (W3.3). Invalid values (non-integer, ≤ 0) emit a warning to stderr and fall back to the default 10. |

Authors may set Wave 3 keys today without breaking Wave 2 consumers — the
graceful-degradation rule (unknown keys emit a warning but do not abort)
means the file remains valid forward-and-backward.

### Field reference

| Field | Type | Default | Effect |
|-------|------|---------|--------|
| `review_pipeline` | `persona` \| `legacy` | `persona` | `legacy` falls back to pre-Wave-2 adaptive selection (no learnings pre-pass, no confidence rubric, no new personas). Use as escape hatch only. |
| `review_depth` | `small` \| `medium` \| `large` | auto | Forces a depth tier regardless of computed diff size. `large` always invokes `adversarial-reviewer`; `small` skips it even on large diffs. |
| `focus_areas` | array of strings | empty (= all) | Narrows reviewer set to those whose `category` matches one of the listed areas. Recognized areas: `security`, `correctness`, `reliability`, `performance`, `maintainability`, `project-compliance`, `project-standards`, `architecture`, `testing`, `documentation`, `types`, `adversarial`. Always-on personas (`project-compliance-reviewer`, `correctness-reviewer`, `maintainability-reviewer`, `project-standards-reviewer`) survive the filter regardless of `focus_areas` — filtering them out would defeat the always-on contract. |
| `reviewer_set.include` | array of agent names | empty | Additive — agents are spawned even if their conditional triggers don't fire. This is also the only way to reach `thermonuclear-reviewer` (yellow-review): an opt-in structural-quality persona that appears in neither dispatch table, so it runs only when named here. Two silent drops apply to `include`, both visible in the precedence pseudo-code under "Reading the config from a command". First, `review_pipeline: legacy` branches before overrides are read at all, so `include` has no effect there. Second, `focus_areas` filters the merged set afterwards, and `thermonuclear-reviewer` is not always-on (its category is `maintainability`), so an included `thermonuclear-reviewer` survives only when `focus_areas` is unset or lists `maintainability`. Neither drop emits a diagnostic. |
| `reviewer_set.exclude` | array of agent names | empty | Subtractive — agents are skipped even if always-on or their triggers fire. Applied after `include`. |
| `stack` | array of `ts` \| `py` \| `rust` \| `go` | auto-detect | Forces language-specific reviewer behavior. When set, `polyglot-reviewer` (when triggered) scopes to listed languages and skips non-matching files. Auto-detect uses repo root signals: `package.json` → `ts`, `pyproject.toml`/`requirements.txt` → `py`, `Cargo.toml` → `rust`, `go.mod` → `go`. Multi-stack repos may set this explicitly to scope review to a subset. Acted on by W3-pending consumers (see status table). |
| `agent_native_focus` | boolean | `false` | When `true`, always invokes the W3.5 agent-native reviewer triplet (`cli-readiness-reviewer`, `agent-cli-readiness-reviewer`, `agent-native-reviewer`) regardless of whether the diff touches `plugins/*/agents/`, `plugins/*/skills/`, or `plugins/*/commands/`. Useful for repos that author Claude Code plugins but house plugin code outside the standard `plugins/` layout. Acted on by W3.5 (pending). |
| `confidence_threshold` | integer 0–100 | `75` | Override the Wave 2 confidence aggregation gate used by `review:pr` and `audit-synthesizer`. Values below `75` surface more findings (more false positives, fewer missed issues); values above `75` suppress more (fewer false positives, more missed issues). Set above `100` to suppress all findings (effectively a dry-run). Acted on by W3.13b (pending). |
| `resolve_pr.cluster_line_distance` | positive integer | `10` | Cluster threshold for `review:resolve` Step 3d. Adjacent threads on the same file with line distance ≤ this value merge into a single resolver task (transitive merge). Larger values cluster more aggressively (fewer resolvers, broader edits per agent); smaller values keep clusters tighter. Invalid values (non-integer, ≤ 0) emit a warning to stderr and fall back to the default. |

### Example: tighten review for a security-critical project

```yaml
---
review_pipeline: persona
review_depth: large
focus_areas: [security, correctness, reliability]
reviewer_set:
  include: [security-reviewer, adversarial-reviewer]
  exclude: [comment-analyzer, type-design-analyzer]
---
```

### Example: rollback escape hatch during Wave 2 dogfooding

```yaml
---
review_pipeline: legacy
---

# Notes for humans (commands ignore this body)

We hit unexpected false-positive noise from `correctness-reviewer` on
2026-04-29; reverting to legacy pipeline until upstream lands a fix.
Re-enable persona pipeline by removing `review_pipeline: legacy` (or
flipping it to `persona`).
```

### Reading the config from a command

Commands that honor this config (today: `review:pr`, `review:all`) read
the file from the project root and merge values with their built-in
defaults. The merge precedence is:

1. Command argument overrides (e.g., explicit flags) — highest
2. `yellow-plugins.local.md` frontmatter
3. Command built-in defaults — lowest

Pseudo-code:

```text
config = load_yaml_frontmatter("yellow-plugins.local.md")
review_pipeline = config.review_pipeline ?? "persona"
review_depth = command_arg.depth ?? config.review_depth ?? auto_detect()

# Precedence step 1: review_pipeline branches BEFORE any reviewer override is
# read. The legacy path dispatches its own fixed persona list and consults
# neither reviewer_set nor focus_areas — see
# plugins/yellow-review/references/review-pr/legacy-fallback.md.
if review_pipeline == "legacy":
  use_legacy_dispatch(LEGACY_FIXED_PERSONA_LIST)
  return

# Precedence step 2 (persona path only): merge reviewer overrides.
focus_areas = config.focus_areas ?? []  # empty = no filter
include = config.reviewer_set.include ?? []
exclude = config.reviewer_set.exclude ?? []

# After computing the default reviewer set per Step 4 of review-pr.md:
reviewer_set = (defaults ∪ include) \ exclude

# Precedence step 3: focus_areas filters the merged set, so an included agent
# is still dropped when its category is not listed.
if focus_areas:
  # Always-on personas survive the filter regardless of focus_areas; filtering
  # them would defeat the always-on contract documented in
  # plugins/yellow-review/commands/review/review-pr.md Step 4.
  always_on = {project-compliance-reviewer, correctness-reviewer,
               maintainability-reviewer, project-standards-reviewer}
  reviewer_set = always_on ∪ filter_by_category(reviewer_set \ always_on, focus_areas)
use_persona_dispatch(reviewer_set)
```

### Validation

- Unknown top-level keys → emit a warning to stderr but do not abort.
  Forward-compatibility matters more than strictness for an optional
  config.
- Unknown reviewer names in `reviewer_set.include` → emit a warning naming
  the unrecognized name. The graceful-degradation guard in `review:pr`
  Step 4 handles missing agents at dispatch time anyway.
- Mutually exclusive entries (same name in both `include` and `exclude`)
  → `exclude` wins; emit a warning naming the conflicting agent.
- `review_pipeline` values other than `persona` / `legacy` → fall back to
  `persona` and emit a warning.
- `stack` entries other than `ts` / `py` / `rust` / `go` → drop the
  unknown entry, emit a warning naming it. An empty array after dropping
  unknowns falls back to auto-detection.
- `agent_native_focus` non-boolean values → fall back to `false` and
  emit a warning. Common mistake: quoting the value (`"true"`) — YAML
  parses that as a string, not a boolean.
- `confidence_threshold` outside `0..100` → clamp to the range and emit
  a warning. Non-integer values fall back to the default (`75`).

### Example: TypeScript-focused plugin repo with strict gating

```yaml
---
review_pipeline: persona
review_depth: large
focus_areas: [security, correctness, project-compliance]
stack: [ts]
agent_native_focus: true
confidence_threshold: 60
---
```

Effect, once Wave 3 consumers land: `polyglot-reviewer` scopes to
TypeScript only, the W3.5 agent-native reviewer triplet is always
invoked, and the confidence gate fires earlier (60 vs. default 75) so
borderline findings surface for human review.

## Migration

Projects that previously relied on hard-coded defaults need no migration —
the absence of `yellow-plugins.local.md` keeps existing behavior. The
file is opt-in.

## Related

- `RESEARCH/upstream-snapshots/e5b397c9d1883354f03e338dd00f98be3da39f9f/confidence-rubric.md` — the
  confidence rubric that the persona pipeline uses for aggregation.
- `plugins/yellow-review/commands/review/review-pr.md` — primary consumer
  of the config keys defined here.
- `plugins/yellow-review/commands/review/review-all.md` — secondary
  consumer; its inline pipeline references the same overrides.
- `plugins/yellow-review/skills/pr-review-workflow/SKILL.md` — selection
  rules and severity definitions.