app-creator/docs/phase-design-draft.md

Phase-design-utkast: app-creators 7-fase-pipeline

Hvorfor dette dokumentet finnes

Den manuelle iOS-prototypen 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. Forventet utfall: 30-60% av detaljene endres når reell bruk avslører hva som virker.

Scope-lås

app-creator dekker utviklings-prosessen — fra app-bestilt til app-bygget. 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, reell-bruk-analyse av shipped app

Hvis en idé peker på pre-decision eller post-shipping, hører den ikke i app-creator. Det er separate verktøy-kategorier (eller for solo-utvikler: utenfor system-scope helt). Brief-templater i dette utkastet skal ikke utvides for å dekke disse områdene.

Brief-pattern som unifisert artefakt-form

Hver fase produserer én eller flere briefer — strukturerte markdown-dokumenter med YAML-frontmatter og phase-spesifikt innhold i seksjoner. Mønsteret er konsistent på tvers av fasene:

• App brief (fase 1) — én per app
• Research briefs (fase 2, valgfri) — én per research-tema
• Arkitektur brief (fase 3) — én per app
• Design brief (fase 4) — én per app
• Constraints brief (fase 5) — én per app
• Features brief (fase 6) — én per app (backlog-oversikt)
• Feature briefer (fase 7) — én per feature, Voyage-handover

Konsistensen gir én HTML-renderer, lik review-UX, og enkel kryss-referansing mellom briefer. Phase-spesifikk struktur lever inni hver brief, ikke som forskjellige format på tvers.

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

Ved revisjon: oppdater merkingen — [testet], [justert YYYY-MM-DD], eller [forkastet] med begrunnelse.

Workflow-oversikt

┌─────────────────────────────────────────────────────────────┐
│ Pre-pipeline: app-discovery, init av app-creator-instans    │
└─────────────────────────────────────────────────────────────┘
                            │
                            ▼
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│ 1. Intervju      │──▶│ 2. Research      │──▶│ 3. Arkitektur    │
│   → app brief    │   │   → research     │   │   → arkitektur   │
│                  │   │      briefer     │   │      brief       │
└──────────────────┘   └──────────────────┘   └──────────────────┘
                                                       │
                            ┌──────────────────────────┘
                            ▼
┌──────────────────┐   ┌──────────────────┐   ┌──────────────────┐
│ 4. Designsystem  │──▶│ 5. Constraints   │──▶│ 6. Feature-      │
│   → design brief │   │   → constraints  │   │    derivasjon    │
│                  │   │      brief       │   │   → features     │
│                  │   │                  │   │      brief       │
└──────────────────┘   └──────────────────┘   └──────────────────┘
                                                       │
                            ┌──────────────────────────┘
                            ▼
┌─────────────────────────────────────────────────────────────┐
│ 7. Feature briefer (per feature, parallell, on-demand)      │
│   → handover til Voyage som filer (Handover 1)              │
└─────────────────────────────────────────────────────────────┘

Sekvenseringen er lineær med backtracking, ikke streng pipeline. Phase 6 kan avsløre arkitektur-gap → tilbake til 3 (arkitektur brief revideres). Phase 7 brief-skriving kan avsløre constraint-konflikt → tilbake til 5. Backtracking er ikke feil — det er læring.

Brief-fasen (7) er kontinuerlig etter at fasene 1-6 har produsert grunnlag. Feature-briefer skrives per feature on-demand når operatøren er klar for handover til Voyage. Faser 1-6 kan også re-besøkes mens 7 pågår.

Filsystem-layout [hypotese]

{app-creator-instance-dir}/
├── app.md                              # App-identitet, opprettet ved init
├── state.json                          # Live status (fase-progress, attention)
├── 01-app-brief.md                     # Output fra fase 1
├── 01-interview-transcript.md          # Råform fra fase 1 (kontekst, ikke brief)
├── 02-research-briefs/                 # Valgfri (mappe finnes kun hvis brukt)
│   ├── 01-{topic-slug}.md
│   └── NN-{topic-slug}.md
├── 03-architecture-brief.md            # Output fra fase 3
├── 04-design-brief.md                  # Output fra fase 4
├── 05-constraints-brief.md             # Output fra fase 5
├── 06-features-brief.md                # Output fra fase 6 (backlog + dependency-graf inni)
└── 07-feature-briefs/                  # Output fra fase 7 — Voyage-kompatible
    └── {NN}-{feature-slug}.md

{app-creator-instance-dir} plassering er [åpent] — kan være under ~/.claude/projects/, under en konkret repo, eller egen app-creator/ mappe. Avgjøres ved /trekbrief etter prototype-erfaring.

Felles brief-frontmatter-felter [hypotese]

Alle briefer i app-creator har disse felles felter (i tillegg til brief-spesifikke):

---
brief_type: app | research | architecture | design | constraints | features | feature
phase: 1-7
phase_status: in-progress | complete | revised
parent_app: {app-slug}              # internal — kun app-creator-konsumert
created: 2026-05-10
last_modified: 2026-05-10
revision: 0                          # bumps ved backtracking
revision_reason: null                # fylles ved revisjon
---

Voyage-relevante feature-briefer (fase 7) trimmer eller skjuler parent_app-felt fordi Voyage skal være agnostisk (se ../../app-factory/docs/architecture-brief.md).

Pre-pipeline: app-discovery og init

Formål: Opprette en app-creator-instans, registrere den i state slik at app-factory kan finne den.

Workflow [hypotese]:

1. Operatøren kjører /app-creator init {slug} (eller tilsvarende)
2. AI oppretter {app-creator-instance-dir}/
3. AI ber om grunn-info: app-navn, plattform-mål, opprettelses-grunn
4. Skriver app.md med denne info
5. Skriver initial state.json (fase 0, ingen attention)

Output: app.md [hypotese]

---
slug: fitness-tracker
name: "Fitness Tracker"
created: 2026-05-10
platform: ios
status: active
---

# {Navn}

## Hvorfor denne appen

{Operatørens initial-begrunnelse — én avsnitt}

## Pre-fase-notater

{Eventuelle notater før intervju-fasen formelt starter}

app.md er identitets-fil, ikke en brief. Fungerer som rot-fil app-factory bruker for app-discovery.

---

Fase 1 — Intervju → App brief

Formål: Hente ut app-intent klart nok til å bygge resten på.

Input:

• app.md (fra pre-pipeline)
• Operatørens åpne ideer/skisser

Workflow [hypotese]:

1. AI starter strukturert intervju basert på sjekkliste
2. Sjekkliste-tema (kategorier, ikke fast spørsmåls-rekkefølge):
   • Problem & motivasjon
   • Brukere
   • Suksess-kriterier
   • Omfang
   • Plattform-spesifikt
   • Tidshorisont
3. AI følger opp på tvetydighet, summerer underveis
4. Operatør korrigerer
5. Avsluttes når sjekkliste er dekket og operatør sier OK

Output 1: 01-interview-transcript.md [hypotese]

Full samtale, råform. Ingen frontmatter krevd. Tidsstempel-merket per spørsmål-svar. Råmateriale for senere referanse, ikke en brief.

Output 2: 01-app-brief.md [hypotese]

---
brief_type: app
phase: 1
phase_status: complete
parent_app: fitness-tracker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
revision_reason: null
---

# App brief: {Navn}

## Problem og motivasjon
{1-2 avsnitt — hva løser appen, for hvem, hvorfor nå}

## Målgruppe
- **Primær:** {beskrivelse, kontekst, ferdighetsnivå}
- **Sekundær:** {beskrivelse hvis aktuelt}

## Suksess-kriterier
- {konkret, helst målbart kriterium}
- {konkret, helst målbart kriterium}

## Omfang

### Innenfor
- {punkt}

### Utenfor (eksplisitt)
- {punkt}

## Plattform
- **Mål:** {iOS-only / universal / watch+phone / etc.}
- **Min-versjon:** {iOS 17 / iOS 18}
- **Andre plattform-detaljer:** {widgets / extensions / shortcuts / etc.}

## Tidshorisont
- **MVP:** {beskrivelse}
- **v1:** {beskrivelse}
- **Lengre sikt:** {beskrivelse hvis relevant}

## Åpne spørsmål etter intervju
- {spørsmål som krever research eller arkitektur-beslutning}

## Referanser
- `01-interview-transcript.md` — full samtale

Transisjon: Operatør markerer fasen complete ved å oppdatere phase_status: complete i app-brief og state.json. Hvis åpne research-temaer finnes, fase 2 anbefales; ellers hopp direkte til fase 3.

---

Fase 2 — Research → Research briefer (valgfri)

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 eller eksplisitt i fasens start)

Workflow [hypotese]:

1. AI foreslår research-plan basert på åpne temaer
2. Operatør approver eller justerer
3. Per tema: AI gjennomfører research (web, docs, kjente kilder), produserer brief
4. Hvert tema lagres som egen brief
5. 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
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}
---

# 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}
- {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. Hopp til fase 3.

---

Fase 3 — Arkitekturavklaringer → Arkitektur brief

Formål: Velge tech-stack, deployment-modell, integrasjoner, sentrale mønstre.

Input:

• 01-app-brief.md
• 02-research-briefs/*.md (hvis fase 2 ble brukt)

Workflow [hypotese]:

1. AI foreslår arkitektur-alternativer (typisk 2-3 sammenligning) basert på intent + research
2. Per beslutnings-punkt: AI gir anbefaling med begrunnelse
3. Operatør approver, foreslår alternativ, eller stiller spørsmål
4. Avsluttes når alle sentrale beslutninger er tatt

Output: 03-architecture-brief.md [hypotese]

---
brief_type: architecture
phase: 3
phase_status: complete
parent_app: fitness-tracker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
decision_count: {N}
---

# Arkitektur brief

## Stack-sammendrag
- **Språk/runtime:** {f.eks. Swift 6 + SwiftUI}
- **Plattform-target:** {iOS 17+ / iOS 18+}
- **State-management:** {f.eks. Observation framework + SwiftData}
- **Persistens:** {f.eks. SwiftData + iCloud}
- **Nettverk:** {f.eks. URLSession + actor isolation}
- **Test-strategi:** {f.eks. Swift Testing + XCUITest}

## Sentrale beslutninger (ADR-style)

### ADR-001: {Beslutnings-tittel}

**Status:** Vedtatt | Foreslått | Erstattet

**Kontekst:** {Problem som krever beslutning}

**Vurderte alternativer:**
1. **{A}** — pros: {...}, cons: {...}
2. **{B}** — pros: {...}, cons: {...}

**Beslutning:** {Valgt alternativ med begrunnelse}

**Konsekvenser:**
- {hva dette gjør lett}
- {hva dette gjør vanskelig}
- {hva dette låser oss til}

**Revisjons-trigger:** {Når denne beslutningen burde re-vurderes}

---

### ADR-002: {neste beslutning}
...

## Sentrale patterns
- **{Pattern A}:** {hvorfor og hvor brukt}
- **{Pattern B}:** {hvorfor og hvor brukt}

## Integrasjoner
- **{Tredjepart eller Apple-API}:** {bruks-formål}
- **{...}:** {...}

## Open architecture concerns
- {Forhold som krever videre research eller revisjon}

## Referanser
- `01-app-brief.md` — app-intent som driver arkitektur-valgene
- `02-research-briefs/NN-*.md` — research som har påvirket beslutninger

Transisjon: Når operatør approver brief, fase complete. Til fase 4.

---

Fase 4 — Designsystem → Design brief

Formål: Visuelle og interaksjons-tokens som binder alle features visuelt og opplevelsesmessig.

Input:

• 01-app-brief.md (for målgruppe og brand-direksjon)
• 03-architecture-brief.md (for plattform-target — påvirker tilgjengelige design-API)

Workflow [hypotese]:

1. AI foreslår design-direksjon basert på app-type, plattform, og målgruppe
2. Standard utgangspunkt: HIG (iOS) eller Material (Android) eller egen for web
3. AI lister tokens: farger, typografi, spacing, motion, interaksjoner
4. Operatør justerer brand-spesifikke valg
5. AI definerer gjenbrukbare komponenter

Output: 04-design-brief.md [hypotese]

---
brief_type: design
phase: 4
phase_status: complete
parent_app: fitness-tracker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
base_system: hig | material | custom
component_count: {N}
---

# Design brief

## Base-system
{HIG / Material / Custom — kort begrunnelse}

## Tokens

### Farger

#### Light
- `accent`: {hex} — {bruk}
- `background-primary`: {hex} — {bruk}
- ...

#### Dark
- `accent`: {hex} — {bruk}
- ...

### Typografi
- `display`: {font-stack, size, weight, line-height}
- `body`: {...}
- `caption`: {...}

### Spacing
- `xs`: 4pt
- `sm`: 8pt
- ...

### Motion
- `quick`: {duration, easing}
- `medium`: {...}

## Interaksjons-prinsipper
- {prinsipp og når det gjelder}

## Komponent-bibliotek

### {KomponentNavn}
**Bruk:** {når brukes denne}
**Anatomi:** {deler}
**States:** default, hover/pressed, disabled, loading
**Token-bruk:**
- Bakgrunn: `{token-navn}`
- Tekst: `{token-navn}`

**Eksempel-implementasjon (skjelett):**
```swift
{kort kode-skisse}

---

{Neste komponent}

...

Referanser

• 01-app-brief.md — målgruppe og tone-direksjon
• 03-architecture-brief.md — plattform-target som begrenser design-API

**Transisjon:** Når brief er approvert, fase complete. Til fase 5.

---

## Fase 5 — Constraints → Constraints brief

**Formål:** Cross-feature regler som gjelder for alle features uavhengig av deres egen logikk.

**Input:**
- `01-app-brief.md` (suksess-kriterier kan inkludere ytelse, A11Y)
- `03-architecture-brief.md` (plattform-target gir baseline-constraints)

**Workflow `[hypotese]`:**
1. AI lister kategorier av constraints og foreslår innhold per kategori
2. Operatør approver eller utvider
3. Hver constraint klassifiseres: enforce (hard krav) eller aspire (mål)

**Output: `05-constraints-brief.md`** `[hypotese]`

```yaml
---
brief_type: constraints
phase: 5
phase_status: complete
parent_app: fitness-tracker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
constraint_count: {N}
---

# Constraints brief

## A11Y
- **[enforce]** WCAG 2.1 AA-kontrast i alle synlige elementer
- **[enforce]** VoiceOver-labels på alle interaktive elementer
- **[aspire]** Dynamic Type opp til AX5
- ...

## Ytelse
- **[enforce]** App launch < 1.5s på iPhone 13
- **[aspire]** 60fps på alle interaksjoner
- ...

## Sikkerhet & personvern
- **[enforce]** Ingen tracking uten ATT-permission
- **[enforce]** All sensitiv data i Keychain
- ...

## Plattform-regler
- **[enforce]** App Store Review Guidelines compliance
- **[enforce]** HIG-konformt navigation-mønster
- ...

## Governance
- **[aspire]** GDPR-klar for europeiske brukere
- ...

## Test-dekning

Per-feature /trekreview er nødvendig men ikke tilstrekkelig — det dekker kun feature-scope. App-level testing krever eksplisitte krav her, og bygges som dedikerte test-infrastruktur-features i fase 6.

### Per-feature-nivå (eierskap: hver feature-brief)
- **[enforce]** Unit-tester for all forretnings-logikk
- **[enforce]** UI-tester for primær-flow i featuren
- **[enforce]** Voyage `/trekreview`-pass uten BLOCKERS før feature regnes som complete

### App-nivå (eierskap: dedikerte test-infrastruktur-features i features-brief)
- **[enforce]** E2E-tester for kritisk-sti-flow (login → core-action)
- **[enforce]** A11Y-compliance-tester på tvers av primære flows
- **[enforce]** Performance-regresjons-tester for app launch og navigasjon
- **[aspire]** Visuell-regresjons-tester med screenshot-sammenligning
- **[aspire]** Cross-feature-regresjons-suite som kjøres når ny feature shippes

App-nivå-tester er **features i backlogen**, ikke et magisk lag — Voyage bygger dem som hvilken som helst annen feature. Se features-brief for mønster.

## Konflikt-håndtering
Når to constraints er i konflikt: prioriter [enforce] over [aspire], deretter eldste over nyeste, deretter operatør-beslutning.

## Referanser
- `01-app-brief.md` — suksess-kriterier som ofte oversettes til constraints
- `03-architecture-brief.md` — plattform-target som gir baseline

Transisjon: Når constraints er listet og kategorisert, fase complete. Til fase 6.

---

Fase 6 — Feature-derivasjon → Features brief

Formål: Avlede feature-backlog fra fasene 1-5, identifisere avhengigheter, prioritere.

Input:

• Alle briefer fra fasene 1-5

Workflow [hypotese]:

1. AI foreslår feature-liste basert på intent + arkitektur + constraints
2. Per feature: navn, formål, suksess-kriterium, avhengigheter, antatt størrelse
3. Operatør approver, omprioriterer, eller flytter ting til "later"
4. AI tegner dependency-graf

Output: 06-features-brief.md [hypotese]

---
brief_type: features
phase: 6
phase_status: complete
parent_app: fitness-tracker
created: 2026-05-10
last_modified: 2026-05-10
revision: 0
feature_count: {N}
---

# Features brief

## Backlog

### F-001: {Feature-navn}
- **Slug:** {feature-slug}
- **Formål:** {én setning}
- **Suksess-kriterium:** {hvordan vet vi at den virker}
- **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
- **Brief-fil:** `07-feature-briefs/01-{slug}.md` (når skrevet)

### F-002: {neste feature}
...

### F-T01: E2E test framework setup *(eksempel test-infrastruktur-feature)*
- **Slug:** test-e2e-framework
- **Formål:** XCUITest-suite for kritisk bruker-flow (driver: `05-constraints-brief.md` § Test-dekning)
- **Suksess-kriterium:** Login → core-action-flow har grønn E2E-test som kjører i CI
- **Avhengigheter:** F-001 (login), F-002 (onboarding), F-003 (main feed) — alle må være shipped
- **Antatt størrelse:** M
- **Prioritet:** P1 — kjør etter F-003 er shipped
- **Status:** brief-pending
- **Brief-fil:** `07-feature-briefs/NN-test-e2e-framework.md` (når skrevet)

### F-T02: A11Y compliance suite *(eksempel test-infrastruktur-feature)*
- **Slug:** test-a11y-suite
- **Formål:** Automatisk A11Y-test på alle skjermer i kritisk sti
- **Avhengigheter:** F-001, F-002, F-003
- **Antatt størrelse:** S
- **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 feature-brief i fase 7. `F-T`-prefiks er en konvensjon for å skille dem visuelt — ikke en arkitektur-grense. Krav til disse driverne fra `05-constraints-brief.md` § Test-dekning.

## 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 — bryt denne, og halvparten av appen blokkeres

Parallelliserbare grupper

Gruppe A (etter F-002):

• F-003 (main feed)
• F-004 (profile)

Disse kan utvikles samtidig hvis du har kapasitet.

Referanser

• 01-app-brief.md — intent som features avledes fra
• 03-architecture-brief.md — patterns som features skal følge
• 04-design-brief.md — komponenter som features bruker
• 05-constraints-brief.md — regler features må overholde

**Transisjon:** Når brief er approvert, fase complete. Til fase 7 (kontinuerlig).

---

## Fase 7 — Brief per feature → Feature briefer

**Formål:** Produsere Voyage-kompatible briefer per feature, on-demand når operatør er klar for å handover.

**Input:**
- `06-features-brief.md`
- Alle briefer fra fasene 1-5 (kontekst per feature)

**Workflow `[hypotese]`:**
1. Operatør velger neste feature å briefer (typisk topp av prioritet, ingen aktive avhengigheter)
2. AI genererer feature-brief basert på feature-definisjon + relevant kontekst fra fasene 1-5
3. Operatør reviewer, approver eller justerer
4. Approvert brief lagres som `07-feature-briefs/{NN}-{slug}.md` — klar for Voyage handover
5. Operatør kjører Voyage manuelt: `/trekplan --brief {sti}`
6. F-XXX status oppdateres til `voyage-running` i features-brief

**Output: `07-feature-briefs/{NN}-{feature-slug}.md`** `[åpent — låses mot Voyages eksakte brief-format]`

Format må matche Voyages Handover 1 nøyaktig (round-trip-test). Skjelett basert på Voyages /trekbrief-output:

```yaml
---
# Voyage-konsumerbare felter (Handover 1)
slug: {feature-slug}
created: 2026-05-10
# ... alle felter Voyage forventer ...

# app-creator-interne felter (Voyage ignorerer eller burde ignorere)
brief_type: feature
phase: 7
parent_app: {app-slug}
parent_feature: F-001
revision: 0
voyage_run_dir: null            # fylles når Voyage kjøres
voyage_run_status: null         # fylles av app-creator state-eksport når Voyage returnerer
---

# {Feature-navn}

## Mål
{Hva denne featuren skal oppnå — én avsnitt}

## Brukerkontekst
{Hvem bruker dette og når}

## Suksess-kriterier
- {testbart kriterium}
- {testbart kriterium}

## Omfang

### Innenfor
- {punkt}

### Utenfor (eksplisitt)
- {punkt}

## Antakelser fra app-rammen
- **Arkitektur:** {referanse til ADR-NNN i 03-architecture-brief.md}
- **Designsystem:** {referanse til komponenter/tokens i 04-design-brief.md}
- **Constraints som gjelder:** {referanse til 05-constraints-brief.md kategori/punkt}

## Avhengigheter til andre features
- **F-XXX:** {beskrivelse av hva som forventes klart først}

## Research-områder (Voyage `--research`)
- {hva Voyage bør utforske før plan skrives}

## Edge-cases å vurdere
- {edge-case 1}
- {edge-case 2}

Forholdet til Voyage: Briefen overleveres som fil. Voyage konsumerer den uendret. parent_app, parent_feature og andre app-creator-interne felter kan Voyage ignorere — eller app-creator kan strippe dem før handover. Detaljer låses ved round-trip-test.

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. Hvis review avslører behov for arkitektur-/constraint-endringer, backtrack til fase 3 eller 5 (revisjon-bumps brief-revision).

---

Cross-cutting: state.json [hypotese]

{
  "app_slug": "fitness-tracker",
  "created": "2026-05-10",
  "current_phase": 6,
  "phase_status": {
    "1": "complete",
    "2": "complete",
    "3": "complete",
    "4": "complete",
    "5": "complete",
    "6": "in-progress",
    "7": "not-started"
  },
  "briefs": {
    "01-app-brief.md": "complete",
    "02-research-briefs/01-swiftdata-cloudkit.md": "complete",
    "03-architecture-brief.md": "complete",
    "04-design-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
  },
  "attention": [
    {
      "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": "07-feature-briefs/02-onboarding.md"
    }
  ],
  "last_activity": "2026-05-10T14:32:00Z"
}

Dette er filen app-factory leser for å aggregere portefølje-state.

Cross-cutting: brief-revisjon ved backtracking [hypotese]

Når en senere fase avdekker behov for endring i en tidligere brief:

1. Bump revision i brief-frontmatter (0 → 1)
2. Sett revision_reason til kort beskrivelse av hvorfor
3. Oppdater last_modified
4. Oppdater referanser i nedstrøms briefer hvis kontrakter har endret seg
5. Hvis features-brief har features som var avhengig av forrige form: marker dem revision-pending til de er reviderte

Mønsteret arvet fra Voyages annoterings-revisjons-mekanisme (Handover 8). Eksakt mekanikk for app-creator låses ved prototype.

Cross-cutting: attention-generering [hypotese]

Heuristikker for hva som regnes som "trenger oppmerksomhet":

• Phase incomplete med ingen 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
• Voyage-run-status blocked
• Constraint-konflikt avdekket i senere fase
• Dependency-konflikt i features-brief
• Brief revisjon-pending etter backtracking

Dette låses ikke nå — prototypen vil avsløre hvilke heuristikker som faktisk 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 — separate dokumenter etter prototype.
• Backtracking-mekanikk i detalj. Hvordan endringer i fase 3 propagerer til allerede-skrevne feature-briefer — åpent spørsmål.
• Multi-platform-apps. Utkastet antar én plattform per app-creator-instans. Universal apps eller iOS+watchOS er åpent.
• Branching i feature-derivasjon. Hva skjer hvis feature spinnes opp basert på A/B-test eller eksperiment — åpent.
• Versjonering av app-creator-instans. Hvordan håndtere "v2 av samme app" eller redesign-faser — åpent.
• Andre brief-typer. Eventuelle test-, deployment-, eller validation-briefer som senere viser seg verdt å ha — åpent for utvidelse i v0.5.0+.

Når dette utkastet skal oppdateres

• Etter første intervju-fase på reell iOS-app: revisjons-merking på fase 1 og app-brief
• Etter første feature-brief gjennom Voyage: låsing av brief-format mot Handover 1 (forutsetter round-trip-test)
• Etter første feature shipped: end-to-end-validering av hele pipelinen
• Etter friksjons-logg-aggregering: brief-templates som ofte ble omskrevet → oppdateres
• v0.4.0 lock: alt som har overlevd reell bruk får [testet]-merking; resterende [hypotese]-felt forblir åpne for v0.5.0+

Dette utkastet er starten. Prototypen er testen.