Kjell Tore Guttormsen
a96b3a9989
brief_version 2.0 → 2.2 (framing + phase_signals + ## TL;DR), re-verifisert
mot voyage/5.9.1 HANDOVER-CONTRACTS.md + trekbrief-template.md 2026-08-11.
Framing-avledningsregel (preserve/refine + operatør-overstyring), phase_signals
med begrunnet "standard"-default (ikke phase_signals_partial — fase 7 har intet
intervju å avbryte), TL;DR-generatorregel.
Handover-mekanikk (R-03) definert og verifisert mot kildekode, ikke antatt:
masterplanens anbefalte "loose-modus konsekvent" er ikke teknisk mulig —
/trekresearch har intet --brief-flagg og krever en pre-eksisterende --project
<dir>. app-creator standardiserer derfor project_dir på
features/{NN}-{slug}/voyage/ med et eksplisitt materialiserings-steg
(mkdir+cp) foran konsekvent --project-bruk for research/plan/execute — fikser
R-03s BRIEF_NOT_FOUND-feilscenario. research.md-rollen avklart ærlig som
app-creator-internt underlagsmateriale, ikke Voyage-input (R-04) — konsum
IKKE verifisert, avgjøres i B1.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EmQGwa3dQ36fjRGfZS7wmS
92 KiB
Phase-design-utkast: app-creators pipeline
Hvorfor dette dokumentet finnes
Den manuelle iOS-prototypen (Akashic Intelligence) trenger et startpunkt. Uten skisse av faser, artefakter og transisjoner blir hver fase ad-hoc improvisert, og friksjons-loggen mister konsistens på tvers av sesjoner.
Dette dokumentet er arbeidshypoteser, ikke spesifikasjon. Hver brief-template her er et utgangspunkt prototypen skal stress-teste. Andreutkastet (S5) er revidert mot design-research (threads A–E, syntetisert i prototype-run/research/research-brief.md) — men kun fase 1 har faktisk friksjons-belegg fra Akashic-kjøringen. Resten er fortsatt hypotese.
Den sentrale design-spenningen (S5-stillingstaken)
Design-researchen avdekket en reell spenning: prior art (threads A, B) sier "strukturen er riktig — fyll gapene"; den contrarian tråden (E) sier "default-retningen er feil — for en solo-dev som bygger en liten app for seg selv er fem av syv faser spekulativ infrastruktur, brief-first ikke full-pipeline-first." S5-stillingstaken (operatør kan overstyre):
- Minimal-men-gyldig app-brief er obligatorisk anker. Aldri hoppbar — uten den hallusinerer AI-en nedstrøms. Men "minimal" kan bety en kort fritekst-variant (
problem-statement + åpne spørsmål), ikke det fulle 8-tema-intervjuet med kvalitets-sjekk. - Fase 2 / 4 / 5 er skippbare med eksplisitt én-setnings-begrunnelse loggført i
state.json— ikke bare "valgfri", men "Hopper over designsystem fordi: early stage, ingen andre brukere." - Fase 4 (designsystem) trigges på bruk, ikke plan — aktiveres etter at første Voyage-kjøring har produsert faktiske UI-komponenter; ellers "bruk HIG/Material direkte" via domain-pack-default.
- Hard lengde-grense per fase-artefakt — differensiert per artefakt-type, ikke ett flatt tall (se § Hard lengde-grense). Lengde er det sterkeste seremoni-signalet.
- En "rapid mode"-sti finnes: app-konsept → minimal-men-gyldig app-brief inline → fase 7 feature-brief, uten å passere 2–6. Den fulle pipelinen er eskalering, ikke default.
- Fase 3 (arkitektur) produserer åpne spørsmål som lukkes etter hvert — ikke en decisions-log skrevet før koden finnes. ADR-formatet beholdes, men ADR-er skrives/oppdateres idet beslutningen faktisk tas.
Konsekvensen: pipelinen presenteres heretter som eskalerings-stige, ikke som standard-løype. Default er kort. Hver ekstra fase er et bevisst valg med begrunnelse.
Scope-lås
app-creator dekker utviklings-prosessen — fra app-konsept til app-bygget (feature-briefer overlevert til Voyage). Eksplisitt utenfor scope:
- Pre-decision: markedsanalyse, business case, om appen i det hele tatt skal lages.
- Post-shipping: TestFlight-feedback-loops, marketing, App Store-optimization (ASO), reell-bruk-analyse av shipped app.
Release/ops-grensen (R10 — gjort eksplisitt)
Mellom "app-bygget" og "post-shipping" ligger en gråsone. Grensen:
- App-brief (fase 1) eier de release-beslutningene som er reelle scope-valg: distribusjons-modell (paid app / freemium / gratis), om det er en bevisst versjonerings-strategi, om appen har analytics-stack i det hele tatt (ja/nei + hvilken type — ikke konfigurasjon). Disse påvirker arkitektur og features, så de hører i app-rammen.
- Domain-pack-checklists eier de operasjonelle submission-artefaktene: App Store-submission-checklist,
NSUsageDescription-inventar, privacy-manifest-mal, eksport-compliance-spørsmål, region-krav, screenshot-spec, App Store Connect-metadata-mal. Enios-app-pack bærer disse; appen gjenoppfinner dem ikke. Sedomain-pack-spec.md. - Eksplisitt utenfor app-creator: force-upgrade-policy-implementasjon, TestFlight-loops, ASO, marketing, analytics-dashboard-oppsett, reell retention-analyse. Brief-templater i dette utkastet skal ikke utvides for å dekke disse.
Test-strategi: ikke en dedikert fase. Test-infrastruktur er features i backlogen (fase 6 — se F-T-konvensjonen); test-strategi-beslutninger (dekningsmål, crash-free-rate, device/OS-matrise) hører som constraints i fase 5, strukturert mot domain-pack-checklisten — ikke som egen fase.
Brief-pattern som unifisert artefakt-form
Hver fase produserer én eller flere briefer — strukturerte markdown-dokumenter med YAML-frontmatter og fase-spesifikt innhold i seksjoner:
- App brief (fase 1) — én per app. Minimal-variant eller full-variant.
- Research briefs (fase 2, skippbar) — én per research-tema.
- Arkitektur brief (fase 3, skippbar for trivielle apper) — én per app.
- Design brief (fase 4, trigges på bruk) — én per app.
- Constraints brief (fase 5, skippbar) — én per app.
- Features brief (fase 6) — én per app (backlog + dependency-graf).
- Feature-artefakter (fase 7) —
brief.md(Voyage-kompatibel) +context.md(embedder upstream) per feature.
Konsistensen gir én HTML-renderer, lik review-UX, og enkel kryss-referansing. Fase-spesifikk struktur lever inni hver brief, ikke som forskjellige format på tvers.
Hver brief har en obligatorisk review-gate før neste fase starter (se § Cross-cutting: Review-gate mellom faser). Brief-en er AI-skrevet; godkjenning gjøres ved at operatøren annoterer artefaktens annotate.mjs-genererte HTML og leverer annotasjonene tilbake via «Copy Prompt». phase_status skiller mellom pending-review (AI-skrevet, venter på operatør) og complete (operatør-godkjent). Neste fase blokkert til complete.
Sidecar-fila finnes ikke (korrigert 2026-08-10 — A1/R-05, M8). Normativ tekst i dette dokumentet omtalte en sidecar
<artefakt>.review.mdsom bærer av annotasjonene.annotate.mjsskriver kun<input>.html; annotasjonene lever i nettleserens localStorage (nøklet på absolutt filsti), og etfindover Akashic-instansen finner null.review.md-filer.sidecar/ref-feltene istate.json-eksemplene under er derfor planlagte, ikke realiserte — behandle dem som en peker til artefakten som skal annoteres, ikke som en fil som eksisterer. Konsekvensen er reell: annotasjonene overlever ikke maskinbytte eller nettleser-rydding. Å gjøre annotasjons-eksport til fil til del av gate-protokollen er masterplan D7 (betinget utvidelse C), operatør-beslutning — ikke besluttet her.
Hard lengde-grense per artefakt (R7) [justert 2026-08-10 — A2/R-07: flat grense erstattet av per-artefakt-tabell]
Lengde er fortsatt det sterkeste seremoni-signalet, og lange artefakter spiser kontekst-budsjett nedstrøms-faser trenger. Men den opprinnelige flate ≤500-ords-grensen er empirisk motbevist — den ble brutt av samtlige åtte artefakter Akashic-prototypen produserte, hver gang av en driver som ikke var seremoni (friksjon #10/#12/#13/#14). Regelen er derfor differensiert per artefakt-type. Tallene er observerte lengder på bevisst-stramme artefakter, ikke ambisjoner — med ett unntak, merket i tabellen: fase 4 ble hoppet over i prototypen, så dens tall er anslått og ikke empirisk.
| Artefakt | Target | Review-flagg ved | Driver (hvorfor akkurat dette tallet) |
|---|---|---|---|
01-app-brief.md |
~2000 ord | >2500 | Bredde: intent + scope + feature-signaler + rabbit holes + antakelser |
02-research-briefs/{NN}-*.md |
~1500 ord | >2000 | Dybde per tema; skalerer per tema-fil, ikke samlet |
03-architecture-brief.md |
~2000 ord | >2500 | Dybde; ~250–300 ord per ADR ved 4+ ADR-er |
04-design-brief.md [anslag — ikke målt] |
~1200 ord | >1800 | Token-tabeller teller mildt; implementasjons-skjeletter holdes minimale. Fase 4 ble hoppet over i Akashic-prototypen — justér mot første reelle kjøring |
05-constraints-brief.md |
~3500 ord | >4500 | Bredde: ISO 25010 + WCAG 2.2 + MASVS + plattform + governance + test |
06-features-brief.md |
~3000 ord ved ~13 entries | >4000 | Skalerer ~200 ord/entry (Voyage-handover-1-klar entry-struktur) + grafer + readiness-check |
features/{NN}-{slug}/brief.md |
~750 ord | >1000 | Voyage strict-mode: frontmatter (21 linjer) + 8 body-seksjoner inkl. falsifiserbare Success Criteria |
features/{NN}-{slug}/context.md |
~650 ord | >900 | Materialisert upstream (BMAD: embedding > linking) — agenten har ingen ambient kontekst |
features/{NN}-{slug}/research.md |
~600 ord | >800 | Research-plan langform: kandidat-tabell + kriterier + beslutnings-prosess |
Unntatt fra grense: 01-interview-transcript.md (råform, ikke en brief), 00-context/domain-pack-*.md (materialisert snapshot — lengden eies av packen), examples/*, og *.revisions.md (audit-trail, se under).
Typologien bak tallene: bredde-faser (1, 5, 6 — tverrsnitt av hele appen) lander ~2000–3500 ord; dybde-faser (2, 3 — få spørsmål, grundig besvart) ~1300–1800; fokus-per-feature (7) ~600–750 per fil. At fase 7 ligger lavest i absolutte tall og likevel over den gamle grensen, er ikke slapphet — det er Voyage-strict-mode-løftet som koster.
Hvis et artefakt sprenger sitt review-flagg: kandidat for å flytte detalj til domain-pack, splitte ut en egen fil (slik research.md ble splittet fra brief.md i S12), eller droppe innholdet. Overskridelse er et eksplisitt review-flagg med skriftlig begrunnelse, ikke en formalitet — og ikke en automatisk feil.
Revisjonshistorikk teller ikke mot grensen — den bor i en sidecar [besluttet 2026-08-10 — A2/R-07, operatør]
## Revisjons-logg-seksjonen skrives ikke inn i artefakten den beskriver. Hver revidert artefakt får en sidecar:
- Fase 1–6:
<artefakt>.revisions.md(f.eks.06-features-brief.revisions.md) - Fase 7: én
features/{NN}-{slug}/revisions.mdfor hele feature-mappa (brief/context/research deler logg — de revideres i samme runde)
Begrunnelse: revisjonshistorikk er app-creator-intern state, ikke kontrakt. Da konvensjonen var «logg på slutten av kilde-artefakten», vokste Akashics features/01-sun-position/brief.md til 4523 ord over seks runder — hvorav ~740 var kontrakten Voyage skal lese og ~3800 var norsk beslutningshistorikk, inkludert forkastede alternativer. Den historikken overleveres da til Voyages planner og kan feilvekte planleggingen. Alternativene «flytt til context.md» og «strip ved handover» ble vurdert og forkastet: context.md overleveres også, og strip-varianten produserer to versjoner av samme kontraktsfil uten maskinell drift-fangst (jf. R-03).
Sidecaren er ikke unntatt fordi den er uviktig, men fordi den er append-only per definisjon: å sette tak på den ville bety å slette historikk.
Domain-pack-konsumering (R4 — krysshenviser til domain-pack-spec.md)
En domain pack er en gjenbrukbar kunnskaps-bunt (conventions, patterns, gotchas, checklists, guardrails, scaffolding, reference-impl, glossary) som fasene 1/3–7 konsumerer for å realisere en app i et bestemt domene. Den ligger mellom app-spesifikk (fase 3–5) og task-spesifikk (fase 7). app-creator shipper referanse-pakker (ios-app, claude-code-plugin) i domain-packs/ i plugin-roten; fork-and-own-brukere lager egne. Full spec: domain-pack-spec.md.
Lasting: eksplisitt fil-sti per fase — ingen always-on injeksjon, ingen glob-magi. Max-3-regel (redefinert 2026-08-10, A1 — R-15): regelen beskytter kontekstbudsjettet, ikke filtellingen. 00-context/-snapshotet teller som ÉN lasting (det er én fil, uansett hvor mange pack-komponenter det bærer); utover snapshotet laster en fase maks 3 supplementary pack-filer ved oppstart. Den gamle formuleringen («aldri mer enn 3 pack-filer») var både brutt på papir (fase 5 krever 3 checklists + gotchas.md) og omgått i praksis (Akashic leste snapshotet med alle fem core-filene gjennom ett filhandle) — den målte antall filhandles, ikke kontekst. Hver fase-seksjon under lister hvilke pack-filer den Read-er. state.json registrerer domain_pack: "ios-app@0.1.0"; app-artefaktenes frontmatter skriver samme verdi. Ved init av appen materialiseres et snapshot av pakken (versjonen appen bruker) inn i 00-context/; ethvert pack-felt kan overrides per-app via 00-context/pack-overrides.md.
| Fase | Pack-filer den typisk Read-er |
|---|---|
| 1 (intervju) | conventions.md (domene-rammer som farger spørsmålene), glossary.md (valgfri, ved behov) |
| 3 (arkitektur) | conventions.md, patterns/{relevant}.md (max 1–2), evt. gotchas.md |
| 4 (designsystem) | conventions.md (HIG/Material-default), patterns/{ui-relevant}.md |
| 5 (constraints) | 00-context/-snapshotet (bærer alle checklist*.md + gotchas.md; App Store / MASVS / WCAG / privacy-manifest). Uten snapshot: checklist-filene + gotchas.md — se max-3-regelen over |
| 6 (feature-derivasjon) | checklist.md (for å identifisere test-infra-features), examples/ (eksempel-backlog, valgfri) |
| 7 (feature-brief) | checklist.md (brief-validerings-items), examples/ (eksempel-feature-brief), scaffold/ (når artefakter materialiseres) |
Flersesjons-protokoll (R3)
Å drive en reell app gjennom pipelinen tar mange sesjoner — kontekstvindu-grenser, naturlige pauser, research-avstikkere. Design-research (thread A: BMAD Discussion #74 / Issue #1343 — agent-kontekst degraderer etter 3–4 runder; store mellomdokumenter spiser budsjettet) bekrefter at dette er hard teknisk nødvendighet, ikke pynt.
Mønsteret (omskrevet 2026-08-10, A1 — R-09; erstatter det opprinnelige SESSION-ROADMAP/NEXT-SESSION-PROMPT/SESSION-LOG-mønsteret):
- Én
STATE.mdper app-creator-instans, i instans-repoets rot. Den bærer current state-of-play og starter ALLTID med en «👉 NESTE — START HER»-blokk øverst: hvor vi er, neste konkrete steg, og pekere til det som må leses. Den overskrives ved hver sesjonsslutt (maks ~60 linjer) — historikk går til git, ikke til fila. git loger langtidsloggen. Ingen egen sesjons-logg-fil.- Sesjonskøen bor ved siden av staten (i app-creator selv:
docs/masterplan.md; i en instans: backlogen i06-features-brief.md+state.json). - Operatør kjører
/cleareller starter ny sesjon; re-entry er STATE.md-ens NESTE-blokk, som injiseres automatisk. Ingen «les og følg X nøyaktig»-prompt skrives. - Faser som produserer store mellomdokumenter (arkitektur, design-tokens, full backlog) MÅ kunne kjøres i egen sesjon.
- Domain-packs lastes selektivt (max-3-regelen over) for å holde nedstrøms-budsjett ledig.
Hvorfor omskrivingen: det opprinnelige tre-fils-mønsteret var improvisert i prototype-runet (friksjon #6/S5) og er siden avviklet i praksis — filene finnes ikke på disk, og operatørens globale konvensjon forbyr eksplisitt lokale kontinuitets-/handover-mekanismer av den typen. Strekker de globale lagene (STATE.md + auto-memory + CLAUDE.md + git) ikke til, utvides de globalt, aldri lokalt i en app-creator-instans.
Lett state.json-felt (maskinlesbart speil, ikke egen mekanikk): session.current (kort tag), session.next_action (én linje), session.log (liste av korte sesjons-noter). Dette er det app-factory leser for «hvor i prosessen er appen, hva er neste handling» — STATE.md er menneske-flaten, state.json.session er maskin-flaten, og de skal si det samme. Beslutning (S5, opprettholdt): ingen innebygd orkestrator (à la Voyages trekcontinue/trekendsession) før behovet er bevist (YAGNI, thread E).
Status-merking
Hver brief-skisse er merket med ett av:
[hypotese]— utkast basert på pre-design-resonering, ikke testet.[arvet]— direkte hentet fra Voyage eller annen kjent kilde, lavere endrings-sannsynlighet.[åpent]— bevisst uavklart inntil prototypen viser hvordan.[testet]— overlevd reell pipeline-kjøring.[justert YYYY-MM-DD]— endret basert på friksjons-belegg; dato + kort begrunnelse.
Konservativ regel: kun det som faktisk er kjørt får [testet]. Per S5 har bare fase 1 friksjons-belegg (Akashic-kjøringen, friksjon #1–4); cross-cutting-revisjonene er [justert 2026-05-11] der research ga belegg, ellers [hypotese].
Workflow-oversikt (eskalerings-stige)
┌─────────────────────────────────┐
│ Pre-pipeline: init (identitet) │ app.md (slug, navn, plattform, dato)
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 1. Intervju → app brief │ default: minimal-variant
│ (minimal | full) │ opt-in: full 8-tema-intervju
└─────────────────────────────────┘
│ │
rapid mode │ │ full pipeline (eskalering)
▼ ▼
┌───────────────────┐ ┌─────────────────────────────────┐
│ 7. feature-brief │ │ 2. Research → research briefer │ SKIPPBAR (begrunnelse i state.json)
│ (uten 2–6) │ └─────────────────────────────────┘
└───────────────────┘ │
▼
┌─────────────────────────────────┐
│ 3. Arkitektur → arkitektur brief│ SKIPPBAR for trivielle apper
│ (åpne spørsmål → ADR ved valg)│
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 5. Constraints → constraints br.│ SKIPPBAR (bæres av domain-pack-checklists)
│ (mot ISO 25010 / WCAG 2.2 / │
│ MASVS 2.1 / privacy manifest) │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 6. Feature-derivasjon → features│
│ brief (backlog + deps) │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ [readiness check: PASS/CONCERNS/│
│ FAIL — koherens fase 1–6] │
└─────────────────────────────────┘
│
▼
┌─────────────────────────────────┐
│ 7. Feature-briefer (per feature)│ brief.md + context.md
│ → handover til Voyage (filer) │ Voyage strict-mode-kompatibel
└─────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────────────┐
│ 4. Designsystem → design brief — TRIGGES PÅ BRUK, ikke plan. │
│ Aktiveres etter første Voyage-kjøring har produsert faktiske UI-komp.; │
│ ellers: "bruk HIG/Material direkte" (domain-pack-default). │
└──────────────────────────────────────────────────────────────────────────┘
Sekvenseringen er lineær med backtracking, ikke streng pipeline. Fase 6 kan avsløre arkitektur-gap → tilbake til 3. Fase 7 brief-skriving kan avsløre constraint-konflikt → tilbake til 5. Backtracking er læring, ikke feil.
Eksplisitte fase-transisjoner = operatør-handling (R15). Hver fase-grense krysses ved at operatøren oppdaterer phase_status i brief-frontmatter og state.json — ikke ved at AI-en "går videre". Design-research (A-P2: spec-kit #1011 — agenten implementerte uten å stoppe ved fase-grensen) viser hvorfor dette ikke kan være kun en prompt-instruksjon. AI-en stopper og venter på operatør-handlingen.
Rapid mode (R5): for en liten app forfatteren bygger for seg selv: app-konsept → minimal-men-gyldig app-brief inline → ett eller flere fase 7-feature-briefer, uten 2–6. Minimal-men-gyldig app-brief = problem & motivasjon + målgruppe + minst ett suksess-kriterium + ikke-tom utenfor-liste + plattform (en delmengde av kvalitets-sjekk-spørsmålene; se fase 1). Det er nok til at nedstrøms ikke hallusinerer (anker-prinsippet, A-P5), uten å passere de fem mellomliggende fasene. Den fulle pipelinen er eskalering når operatøren genuint er usikker eller appen er stor nok til at koordinering mellom fase-artefakter lønner seg.
Filsystem-layout [justert 2026-05-11 — R1: features/{NN}-{slug}/, 00-context/]
{app-creator-instance-dir}/
├── app.md # App-identitet (slug, navn, plattform, dato, domain_packs)
├── state.json # Live status (fase-progress, attention, domain_pack, session)
├── 00-context/ # Materialiserte domain-pack-snapshots + per-app-overrides
│ ├── domain-pack-{name}.md # Snapshot av pakken appen bruker (versjon innskrevet)
│ └── pack-overrides.md # Escape hatch — per-app-overstyringer av pack-felt
├── 01-app-brief.md # Output fra fase 1 (minimal- eller full-variant)
├── 01-app-brief.revisions.md # Valgfri — audit-trail, finnes først ved revision ≥ 1
├── 01-interview-transcript.md # Råform fra fase 1 — kun hvis full-variant (kontekst, ikke brief)
├── 02-research-briefs/ # Skippbar — mappen finnes kun hvis brukt
│ └── NN-{topic-slug}.md
├── 03-architecture-brief.md # Output fra fase 3 (skippbar)
├── 04-design-brief.md # Output fra fase 4 (trigges på bruk)
├── 05-constraints-brief.md # Output fra fase 5 (skippbar)
├── 06-features-brief.md # Output fra fase 6 (backlog + dependency-graf)
└── features/ # Output fra fase 7 — én mappe per feature
└── {NN}-{feature-slug}/
├── brief.md # Voyage strict-mode-kompatibel — implementerers primær-input
├── context.md # Embedder upstream (fase 1–5-utdrag + domain-pack-utdrag)
├── research.md # Valgfri — feature-spesifikk research
├── design-ref.md # Valgfri — UX-sketch, token-referanser, HIG-pekere
├── revisions.md # Valgfri — audit-trail for hele mappa, finnes først ved revision ≥ 1
└── voyage_run.md # Valgfri — peker til Voyage-run-dir + run-status (skrevet av state-eksport)
{NN}-prefiks på feature-mapper håndhever dependency-rekkefølgen fra fase 6: lavere NN avhenger ikke av høyere NN innen samme app.brief.md+context.mder obligatoriske per feature; resten kun når innhold finnes.*.revisions.mder audit-trail, aldri kontrakt (A2, 2026-08-10): hver revidert fase 1–6-artefakt får<artefakt>.revisions.mdved siden av seg; fase 7 samler énrevisions.mdper feature-mappe. Filene overleveres aldri til Voyage og teller ikke mot lengde-grensene. Errevision: 0, finnes de ikke.- En Voyage-kjøring skriver sine egne artefakter (
plan.md,progress.json,review.md, …) i SIN{project_dir}. app-creator linker dit viavoyage_run_diribrief.md-frontmatter og leserprogress.json/review.mdderfra for status-eksport — den kopierer dem ikke inn ifeatures/{NN}/for øvrig. A5 (2026-08-11) formaliserte{project_dir}somfeatures/{NN}-{slug}/voyage/, ikke.claude/projects/{date}-{slug}/— se § Fase 7 «Handover-mekanikk» for den verifiserte begrunnelsen (/trekresearchkrever en eksisterende--project-katalog og har ingen løs--brief-modus). {app-creator-instance-dir}-plassering er[åpent]— kan være under~/.claude/projects/, under en konkret repo, eller egen mappe (Akashic-instansen ligger i eget repo,/Users/ktg/repos/akashic-intelligence/— én gyldig variant).
Felles brief-frontmatter-felter [hypotese]
Alle interne briefer i app-creator (fase 1–6) har disse felles felter:
---
brief_type: app | research | architecture | design | constraints | features
phase: 1-6
phase_status: not-started | in-progress | pending-review | revision-in-progress | revised | complete | skipped
parent_app: {app-slug}
domain_pack: "ios-app@{version}" # null hvis ingen pack brukt; pin til den versjonen appen faktisk bruker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0 # bumps ved backtracking
revision_reason: null # fylles ved revisjon
length_words: {N} # ordtelling — review-flagg mot artefaktets eget tak, se § Hard lengde-grense
# (teller IKKE sidecar-en <artefakt>.revisions.md)
---
Fase 7-feature-briefer (features/{NN}-{slug}/brief.md) bruker Voyages frontmatter-skjema, ikke dette — se Fase 7.
phase_status — én autoritativ enum [justert 2026-08-10 — A1/R-06]
Vokabularet lå tidligere i tre innbyrdes uforenlige varianter (frontmatter-spec, state.json-spec, og en tredje form Akashic bruker i praksis). Dette er den ene listen; alle andre steder viser hit.
| Verdi | Betyr | Neste fase blokkert? |
|---|---|---|
not-started |
Fasen er ikke begynt. | ja |
in-progress |
AI arbeider på artefakten. | ja |
pending-review |
Artefakten er AI-skrevet, ikke operatør-godkjent. Review-gaten står åpen. | ja |
revision-in-progress |
Annotasjoner mottatt, AI reviderer. | ja |
revised |
Revidert etter annotasjoner; venter på ny gate-passering. | ja |
complete |
Operatør-godkjent. Eneste verdi som slipper neste fase gjennom. | nei |
skipped |
Bevisst hoppet over, med reason. |
nei |
Kritisk skille (friksjon #15 / Akashic S13): complete betyr operatør-godkjent, aldri «AI ble ferdig». Det er pending-review som betyr sistnevnte. Den gamle frontmatter-enumen manglet pending-review helt, så en sesjon som fulgte spec-en bokstavelig kunne bare skrive complete når den mente pending-review — nøyaktig forvekslingen som utløste operatør-stoppen i S13.
Objektformer (i state.json, der en skalar ikke er nok):
- Skippet fase:
{ "status": "skipped", "reason": "..." } - Review-gate åpen:
{ "status": "pending-review", "revision": 0, "sidecar": "<filsti>", "blocking": [<faser>] }
Kjent avvik, ikke løst her: Akashic-instansen bruker i praksis to objektformer ingen spec dekker (revised med revision/revised_at/driver/open_questions, og complete med completed/total/completed_at/completed_note), og fase 7 er modellert som en skalar selv om den er en kontinuerlig aktivitet ("7": "complete" ved 1 av 12 briefer er villedende for en aggregator). Begge er utsatt til C2 (state-schema med per-feature fase 7-semantikk + normalisering av instansen) — A1 samler bare vokabularet, den redesigner det ikke.
Attention-typene har samme sprik: spec-en nevnte review-pending/decision/review, mens virkeligheten bruker decision-pending, action-pending, environment-blocker, revision-pending, og phase-feltet er udefinert fritekst. Lukket enum + phase-domene defineres i C2.
Pre-pipeline: init [justert 2026-05-11 — R12 / friksjon #1: identitet only]
Formål: Opprette en app-creator-instans og registrere den i state.
Workflow [hypotese]:
- Operatøren kjører
/app-creator init {slug}(eller tilsvarende). - AI oppretter
{app-creator-instance-dir}/. - AI ber om kun identitets-data: app-navn, plattform-mål, dato. Eventuelt hvilken domain-pack appen skal bruke (
ios-app,claude-code-plugin, ingen) — eller dette settes i fase 1. - Materialiserer
00-context/domain-pack-{name}.md-snapshot hvis en pack er valgt. - Skriver
app.md(identitets-fil) og initialstate.json(fase 0, ingen attention).
Output: app.md [justert 2026-05-11 — R12: "Hvorfor" + "Pre-fase-notater" droppet fra init]
---
slug: fitness-tracker
name: "Fitness Tracker"
created: 2026-05-10
platform: ios
domain_packs: ["ios-app@0.1.0"]
status: active
---
# {Navn}
## Hvorfor denne appen
<!-- Tom ved init. Genereres retrospektivt etter fase 1 complete som ett-avsnitts-
destillering av app-brief sin Problem & motivasjon-seksjon. Aldri besvart i init —
da risikerer vi to versjoner som ikke matcher (friksjon #1). -->
app.md er identitets-fil, ikke en brief. Intent-fila er 01-app-brief.md. app.md er rot-fila app-factory bruker for app-discovery. Endring fra førsteutkastet: "Hvorfor denne appen" og "Pre-fase-notater" er fjernet fra init-spørsmålene — fase 1 sin Anchor for Problem & motivasjon spør i praksis det samme, bare grundigere, og to versjoner som ikke matcher er ren friksjon. "Hvorfor"-avsnittet skrives etter fase 1 som destillering.
Fase 1 — Intervju → App brief [delvis testet 2026-05-11 — Akashic-kjøring; justert per friksjon #1–4]
Formål: Hente ut app-intent klart nok til å bygge resten på.
To varianter:
- Minimal-variant (default). En kort fritekst-runde: operatør skriver/dikterer problem & motivasjon + målgruppe + minst ett suksess-kriterium + ikke-tom utenfor-liste + plattform; AI strukturerer det til en
01-app-brief.mdi minimal form. Ingen weakest-section-loop, ingen 6 kvalitets-sjekk-spørsmål, ingen transkript-fil. Dette er nok for rapid mode og for små apper. (Thread E: å intervjue seg selv er rituell nedskriving — den lette varianten respekterer det.) - Full-variant (opt-in). Det strukturerte 8-tema-intervjuet (sjekkliste-temaene under) med trekbrief-disiplinene. Velges når operatøren genuint er usikker på app-intent og trenger AI til å presse fram presisjon. Produserer
01-interview-transcript.mdi tillegg til01-app-brief.md.
Input (begge varianter):
app.md(fra pre-pipeline).- Operatørens åpne ideer/skisser.
- Domain-pack:
conventions.md(domene-rammer som farger spørsmålene — f.eks. "dette er en iOS-app, så plattform-spørsmålet inkluderer widgets/extensions"), evt.glossary.md.
Tidlig eierskaps-spørsmål (begge varianter, R12 / friksjon #4): Som ett av de første spørsmålene (tur 1–2 i full-variant; del av minimal-prompten): "Hvem er dette egentlig for: deg selv, andre, eller begge? Hvis du må velge én — hvilken vinner når de er i konflikt?" Dette rammer alle påfølgende svar riktig fra start. (I Akashic-kjøringen kom denne rekalibreringen i tur 9 og endret tolkningen av tur 4 betydelig.)
Appetite / scope-budsjett (begge varianter, R13): Tidlig i fase 1: "Hvor mye er du villig til å bruke på dette — en helg, et par uker, måneder?" Appetite er ikke et estimat, det er et budsjett som dobler som scope-constraint (Shape Up). Skrives inn i app-brief.
Workflow — full-variant [hypotese]
- AI starter strukturert intervju.
- Sjekkliste-tema (kategorier, ikke fast rekkefølge):
- Eierskap & intensjon (tidlig — se over)
- Problem & motivasjon
- Brukere
- Suksess-kriterier
- Omfang
- Appetite / scope-budsjett
- Plattform-spesifikt
- Tidshorisont
- AI følger opp på tvetydighet, summerer underveis.
- Operatør korrigerer.
- Avsluttes når sjekkliste er dekket, pre-draft-kvalitets-sjekken passerer, app-brief er skrevet, post-draft-sjekken passerer, og operatør sier OK.
Kjøre-disiplin (importert fra Voyage trekbrief) [importert fra trekbrief, justert for per-app, hypotese — kun full-variant]
Voyages /trekbrief har fem disipliner som per-task-intervjuet hviler på. Full-varianten importerer dem her som kjøre-disiplin (ikke kode), justert for at app-scope er bredere og mykere enn task-scope.
1. Weakest-section-first-loop. Gå ikke gjennom temaene kronologisk. Velg svakeste tema mellom hvert svar. Standard prioritering:
Eierskap & intensjon → Problem & motivasjon → Brukere → Suksess-kriterier → Omfang → Appetite → Plattform → Tidshorisont
Begrunnelse: Eierskap rammer alt annet (friksjon #4); Suksess-kriterier kan ikke skrives før Brukere er konkret; Omfang kan ikke skrives før Problem er tydelig.
2. Anchor / Sharpen-mønster. Per tema starter med en Anchor — åpent spørsmål uten å lede. Hvis svaret er vagt, bruk Sharpen — krev konkretisering. For Omfang spesifikt (R12 / friksjon #3): skill eksplisitt:
- "Hva appen GJØR" — funksjonelle features (det som hører i fase 1-brief og driver fase 6 feature-derivasjon).
- "Hvordan appen ER" — kvalitative egenskaper (visuelt, brukervennlig, ytelse — hører i fase 4 designsystem og fase 5 constraints).
Hvis operatør svarer på Omfang med produkt-kvaliteter ("visuelt innbydende", "brukervennlig"), er det fint — det er fase 4/5-input. Følg så opp med en AI-foreslått funksjonell-features-hypotese som standard neste steg ("Basert på dette: appen MÅ kanskje kunne X, Y, Z — stemmer det?"), ikke en ad-hoc redning. (I Akashic tok dette en ekstra runde fordi det ikke var planlagt.)
Aldri repeter samme Sharpen-variant på samme tema. Hvis Sharpen ikke gir mer presisjon: marker som [ANTAKELSE] (disiplin 4) og gå videre.
3. Aktiv research-tema-uthenting under dialog. Lytt etter signaler som krever research før arkitektur (fase 3): ukjent teknologi, ny iOS-versjon/framework-API, security-valg, arkitektur-valg, opphavsrett/juridiske spørsmål. Fang med struktur i transkript:
[RESEARCH-TEMA]
Question: ... ? # slutter med ?, spesifikt nok til at noen kan svare
Confidence needed: high # high (driver arkitektur-beslutning) | medium | low
Scope hint: ekstern docs # lokal kode-research | ekstern docs | begge
Disse bæres til fase 2-research-plan. Hvis operatør sier "jeg vet svaret", strykes temaet — svaret skrives kort i transkript som referanse.
4. [ANTAKELSE]-markører. Når operatør sier "ikke vet" om noe materielt, skriv det eksplisitt: [ANTAKELSE] {plattform-min-versjon} er minimum — ikke verifisert mot målgruppens enhets-park. Forskjellen fra et research-tema: en antakelse er en bevisst pause vi bærer risiko-en for; et research-tema er et åpent svar vi planlegger å hente. Antakelser legges i app-brief sin "Åpne spørsmål"-seksjon med [ANTAKELSE]-prefiks, bæres til fase 3 hvor de aktivt resolveres eller eksplisitt aksepteres.
5. Kvalitets-sjekk — splittet i to (R12 / friksjon #2). Ikke en agent, ikke scoring. Det opprinnelige spørsmål #1 ("Er problem & motivasjon skrevet i 1–2 avsnitt operatør står bak?") forutsatte artefakten den skulle validere — kylling-og-egg. Løsning: splitt.
Pre-draft-sjekk (5 ja/nei, besvarbare fra transkriptet — kjøres FØR app-brief skrives):
- Har vi nok materiale i transkriptet til å skrive et problem & motivasjon-avsnitt operatør vil stå bak?
- Er primær målgruppe konkret nok til å peke på én person eller persona med kontekst?
- Finnes minst ett suksess-kriterium med konkret målbarhet — selv om målingen først kan gjøres post-shipping?
- Er omfang-utenfor-listen ikke-tom? (Ingen ærlig app har tomt utenfor-omfang.)
- Er åpne spørsmål kategorisert som research-tema / arkitektur-beslutning /
[ANTAKELSE]bæres videre? Og er plattform-detaljer (target, min-versjon, extensions/widgets) eksplisitte?
Post-draft-sjekk (1 ja/nei — kjøres ETTER app-brief er skrevet og operatør har lest den): 6. Står operatør bak problem & motivasjon-avsnittet slik AI formulerte det?
Hvis ett eller flere svar er nei: gå tilbake til svakeste tema og kjør en runde til. Maks 3 runder før operatør tar eksplisitt beslutning om å eksitere med kjent svakhet (dokumenteres i brief sin "Åpne spørsmål"-seksjon).
Det som IKKE oversettes fra trekbrief
trekbrief har mekanisk 1–5-scoring og dedikert reviewer-agent. Disse hører i per-task-kontekst der suksess-kriterier kan være command-checkable. Per-app-intervjuet skal IKKE importere dette — det blir premature lock-down. Hvis prototypen viser at en lett reviewer-pass faktisk hjelper, vurderes det i v0.5.0+.
Output 1: 01-interview-transcript.md [hypotese — kun full-variant] — full samtale, råform, tidsstempel-merket per spørsmål-svar. Ingen frontmatter krevd. Ingen lengde-grense. Råmateriale for senere referanse, ikke en brief.
Output 2: 01-app-brief.md [delvis testet 2026-05-11]
---
brief_type: app
phase: 1
phase_status: complete
parent_app: fitness-tracker
domain_pack: "ios-app@0.1.0"
variant: minimal | full
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
revision_reason: null
length_words: {N}
---
# App brief: {Navn}
## Problem og motivasjon
{1-2 avsnitt — hva løser appen, for hvem, hvorfor nå}
## Eierskap & intensjon
{For hvem: deg selv / andre / begge. Hvilken vinner ved konflikt.}
## Målgruppe
- **Primær:** {beskrivelse, kontekst, ferdighetsnivå}
- **Sekundær:** {beskrivelse hvis aktuelt — ellers "ingen"}
## Suksess-kriterier
- {konkret, helst målbart kriterium}
- {konkret, helst målbart kriterium}
## Omfang
### Innenfor (funksjonelle features — "hva appen GJØR")
- {punkt}
### Utenfor (eksplisitt — no-gos)
- {punkt}
### Rabbit holes (ting som ser små ut men kan eksplodere — distinkt fra no-gos)
- {punkt — f.eks. "opphavsrett på tredjepart-innhold: kan bli en juridisk avgrunn"}
## Appetite / scope-budsjett
- {en helg / et par uker / måneder — budsjettet som også er scope-constraint}
## Plattform
- **Mål:** {iOS-only / universal / watch+phone / etc.}
- **Min-versjon:** {min-versjon — verifiser mot domain-pack `conventions.md`, ikke mot hukommelse}
- **Andre plattform-detaljer:** {widgets / extensions / shortcuts / Live Activities / etc.}
## Tidshorisont
- **MVP / v1:** {beskrivelse}
- **v1.1+:** {beskrivelse hvis relevant}
- **Lengre sikt:** {beskrivelse hvis relevant}
## Release-modell (de scope-relevante valgene — se scope-lås)
- **Distribusjon:** {paid app / freemium / gratis — og hvorfor}
- **Analytics:** {ja/nei + type hvis ja — ikke konfigurasjon}
- **Versjonerings-strategi:** {kun hvis det er en bevisst beslutning, ellers "standard"}
## Åpne spørsmål etter intervju
- {[RESEARCH-TEMA] ... — fase 2 håndterer}
- {[ANTAKELSE] ... — fase 3 resolverer eller aksepterer}
- {arkitektur-beslutning ... — fase 3 håndterer}
## Referanser
- `01-interview-transcript.md` — full samtale (kun full-variant)
(I minimal-variant droppes Eierskap-, Appetite- og Rabbit-holes-seksjonen til egne overskrifter hvis de blir tomme — men eierskaps-spørsmålet stilles uansett, og svaret går inn i Problem & motivasjon-avsnittet.)
Transisjon: Operatør markerer fasen complete ved å oppdatere phase_status: complete i app-brief og state.json. Skriv "Hvorfor denne appen"-avsnittet i app.md som destillering. Hvis åpne research-temaer finnes og operatøren vil ha dem løst først → fase 2 (eskalering). Hvis ikke → fase 3, eller rapid mode → fase 7.
Fase 2 — Research → Research briefer [hypotese — SKIPPBAR]
Skippbar. Hopp er gyldig hvis det ikke finnes høy-confidence research-temaer som driver arkitektur-beslutninger. Et hopp loggføres i state.json: "2": {"status": "skipped", "reason": "ingen research-temaer som driver arkitektur"}. Ikke bare "valgfri" — et bevisst, begrunnet hopp.
Formål: Validere antakelser, finne presedens, identifisere gotchas før arkitektur låses.
Input:
01-app-brief.md.- Liste over åpne research-temaer (fra app-brief).
- Ingen domain-pack-input. (Justert 2026-08-10 — A1/R-14: pack-input for fase 2 er strøket.) Fase 2 står ikke i noen pack-manifests
phases-liste (ios-app/pack.jsonlister[1,3,4,5,6,7]), står ikke i pack-tabellen over, og er utelatt idomain-pack-spec.md. Akashic-kjøringens fase 2 klarte seg uten pack-filer. Den gamle linjen (gotchas.md+patterns/) var derfor en selvmotsigelse en implementasjon ville måttet velge side i — og hadde den valgt linjen, ville den brutt pack-manifestets kontrakt. Trenger et research-tema domene-kunnskap, kommer den via01-app-brief.md(skrevet med pack-input i fase 1) eller via00-context/-snapshotet.
Workflow [hypotese]:
- AI foreslår research-plan basert på åpne temaer.
- Operatør approver eller justerer.
- Per tema: AI gjennomfører research (web, docs, kjente kilder), produserer brief.
- Hvert tema lagres som egen brief.
- Avsluttes når alle planlagte temaer er undersøkt.
Output: 02-research-briefs/NN-{topic-slug}.md [hypotese, arvet fra Voyages research-format]
---
brief_type: research
phase: 2
phase_status: complete
parent_app: fitness-tracker
domain_pack: "ios-app@0.1.0"
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
topic: {kort tittel}
question: {opprinnelig spørsmål}
confidence: high | medium | low
sources_count: {antall}
length_words: {N}
---
# Research brief: {Tittel}
## Spørsmål
{Det vi prøver å svare på, med kontekst fra app-brief}
## Funn
{Strukturerte funn med inline-kilder}
## Konsekvens for senere faser
- **Arkitektur (fase 3):** {hva dette betyr}
- **Designsystem (fase 4):** {hvis relevant}
- **Constraints (fase 5):** {hvis relevant}
- **Features (fase 6):** {hvis relevant}
## Kilder
- {URL eller referanse}
## Restrisiko / åpne spørsmål
- {hva som fortsatt ikke er sikkert}
Transisjon: Når alle planlagte temaer er complete, fase markeres complete. Til fase 3.
Fase 3 — Arkitekturavklaringer → Arkitektur brief [justert 2026-05-11 — R9: spørsmål før spekulasjon; R14: requirements-first/design-first + problem-gate]
Skippbar for trivielle apper. Hvis app-en er liten nok til at arkitektur-valgene er åpenbare (én plattform, ingen backend, standard-stack), kan fasen hoppes med begrunnelse i state.json. For Akashic er den ikke skippbar — ANTAKELSE #2–5 er reelle arkitektur-beslutninger.
Formål: Velge tech-stack, deployment-modell, integrasjoner, sentrale mønstre — og avklare hvilke spørsmål som fortsatt er åpne.
To gate-spørsmål før fasen starter (R14):
- Problem-gate: "Er dette fortsatt riktig problem å løse?" (PR/FAQ-stil — ett kort avsnitt: hvis vi shippet dette i morgen, hva ville pressemeldingen sagt, og holder den fortsatt?) Hvis svaret vakler: tilbake til fase 1, ikke videre.
- Requirements-first vs design-first: "Vet vi hva appen skal gjøre og lar arkitektur følge, eller er det en arkitektur-/teknologi-beslutning som former hva appen kan være?" (Kiro-distinksjonen.) For Akashic: requirements-first — men ANTAKELSE #2–5 grenser mot design-first og må behandles som arkitektur-constraints.
Input:
01-app-brief.md.02-research-briefs/*.md(hvis fase 2 ble brukt).- Domain-pack:
conventions.md, max 1–2patterns/{relevant}.md, evt.gotchas.md.
Workflow [hypotese]:
- AI foreslår arkitektur-alternativer (typisk 2–3 sammenligning) basert på intent + research.
- Per beslutnings-punkt: AI gir anbefaling med begrunnelse. ADR-en skrives idet beslutningen tas — ikke en full decisions-log opp front. Hvis beslutningen ikke kan tas ennå: den havner i "Uavklarte arkitektur-spørsmål", ikke som en spekulativ ADR.
- Operatør approver, foreslår alternativ, eller stiller spørsmål.
- Avsluttes når de beslutningene som kan tas er tatt, og resten er eksplisitt listet som åpne.
Output: 03-architecture-brief.md [hypotese]
---
brief_type: architecture
phase: 3
phase_status: complete
parent_app: fitness-tracker
domain_pack: "ios-app@0.1.0"
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
decision_count: {N}
open_question_count: {N}
length_words: {N}
---
# Arkitektur brief
## Problem-gate (PR/FAQ — ett avsnitt)
{Hvis vi shippet dette i morgen: hva ville pressemeldingen sagt, og holder den?}
## Requirements-first eller design-first?
{Hvilken — og hvilke arkitektur-constraints fra app-brief som låser hva.}
## Stack-sammendrag
- **Språk/runtime:** {f.eks. Swift 6 + SwiftUI}
- **Plattform-target:** {deployment-target — verifiser mot domain-pack `conventions.md`}
- **State-management:** {f.eks. Observation framework + SwiftData}
- **Persistens:** {f.eks. SwiftData, ingen backend}
- **Nettverk:** {f.eks. URLSession + actor isolation — eller "ingen"}
- **Test-strategi-baseline:** {f.eks. Swift Testing + XCUITest — strategi-detaljer i fase 5}
## Vedtatte beslutninger (ADR-style — skrevet idet beslutningen ble tatt)
### ADR-001: {Beslutnings-tittel}
**Status:** Vedtatt {YYYY-MM-DD}
**Kontekst:** {Problem som krevde beslutning}
**Vurderte alternativer:**
1. **{A}** — pros: {...}, cons: {...}
2. **{B}** — pros: {...}, cons: {...}
**Beslutning:** {Valgt alternativ med begrunnelse}
**Konsekvenser:** {hva dette gjør lett / vanskelig / låser oss til}
**Revisjons-trigger:** {Når denne burde re-vurderes}
---
## Uavklarte arkitektur-spørsmål (lukkes etter hvert — ikke spekuler nå)
- **AQ-001:** {spørsmål} — blokkerer: {hva}; forventet lukket: {fase / hendelse}
- **AQ-002:** {[ANTAKELSE] fra fase 1 som må resolveres her}
## Sentrale patterns (kun de som faktisk er besluttet)
- **{Pattern A}:** {hvorfor og hvor brukt}
## Integrasjoner
- **{Tredjepart eller Apple-API}:** {bruks-formål}
## Referanser
- `01-app-brief.md`
- `02-research-briefs/NN-*.md` (hvis brukt)
Transisjon: Når de mulige beslutningene er tatt og resten er listet som åpne, fase complete. Til fase 5 (fase 4 trigges separat på bruk).
Fase 4 — Designsystem → Design brief [justert 2026-05-11 — R8: trigges på bruk, ikke plan]
Trigges på bruk, ikke plan. Et designsystem kodifisert før det finnes UI-komponenter er prematur abstraksjon (YAGNI, thread E — den mest sårbare fasen). Fasen aktiveres etter at første Voyage-kjøring har produsert faktiske UI-komponenter og feature-settet er stabilt nok til at det lønner seg å kodifisere tokens. Inntil da: "bruk HIG (iOS) / Material (Android) direkte" — domain-pack conventions.md bærer base-systemets regler, og hver feature-brief refererer dem. For mange små apper utløses fase 4 aldri, og det er riktig.
Når den utløses — formål: kodifisere tokens og gjenbrukbare komponenter når feature-settet er stabilt nok til at konsistens-gevinsten overstiger kostnaden.
Input:
01-app-brief.md(målgruppe, tone).03-architecture-brief.md(plattform-target — begrenser tilgjengelige design-API).- Faktiske UI-komponenter fra første Voyage-kjøring(er).
- Domain-pack:
conventions.md(HIG/Material-default),patterns/{ui-relevant}.md.
Workflow [hypotese]:
- AI ekstraherer tokens fra de UI-komponentene som faktisk er bygget (farger, typografi, spacing, motion, interaksjons-mønstre som har dukket opp).
- AI foreslår konsolidering: hvilke ad-hoc-verdier som bør bli navngitte tokens.
- Operatør justerer brand-spesifikke valg.
- AI definerer gjenbrukbare komponenter basert på det som allerede er bygget mer enn én gang.
Output: 04-design-brief.md [hypotese] — samme struktur som førsteutkastet (frontmatter brief_type: design, base_system: hig | material | custom, component_count; body: Base-system / Tokens (Farger light+dark / Typografi / Spacing / Motion) / Interaksjons-prinsipper / Komponent-bibliotek med token-bruk per komponent / Referanser), men innenfor artefaktets lengde-target (~1200 ord, review-flagg >1800 — token-tabeller teller mildt). Eksempel-implementasjons-skjeletter holdes minimale.
Transisjon: Når brief er approvert, fase complete. Nedstrøms feature-briefer kan nå referere navngitte tokens; tidligere feature-briefer oppdateres kun ved revisjon.
Fase 5 — Constraints → Constraints brief [justert 2026-05-11 — R11: strukturert mot ISO 25010:2023 / WCAG 2.2 / MASVS 2.1 / privacy manifest; SKIPPBAR]
Skippbar. Mye av denne fasens innhold bæres av domain-pack checklist.md (App Store-submission-checklist, MASVS 2.1, WCAG 2.2 AA, privacy-manifest-mal) — for en liten app som følger domain-pack-defaults kan fasen hoppes med begrunnelse i state.json. Constraints som faktisk avviker fra pack-defaults, eller app-spesifikke krav (Akashic: ingen-effekt-claims, ikke-affiliering-disclaimer), MÅ skrives ned — da er ikke fasen skippbar.
Formål: Cross-feature regler som gjelder for alle features uavhengig av deres egen logikk — strukturert mot de standardene den implisitt refererer, slik at gap er synlige.
Input:
01-app-brief.md(suksess-kriterier, constraint-signaler, release-modell).03-architecture-brief.md(plattform-target gir baseline).- Domain-pack:
00-context/-snapshotet (én lasting — bærer alle core-filene, inkl. samtligechecklist*.mdoggotchas.md; standardenes innhold lever der — referanse, ikke kopi). Uten snapshot: checklist-filene (ios-apphar dem splittet i tre) +gotchas.mdlastes direkte — det er >3 filer og derfor kun gyldig via snapshotet eller ved å laste dem i to omganger. (Justert 2026-08-10 — A1/R-15: den gamle linjen sprengte max-3-regelen på papir mens praksis leste snapshotet.)
Workflow [hypotese]:
- AI går gjennom domain-pack
checklist.mdog lister hvilke punkter som gjelder denne appen. - AI lister app-spesifikke constraints som ikke er i checklisten.
- Hver constraint klassifiseres:
[enforce](hard krav) eller[aspire](mål). - Operatør approver eller utvider.
Output: 05-constraints-brief.md [hypotese] — body strukturert mot standardene (referanse, ikke uttømmende inline — checklisten i domain-pack-en er det uttømmende):
---
brief_type: constraints
phase: 5
phase_status: complete
parent_app: fitness-tracker
domain_pack: "ios-app@0.1.0"
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
constraint_count: {N}
length_words: {N}
---
# Constraints brief
## Kvalitet (mot ISO/IEC 25010:2023 — 9 karakteristikker)
*Per relevant karakteristikk: hva gjelder. Særlig de nye i 2023-revisjonen: Safety, Flexibility/Scalability.*
- **Performance efficiency:** **[enforce]** App launch < 1.5s på iPhone 13. **[aspire]** 60fps på alle interaksjoner.
- **Compatibility / Portability:** **[enforce]** {baseline-versjon} som baseline; API-er fra nyere versjoner degraderer ikke baseline-funksjonalitet. (Konkrete versjonstall hentes fra domain-pack `conventions.md` — templaten skal ikke bære dem, jf. friksjon #9.)
- **Reliability:** **[aspire]** Crash-free-rate > 99.5%.
- **Security:** se egen seksjon (MASVS).
- **Maintainability / Flexibility:** {hvis relevant}
- ... (kun de karakteristikkene som faktisk har constraints)
## Tilgjengelighet (mot WCAG 2.2 AA — inkl. de 4 nye 2.2-kriteriene)
- **[enforce]** WCAG 2.2 AA-kontrast i alle synlige elementer (1.4.3 / 1.4.11).
- **[enforce]** VoiceOver-labels på alle interaktive elementer.
- **[enforce]** Target Size (Minimum) 2.5.8 — interaktive mål ≥ 24×24pt (Apple anbefaler 44×44).
- **[enforce]** Focus Not Obscured (Minimum) 2.4.11.
- **[enforce]** Accessible Authentication (Minimum) 3.3.8 — hvis appen har innlogging.
- **[aspire]** Focus Appearance 2.4.13; Dynamic Type opp til AX5.
## Sikkerhet & personvern (mot OWASP MASVS 2.1 — 8 kontroll-grupper + privacy manifest)
- **[enforce]** MASVS-STORAGE: sensitiv data i Keychain, ikke UserDefaults.
- **[enforce]** MASVS-NETWORK: ATS på, ingen unntak uten begrunnelse.
- **[enforce]** MASVS-PRIVACY: required-reason-API-deklarasjon i `PrivacyInfo.xcprivacy` (template i domain-pack `scaffold/`); per-SDK privacy-manifest-krav; App Privacy Details "nutrition label" utfylt.
- **[enforce]** Ingen tracking uten ATT-permission.
- ... (kun de MASVS-gruppene som har constraints)
## Plattform-regler (App Store)
- **[enforce]** App Store Review Guidelines compliance — se domain-pack `checklist.md` for full submission-checklist.
- **[enforce]** HIG-konformt navigation-mønster.
- **[enforce]** Eksport-compliance-deklarasjon; region-krav (DSA / aldersmerking) der relevant.
## Governance / juridisk (app-spesifikt)
- {f.eks. Akashic: **[enforce]** ingen vitenskaplig udokumenterte effekt-claims; **[enforce]** eksplisitt ikke-affiliering med Isha i App Store-beskrivelse.}
- **[aspire]** GDPR-klar for europeiske brukere.
## Test-strategi (strategi-beslutninger — infrastruktur er features i fase 6)
- **[enforce]** Per-feature: unit-tester for forretnings-logikk; UI-tester for primær-flow; Voyage `/trekreview`-pass uten BLOCKERS før feature regnes complete.
- **[enforce]** App-nivå (bygges som `F-T`-features i fase 6): E2E for kritisk sti; A11Y-compliance-suite; performance-regresjon for launch + navigasjon.
- **[aspire]** Visuell regresjon (screenshot-sammenligning); cross-feature-regresjons-suite ved hver ny feature.
- **Dekningsmål:** {konkret tall hvis besluttet}. **Device/OS-matrise:** {hvilke}.
## Konflikt-håndtering
[enforce] over [aspire] → eldste over nyeste → operatør-beslutning.
## Referanser
- `01-app-brief.md`, `03-architecture-brief.md`
- domain-pack `checklist.md` — det uttømmende submission-/standard-grunnlaget
Transisjon: Når constraints er listet og kategorisert, fase complete. Til fase 6.
Fase 6 — Feature-derivasjon → Features brief [hypotese]
Formål: Avlede feature-backlog fra fasene 1–5, identifisere avhengigheter, prioritere — inkludert test-infrastruktur-features avledet fra fase 5-test-strategien.
Input:
- Alle briefer fra fasene 1–5 (fase 4 kan være tom — da brukes domain-pack
conventions.mdfor UI-konvensjoner). - Domain-pack:
checklist.md(for å identifisere hvilke test-infra-/submission-features backlogen trenger), evt.examples/(eksempel-backlog).
Workflow [hypotese]:
- AI foreslår feature-liste basert på intent + arkitektur + constraints.
- Per feature: navn, formål, suksess-kriterium, avhengigheter, antatt størrelse, prioritet.
- AI legger til
F-T-features for app-nivå-test-infrastruktur (driver: fase 5 § Test-strategi). - Operatør approver, omprioriterer, flytter ting til "later".
- AI tegner dependency-graf og identifiserer kritisk sti + parallelliserbare grupper.
Output: 06-features-brief.md [hypotese] — samme struktur som førsteutkastet, men feature-mapping oppdatert til features/{NN}-{slug}/:
---
brief_type: features
phase: 6
phase_status: complete
parent_app: fitness-tracker
domain_pack: "ios-app@0.1.0"
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
feature_count: {N}
---
# Features brief
## Backlog
### F-001: {Feature-navn}
- **Slug:** {feature-slug} → mappe: `features/01-{feature-slug}/`
- **Formål:** {én setning}
- **Suksess-kriterium:** {hvordan vet vi at den virker — helst command-checkable}
- **Avhengigheter:** F-002, F-003 (eller "ingen")
- **Antatt størrelse:** XS / S / M / L
- **Prioritet:** P0 / P1 / P2 / P3
- **Status:** brief-pending | brief-written | voyage-running | voyage-complete | shipped
### F-T01: E2E test framework setup *(test-infra-feature)*
- **Slug:** test-e2e-framework → mappe: `features/T01-test-e2e-framework/`
- **Formål:** XCUITest-suite for kritisk bruker-flow (driver: `05-constraints-brief.md` § Test-strategi)
- **Suksess-kriterium:** Login → core-action-flow har grønn E2E-test som kjører i CI
- **Avhengigheter:** F-001, F-002, F-003 — alle må være shipped
- **Antatt størrelse:** M · **Prioritet:** P1 · **Status:** brief-pending
> **Mønster:** Test-infrastruktur er features i backlogen, ikke et separat lag. Voyage bygger dem som hvilken som helst feature ved at de får sin egen `brief.md` i fase 7. `F-T`-prefiks er en konvensjon for visuelt skille — ikke en arkitektur-grense. Krav til disse driverne fra `05-constraints-brief.md` § Test-strategi (eller domain-pack `checklist.md` hvis fase 5 ble hoppet).
## Dependency-graf
```mermaid
graph TD
F-001[Login flow] --> F-002[Onboarding]
F-002 --> F-003[Main feed]
F-002 --> F-004[Profile]
F-003 --> F-005[Detail view]
Kritisk sti
F-001 → F-002 → F-003 → F-005
Parallelliserbare grupper
Gruppe A (etter F-002): F-003, F-004 — kan utvikles samtidig.
Referanser
01-app-brief.md,03-architecture-brief.md,04-design-brief.md(hvis finnes),05-constraints-brief.md
`{NN}`-prefiks på feature-mappene tildeles i topologisk rekkefølge fra dependency-grafen: en feature uten avhengigheter får lavt NN, en som avhenger av andre får høyere. Innen samme app: lavere NN avhenger aldri av høyere NN.
**Transisjon:** Når brief er approvert, fase complete. Til readiness-check, så fase 7 (kontinuerlig).
---
## Implementation-readiness-check (R14 — før fase 7-handover)
Før den første feature-briefen overleveres til Voyage: en lett koherens-sjekk på tvers av fase 1–6-briefene (inspirert av BMAD `bmad-check-implementation-readiness`). Ikke en agent, en operatør-gjennomgang med PASS / CONCERNS / FAIL:
- Sporbarhet: hver feature i fase 6-backloggen sporer til et behov i fase 1-brief? Ingen orphan-features?
- Constraint-dekning: fase 5-constraints (eller domain-pack-checklist) er reflektert i de feature-briefene som berøres?
- Arkitektur-konsistens: ingen feature forutsetter noe som motsier en vedtatt ADR i fase 3? Åpne arkitektur-spørsmål (AQ-NNN) som blokkerer en feature er fortsatt åpne — er featuren da klar?
- Dependency-koherens: dependency-grafen er asyklisk, og `{NN}`-rekkefølgen respekterer den?
**FAIL** → tilbake til den fasen som mangler. **CONCERNS** → operatør beslutter eksplisitt om handover skjer likevel, og hva risikoen er. **PASS** → fase 7 kan starte. (For rapid mode: en mini-versjon — bare "sporer feature-briefen til den minimal-men-gyldige app-briefen, og er app-briefen ikke-tom på de fem feltene?")
---
## Fase 7 — Brief per feature → Feature-artefakter `[justert 2026-05-11 — R2: mot Voyages faktiske Handover-1-kontrakt, strict mode; brief.md + context.md-splitt]`
**Formål:** Produsere Voyage-kompatible feature-artefakter per feature, on-demand når operatør er klar for handover.
**Input:**
- `06-features-brief.md` (eller, i rapid mode: den minimal-men-gyldige app-briefen).
- Alle briefer fra fasene 1–5 (kontekst per feature — fase 4 kan være tom).
- Domain-pack: `checklist.md` (brief-validerings-items), `examples/` (eksempel-feature-brief), `scaffold/` (når artefakter materialiseres).
**Workflow `[hypotese]`:**
1. Operatør velger neste feature å briefe (typisk topp av prioritet, ingen aktive avhengigheter).
2. AI genererer `brief.md` (Voyage strict-mode-kompatibel) + `context.md` (embedder upstream) i `features/{NN}-{slug}/`.
3. Operatør reviewer, approver eller annoterer (samme review-gate som for interne briefer — se under).
4. Approvert: filene er klare for Voyage-handover.
5. Operatør materialiserer og kjører Voyage manuelt — se **Handover-mekanikk** under; kort versjon: `mkdir -p features/{NN}-{slug}/voyage/ && cp features/{NN}-{slug}/brief.md features/{NN}-{slug}/voyage/brief.md`, deretter `--project features/{NN}-{slug}/voyage/` konsekvent for research/plan/execute.
6. AI/operatør oppdaterer F-XXX-status til `voyage-running` i features-brief; `voyage_run_dir` fylles i `brief.md`-frontmatter.
**Handover-mekanikk (R-03, A5-beslutning — verifisert, ikke antatt):** `/trekresearch` har ikke noe løst `--brief`-modus (kun `--project <dir>`, og `{dir}` må eksistere på forhånd — verifisert mot `trekresearch.md` Phase 1). Konsekvent `--project` er derfor ikke et preferansevalg, men den eneste mekanikken som fungerer for hele pipelinen når `research_topics > 0`. app-creator standardiserer på **`features/{NN}-{slug}/voyage/`** som Voyages `project_dir` (ikke `.claude/projects/{date}-{slug}/` — validatoren håndhever ikke stimønsteret, kun feltets tilstedeværelse, så dette er gyldig under Handover 1s «no producer is privileged»). Handover-steget: `mkdir -p features/{NN}-{slug}/voyage/` og kopiér `brief.md` dit (`project_dir`-frontmatter-feltet i `brief.md` peker allerede dit — se frontmatter-blokken under), deretter kjør research/plan/execute med samme `--project features/{NN}-{slug}/voyage/` gjennom hele pipelinen. Dette holder Voyage-siden av en feature selvstendig under featurens egen mappe, i tråd med layout-notatet i § Filsystem-layout, og unngår R-03s `BRIEF_NOT_FOUND`-feilscenario fordi operatøren nå har et reelt kommando-steg før første Voyage-kall i stedet for en `How to continue` som pekte på en katalog ingen hadde opprettet.
**Lengde og revisjonshistorikk i fase 7** *(A2-beslutning 2026-08-10, operatør — full begrunnelse i § Hard lengde-grense)*: `brief.md` ~750 ord (flagg >1000), `context.md` ~650 (>900), `research.md` ~600 (>800). Revisjonshistorikk skrives i **`features/{NN}-{slug}/revisions.md`**, aldri som `## Revisjons-logg`-seksjon i `brief.md` — kontraktsfila skal bære kontrakten, ikke audit-trailen. Driveren er målt: da loggen lå i fila, vokste F-001 `brief.md` til 4523 ord der ~740 var kontrakt.
**`research.md`-rollen** *(A5-avklaring, jf. review R-04)*: `features/{NN}-{slug}/research.md` er app-creator-internt underlagsmateriale — kandidat-tabell, kriterier og beslutningsprosessen bak `brief.md` sine `## Research Plan`-Topic-entries. Det er IKKE en fil Voyage konsumerer: Handover 1 nevner ingen produsent-levert `research.md`, og Voyages egne research-artefakter (Handover 2) skrives til `{project_dir}/research/*.md` av `/trekresearch` selv — et helt annet sted. Om og hvordan `research.md`s innhold i tillegg bør nå Voyage (via `context.md` punkt 6, eller ikke i det hele tatt siden Topic-entryene i `brief.md` allerede bærer spørsmålet) er **konsum av Voyage IKKE verifisert — avgjøres i B1.**
### `brief.md` — Voyage Handover-1-kontrakt `[revidert 2026-08-11 — A5: brief_version 2.2, framing/phase_signals/TL;DR, handover-mekanikk; runde-trip fortsatt untestet, se B1]`
> **Verifikasjons-status (oppdatert 2026-08-11, A5):** blokken under er omskrevet fra brief_version 2.0 til **2.2**, re-verifisert mot Voyage-kildekode **2026-08-11** (`~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/5.9.1/docs/HANDOVER-CONTRACTS.md` § Handover 1 + `templates/trekbrief-template.md`). 2.2 er fortsatt gjeldende baseline (uendret siden A1s lesning 2026-07-10): 8 påkrevde Voyage-felter + `framing` (påkrevd ≥2.2) + `## TL;DR` (påkrevd ≥2.2); `phase_signals`-enum `[research, plan, execute, review]` × effort `[low, standard, high]` × model `[sonnet, opus, fable]` uendret.
>
> **Premiss-korrigering (A5, verifisert mot kildekode, ikke antatt):** masterplanens A5-fremgangsmåte anbefalte «loose-modus konsekvent (`--brief <sti>` for research og plan)» som førstevalg for handover-mekanikken (R-03). Det er **ikke teknisk mulig**: `/trekresearch` støtter KUN `--project <dir>` — det finnes ikke noe `--brief`-flagg i kommandoen (`trekresearch.md` Phase 1, punkt 4), og `{dir}` MÅ eksistere på forhånd (hard halt ellers). `/trekplan` støtter begge moduser, men selv i `--brief`-modus styres plan.md-destinasjonen av briefens EGEN `project_dir`-frontmatter-felt når det er satt (`trekplan.md:315-316`) — og `project_dir` er et påkrevd Handover 1-felt, så det er alltid satt. Handover-mekanikken under er derfor bygget på det gjenstående alternativet — dokumentert materialiserings-steg — ikke løs modus. Se «Handover-mekanikk» under.
>
> **Ingen reell round-trip har noensinne kjørt** (`voyage_running: 0`). «Round-trip-test PASS» i friksjon #14 og i Akashic-loggen er en **mental simulering**, ikke en kjøring — behandle den som papir. Denne omskrivingen (2.2, framing-avledning, TL;DR-generering, phase_signals-strategi, handover-mekanikk) er masterplan **A5**; første reelle kjøring er **B1**. Handover-mekanikken og `research.md`-rollen under er design, ikke verifisert adferd — B1 tester dem mot en reell Voyage-kjøring.
**Frontmatter** — alle 8 Voyage-påkrevde felter + state-machine-constraint + app-creator-interne felter:
```yaml
---
# --- Voyage-påkrevde (Handover 1, brief_version 2.2 — verifisert 2026-08-11 mot voyage/5.9.1) ---
type: trekbrief
brief_version: "2.2"
created: 2026-05-10
task: "{én-linjes task-beskrivelse — typisk feature-formålet}"
slug: {feature-slug}
project_dir: features/{NN}-{feature-slug}/voyage/ # se «Handover-mekanikk» — IKKE .claude/projects/, A5-korrigering
research_topics: {N} # ≥ 0
research_status: pending # pending | in_progress | complete | skipped
# State-machine: hvis research_topics > 0 OG research_status === "skipped" → brief_quality: partial PÅKREVD
brief_quality: complete # complete | partial — sett "partial" hvis ovenstående gjelder
# Valgfrie Voyage-felter:
source: manual # interview | manual — app-creator-genererte er "manual"
# v5.5 — framing: forholdet til tidligere operatør-intensjon. PÅKREVD ved brief_version ≥ 2.2.
# Avledningsregel (A5): ny feature fra godkjent 06-features-brief-backlog (revision: 0 på
# denne brief.md) → preserve (formaliserer allerede godkjent intensjon, introduserer ingen ny).
# Revidert feature (revision > 0 — backtrack fra arkitektur/constraints/annotasjon) → refine.
# replace/new-direction avledes ALDRI automatisk — kun operatør-overstyring via samme
# annotate.mjs-review-gate som resten av fase 7 (§ Annotering før handover).
framing: {preserve | refine} # operatør kan overstyre til replace | new-direction
# v5.1 — per-phase effort + model. Fase 7 har INGEN interaktiv Phase-3.5-ekvivalent (intet
# operatør-intervju per fase) — phase_signals_partial: true ville derfor feilaktig lest som et
# avbrutt intervju. Generatoren emitterer i stedet eksplisitt "standard" (samme verdi
# profile-resolveren ville falt tilbake til uansett) for alle fire faser — ærlig og
# skjema-gyldig; operatør redigerer enkeltlinjer i brief.md før Voyage-kjøring om ønsket.
phase_signals:
- phase: research
effort: standard
- phase: plan
effort: standard
- phase: execute
effort: standard
- phase: review
effort: standard
# --- app-creator-interne (Voyage ignorerer, eller app-creator stripper ved handover) ---
brief_type: feature
phase: 7
parent_app: {app-slug}
parent_feature: F-001
domain_pack: "ios-app@{version}" # pin til den versjonen appen faktisk bruker
revision: 0
voyage_run_dir: null # fylles når Voyage kjøres — peker til {project_dir} (= features/{NN}-{slug}/voyage/)
voyage_run_status: null # fylles av app-creator state-eksport fra Voyages progress.json/review.md
---
Body — de tre PÅKREVDE seksjonene (## Intent, ## Goal, ## Success Criteria) + standard-seksjonene. Generer for strict mode, ikke soft:
# Task: {feature-tittel}
> Generert av app-creator fase 7 på {YYYY-MM-DD} fra {app-slug} feature {F-XXX}.
## TL;DR ← PÅKREVD ved brief_version ≥ 2.2
{≤5 linjer. Komponert av generatoren fra `task`-linjen + en 2-3-setnings kondensering av
## Goal under, avsluttet med en eksplisitt framing-linje — f.eks. "Framing: preserve —
formaliserer godkjent F-003 fra 06-features-brief.md." Skrevet FØRST i lesrekkefølge (som i
Voyages egen template) slik at en reviewer fanger en feil premiss før resten av briefen.}
## Intent ← PÅKREVD
{Hvorfor denne featuren — fra feature-formål + relevant del av app-brief Problem & motivasjon. 3-5 setninger. Load-bearing.}
## Goal ← PÅKREVD
{Hva success ser ut som konkret når featuren er ferdig. Ett avsnitt. Spesifikt nok til å være uenig i.}
## Non-Goals
- {feature-no-gos + relevant subset av app-brief utenfor-liste}
## Constraints
- {relevant subset fra fase 5-constraints — IKKE hele constraints-brief-en, kun det som gjelder denne featuren}
## Preferences
- {preferte mønstre/biblioteker — fra fase 3 ADRer der relevant}
## Non-Functional Requirements
- {relevante NFRs, kvantifisert — f.eks. "ingen nye npm-deps", "60fps på scroll"}
## Success Criteria ← PÅKREVD
- {falsifiserbart, command-checkable kriterium — helst Given-When-Then}
- {f.eks. "Alle eksisterende tester passerer: `swift test` exit 0"}
- IKKE vage kriterier ("det skal fungere", "featuren er implementert")
## Research Plan
{Hvis research_topics = 0: én linje — "No external research needed — the codebase and this brief contain sufficient context for planning."}
### Topic 1: {Kort tittel}
- **Why this matters:** {hvordan planen avhenger av svaret}
- **Research question:** "{ett spørsmål, slutter med ?}"
- **Suggested invocation:** `/trekresearch --project {project_dir} --external "{spørsmål}"`
- **Required for plan steps:** {hvilke slags steg konsumerer dette}
- **Confidence needed:** {high | medium | low}
- **Estimated cost:** {quick | standard | deep}
- **Scope hint:** {local | external | both}
## Open Questions / Assumptions
- {[ANTAKELSE] som fortsatt gjelder for denne featuren}
## How to continue
Materialiser først (obligatorisk — se «Handover-mekanikk»):
```bash
mkdir -p features/{NN}-{slug}/voyage/
cp features/{NN}-{slug}/brief.md features/{NN}-{slug}/voyage/brief.md
Deretter, konsekvent --project (ikke --brief — /trekresearch støtter det ikke):
/trekresearch --project features/{NN}-{slug}/voyage/ --external "{Topic 1-spørsmål}" # hvis research_topics > 0, gjenta per topic
/trekplan --project features/{NN}-{slug}/voyage/
/trekexecute --project features/{NN}-{slug}/voyage/
**Round-trip-test (krav før formatet låses):** skriv en faktisk Akashic-feature-brief → materialiser til `features/{NN}-{slug}/voyage/` (se «Handover-mekanikk») og kjør `/trekplan --project features/{NN}-{slug}/voyage/` → bekreft at Voyages brief-validator passerer den i **strict mode uten endring**. Gjøres når Akashic når fase 7; formatet over låses ikke før da. **Re-verifiser Voyage-kontrakten fra kildekode** rett før omskrivingen — Voyage er en levende plugin. Kanonisk sti (samme cache-regel som for `annotate.mjs`, A1/R-05): `~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/<nyeste-versjon>/docs/HANDOVER-CONTRACTS.md` og `templates/trekbrief-template.md`. Slå opp nyeste versjon med `ls` — hardkod ikke versjonsnummeret, og bruk ikke den gamle `plugins/marketplaces/…`-stien (den finnes ikke).
### `context.md` — embedder upstream (BMAD-prinsippet: embedding slår linking)
Implementerers sekundær-input. Materialiserer (ikke bare refererer) det relevante utdraget — Voyage-agenten har ingen ambient kontekst å trekke på. Seksjoner:
1. **Dependencies** — features dette avhenger av (`{NN}-{slug}`-referanser) + features som avhenger av dette.
2. **Cross-cutting constraints** — relevant subset fra fase 5 (kun det som gjelder denne featuren).
3. **Architecture context** — relevant utdrag fra fase 3 ADRer (datamodell, API-kontrakt, mønster å følge). **Maks ~10–15 linjer** — ikke lim inn hele arkitektur-brief-en.
4. **Design-system tokens** — relevant subset fra fase 4 for denne featurens UI-overflate (eller, hvis fase 4 er tom: relevante HIG/Material-pekere fra domain-pack `conventions.md`).
5. **Domain-pack-utdrag** — relevante deler av `00-context/domain-pack-{name}.md`-snapshotet (iOS-konvensjoner, App Store-checklist-items, gotchas) som gjelder denne featuren. **Aldri merket "domain-pack-generert"** — det er bare kontekst.
6. **Research signals** — 2–3 mest relevante punkter fra fase 2-research (hvis relevant).
To-fil-splittet speiler BMAD: `brief.md` er det Voyage MÅ honorere (kontrakten); `context.md` er det Voyage trenger for å forstå kontrakten. Voyage leser begge, men er bundet kun av Success Criteria i `brief.md`. Avviker Voyage fra dem, er det en handover-feil sporbar til briefen.
### Annotering før handover (R-restpunkt 2 — lett variant)
Hvis operatøren reviewer en `brief.md` og vil annotere før handover: bruk **samme review-gate som for interne briefer** — `annotate.mjs` mot artefakten, annoter i HTML-en, Copy Prompt, AI applisere, `revision` bumps (se § Cross-cutting: Review-gate mellom faser).
*(Justert 2026-08-10 — A1/R-01.)* Den tidligere teksten foreskrev **Voyages anchor-format (Handover 8)** for fase 7-briefer spesifikt: `<!-- voyage:anchor id="ANN-0001" … -->`-kommentarer, `ANN-NNNN`-IDer og `annotation_digest` (16-hex SHA-256 over sortert `source_annotations`). **Handover 8, `/trekrevise` og anchor-/revisjonsbibliotekene ble slettet i Voyage v5.0.0** (2026-05-12). Ingen Voyage-versjon konsumerer lenger de kommentarene eller den digesten — å produsere dem er ren støy i en fil som overleveres. S5-beslutningen om «to nivåer» (lett internt, Voyage-presist på fase 7) faller derfor bort: det er **én** gate-mekanikk, den lette, for alle briefer.
**Transisjon:** Brief overleveres til Voyage. app-creators fase 7 er ferdig for den featuren. Voyage tar over. Når Voyage returnerer (plan/review), oppdateres feature-status i features-brief; `voyage_run.md` i feature-mappa skrives av state-eksport. Hvis review avslører behov for arkitektur-/constraint-endringer → backtrack til fase 3 eller 5 (revision-bump).
---
## Cross-cutting: state.json `[justert 2026-05-11 — domain_pack, skipped-reasons, session-felt]`
```json
{
"app_slug": "fitness-tracker",
"created": "2026-05-10",
"domain_pack": "ios-app@0.1.0",
"mode": "full",
"current_phase": 6,
"phase_status": {
"1": "complete",
"2": { "status": "skipped", "reason": "ingen research-temaer som driver arkitektur" },
"3": "complete",
"4": { "status": "skipped", "reason": "early stage, ingen andre brukere — trigges på bruk hvis det blir behov" },
"5": "complete",
"6": { "status": "pending-review", "revision": 0, "sidecar": "06-features-brief.review.md", "blocking": [7] },
"7": "not-started"
},
"briefs": {
"01-app-brief.md": "complete",
"03-architecture-brief.md": "complete",
"05-constraints-brief.md": "complete",
"06-features-brief.md": "in-progress"
},
"feature_summary": {
"total": 12, "brief_pending": 8, "brief_written": 2,
"voyage_running": 1, "voyage_complete": 1, "shipped": 0
},
"session": {
"current": "S12-fase6-backlog",
"next_action": "Operatør approver F-007-prioritet, så generer feature-briefer for F-001..F-003",
"log": [
"S10: fase 3 arkitektur — 4 ADRer vedtatt, 2 åpne AQ",
"S11: fase 5 constraints mot domain-pack-checklist",
"S12: fase 6 backlog — 12 features + 2 F-T, dependency-graf tegnet"
]
},
"attention": [
{ "type": "review-pending", "phase": 6, "description": "06-features-brief.md venter på operatør-review per § Cross-cutting: Review-gate.", "ref": "06-features-brief.review.md" },
{ "type": "decision", "phase": 6, "description": "F-007 har ingen prioritet satt", "ref": "06-features-brief.md#F-007" },
{ "type": "review", "phase": 7, "description": "Voyage returnerte plan for F-002, venter på review", "ref": "features/02-onboarding/voyage_run.md" }
],
"last_activity": "2026-05-10T14:32:00Z"
}
phase_status-verdier er enten en string eller et objekt med utvidet form — enum og objektformer står i § phase_status — én autoritativ enum, som er eneste kilde. Gjenta dem ikke her. domain_pack er null hvis ingen pack brukes. session er det lette flersesjons-feltet (ikke en innebygd orkestrator). Dette er filen app-factory leser for portefølje-aggregering.
Cross-cutting: Review-gate mellom faser [justert 2026-05-14 — friksjon #15; Voyage annotate.mjs adoptert 1:1]
Etter at en fase produserer sin brief (eller fase 7 sine feature-artefakter) er artefakten AI-skrevet, ikke operatør-godkjent. Neste fase kan ikke starte før operatør har gått gjennom artefakten og signert av. Mønsteret er gjenbrukt fra Voyage (scripts/annotate.mjs — per-artefakt annoterings-HTML). (Justert 2026-08-10 — A1/R-01: den tidligere formuleringen viste til /trekrevise og Handover 8. Begge ble slettet i Voyage v5.0.0 (2026-05-12) sammen med playground/; annotate.mjs er erstatningen og det eneste som finnes. Merk at annotate.mjs er en Voyage-intern fil utenfor Handover 1 — se sti-regelen under, og vendoring-beslutningen i masterplan D7.)
Hvorfor
Pipelinen er operatør-styrt syntese, ikke autonom AI-prosessering. Hvis fase n+1 bygger på u-validert fase n-output, akkumulerer alle nedstrøms-artefakter feilantakelser. Friksjon #15 (Akashic S13) oppstod nettopp slik: S11 skrev features-brief med 13 features, S12 startet fase 7 på toppen, S13 stoppet med "F-006 ville jeg ikke godkjent" — F-001-brief (S12) var allerede bygget på u-validert backlog. phase_status: "complete" betydde "AI-skrevet", ikke "operatør-godkjent". Forskjellen er kritisk og må reflekteres i status-vokabularet.
Annoterings-mekanikk (Voyage-mønsteret)
App-creator adopterer Voyage scripts/annotate.mjs direkte uten egen implementering. Mekanikken:
-
AI-side: etter at fase n-brief er skrevet, kjør Voyage-scriptet mot artefakten:
node ~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/<nyeste-versjon>/scripts/annotate.mjs <brief.md>Sti-regel (A1/R-05, 2026-08-10): installerte plugins ligger under
~/.claude/plugins/**cache**/<marketplace>/<plugin>/<versjon>/. Den tidligere dokumenterte stien (…/plugins/marketplaces/ktg-plugin-marketplace/plugins/voyage/…) finnes ikke — den gaENOENT. Slå opp nyeste versjon før bruk (ls ~/.claude/plugins/cache/ktg-plugin-marketplace/voyage/) i stedet for å hardkode et versjonsnummer; katalogen inneholder flere versjoner samtidig. Dette er en Voyage-intern fil uten kontraktsvern — Voyage har slettet interne flater med én dags varsel før. Strukturell fiks (vendore en kopi inn i app-creator) er masterplan D7, operatør-beslutning. Det produserer<brief>.htmlved siden av kilde-fila (single-file, zero deps, lokal). HTML-en rendrer markdown som en ordentlig artikkel (overskrifter, lister, kodeblokker — ikke rå-tekst), meddata-anchor-idpå hvert annotérbart element. -
Operatør-side: operatør åpner HTML-en i nettleser (
file://-lenke), velger tekst eller klikker et element, velger intent (Fiks / Endre / Spørsmål), skriver kommentar, lagrer. Annotasjoner persisterer i nettleserens localStorage (keyed på absolutt fil-sti). -
Overlevering: operatør klikker "Copy Prompt" — den genererer strukturert markdown med alle annotasjonene gruppert per seksjon, og kopierer til clipboard.
-
Applisering: operatør limer prompt-en inn i Claude i neste sesjon. AI parserer annotasjons-blokker og applisere endringer i kilde-artefakten. Bumpe
revision: N → N+1, oppdaterlast_modified, og skriv ny revisjons-entry i sidecaren<artefakt>.revisions.md(fase 7:features/{NN}-{slug}/revisions.md) — ikke i artefakten selv.
Vokabular (arvet fra Voyage)
| Intent | Norsk | Når brukes |
|---|---|---|
| Fiks | direkte korrigering | Faktafeil, typo, dårlig formulering. AI fikser uten ny diskusjon. |
| Endre | struktur-/innholds-endring | Featuren skal endres, droppes, utsettes; arkitektur-beslutning revurderes. AI applisere; konsekvenser oppstrøms/nedstrøms flagges. |
| Spørsmål | klargjøring trengs | Operatør trenger AI-svar før beslutning. AI svarer i neste sesjon; ny annoterings-runde for endelig beslutning. |
Vokabularet er tre-tier (lavnivå-Fiks → mellomnivå-Endre → høynivå-Spørsmål), ikke fem-tier fast taksonomi (approved/revise/defer/drop/question). Forskjellen er bevisst: Voyage-vokabularet er fri-form innenfor intent (kommentar bestemmer hva endringen er), ikke type-strukturert. Det matcher hvordan operatør faktisk tenker — "drop F-006" er en Endre-annotasjon med kommentar "drop fra v1", ikke en separat drop-status.
Eksempel — operatør-flow (fase 6 review)
- Åpne
06-features-brief.html(file://-lenke fra app-instansensindex.html). - Bla til F-006-seksjonen. Klikk overskriften "F-006: Daglig HVORFOR-forsterkning".
- Popover åpnes. Velg Endre. Skriv: "Drop denne featuren fra v1. Kuratert daglig YouTube-lenke føles som tvunget innhold; trenger ny vinkling som ikke binder appen til Sadhguru-kilder."
- Klikk Lagre. Annotasjonen vises i sidebar gruppert under "Backlog".
- Bla til F-002. Velg
.timeSensitive-setningen i Goal-paragrafen. Velg Endre. Skriv: "Trim til.activefor v1..timeSensitive-entitlement-søknad er overkill — flytt til v1.1+-kandidat." - Bla til F-001. Klikk Goal-paragrafen. Velg Spørsmål. Skriv: "Skal AQ-001-research-arbeidet skje i app-creator's
research.mdeller flyttes til Voyage/trekresearch?" - Klikk Copy Prompt i topbar. Strukturert markdown kopieres til clipboard.
/cleari Claude (eller start ny sesjon). Re-entry er instansensSTATE.md§ «👉 NESTE — START HER», som injiseres automatisk — ingen prompt-fil å peke på. Lim inn den kopierte annoterings-prompten når sesjonen er i gang.
Applisering — AI-side
AI parserer annotasjons-prompten (Voyage-format: H2-overskrifter per seksjon, bullet-entries med intent + sitat + kommentar). For hver Endre/Fiks:
- Endre på element: erstatt element i kilde-artefakten per kommentar. Bumpe revisjon.
- Endre på seksjon: omskriv hele seksjonen per kommentar.
- Fiks: punktuell endring (typo, formulerings-trim) uten å diskutere.
- Spørsmål: ikke applisere. Skriv AI-svar i annoterings-respons; trigge ny runde (operatør re-annoterer med ferdig info).
Etter applisering: bump revision: N → N+1 og oppdater last_modified i kilde-artefakten, og skriv revisjons-entryen i sidecaren — <artefakt>.revisions.md for fase 1–6, features/{NN}-{slug}/revisions.md for fase 7 (A2-beslutning 2026-08-10; se § Hard lengde-grense for begrunnelsen). Kilde-artefakten får ingen ## Revisjons-logg-seksjon. Sidecaren er append-only, nyeste entry øverst under H1-en:
<!-- 06-features-brief.revisions.md — audit-trail for 06-features-brief.md. Ikke en kontrakt; overleveres aldri. -->
# Revisjons-logg — 06-features-brief.md
### Revision 1 (2026-05-14, driver: operatør-annotasjoner fra 06-features-brief.html)
- F-006 daily-why: DROPPET. Endre-annotasjon: "drop fra v1, trenger ny vinkling som ikke binder appen til Sadhguru-kilder". Konsekvens oppstrøms: app-brief § Omfang #6 må re-revideres (lagt til revision-pending).
- F-002 notifications: REVIDERT. Endre-annotasjon: ".timeSensitive trim til .active for v1". Endring: Goal-seksjon + Preferences-seksjon. Konsekvens oppstrøms: constraints-brief § .timeSensitive-entitlement re-revideres.
- F-001 sun-position: SPØRSMÅL. AQ-001-handling-spørsmål mottatt; svar gitt i [responsfila]. Avventer ny annotasjons-runde.
- Andre features: GODKJENT (ingen annotasjoner mottatt).
Hvis ytterligere runder trengs: ingen ny sidecar — operatør re-åpner samme HTML, gjør nye annotasjoner (localStorage husker forrige runde, men kan ryddes). Copy Prompt → ny runde.
Konsekvens-håndtering oppstrøms
Hvis fase n-review avslører at fase n-1 må endres (f.eks. F-006-drop i fase 6 avslører at app-brief § Omfang #6 må re-revideres): operatør får eksplisitt valg i AI-tilbakemeldingen:
- (a) Backtrack til fase n-1. Bump n-1 til
revised, propagér gjennom mellomliggende faser per § Cross-cutting: brief-revisjon ved backtracking. - (b) Registrer som
revision-pendingder. Lavt-prioritet-flagging — ingen umiddelbar backtrack, men n-1-brief markeres for re-revision ved neste touch.
Konsekvens-håndtering nedstrøms (fase 7)
Hvis review av fase 6 endrer eller dropper en feature som fase 7 allerede har skrevet brief.md for: nedstrøms-konsekvens er destruktiv.
dropav feature med eksisterendefeatures/<NN>-<slug>/: AI sletter mappen + bumperfeature_summary.brief_writtenned. Hvis Voyage allerede kjører på den: settvoyage_run_statustilobsolete.reviseav feature med eksisterende brief.md: bump brief.mdrevisionog oppdater perchanges-liste; settvoyage_run_statustilstalehvis Voyage kjører.deferav feature med eksisterende brief.md: flytt mappen tildeferred/v1.1/<NN>-<slug>/; settvoyage_run_statustildeferred.
Retroaktiv review
Hvis pipelinen har kjørt uten review-gate (som Akashic gjorde frem til S12): operatør kan kjøre retroaktiv review per fase. Sidecar-fila skrives mot eksisterende artefakt; applisering bumper revisjon fra 0 → 1. Hvis retroaktiv review avslører at flere oppstrøms-faser også må revideres: backtracking-mekanikk § Cross-cutting: brief-revisjon ved backtracking håndterer propagering.
Attention-entry
state.json.attention[] får ny type review-pending:
{
"type": "review-pending",
"phase": 6,
"description": "06-features-brief.md venter på operatør-review. Annotér 06-features-brief.review.md per § Cross-cutting: Review-gate.",
"ref": "06-features-brief.review.md"
}
Attention-entry fjernes når sidecar applisert + phase_status → complete.
Frekvens og lett anvendelse
Review-gate er obligatorisk mellom hver fase. Det er ikke valgfri "kvalitetskontroll" — uten review-gate kan operatør ikke kalibrere AI-output mot egen intuisjon, og pipelinen sklir mot "AI-skrevet → AI-konsumert" hvor operatør blir gummi-stempler.
For minimal-friksjon-faser (kort app-brief, ren research-brief uten kontroversielle funn) kan sidecar bestå av én linje:
all-approved
AI applisere som tom revisjon: phase_status → complete uten revision-bump. Sidecar-fila committes som audit-spor selv ved all-approved.
Forholdet til status-merking
Status-merkene fra § Status-merking ([hypotese], [testet], [justert YYYY-MM-DD]) er om template-/spec-modenhet. Review-gate-status er om operatør-godkjenning av en konkret app-instans' brief. De to er ortogonale: en fase kan ha [testet]-template og likevel kreve review-gate for hver kjøring.
Cross-cutting: brief-revisjon ved backtracking [hypotese]
Når en senere fase avdekker behov for endring i en tidligere brief:
- Bump
revisioni brief-frontmatter (0→1). - Sett
revision_reasontil kort beskrivelse. - Oppdater
last_modified. - Oppdater referanser i nedstrøms briefer hvis kontrakter har endret seg.
- Hvis features-brief har features avhengig av forrige form: marker dem
revision-pendingtil de er reviderte. For allerede-skrevne fase 7-brief.md/context.md: bump deresrevision, settvoyage_run_statustilstalehvis Voyage allerede kjører på den.
Den eksakte backtracking-propagerings-mekanikken (hvordan en fase 3-endring forplanter seg til allerede-skrevne feature-briefer) er fortsatt [åpent] — Akashic vil avsløre den når en backtrack faktisk skjer. Mønsteret er inspirert av Voyages annoterings-revisjons-mekanisme (annotate.mjs), ikke en kopi.
Cross-cutting: attention-generering [hypotese]
Heuristikker for "trenger oppmerksomhet": fase incomplete uten aktivitet siste 7 dager; brief uten phase_status: complete etter at fasen burde være ferdig; feature uten prioritet etter at features-brief er complete; brief-written feature uten Voyage-run startet; Voyage-run-status review-pending / blocked; constraint-konflikt avdekket senere; dependency-konflikt i features-brief; brief revisjon-pending; skippet fase uten begrunnelse (manglende reason-felt). Låses ikke nå — prototypen avslører hvilke heuristikker som er nyttige vs støy.
Hva dette utkastet IKKE dekker
- Eksakte AI-prompts. Hvilke spørsmål AI stiller i fase 1, hvordan AI rammer arkitektur-alternativer i fase 3 — låses ikke før prototypen viser hva som virker.
- Implementasjons-detaljer. Hooks, scripts, HTML-rendering, en eventuell
/app-creator-command — separate dokumenter etter prototype. - Backtracking-propagerings-mekanikk i detalj. Hvordan fase 3-endringer forplanter seg til allerede-skrevne feature-briefer —
[åpent]. - Innebygd flersesjons-orkestrator. Mønsteret er dokumentert + lett state-felt; en innebygd
trekcontinue-aktig mekanikk vurderes først hvis prototypen viser at den manuelle protokollen ikke holder. - Multi-platform-apps. Utkastet antar én plattform per app-creator-instans (= én domain-pack). Universal apps eller iOS+watchOS er
[åpent]. - Branching i feature-derivasjon. Hva skjer hvis en feature spinnes opp basert på A/B-test eller eksperiment —
[åpent]. - Versjonering av app-creator-instans. "v2 av samme app" / redesign-faser —
[åpent]. - Domain-pack-spec i detalj. Egen fil:
domain-pack-spec.md. - Andre brief-typer. Eventuelle deployment- eller validation-briefer som senere viser seg verdt å ha —
[åpent]for v0.5.0+.
Når dette utkastet skal oppdateres
- Etter Akashic fase 2–6: revisjons-merking på hver fase som faktisk kjøres;
[hypotese]→[testet]eller[justert YYYY-MM-DD]. - Etter første feature-brief gjennom Voyage: låsing av fase 7-formatet mot Handover 1 (forutsetter round-trip-test som passerer strict mode).
- Etter at fase-overhead-tid er målt i Akashic-kjøringen (R17): faser som tar timer og produserer artefakter ingen Voyage-brief refererer = bevist seremoni → kandidater for å bli skippbare-by-default eller fjernes.
- Etter første feature shipped: end-to-end-validering av hele pipelinen.
- v0.4.0 lock: alt som har overlevd reell bruk får
[testet]-merking; resterende[hypotese]/[åpent]-felt forblir åpne for v0.5.0+.
Dette utkastet er starten. Prototypen er testen.