<!-- domain-pack: claude-code-plugin · component: conventions · core -->
<!-- Ekstrahert 2026-05-12 fra ktg-privat CLAUDE.md + .claude/rules/. Re-verifiser plattform-detaljer mot offisiell Claude Code-dokumentasjon. -->

# Claude Code-plugin — konvensjoner

Ikke-forhandlbare beslutninger for plugins i ktg-privat-mønsteret. Avvik krever en `00-context/pack-overrides.md`-oppføring.

## Mappestruktur

```
plugin-name/
├── .claude-plugin/plugin.json   # Manifest (auto_discover: true)
├── commands/                    # Slash-commands → /plugin:command
├── agents/                      # Subagenter med frontmatter
├── skills/                      # skill-name/SKILL.md + references/
├── hooks/
│   ├── hooks.json               # Hook-konfig (auto-discovered)
│   └── scripts/                 # Executable scripts (.mjs)
├── templates/                   # Prosjekt-templates (valgfri)
├── README.md                    # Plugin-dokumentasjon
├── CLAUDE.md                    # Plugin-instruksjoner
└── plugin.local.md              # Lokal konfig (gitignored)
```

## Navnekonvensjoner

| Komponent | Mønster | Eksempel |
|-----------|---------|----------|
| Commands | `command.md` | `build.md` → `/plugin:build` |
| Agents | `descriptive-name-agent.md` | `gap-analysis-agent.md` |
| Skills | `skill-name/SKILL.md` | `prd-writing/SKILL.md` |
| References | `skill-name/references/*.md` | `prd-writing/references/task-format.md` |

## Frontmatter

**Commands:**
```yaml
---
name: plugin:command
description: Short description
allowed-tools: Read, Write, Bash, Task
model: sonnet
---
```

**Agents:**
```yaml
---
name: agent-name
description: |
  Multi-line description for WHEN to use this agent (triggering matters).
model: opus|sonnet|haiku
color: blue|green|yellow|purple|cyan
tools: ["Read", "Glob", "Task"]
---
```

**Skills:** `SKILL.md` har `name` + en `description` som avgjør triggering — beskriv hva skillen gjør *og når den skal aktiveres*. Bruk progressive disclosure: kompakt SKILL.md + `references/` for detaljer.

## Hooks-format

- `hooks` er et **objekt** med event-nøkler (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, …) — **ikke** en array.
- `matcher` er en **enkel string** (`"Bash"`, `"Write|Edit"`) — **ikke** et nestet objekt.
- Bruk `${CLAUDE_PLUGIN_ROOT}` for script-stier.
- **Ikke** deklarer `"hooks"` i `plugin.json` — Claude Code auto-discoverer `hooks/hooks.json`.
- Runtime-hooks er Node.js `.mjs` (cross-platform: macOS/Linux/Windows) — ingen bash/Python-runtime-avhengighet.

```json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "node ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/firewall.mjs" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "prompt", "prompt": "Reminder text." }] }
    ]
  }
}
```

## Context-budget-regler (gjelder alle plugins)

1. Max **3 knowledge-filer** per agent-invokasjon — les kun det oppgaven trenger.
2. Aldri last hele kataloger — navngi spesifikke filer, ikke `references/`.
3. Bruk **registrerte `subagent_type`** — ikke `general-purpose` + "les agentfilen".
4. **Sekvensiell agent-spawning** som default; parallell kun med begrunnelse.
5. Supplementære filer (templates, matrices) lastes kun ved eksplisitt behov.
6. SKILL.md = progressive disclosure (kompakt oversikt + `references/`).
7. Plugin-`CLAUDE.md` **under 100 linjer** — tabeller, ikke prosa. Påkrevde seksjoner: tittel/beskrivelse, commands-tabell, agents-tabell, hooks-tabell, arkitektur, state-håndtering.

## Guardrails

- **`CLAUDE.md` oppdateres i samme commit som endringen den dokumenterer** — ny agent → agent-tabell; ny command → command-tabell; ny hook → hook-oversikt; strukturendring → relevant seksjon. Ikke batch dokumentasjon til en separat commit.
- **Plugin-`CLAUDE.md` skal score Grade B (70+/100)** på config-audit-kvalitetsvurderingen.
- **Bash 3.2-kompatibilitet** for alle shell-/hook-scripts (macOS-default): ingen `declare -A`, ingen `readarray`/`mapfile`, ingen `|&`. (Foretrekk `.mjs`.)
- Conventional Commits: `type(scope): beskrivelse`.

## core / supplementary

`pack.json` → `components` er autoritativ. `00-context/`-snapshotet inkluderer core (`conventions.md`, `gotchas.md`, `checklist.md`); supplementary lastes on-demand.