design(app-creator): S5 — revider phase-design-draft per research-brief + skriv domain-pack-spec
Anvendt revisjons-mandat R1–R17 fra prototype-run/research/research-brief.md:
- features/{NN}-{slug}/-layout (brief.md + context.md) + 00-context/ (snapshots + pack-overrides.md)
- fase 7 omskrevet mot Voyage Handover-1 strict-mode (8 frontmatter-felter, state-machine, 3 påkrevde body-seksjoner + Research Plan); context.md-splitt (BMAD: embedding>linking); round-trip-test-krav
- flersesjons-protokoll formalisert (dokumentert praksis + lett state.json-session-felt)
- domain-pack-konsumering per fase (max-3-regel, domain_pack-felt)
- rapid mode + skippbare faser 2/4/5 med begrunnelse + hard lengde-grense (≤500 ord)
- fase 4 trigger-på-bruk; fase 3 ADR-ved-beslutning + åpne AQ-spørsmål; fase 5 mot ISO 25010:2023/WCAG 2.2/MASVS 2.1/privacy manifest
- fase 1: minimal-variant (default) vs full-variant; splittet kvalitets-sjekk; GJØR-vs-ER-skille; tidlig eierskaps-spørsmål; appetite + rabbit holes
- problem-gate + requirements-first/design-first + implementation-readiness-check
- release/ops-grense gjort eksplisitt i scope-lås; status-merking oppdatert
Ny docs/domain-pack-spec.md (domene-nøytral) per innholds-mandat D1–D7:
8-komponent-liste, pack.json-skjema, fil-sti-aktivering + materialisert snapshot,
uformell semver + pack-overrides.md escape hatch, Voyage-agnostisk håndtering,
skisse av ios-app- og claude-code-plugin-referanse-pakkene (S6 forfatter).
Beslutninger: domain-packs/ i plugin-roten; flersesjons = dokumentert + lett state-felt;
/trekrevise = lett intern variant + Voyages anchor-format kun på fase 7-briefer;
lengde-grense ≤500 ord/én skjerm; fase 1-default = minimal-variant.
prototype-run/friksjon.md: S5-bekreftelses-noter på #1–8 + R17-protokoll-tillegg (mål fase-overhead-tid).
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
parent
5e7ba91608
commit
e4ae4ac5b4
3 changed files with 757 additions and 488 deletions
186
docs/domain-pack-spec.md
Normal file
186
docs/domain-pack-spec.md
Normal file
|
|
@ -0,0 +1,186 @@
|
||||||
|
# Domain-pack-spec (app-creator)
|
||||||
|
|
||||||
|
<!-- Skrevet: 2026-05-11 (S5) -->
|
||||||
|
<!-- Status: FØRSTEUTKAST. Domene-nøytral spec. Referanse-pakkene (ios-app, claude-code-plugin) forfattes i S6 — kun skissert her (§ 7). Spec-en er hypotese inntil den første referanse-pakken faktisk er bygget og konsumert av en pipeline-fase. -->
|
||||||
|
<!-- Begrunnelse / research-grunnlag: prototype-run/research/research-brief.md § 5 (D1–D7), prototype-run/research/C-domain-packs.md § 5, friksjon #5 og #7. -->
|
||||||
|
|
||||||
|
## D1 — Hva en domain pack er
|
||||||
|
|
||||||
|
En **domain pack** er en gjenbrukbar kunnskaps-bunt som app-creator-fasene 1 og 3–7 konsumerer for å realisere en app i et bestemt domene (iOS-app, Claude Code-plugin, web-app, …). Den ligger som et **mellomlag** mellom:
|
||||||
|
|
||||||
|
- **app-spesifikk kunnskap** (fase 3–5 — denne appens arkitektur, design, constraints), og
|
||||||
|
- **task-spesifikk kunnskap** (fase 7 — denne featurens brief).
|
||||||
|
|
||||||
|
Domene-laget er det som svarer "dette er en iOS-app, så her er konvensjonene, mønstrene, fallgruvene, sjekklistene og guardrails som gjelder for *alle* iOS-apper" — slik at hver app ikke gjenoppfinner det.
|
||||||
|
|
||||||
|
**En domain pack er MER enn en Anthropic-skill.** En skill dekker primært *patterns* + delvis *gotchas* + *reference-impl* — den er optimalisert for å lære en agent å gjøre én ting. En domain pack legger til *conventions*, *checklists*, *guardrails* og *scaffolding* som førsteklasses navngitte komponenter, fordi en app-pipeline trenger ikke bare "hvordan gjør jeg X" men også "hvilke ikke-forhandlbare regler gjelder", "hva er fase-exit-kriteriene", og "hvilke fil-templater materialiseres inn i prosjektet". (Research-grunnlag: dekomponering av modne kunnskaps-bunter på tvers av Cursor rules, Copilot instructions, Anthropic skills, Yeoman/Cookiecutter/Copier, ESLint shareable configs, Azure CAF / AWS WAF — `C-domain-packs.md` § 1.)
|
||||||
|
|
||||||
|
**Hva en domain pack IKKE er:**
|
||||||
|
- Ikke en runtime — det finnes ikke noe "domain-pack-engine" som lastes inn. En fase-agent leser `state.json`, resolver pack-stien, leser den/de spesifikke fil(ene) den trenger. Zero eksterne verktøy, zero npm-deps.
|
||||||
|
- Ikke alltid-på. Ingen always-on injeksjon, ingen glob-magi. Eksplisitt fil-sti-lasting per fase (se D4).
|
||||||
|
- Ikke en erstatning for app-spesifikt arbeid. Pakken bærer det *generiske* for domenet; fase 3–5 bærer det *spesifikke* for appen; `pack-overrides.md` lar appen avvike fra pakken der det trengs (se D5).
|
||||||
|
|
||||||
|
## D2 — De 8 komponentene
|
||||||
|
|
||||||
|
Hver komponent er en dedikert fil eller katalog under en `domain-pack/`-rot. Seks av disse åtte gjenkommer pålitelig på tvers av modne kunnskaps-bunter (manifest, conventions, patterns, gotchas, checklists, reference-impl); scaffolding og glossary er domene-avhengige men ofte nyttige.
|
||||||
|
|
||||||
|
| # | Komponent | Fil / katalog | Hva den inneholder | core / supplementary |
|
||||||
|
|---|-----------|---------------|--------------------|--------------------|
|
||||||
|
| 1 | Manifest | `pack.json` | Maskinlesbart metadata — se D3. | core |
|
||||||
|
| 2 | Conventions | `conventions.md` | Domene-spesifikke ikke-forhandlbare beslutninger (plattform-regler, kode-konvensjoner, navnemønstre). Guardrails ligger som underseksjon: regler med enforcement-vekt (App Store-constraints, GDPR-håndtering = conventions du *ikke* avviker fra uten god grunn). | core |
|
||||||
|
| 3 | Patterns | `patterns/` | Én fil per gjenbrukbart mønster (f.eks. `patterns/offline-first-swiftdata.md`, `patterns/command-router.md`). Fasene `Read` spesifikke filer ved behov — aldri hele katalogen. | supplementary (per-fil) |
|
||||||
|
| 4 | Gotchas | `gotchas.md` | Eksplisitt "ikke gjør dette"-liste — kjente fallgruver, ting som ser riktige ut men ikke er det. | core |
|
||||||
|
| 5 | Checklists | `checklist.md` | Fase-exit-kriterier som checkbokser; mapper til brief-validering i fase 7. Standard-baserte sjekklister lever HER (App Store-submission-checklist, MASVS 2.1, WCAG 2.2 AA, privacy-manifest-mal — for `ios-app`; plugin-validator-pass, CLAUDE.md-grade — for `claude-code-plugin`). Dette er komponenten som løser "manglende eierfaser"-problemet (friksjon #7). | core |
|
||||||
|
| 6 | Scaffolding | `scaffold/` | Fil-templater som materialiseres inn i per-app-artefakt-treet (f.eks. `scaffold/PrivacyInfo.xcprivacy`, `scaffold/plugin.json`). Konsumeres av fase 7 / fase 3 når en konkret fil skal opprettes. | supplementary |
|
||||||
|
| 7 | Reference impl | `examples/` | Eksempel-briefer, eksempel-artefakter — konsumeres av brief-generator i fase 6/7 som "slik ser en god feature-brief ut i dette domenet". | supplementary |
|
||||||
|
| 8 | Glossary | `glossary.md` | Domene-vokabular — lastes selektivt (fase 1 ved behov, ved oppslag). | supplementary |
|
||||||
|
|
||||||
|
**Hard lengde-grense per fil:** ~500 ord / én skjerm der mulig. Lange filer er usynlige for agenten (Cursor-erfaringen: regler ignoreres når de blir for lange). Hvis en pattern-fil eller checklist sprenger grensen: del den i flere filer under `patterns/` eller seksjoner i `checklist.md` som lastes uavhengig. `examples/`-filer er unntatt grensen (de er referanse-materiale, ikke instruksjon).
|
||||||
|
|
||||||
|
**Katalog-layout:**
|
||||||
|
```
|
||||||
|
domain-pack/ ({name}/)
|
||||||
|
├── pack.json
|
||||||
|
├── conventions.md
|
||||||
|
├── gotchas.md
|
||||||
|
├── checklist.md
|
||||||
|
├── glossary.md
|
||||||
|
├── patterns/
|
||||||
|
│ ├── {pattern-a}.md
|
||||||
|
│ └── {pattern-b}.md
|
||||||
|
├── scaffold/
|
||||||
|
│ ├── {template-fil-1}
|
||||||
|
│ └── {template-fil-2}
|
||||||
|
└── examples/
|
||||||
|
└── {eksempel-feature-brief}.md
|
||||||
|
```
|
||||||
|
|
||||||
|
## D3 — `pack.json`-skjema
|
||||||
|
|
||||||
|
Minimalt JSON-manifest. Ingen npm-semantikk, ingen build-step, ingen lock-fil.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"schema": "domain-pack/v1",
|
||||||
|
"name": "ios-app",
|
||||||
|
"version": "0.1.0",
|
||||||
|
"domain": "iOS-app-utvikling (Swift/SwiftUI)",
|
||||||
|
"description": "Domene-kunnskap for iOS-app-utvikling med Swift/SwiftUI",
|
||||||
|
"phases": [1, 3, 4, 5, 6, 7],
|
||||||
|
"verified": { "date": "2026-05-11", "against": "iOS 18, HIG WWDC2025, MASVS 2.1, WCAG 2.2" }
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
| Felt | Type | Påkrevd | Betydning |
|
||||||
|
|------|------|---------|-----------|
|
||||||
|
| `schema` | string | ja | Skjema-versjon. `"domain-pack/v1"` for nå. Bumps hvis manifest-strukturen endres. |
|
||||||
|
| `name` | string | ja | Pakke-navn, URL-trygg slug. Brukes i `@`-notasjon (`ios-app@0.1.0`) og i `00-context/domain-pack-{name}.md`. |
|
||||||
|
| `version` | string | ja | Uformell semver — se D5. |
|
||||||
|
| `domain` | string | ja | Menneskelesbar domene-beskrivelse. |
|
||||||
|
| `description` | string | ja | Én-linjes formålsbeskrivelse. |
|
||||||
|
| `phases` | number[] | ja | Hvilke pipeline-faser som *kan* laste fra pakken (1–7). En fase som ikke er i lista laster ikke pack-filer. |
|
||||||
|
| `verified` | object | ja | `{ "date": "YYYY-MM-DD", "against": "..." }` — sist-verifisert-dato + mot hvilken versjon av domenet (iOS-versjon, HIG-utgave, standard-versjoner). Gjør at man ser når en pakke er i ferd med å råtne. |
|
||||||
|
|
||||||
|
Ingenting i `pack.json` er menneske-leselig *innhold* — alt innhold lever i markdown-filene. Manifestet er kun maskinlesbart metadata.
|
||||||
|
|
||||||
|
## D4 — Referanse / aktiverings-mekanisme
|
||||||
|
|
||||||
|
**Eksplisitt fil-sti-lasting per fase.** Hver fase-prompt (i `phase-design-draft.md`) lister hvilke pack-filer den `Read`-er ved oppstart — progressive disclosure, verbatim fra Anthropic-skill-mønsteret. Ingen glob-magi, ingen always-on injeksjon. Eksempel (fra `phase-design-draft.md` § Domain-pack-konsumering):
|
||||||
|
|
||||||
|
| Fase | `Read`-er typisk |
|
||||||
|
|------|------------------|
|
||||||
|
| 1 (intervju) | `conventions.md`, evt. `glossary.md` |
|
||||||
|
| 3 (arkitektur) | `conventions.md`, `patterns/{relevant}.md` (max 1–2), evt. `gotchas.md` |
|
||||||
|
| 4 (designsystem) | `conventions.md`, `patterns/{ui-relevant}.md` |
|
||||||
|
| 5 (constraints) | `checklist.md`, `gotchas.md` |
|
||||||
|
| 6 (feature-derivasjon) | `checklist.md`, evt. `examples/` |
|
||||||
|
| 7 (feature-brief) | `checklist.md`, `examples/`, `scaffold/` (når artefakter materialiseres) |
|
||||||
|
|
||||||
|
**Max-3-regel.** En fase laster aldri mer enn 3 pack-filer ved oppstart. Trenger den en fjerde underveis (en spesifikk `patterns/`-fil), leser den den når behovet oppstår — den preloader ikke. Dette holder kontekst-budsjettet ledig for nedstrøms-faser (arvet fra kiur og `phase-design-draft.md` § Context Budget).
|
||||||
|
|
||||||
|
**`domain_pack`-felt i `state.json`** og i app-artefaktenes frontmatter: `domain_pack: "ios-app@0.1.0"`. Pack-identiteten er del av app-state. `null` hvis appen ikke bruker en pack.
|
||||||
|
|
||||||
|
**Materialisert snapshot i `00-context/`.** Ved init av app-creator-instansen (eller når en pack legges til) materialiseres et snapshot av pakken — versjonen appen bruker — inn i `{app-creator-instance-dir}/00-context/domain-pack-{name}.md`. Snapshotet er en sammenslått, lesbar form av pakkens core-komponenter (conventions + gotchas + checklist + de patterns appen faktisk bruker), med pack-versjonen innskrevet i toppen. Begrunnelse: embedding slår linking for AI-konsum (BMAD-prinsippet) — fase 7-`context.md` embedder utdrag fra dette snapshotet, ikke pekere til en ekstern pakke som kan ha endret seg. (Copier-mønsteret: den genererte appen "kjenner" sin egen versjon av kilden.)
|
||||||
|
|
||||||
|
**core vs supplementary-merking.** Hver pack-fil merkes `core` (alltid relevant for de fasene den gjelder) eller `supplementary` (lastes kun ved eksplisitt behov). Snapshotet i `00-context/` inkluderer core-komponentene; supplementary lastes on-demand fra `domain-packs/{name}/` direkte.
|
||||||
|
|
||||||
|
**Ingen runtime-framework.** Hele mekanikken er: fase-agent leser `state.json` → finner `domain_pack`-verdien → resolver stien (`domain-packs/{name}/` i plugin-roten) → leser den/de fil(ene) fase-prompten ber om → bruker `00-context/`-snapshotet for embedding i fase 7. Matcher filsystem-som-state-invarianten. Zero eksterne verktøy.
|
||||||
|
|
||||||
|
## D5 — Versjonering
|
||||||
|
|
||||||
|
**`version` følger semver-semantikk uformelt:**
|
||||||
|
- **major** — breaking: fjerne en komponent, rename et `pack.json`-felt, endre `schema`, omstrukturere `checklist.md` slik at fase 7-brief-validering bryter.
|
||||||
|
- **minor** — additivt: ny `patterns/`-fil, nye checklist-items, ny scaffold-template.
|
||||||
|
- **patch** — fixes: rette en gotcha, oppdatere `verified.date`, korrigere en konvensjon uten å endre dens betydning.
|
||||||
|
|
||||||
|
En breaking pack-bump behandles som det den er: skriv et changelog-notat (i pakkens egen `CHANGELOG.md` hvis den vokser dit, ellers i app-creators CHANGELOG), bump major. Inntil pakker ekstraheres til eget repo er versjons-feltet primært dokumentasjon — ingen lock-fil trengs fordi forfatteren er eneste konsument og pakker committes sammen med app-creator. `@`-notasjonen (`ios-app@0.1.0`) muliggjør framtidig snapshot-pinning via git-tag hvis en pakke senere får eget repo.
|
||||||
|
|
||||||
|
**Skriv pack-versjon inn i app-artefakter.** `domain_pack: "ios-app@0.1.0"` i `state.json`, i hver brief-frontmatter (fase 1–6) og i fase 7-`brief.md`. Toppen av `00-context/domain-pack-{name}.md`-snapshotet skriver hvilken pack-versjon det er et snapshot av, og hvilken dato det ble materialisert. Slik vet man alltid hvilken pack-versjon som genererte et gitt prosjekt — selv om pakken senere endrer seg. (Copier-mønsteret.)
|
||||||
|
|
||||||
|
**`pack-overrides.md` som escape hatch — first-class.** Ethvert pack-felt skal kunne overrides per-app via `{app-creator-instance-dir}/00-context/pack-overrides.md`. Aldri hardkode en pack-verdi uten at app-konteksten kan si "for denne appen, ikke dette" (Projen-lærdommen: "stivhet uten fluktvei = tidsbomb"). `pack-overrides.md` er en enkel markdown-fil: en seksjon per overstyring, med (a) hvilken pack-fil/regel som overstyres, (b) hva den nye verdien er, (c) hvorfor. Fase-agentene leser `pack-overrides.md` *sammen med* pack-filene og lar override-en vinne ved konflikt. Eksempel:
|
||||||
|
|
||||||
|
```markdown
|
||||||
|
# Pack-overrides — {app-slug}
|
||||||
|
|
||||||
|
## conventions.md → "min-iOS-versjon"
|
||||||
|
**Pack sier:** iOS 18 baseline.
|
||||||
|
**Denne appen:** iOS 17 baseline.
|
||||||
|
**Hvorfor:** målgruppen har eldre enheter; verifisert mot {kilde}.
|
||||||
|
|
||||||
|
## checklist.md → "App Privacy Details — tracking"
|
||||||
|
**Pack sier:** fyll ut tracking-seksjon.
|
||||||
|
**Denne appen:** N/A — appen sporer ingenting, ingen SDK-er med tracking.
|
||||||
|
**Hvorfor:** all-local, ingen analytics.
|
||||||
|
```
|
||||||
|
|
||||||
|
**Lagrings-sted (S5-beslutning): `domain-packs/` i plugin-roten.** Pakker committes sammen med app-creator-pluginen. Alternativet — `~/.claude/domain-packs/` (delt globalt på tvers av apper) — vurderes hvis det blir behov for å dele pakker mellom app-creator-instanser i ulike repos, eller hvis en pakke vokser nok til å fortjene eget repo. Inntil da: i plugin. (Begrunnelse: forfatteren er eneste konsument, fork-and-own-modellen tilsier at pakkene er en del av pluginen man forker, ingen lock-fil trengs.)
|
||||||
|
|
||||||
|
## D6 — Voyage-agnostisk håndtering
|
||||||
|
|
||||||
|
Når en feature-brief overleveres til Voyage (fase 7):
|
||||||
|
- Relevant pack-utdrag embeddes i `features/{NN}-{slug}/context.md` — **ikke i `brief.md`**. `brief.md` er den rene Voyage-kontrakten (Handover 1); `context.md` er det implementerers-agenten leser for å forstå kontrakten.
|
||||||
|
- Voyage ser **kun en velformet brief + en kontekst-fil**. Ingen "domain-pack-generert"-merking, ingen pack-navn, ingen pack-versjon synlig for Voyage. Pack-identiteten er app-creator-intern state — den lever i `state.json` og i app-artefaktenes frontmatter, ikke i det som overleveres.
|
||||||
|
- Voyage vet ikke at domain-packs finnes, og skal ikke vite det. Asymmetrien er bevisst (samme prinsipp som "Voyage vet ikke om app-creator" i `CLAUDE.md`): det er det som lar lag 1 (Voyage) og lag 2 (app-creator) utvikles uavhengig uten å lekke ansvar.
|
||||||
|
|
||||||
|
Praktisk: når fase 7 skriver `context.md`, henter den relevante avsnitt fra `00-context/domain-pack-{name}.md`-snapshotet (med `pack-overrides.md` anvendt), parafraserer/utdrag-er dem inn under `## Domain-pack-utdrag`-seksjonen som *bare kontekst* — uten metadata om hvor det kom fra.
|
||||||
|
|
||||||
|
## D7 — Referanse-pakkene (skisse — S6 forfatter dem)
|
||||||
|
|
||||||
|
app-creator shipper to referanse-pakker som eksempel-implementasjoner. Fork-and-own-brukere lager egne. **Disse skisseres her, ikke spesifiseres — S6 er forfatter-sesjonen.**
|
||||||
|
|
||||||
|
### `ios-app`-pakke (fra Akashics reelle behov)
|
||||||
|
|
||||||
|
- **`pack.json`:** `name: "ios-app"`, `version: "0.1.0"`, `phases: [1, 3, 4, 5, 6, 7]`, `verified` mot iOS 18 / HIG WWDC2025 / MASVS 2.1 / WCAG 2.2.
|
||||||
|
- **`conventions.md`:** HIG-regler (navigasjon, layout, "Liquid Glass"-konformans-notat); Swift/SwiftUI-konvensjoner; MVVM-vs-TCA-veiledning (når hva); min-iOS-versjon-policy; guardrails-underseksjon (App Store-constraints du ikke avviker fra; GDPR-håndtering).
|
||||||
|
- **`patterns/`:** `offline-first-swiftdata.md`, `local-notifications.md`, `widget-live-activities-shared-model.md` (deling av datamodell mellom app/widget/Live Activity), `current-location-regeneration.md` (current-location-basert beregning + fallback ved nektet permission).
|
||||||
|
- **`gotchas.md`:** required-reason-API-deklarasjon (manglende = avvisning); ATS-unntak uten begrunnelse; `NSUsageDescription` manglende = umiddelbar App Store-avvisning; vanlige App Store Review-avvisnings-triggere.
|
||||||
|
- **`checklist.md`:** App Store-submission-checklist (aldersmerking, screenshot-spec, eksport-compliance, region-krav DSA/ICP/GRAC, App Store Connect-metadata); MASVS 2.1-checklist (8 kontroll-grupper); WCAG 2.2 AA-checklist (inkl. de 4 nye 2.2-kriteriene); privacy-manifest-mal (`PrivacyInfo.xcprivacy`-felter, per-SDK-krav); App Privacy Details "nutrition label"-felter.
|
||||||
|
- **`scaffold/`:** `PrivacyInfo.xcprivacy`-mal; `NSUsageDescription`-inventar-mal; App Store Connect-metadata-mal.
|
||||||
|
- **`examples/`:** ett eksempel-feature-brief for en iOS-feature (sannsynligvis avledet fra en faktisk Akashic-feature etter at Akashic når fase 7).
|
||||||
|
- **`glossary.md`:** iOS/App Store-vokabular (TestFlight, App Review, entitlements, capabilities, ATT, ATS, …).
|
||||||
|
|
||||||
|
### `claude-code-plugin`-pakke (ekstraksjon fra eksisterende CLAUDE.md + `.claude/rules/`)
|
||||||
|
|
||||||
|
- **`pack.json`:** `name: "claude-code-plugin"`, `version: "0.1.0"`, `phases: [1, 3, 5, 6, 7]` (sannsynligvis ikke 4 — plugins har sjelden et "designsystem").
|
||||||
|
- **`conventions.md`:** `plugin.json`-manifest-regler; frontmatter-regler (commands/agents/skills) fra ktg-privat CLAUDE.md; navnekonvensjoner (`command.md`, `descriptive-name-agent.md`, `skill-name/SKILL.md`); context-budget-regler (max-3, ingen hele-katalog-lasting, progressive disclosure).
|
||||||
|
- **`patterns/`:** `command-router.md`; `agent-definition.md`; `skill-progressive-disclosure.md`; `three-layer-architecture.md` (à la kiur).
|
||||||
|
- **`gotchas.md`:** `hooks` er objekt ikke array; `matcher` er string ikke nestet objekt; ikke deklarer `"hooks"` i `plugin.json` (auto-discovers); aldri last hele kataloger.
|
||||||
|
- **`checklist.md`:** plugin-validator-pass; CLAUDE.md grade B (70+); hook-format-regler; CLAUDE.md-vedlikehold-i-samme-commit-regel.
|
||||||
|
- **`scaffold/`:** plugin-katalog-skjelett (`.claude-plugin/plugin.json`, `commands/`, `agents/`, `skills/`, `hooks/hooks.json`, `README.md`).
|
||||||
|
- **`examples/`:** eksisterende plugin-strukturer i ktg-privat som referanse (kiur for 3-lags-arkitektur, harness for "ikke last alt på en gang", vegnormalene for ren MCP/RAG).
|
||||||
|
- **`glossary.md`:** plugin-vokabular (slash-command, subagent, hook-event, skill, marketplace, `${CLAUDE_PLUGIN_ROOT}`, …).
|
||||||
|
|
||||||
|
## Åpne spørsmål / restrisiko
|
||||||
|
|
||||||
|
- **Snapshot-materialiserings-mekanikk.** Nøyaktig hvordan `00-context/domain-pack-{name}.md` genereres fra `domain-packs/{name}/` (hvilke filer slås sammen, i hvilken rekkefølge, hvor mye trimmes) — låses når den første pakken faktisk materialiseres i S7. Inntil da: "core-komponentene, sammenslått, pack-versjon innskrevet".
|
||||||
|
- **`pack.md` med YAML-frontmatter som alternativ til `pack.json`.** Thread C nevnte begge. S5-valg: `pack.json` (rent maskinlesbart, ingen risiko for at noen putter innhold i frontmatter). Revurderes hvis det viser seg upraktisk.
|
||||||
|
- **Når en fase trenger en `patterns/`-fil som ikke er i `phases`-lista.** Skal pakken da utvides, eller skal fasen klare seg uten? Sannsynlig: utvid pakken (en pattern relevant for en fase hører i pakken) — men det er en S6+-beslutning per konkret tilfelle.
|
||||||
|
- **Pakke-deling på tvers av repos.** Hvis app-creator-instanser i ulike repos vil dele samme `ios-app`-pakke: da må lagrings-stedet flyttes til `~/.claude/domain-packs/` eller eget repo. Ikke et problem så lenge forfatteren er eneste konsument med pakkene i plugin-roten.
|
||||||
|
|
||||||
|
## Kilder
|
||||||
|
|
||||||
|
- `prototype-run/research/research-brief.md` § 5 (D1–D7) — innholds-mandatet denne spec-en realiserer.
|
||||||
|
- `prototype-run/research/C-domain-packs.md` — dekomponering av modne kunnskaps-bunter (Cursor rules, Copilot instructions, Anthropic skills, Yeoman/Cookiecutter/Copier, ESLint shareable configs, Azure CAF / AWS WAF) + erfaringsrapporter (Cursor-drift, eslint-config-love breaking changes, Projen escape-hatches).
|
||||||
|
- `prototype-run/research/D-feature-artifacts.md` § 2 — BMAD-prinsippet (embedding slår linking for AI-konsum) som begrunner `00-context/`-snapshot framfor ekstern peker.
|
||||||
|
- `prototype-run/friksjon.md` #5 (flat layout antok ikke domain-pack-kontekst), #7 (tre sjekkliste-grupper uten eierfase — løses av `checklist.md`-komponenten).
|
||||||
|
- `phase-design-draft.md` — fase-seksjonene som konsumerer pakkene; `CLAUDE.md` — verktøy-agnostisk- og Voyage-agnostisk-invariantene D6 respekterer.
|
||||||
File diff suppressed because it is too large
Load diff
|
|
@ -5,6 +5,10 @@
|
||||||
**Prototype-app:** akashic-intelligence
|
**Prototype-app:** akashic-intelligence
|
||||||
**Startet:** 2026-05-10
|
**Startet:** 2026-05-10
|
||||||
|
|
||||||
|
## Prototype-protokoll-tillegg (R17, lagt til 2026-05-11 / S5)
|
||||||
|
|
||||||
|
**Mål faktisk fase-overhead-tid i Akashic-kjøringen.** Per fase som kjøres (2–7): noter omtrentlig tid brukt og hvilken artefakt fasen produserte. En fase som tar timer og produserer en artefakt ingen Voyage-brief refererer = bevist seremoni → kandidat for å bli skippbar-by-default eller fjernes (jf. thread E). Loggføres i `SESSION-LOG.local.md` per fase-sesjon, oppsummeres i en revisjon av `phase-design-draft.md` § "Når dette utkastet skal oppdateres".
|
||||||
|
|
||||||
## Format
|
## Format
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
@ -32,6 +36,8 @@
|
||||||
|
|
||||||
Anbefaler (A) for renere kontrakt — `app.md` blir identitets-fil only, intent-fil-en er `01-app-brief.md`.
|
Anbefaler (A) for renere kontrakt — `app.md` blir identitets-fil only, intent-fil-en er `01-app-brief.md`.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R12, alternativ A). `phase-design-draft.md` § Pre-pipeline: init samler kun identitets-data (slug, navn, plattform, dato, evt. domain-pack); "Hvorfor denne appen" er tom ved init, genereres retrospektivt etter fase 1 complete som destillering av app-brief Problem & motivasjon; "Pre-fase-notater" fjernet helt.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #2: Kvalitets-sjekk #1 forutsetter artefakten den skal validere
|
## #2: Kvalitets-sjekk #1 forutsetter artefakten den skal validere
|
||||||
|
|
@ -48,6 +54,8 @@ Anbefaler (A) for renere kontrakt — `app.md` blir identitets-fil only, intent-
|
||||||
|
|
||||||
Eller: omformuler #1 til "Har vi nok materiale i transkriptet til å skrive et problem & motivasjon-avsnitt operatør vil stå bak?" — da er det besvarbart før draft.
|
Eller: omformuler #1 til "Har vi nok materiale i transkriptet til å skrive et problem & motivasjon-avsnitt operatør vil stå bak?" — da er det besvarbart før draft.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R12). `phase-design-draft.md` § Fase 1 § Kjøre-disiplin disiplin 5: kvalitets-sjekken splittet — 5 pre-draft-spørsmål (besvarbare fra transkriptet, inkl. omformulert #1: "Har vi nok materiale ...?") + 1 post-draft-spørsmål ("Står operatør bak problem & motivasjon-avsnittet slik AI formulerte det?"). Gjelder kun full-variant; minimal-variant har ingen kvalitets-sjekk.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #3: "Omfang innenfor"-spørsmålet henter produkt-kvaliteter, ikke features
|
## #3: "Omfang innenfor"-spørsmålet henter produkt-kvaliteter, ikke features
|
||||||
|
|
@ -64,6 +72,8 @@ Eller: omformuler #1 til "Har vi nok materiale i transkriptet til å skrive et p
|
||||||
|
|
||||||
Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features-hypotese til standard neste-steg i Omfang-fasen i stedet for en ad-hoc redning.
|
Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features-hypotese til standard neste-steg i Omfang-fasen i stedet for en ad-hoc redning.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R12 + R13). `phase-design-draft.md` § Fase 1 § Kjøre-disiplin disiplin 2 (Anchor/Sharpen): Omfang skiller eksplisitt "Hva appen GJØR" (funksjonelle features → fase 1-brief, driver fase 6) fra "Hvordan appen ER" (kvalitative egenskaper → fase 4/5); AI-foreslått funksjonell-features-hypotese er nå standard neste steg, ikke ad-hoc redning. App-brief-templaten har egen "Innenfor (funksjonelle features — 'hva appen GJØR')"-overskrift + en distinkt "Rabbit holes"-seksjon (R13).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #4: Skala-/eierskaps-rekalibrering kom for sent i intervjuet
|
## #4: Skala-/eierskaps-rekalibrering kom for sent i intervjuet
|
||||||
|
|
@ -76,6 +86,8 @@ Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features
|
||||||
|
|
||||||
**Foreslått revisjon:** Legg til et tidlig spørsmål — Tur 1 eller 2, under Problem & motivasjon — om eierskap/intensjon: "Hvem er dette egentlig for: deg selv, andre, eller begge? Og hvis du måtte velge én — hvilken vinner når de er i konflikt?" Dette rammer alle påfølgende svar riktig fra start.
|
**Foreslått revisjon:** Legg til et tidlig spørsmål — Tur 1 eller 2, under Problem & motivasjon — om eierskap/intensjon: "Hvem er dette egentlig for: deg selv, andre, eller begge? Og hvis du måtte velge én — hvilken vinner når de er i konflikt?" Dette rammer alle påfølgende svar riktig fra start.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R12 + R13). `phase-design-draft.md` § Fase 1: "Tidlig eierskaps-spørsmål" stilles som ett av de første spørsmålene i begge varianter ("Hvem er dette egentlig for ... hvilken vinner ved konflikt?"); weakest-section-loopen i full-variant starter med "Eierskap & intensjon" før "Problem & motivasjon"; app-brief-templaten har egen "Eierskap & intensjon"-seksjon. I tillegg lagt til "Appetite / scope-budsjett" tidlig (R13 — adresserer at skala-rekalibreringen i Akashic kom for sent).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #5: Flat artefakt-layout antok ikke per-feature-akkumulering eller domain-pack-kontekst
|
## #5: Flat artefakt-layout antok ikke per-feature-akkumulering eller domain-pack-kontekst
|
||||||
|
|
@ -92,6 +104,8 @@ Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features
|
||||||
- Skriv en domene-nøytral `domain-pack-spec.md`: hva en pakke inneholder (konvensjoner, patterns, gotchas, scaffolding, review-kriterier, referanse-impl), hvilket format, hvordan fasene 3-7 konsumerer den, hvordan den refereres i Voyage-handover uten å bryte Voyage-agnostisk-invarianten.
|
- Skriv en domene-nøytral `domain-pack-spec.md`: hva en pakke inneholder (konvensjoner, patterns, gotchas, scaffolding, review-kriterier, referanse-impl), hvilket format, hvordan fasene 3-7 konsumerer den, hvordan den refereres i Voyage-handover uten å bryte Voyage-agnostisk-invarianten.
|
||||||
- app-creator shipper referanse-pakker (ios-app, claude-code-plugin) som eksempel-implementasjoner; fork & own-brukere lager egne.
|
- app-creator shipper referanse-pakker (ios-app, claude-code-plugin) som eksempel-implementasjoner; fork & own-brukere lager egne.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt fullt (R1 + ny `docs/domain-pack-spec.md`). `phase-design-draft.md` § Filsystem-layout: flat `07-feature-briefs/{NN}-{slug}.md` erstattet med `features/{NN}-{slug}/` (`brief.md` + `context.md` obligatoriske, + valgfritt `research.md`/`design-ref.md`/`voyage_run.md`); `00-context/` lagt til (materialiserte domain-pack-snapshots + `pack-overrides.md`). `domain-pack-spec.md` skrevet domene-nøytralt: 8-komponent-liste med fil-navn, `pack.json`-skjema, eksplisitt-fil-sti-lasting + max-3-regel + materialisert snapshot, uformell semver med `pack-overrides.md` som first-class escape hatch, Voyage-agnostisk håndtering (pack-utdrag embeddes i `context.md`, aldri "domain-pack-generert"-merking). Lagrings-sted besluttet: `domain-packs/` i plugin-roten.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #6: Design-utkastet behandler hver fase som om den skjer i én sitting
|
## #6: Design-utkastet behandler hver fase som om den skjer i én sitting
|
||||||
|
|
@ -106,6 +120,8 @@ Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features
|
||||||
|
|
||||||
**S2-oppdatering (2026-05-11):** Design-research thread A bekrefter dette som hard teknisk nødvendighet, ikke pynt. BMAD Discussion #74 / Issue #1343: agent-kontekst degraderer etter 3-4 runder, og store mellomdokumenter (arkitektur, design-tokens, full backlog) spiser kontekst-budsjett nedstrøms-faser trenger. Anbefaling fra research: faser som produserer store artefakter MÅ kunne kjøres i egen sesjon; domain-packs lastes selektivt (max-3-regel à la kiur). Se `research/A-prior-art.md` § P3.
|
**S2-oppdatering (2026-05-11):** Design-research thread A bekrefter dette som hard teknisk nødvendighet, ikke pynt. BMAD Discussion #74 / Issue #1343: agent-kontekst degraderer etter 3-4 runder, og store mellomdokumenter (arkitektur, design-tokens, full backlog) spiser kontekst-budsjett nedstrøms-faser trenger. Anbefaling fra research: faser som produserer store artefakter MÅ kunne kjøres i egen sesjon; domain-packs lastes selektivt (max-3-regel à la kiur). Se `research/A-prior-art.md` § P3.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R3). `phase-design-draft.md` § Flersesjons-protokoll: den improviserte protokollen (`SESSION-ROADMAP` + `NEXT-SESSION-PROMPT` + `SESSION-LOG`, `/clear` mellom sesjoner, "Les og følg ... nøyaktig" som re-entry) er formalisert som dokumentert praksis; faser som produserer store mellomdokumenter MÅ kunne kjøres i egen sesjon. **Beslutning:** dokumentert praksis + lett `state.json`-felt (`session.current`, `session.next_action`, `session.log`) — IKKE innebygd `trekcontinue`-aktig mekanikk ennå (YAGNI; vurderes hvis prototypen viser at manuell protokoll ikke holder). Også lagt til hard lengde-grense per artefakt (R7, ≤500 ord / én skjerm) som adresserer at store mellomdokumenter spiser budsjett.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #7: Tre sjekkliste-grupper har ingen eierfase (G9 App Store-submission, G11 test-strategi, G12 release/ops-grense)
|
## #7: Tre sjekkliste-grupper har ingen eierfase (G9 App Store-submission, G11 test-strategi, G12 release/ops-grense)
|
||||||
|
|
@ -122,6 +138,8 @@ Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features
|
||||||
|
|
||||||
**S3-bekreftelse (2026-05-11):** Thread C (domain-packs) dekomponerte en moden kunnskaps-bunt i 8 komponenter; checklists + guardrails (App Store-submission-checklist, MASVS 2.1, WCAG 2.2, privacy-manifest-mal) er nettopp det en `ios-app`-pack bærer. Beslutning bekreftet som riktig retning — `domain-pack-spec.md` skrives i S5 med komponent-liste, `pack.json`-format, eksplisitt-fil-sti-lasting + materialisert snapshot i `00-context/`, semver-uformell versjonering med per-app `pack-overrides.md` som escape hatch. Se `research/C-domain-packs.md`.
|
**S3-bekreftelse (2026-05-11):** Thread C (domain-packs) dekomponerte en moden kunnskaps-bunt i 8 komponenter; checklists + guardrails (App Store-submission-checklist, MASVS 2.1, WCAG 2.2, privacy-manifest-mal) er nettopp det en `ios-app`-pack bærer. Beslutning bekreftet som riktig retning — `domain-pack-spec.md` skrives i S5 med komponent-liste, `pack.json`-format, eksplisitt-fil-sti-lasting + materialisert snapshot i `00-context/`, semver-uformell versjonering med per-app `pack-overrides.md` som escape hatch. Se `research/C-domain-packs.md`.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt (R10 + R11 + `domain-pack-spec.md`). `domain-pack-spec.md` § D2: `checklist.md`-komponenten bærer App Store-submission-checklist, MASVS 2.1, WCAG 2.2 AA, privacy-manifest-mal — den eksplisitt nevnte løsningen på "manglende eierfaser". `phase-design-draft.md` § Scope-lås: ny "Release/ops-grensen"-underseksjon gjør grensen eksplisitt (app-brief eier scope-relevante release-valg: distribusjons-modell, analytics ja/nei, versjonerings-strategi; domain-pack-checklist eier operasjonelle submission-artefakter; force-upgrade/TestFlight/ASO/marketing eksplisitt utenfor). Test-strategi: ikke egen fase — strategi-beslutninger som constraints i fase 5 (strukturert mot domain-pack-checklist), infrastruktur som `F-T`-features i fase 6. `phase-design-draft.md` § Fase 5: constraints-brief-templaten har navngitte underseksjoner mot ISO/IEC 25010:2023 (9 karakteristikker, særlig de nye Safety + Flexibility), WCAG 2.2 AA (de 4 nye 2.2-kriteriene navngitt), OWASP MASVS 2.1 (8 kontroll-grupper), privacy manifest (`PrivacyInfo.xcprivacy`, App Privacy Details) — som referanse, med checklisten i domain-pack-en som det uttømmende grunnlaget. Fase 5 er nå merket SKIPPBAR (bæres av domain-pack-checklists for apper som følger defaults).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## #8: Pipeline-designet antar "full pipeline" som default — solo-dev-bruk + contrarian-research tilsier "brief-first, faser som opt-in"
|
## #8: Pipeline-designet antar "full pipeline" som default — solo-dev-bruk + contrarian-research tilsier "brief-first, faser som opt-in"
|
||||||
|
|
@ -134,4 +152,10 @@ Eventuelt: aksepter at operatør gir kvaliteter, og gjør AI-foreslått-features
|
||||||
|
|
||||||
**Foreslått revisjon (avgjøres S4-syntese / S5):** (a) Innfør en eksplisitt "rapid mode" / "sketch brief"-sti — konsept → minimal-men-gyldig app-brief inline → fase 7 feature-brief, uten å passere 2-6; den fulle pipelinen blir eskalering, ikke default. (b) Faser skippbare med eksplisitt én-setnings-begrunnelse loggført i `state.json` (ikke bare "valgfri"). (c) Hard lengde-grense per fase-artefakt (≤500 ord / én skjerm der mulig) — lengde er sterkeste seremoni-signalet. (d) Arkitektur-fasen produserer *åpne spørsmål som lukkes etterpå*, ikke en decisions-log skrevet før koden (decisions-log før kode = grunnlag for spec-drift). (e) Legg til i prototype-protokollen: mål faktisk tid brukt per fase i Akashic-kjøringen; en fase som tar timer og produserer en artefakt ingen Voyage-brief refererer = bevist seremoni. NB: dette *skjerper* thread A's takeaway ("strukturen er solid, men risikoen er at den blir for tung") til "risikoen er ikke bare for tung — det er feil default-retning". Se `research/E-contrarian.md`.
|
**Foreslått revisjon (avgjøres S4-syntese / S5):** (a) Innfør en eksplisitt "rapid mode" / "sketch brief"-sti — konsept → minimal-men-gyldig app-brief inline → fase 7 feature-brief, uten å passere 2-6; den fulle pipelinen blir eskalering, ikke default. (b) Faser skippbare med eksplisitt én-setnings-begrunnelse loggført i `state.json` (ikke bare "valgfri"). (c) Hard lengde-grense per fase-artefakt (≤500 ord / én skjerm der mulig) — lengde er sterkeste seremoni-signalet. (d) Arkitektur-fasen produserer *åpne spørsmål som lukkes etterpå*, ikke en decisions-log skrevet før koden (decisions-log før kode = grunnlag for spec-drift). (e) Legg til i prototype-protokollen: mål faktisk tid brukt per fase i Akashic-kjøringen; en fase som tar timer og produserer en artefakt ingen Voyage-brief refererer = bevist seremoni. NB: dette *skjerper* thread A's takeaway ("strukturen er solid, men risikoen er at den blir for tung") til "risikoen er ikke bare for tung — det er feil default-retning". Se `research/E-contrarian.md`.
|
||||||
|
|
||||||
|
**S5-bekreftelse (2026-05-11):** Anvendt fullt (R5–R9, R14, R17). `phase-design-draft.md` ny § "Den sentrale design-spenningen (S5-stillingstaken)" + workflow-oversikten omtegnet som **eskalerings-stige** (default er kort; hver ekstra fase er et bevisst valg). (a) Rapid mode: ny § + egen gren i workflow-diagrammet — app-konsept → minimal-men-gyldig app-brief → fase 7, uten 2–6; minimal-men-gyldig = problem & motivasjon + målgruppe + ≥1 suksess-kriterium + ikke-tom utenfor-liste + plattform. (b) Skippbare faser: fase 2/4/5 merket SKIPPBAR; `state.json` `phase_status` aksepterer `{"status": "skipped", "reason": "..."}`-objekt. (c) Hard lengde-grense: ny § (≤500 ord / én skjerm), `length_words`-felt i alle interne brief-frontmatter, overskridelse = review-flagg. (d) Fase 3: ADR-er skrives idet beslutningen tas; egen "Uavklarte arkitektur-spørsmål (AQ-NNN)"-seksjon som lukkes etter hvert; problem-gate (PR/FAQ-stil) + requirements-first-vs-design-first-spørsmål før fasen (R14). (e) R17: lagt til i prototype-protokollen i denne fila (§ Prototype-protokoll-tillegg) — mål fase-overhead-tid i Akashic-kjøringen. I tillegg: fase 1 har nå minimal-variant (default, kort fritekst) vs full-variant (opt-in, 6-tema-intervju med trekbrief-disipliner) — adresserer "å intervjue seg selv er rituell nedskriving"; fase 4 trigges på bruk (R8 — aktiveres etter første Voyage-UI-komponenter, ellers HIG/Material direkte); implementation-readiness-check (PASS/CONCERNS/FAIL) før fase 7-handover (R14).
|
||||||
|
|
||||||
|
## Ny friksjon oppstått i S5
|
||||||
|
|
||||||
|
Ingen ny design-friksjon. S5 var en ren revisjons-/spec-skrivings-sesjon mot research-brief-mandatet — ingen reell pipeline-kjøring som kunne avsløre nye gap. Prosess-merknad: revisjonen av `phase-design-draft.md` ble stor (førsteutkast ~900 linjer → andreutkast tilsvarende), men holdt seg innenfor token-budsjett ved å skrives som ett `Write`-kall etter at all kontekst var lest. Neste reelle friksjons-belegg kommer når Akashic kjøres videre (fase 2+) i S8+.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue