design(app-creator): S6 — forfatt ios-app referanse-domain-pack + start claude-code-plugin-pakke

- domain-packs/ios-app/: komplett referanse-pakke (8 komponenter) — pack.json med
  components-map, conventions.md, 4 patterns/, gotchas.md, checklist.md splittet i 3
  (App Store-submission + security-privacy/MASVS 2.1 + accessibility/WCAG 2.2 AA),
  3 scaffold/-maler (PrivacyInfo.xcprivacy-plist, NSUsageDescription-inventar,
  ASC-metadata), eksempel-feature-brief i Voyage strict-mode-format, glossary.md.
  Hver teknisk påstand verifisert mot Apple Developer / W3C WAI / OWASP MAS.
- domain-packs/claude-code-plugin/: stub — pack.json + conventions.md + gotchas.md
  + checklist.md + glossary.md ferdige (ekstrahert fra ktg-privat-konvensjoner);
  patterns/scaffold/examples er stubs.
- docs/domain-pack-spec.md: § D2/D3/D4/D7 + restrisiko oppdatert — pack.json
  components-felt, core/supplementary låst til manifestet, checklist-splitt-konvensjon,
  snapshot-materialiserings-mekanikk presisert, iOS-versjons-korreksjon (iOS 26, ikke
  "iOS 18/19"), D7 → "forfattet i S6".
- prototype-run/friksjon.md: #9 (Akashic-briefen refererer "iOS 19" som ikke finnes —
  rettes i S7) + S6-prosessnotater (checklist-splitt bekreftet nødvendig, components-gap
  fylt, verifiserings-asymmetri ios-app vs claude-code-plugin notert).
- CLAUDE.md: peker til domain-packs/ under § Status.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-12 14:06:54 +02:00
commit 2011507ea1
27 changed files with 1059 additions and 17 deletions

View file

@ -0,0 +1,64 @@
<!-- domain-pack: claude-code-plugin · component: checklists · core -->
<!-- Ekstrahert 2026-05-12 fra ktg-privat CLAUDE.md + .claude/rules/. -->
# Claude Code-plugin — sjekkliste
Fase-exit-kriterier for en plugin i ktg-privat-mønsteret. En `[skip]`-merket linje begrunnes i `00-context/pack-overrides.md`.
## A. Struktur & manifest
- [ ] `.claude-plugin/plugin.json` finnes, gyldig JSON, `auto_discover: true`.
- [ ] Mappestruktur følger mønsteret (`commands/`, `agents/`, `skills/`, `hooks/`, `templates/` etter behov).
- [ ] `README.md` finnes og beskriver plugin-formål + hovedcommand.
- [ ] `CLAUDE.md` finnes, **< 100 linjer**, tabell-basert.
- [ ] `*.local.md` i `.gitignore`.
- [ ] **`plugin-dev:plugin-validator` kjørt og passerer** (struktur, frontmatter, cross-komponent-koherens).
## B. Navnekonvensjoner
- [ ] Commands: `command.md``/plugin:command`.
- [ ] Agents: `descriptive-name-agent.md`.
- [ ] Skills: `skill-name/SKILL.md` (+ `references/*.md` ved behov).
## C. Frontmatter
- [ ] Hver command har `name`, `description`, `allowed-tools`, `model`.
- [ ] Hver agent har `name`, multi-line `description` med **when-to-use** + eksempler, `model`, `color`, `tools`.
- [ ] Hver skill har `name` + en `description` som beskriver hva **og når** (triggering-effektiv — kjør `plugin-dev:skill-reviewer`).
## D. Hooks (hvis pluginen har hooks)
- [ ] `hooks/hooks.json` finnes; `hooks` er et **objekt** med event-nøkler.
- [ ] `matcher` er en string, ikke et objekt.
- [ ] Stier bruker `${CLAUDE_PLUGIN_ROOT}`.
- [ ] `"hooks"` er **ikke** deklarert i `plugin.json`.
- [ ] Hook-scripts er `.mjs` (eller bash 3.2-kompatible hvis bash er nødvendig).
- [ ] Hver hook står i `CLAUDE.md`s hook-tabell (event, script, formål).
## E. Context-budget
- [ ] Ingen agent-invokasjon laster > 3 knowledge-filer.
- [ ] Ingen hele-katalog-lasting — spesifikke filer navngis.
- [ ] Registrerte `subagent_type` brukes (ikke `general-purpose` + "les agentfilen").
- [ ] Sekvensiell agent-spawning som default (parallell begrunnet der brukt).
- [ ] SKILL.md bruker progressive disclosure.
## F. Dokumentasjon & kvalitet
- [ ] `CLAUDE.md` har alle påkrevde seksjoner: tittel/beskrivelse, commands-tabell, agents-tabell, hooks-tabell, arkitektur, state-håndtering (hvis relevant).
- [ ] `CLAUDE.md` scorer **Grade B (70+/100)** på config-audit-kvalitetsvurderingen.
- [ ] `CLAUDE.md`-oppdatering er i **samme commit** som endringen den dokumenterer.
- [ ] Linear-label dokumentert i `CLAUDE.md` (hvis konvensjonen gjelder).
## G. Commit & release
- [ ] Conventional Commits (`type(scope): beskrivelse`).
- [ ] Versjonsbump → alle versjons-refererende filer oppdatert i samme commit (`plugin.json`, README-badges, CHANGELOG, konstanter).
- [ ] Committet + pushet (Forgejo, ikke GitHub).
- [ ] Marketplace-sync hvis pluginen er nyregistrert/omdøpt.
## H. Røyktest
- [ ] Alle slash-commands kjører uten feil.
- [ ] Agenter triggerer på sine beskrevne situasjoner.
- [ ] Hooks fyrer og oppfører seg som forventet (ingen falske positiver som blokkerer arbeid).

View file

@ -0,0 +1,101 @@
<!-- 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.

View file

@ -0,0 +1,14 @@
<!-- domain-pack: claude-code-plugin · component: examples · supplementary · STUB -->
# examples/ — STUB (forfattes senere)
Planlagt referanse-materiale:
- `feature-brief-add-command.md` — eksempel-feature-brief (Voyage strict-mode) for "legg til en ny slash-command i en plugin" — illustrerer hvordan en plugin-feature-brief ser ut.
- Pekere til eksisterende ktg-privat-plugins som referanse-implementasjoner:
- `kiur` — 3-lags-arkitektur, max-3-regel, hooks.
- `harness` — "ikke last alt på en gang", multi-session state.
- `vegnormalene` — ren MCP/RAG-plugin.
- `newsletter` — mange-agent-orkestrering (18 agenter).
Forfatt et faktisk eksempel-brief når en plugin-feature faktisk drives gjennom pipelinen — da blir det informert av reell bruk, ikke spekulasjon (samme prinsipp som `ios-app/examples/`).

View file

@ -0,0 +1,28 @@
<!-- domain-pack: claude-code-plugin · component: glossary · supplementary -->
<!-- Ekstrahert 2026-05-12 fra ktg-privat-konvensjoner + Claude Code-terminologi. -->
# Claude Code-plugin — glossar
**Agent (subagent)** — et avgrenset Claude-instans med egen system-prompt, verktøy-sett og modell, spawnet for en deloppgave. Defineres i `agents/descriptive-name-agent.md` med frontmatter (`name`, `description`, `model`, `color`, `tools`). Velges automatisk på `description`-en.
**Auto-discovery** — Claude Code finner commands/agents/skills/hooks ved konvensjonelle stier uten manuell deklarasjon i `plugin.json` (forutsetter `auto_discover: true`). Hooks auto-discoveres fra `hooks/hooks.json`.
**`${CLAUDE_PLUGIN_ROOT}`** — miljøvariabel som ekspanderer til plugin-rotmappa ved kjøretid; brukes i hook-command-stier slik at plugin-en virker uavhengig av installasjonssted.
**Command (slash-command)** — `/plugin:command`, definert i `commands/command.md` med frontmatter (`name`, `description`, `allowed-tools`, `model`). Kjøres av brukeren i terminalen.
**Hook** — event-drevet automasjon. Konfigureres i `hooks/hooks.json` som et **objekt** med event-nøkler (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `Stop`, `SubagentStop`, `PreCompact`, `Notification`, `SessionEnd`). To typer: `command` (kjør et script) eller `prompt` (injiser tekst).
**`matcher`** — i en hook-oppføring: en string som bestemmer hvilke verktøy/eventer hooken gjelder (`"Bash"`, `"Write|Edit"`). Ikke et nestet objekt.
**MCP (Model Context Protocol)** — protokoll for å koble eksterne verktøy/tjenester til Claude Code; konfigureres via `.mcp.json` i plugin-en. Server-typer: stdio, SSE, HTTP, WebSocket.
**Marketplace** — register over plugins (her: `ktg-privat`, `ktg-plugin-marketplace`). Plugins aktiveres i `~/.claude/settings.json` under `enabledPlugins` med `plugin@marketplace`-notasjon.
**Progressive disclosure** — skill-mønster: en kompakt `SKILL.md` med oversikt + `references/*.md` for detaljer som lastes kun ved behov. Holder kontekst-forbruket lavt.
**Skill** — `skills/skill-name/SKILL.md` (+ `references/`). En `description` som beskriver hva skillen gjør *og når den skal aktiveres* (triggering avhenger av dette). Kan være user-invocable (`/skill-name`) eller modell-invoked.
**`subagent_type`** — den registrerte typen som velges når man spawner en agent; å bruke `general-purpose` + "les agentfilen" i stedet er en context-budget-anti-pattern.
**Three-layer architecture** — referansemønster (fra `kiur`): orkestrator-lag (hovedkontekst) / agent-lag (delegert arbeid) / knowledge-lag (`references/`, lastes max 3 av gangen). Brukes for å holde plugins skalerbare uten kontekst-eksplosjon.

View file

@ -0,0 +1,35 @@
<!-- domain-pack: claude-code-plugin · component: gotchas · core -->
<!-- Ekstrahert 2026-05-12 fra ktg-privat CLAUDE.md + .claude/rules/hook-format.md. -->
# Claude Code-plugin — gotchas ("ikke gjør dette")
Feil som faktisk har brutt plugins i dette repoet.
## Hooks
- **`hooks` som array.** Det er et **objekt** med event-nøkler (`PreToolUse`, `PostToolUse`, `Stop`, `SessionStart`, `UserPromptSubmit`, …). En array feiler stille / lastes ikke.
- **`matcher` som nestet objekt.** Det er en **enkel string**`"Bash"`, `"Write|Edit"`. Et objekt der er feil.
- **Deklarere `"hooks"` i `plugin.json`.** Ikke gjør det — Claude Code auto-discoverer `hooks/hooks.json`. Dobbel-deklarasjon = uforutsigbar oppførsel.
- **Hardkode stier i hook-commands.** Bruk `${CLAUDE_PLUGIN_ROOT}` — plugin-roten varierer per installasjon.
- **Bash-/Python-avhengige hooks.** Runtime-hooks skal være Node.js `.mjs` (cross-platform). Hvis du ** bruke bash: bash 3.2-kompatibel (ingen `declare -A`, `readarray`/`mapfile`, `|&`) — macOS-default er 3.2.
## Context-budget
- **Laste en hel katalog** (`references/`, `references/ai-security/`). Navngi spesifikke filer. Hele kataloger sprenger budsjettet for nedstrøms-arbeid.
- **Bruke `general-purpose` + "les agentfilen X"** i stedet for en registrert `subagent_type`. Det dobler kostnaden og hopper over agent-definisjonens egen verktøy-/modell-konfig.
- **Preloade "i tilfelle".** Max-3-filer-per-invokasjon. Trenger du en fjerde, les den når behovet oppstår.
- **Parallell agent-spawning uten grunn.** Sekvensiell er default; parallell krever begrunnelse (uavhengige oppgaver, ikke "raskere").
- **Plugin-`CLAUDE.md` som prosa-essay.** Under 100 linjer, tabell-basert. Lang = ignorert (samme dynamikk som Cursor-regler).
## Manifest & struktur
- **`plugin.json` uten `auto_discover`** (eller med komponenter både auto-discovered *og* manuelt deklarert). Hold det konsistent — auto-discovery for commands/agents/skills/hooks.
- **Feil filnavn-mønster.** Agenter: `descriptive-name-agent.md`. Commands: `command.md`. Skills: `skill-name/SKILL.md`. Avvik = komponenten oppdages ikke.
- **Skill-`description` som bare sier hva, ikke når.** Triggering avhenger av at description-en beskriver *aktiveringssituasjonen*. "Does X" trigges ikke; "Use when the user asks to X / mentions Y" trigges.
- **Agent-`description` uten when-to-use.** Samme: agenten velges på description-en. Inkluder konkrete triggere / eksempler.
## Prosess
- **Oppdatere `CLAUDE.md` i en separat commit etterpå.** Samme commit som endringen — ny agent + agent-tabell, ny command + command-tabell, ny hook + hook-oversikt.
- **Glemme versjonssync.** Versjonsbump? Oppdater package.json/`plugin.json`, README-badges, CHANGELOG, konstanter — alle i samme commit.
- **Skrive kode i andre repos / utvide scope etter godkjent plan** uten eksplisitt klarsignal.

View file

@ -0,0 +1,23 @@
{
"schema": "domain-pack/v1",
"name": "claude-code-plugin",
"version": "0.1.0",
"domain": "Claude Code-plugin-utvikling (commands / agents / skills / hooks / MCP)",
"description": "Domene-kunnskap for å bygge Claude Code-plugins: manifest- og frontmatter-regler, navnekonvensjoner, hooks-format, context-budget-disiplin, plugin-validator-pass.",
"phases": [1, 3, 5, 6, 7],
"verified": {
"date": "2026-05-12",
"against": "ktg-privat CLAUDE.md + .claude/rules/{plugin-convention,hook-format}.md (intern konvensjon); Anthropic plugin-dev-skills (struktur/commands/agents/skills/hooks)",
"note": "Ekstrahert fra eksisterende ktg-privat-konvensjoner. Påstander om Claude Code-plattformen (hooks-API, ${CLAUDE_PLUGIN_ROOT}, auto-discovery) bør re-verifiseres mot offisiell Claude Code-dokumentasjon ved neste oppdatering — ikke gjort uttømmende i S6 (pakken er en STUB utover de fire core-filene)."
},
"components": {
"conventions.md": "core",
"gotchas.md": "core",
"checklist.md": "core",
"glossary.md": "supplementary",
"patterns/README.md": "supplementary",
"scaffold/README.md": "supplementary",
"examples/README.md": "supplementary"
},
"status": "stub — pack.json + conventions.md + gotchas.md + checklist.md + glossary.md ferdige; patterns/scaffold/examples er stubs (forfattes senere). Ikke konsumert av Akashic-prototypen."
}

View file

@ -0,0 +1,13 @@
<!-- domain-pack: claude-code-plugin · component: patterns · supplementary · STUB -->
# patterns/ — STUB (forfattes senere)
`claude-code-plugin`-pakken er en stub utover de fire core-filene (`pack.json`, `conventions.md`, `gotchas.md`, `checklist.md`) + `glossary.md`. Planlagte pattern-filer (kilde: ktg-privat-plugins + Anthropic `plugin-dev`-skills):
- `command-router.md` — hovedrouter-command som dispatcher til sub-commands (`/plugin``/plugin:build`, `/plugin:status`, …).
- `agent-definition.md` — hvordan skrive en agent-`description` som faktisk trigger; verktøy-/modell-valg per agent.
- `skill-progressive-disclosure.md` — kompakt SKILL.md + `references/`-struktur; når noe hører i SKILL.md vs en referanse-fil.
- `three-layer-architecture.md` — orkestrator/agent/knowledge-lag-mønsteret fra `kiur`; max-3-regel i praksis.
- `hook-mjs.md` — self-contained `.mjs`-hook-script: input-parsing (stdin JSON), exit-koder, `${CLAUDE_PLUGIN_ROOT}`.
Hver fil ≤500 ord. Forfatt ved behov — destiller fra `plugin-dev:plugin-structure`, `plugin-dev:command-development`, `plugin-dev:agent-development`, `plugin-dev:skill-development`, `plugin-dev:hook-development` + eksisterende ktg-privat-plugins (`kiur`, `harness`, `vegnormalene`).

View file

@ -0,0 +1,15 @@
<!-- domain-pack: claude-code-plugin · component: scaffold · supplementary · STUB -->
# scaffold/ — STUB (forfattes senere)
Planlagte fil-templater som materialiseres inn i en ny plugin:
- `plugin.json` — manifest-skjelett (`name`, `version`, `description`, `auto_discover: true`).
- `hooks.json` — tomt hook-skjelett (objekt med event-nøkler, kommentert eksempel).
- `command.md` — command-frontmatter-skjelett.
- `agent.md` — agent-frontmatter-skjelett (med when-to-use-eksempel-blokk).
- `SKILL.md` — skill-skjelett med progressive-disclosure-struktur.
- `CLAUDE.md` — plugin-CLAUDE.md-skjelett med alle påkrevde seksjoner (< 100 linjer, tabell-basert).
- `plugin-tree/` — full katalog-skjelett (`.claude-plugin/`, `commands/`, `agents/`, `skills/`, `hooks/scripts/`, `README.md`).
Forfatt ved behov. Hold templates minimale — de skal kompletteres per plugin, ikke kopieres ordrett.