# Three-tier ecosystem context

<!-- Skrevet: 2026-05-10 -->
<!-- Status: Architectural-awareness-doc. Voyage stays agnostic in code; this doc is for development context only. -->

## Why this document exists

Voyage is consumed by upstream tooling. This document names that ecosystem so future Voyage development can make informed decisions about contracts (brief format, CLI shape, handover schemas) without either ignoring or coupling to specific consumers.

The principle is hard: **Voyage code stays agnostic.** No imports of upstream plugins, no "is this app-creator?" checks, no special cases. Voyage works standalone and runs identically whether its consumers exist or not.

What this document gives you is **awareness**, not coupling. It is the documentation-level analog of the existing pattern in `CLAUDE.md` § Architecture, where the optional upstream architect plugin is acknowledged without being depended on.

## The three tiers

```
Tier 3 — app-factory       Per-portefølje
                            Aggregerer state fra Tier 2-instanser
                                  ▲
                                  │ leser
                                  │
Tier 2 — app-creator       Per-app
                            Pipeline fra app-konsept til feature-briefer
                                  │
                                  │ produserer briefer som Voyage konsumerer
                                  ▼
Tier 1 — Voyage (this)     Per-task
                            Per-feature pipeline (brief → research → plan
                            → execute → review)
```

Voyage er Tier 1. Voyage er ikke avhengig av Tier 2 eller Tier 3. Tier 2 og 3 leser Voyages output (artefakt-filer) og produserer input til Voyage (briefer).

## Upstream-konsumenter (status: privat marketplace)

- **app-creator** — `ktg-privat/plugins/app-creator` — pre-design. Pipeline som produserer Voyage-briefer fra app-konsept (intervju → research → arkitektur → designsystem → constraints → features → briefer).
- **app-factory** — `ktg-privat/plugins/app-factory` — konseptuell pre-design. Portefølje-HTML som leser app-creator state.

Begge er for tiden i privat marketplace under inkubasjon. De vil bli flyttet til en offentlig marketplace når de er modne. Voyage-utvikling skal **ikke** vente på dem.

## Voyage-kontrakter som er upstream-konsumerte

Disse er stabilitets-kritiske fordi upstream-tooling avhenger av dem:

| Kontrakt | Hva den er | Konsumert av |
|----------|------------|--------------|
| `brief.md` frontmatter + struktur (Handover 1) | Format som /trekbrief produserer og /trekplan konsumerer | app-creators brief-generator (fase 7) |
| `/trekplan` CLI shape (`--brief`, `--project`, `--research`, `--decompose`) | Måter å starte plan-fasen på | Operatører som kjører på app-creator-genererte briefer |
| `plan.md` schema (Handover 2) | Output fra /trekplan | app-creators state-eksport (etter at Voyage har returnert) |
| `review.md` schema (Handover 6) | Output fra /trekreview | app-creators state-eksport, app-factorys attention-aggregering |
| `progress.json` schema | Voyages eksekverings-state | app-creators per-app HTML, app-factorys portefølje-HTML |
| `.session-state.local.json` schema (Handover 7) | Multi-session resume-state | app-creators state-eksport |

Endringer i disse er ikke per definisjon brytende, men krever bevisst vurdering. Spør:
- Er den eksisterende formen forward-kompatibel? (legg til felter, ikke fjern dem)
- Hvis brytende: er det reflektert i major bump?
- Har upstream-konsumenter fått tid til å oppdatere?

For tidlig fase (mens app-creator/app-factory er pre-design): brytende endringer er akseptable, bare flagg dem tydelig i CHANGELOG.

For senere (når app-creator har shipped v0.4.0 — som er versjonen der upstream-kontraktene låses): brytende endringer krever major bump i Voyage og koordinert utgivelse.

## Hva Voyage IKKE skal gjøre

- **Ikke importere kode fra app-creator/app-factory.** Voyage er standalone.
- **Ikke ha "running under app-creator?"-deteksjon.** Pipeline-en oppfører seg likt uansett.
- **Ikke generere briefer formattert spesifikt for app-creator.** /trekbrief produserer Voyage-kanonisk brief; det er upstream-tooling som må matche.
- **Ikke legge til CLI-flagg som betjener app-creator-spesifikke use-cases.** Hold flaggene generelle.
- **Ikke endre Voyage-scope basert på upstream-behov.** Hvis app-creator trenger noe Voyage ikke gir, er det app-creator som må løse det internt — eller flagge det som arkitektur-spørsmål oppover (i app-creator-laget), ikke nedover (i Voyage-laget).

## Hva Voyage MÅ gjøre

- **Dokumentere brytende endringer eksplisitt** i CHANGELOG selv om upstream-konsumenter for tiden er pre-design.
- **Tenke på handover-kontrakter som API-er.** Selv om de er filer, behandles de av andre verktøy som strukturerte data.
- **Fortsette å utvikle Voyage på sin egen kadens.** Voyage venter ikke på upstream.

## Beslutninger der denne konteksten matter

Når du som Claude jobber med Voyage og vurderer:

| Endring | Spør først |
|---------|-----------|
| Endre brief.md frontmatter-felter | Er dette brytende for upstream brief-generatorer? |
| Endre /trekplan CLI-flagg | Vil dette brekke operatører som kjører automatiserte pipelines? |
| Endre handover-schemaene (plan/review/progress/session-state) | Hvilke verktøy leser disse i dag? |
| Legge til nye Voyage-features | Hører dette hjemme i Voyage, eller i upstream-laget? |

For "Hører dette hjemme i Voyage?": hvis featuren handler om per-app-orkestrering eller multi-app portefølje, hører den IKKE hjemme i Voyage. Henvis spørsmålet oppover (app-creator eller app-factory).

## Forholdet til Plugin Playground (v4.3)

v4.3 Plugin Playground er Voyages **per-feature** HTML-flate. Den er Tier 1 i tre-tier-modellen. Tier 2 (app-creator per-app HTML) og Tier 3 (app-factory portefølje-HTML) er arkitektonisk identiske — single-file, vendored DS, polling, theme-bootstrap, WCAG. De vil sannsynligvis arve mønstre fra v4.3 1:1.

v4.3-pre-briefen i ROADMAP.md trenger ikke endres — Plugin Playground er Tier 1's konsern. Men hvis nye HTML-mønstre etableres i v4.3, vurder å gjøre dem reusable for tiers oppover (vendored DS, parser-mønstre, etc.).

## Referanser

- `voyage/CLAUDE.md` — Voyages egne arbeidsregler
- `voyage/ROADMAP.md` — Voyages egen plan (uavhengig av upstream)
- `voyage/docs/HANDOVER-CONTRACTS.md` — kanonisk definisjon av handover-schemaer
- `ktg-privat/plugins/app-creator/CLAUDE.md` — Tier 2 design (privat)
- `ktg-privat/plugins/app-factory/CLAUDE.md` — Tier 3 design (privat)
- `ktg-privat/plugins/app-factory/docs/architecture-brief.md` — Tre-tier HTML-arkitektur og verktøy-agnostisk invariant (privat)
- `ktg-privat/plugins/app-factory/docs/alignment-brief.md` — Cross-tier-kontrakter og funn (privat)

Privat-merking: når app-creator/app-factory blir publisert, oppdater stiene til offentlige posisjoner.

## Når denne briefen skal oppdateres

- Når app-creator/app-factory blir publisert (oppdater paths)
- Når en upstream-relevant kontrakt endres i Voyage (CHANGELOG-link her)
- Når en ny upstream-konsument identifiseres
- Når Voyage tar en arkitektur-beslutning som påvirker upstream
