open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions
ktg-plugin-marketplace/plugins/voyage/docs/three-tier-context.md
Kjell Tore Guttormsen 68842cf773 docs(voyage): add three-tier ecosystem context brief 
New docs/three-tier-context.md (110 lines) documents Voyage's position as
Tier 1 in a three-tier ecosystem with upstream consumers (app-creator,
app-factory; both currently in private incubation). The brief identifies
upstream-consumed contracts (brief.md format, /trekplan CLI, handover
schemas), prescribes stability principles, and explicitly preserves
Voyage's runtime agnosticism — no imports, no detection, no special cases.
Awareness without coupling.

CLAUDE.md § Architecture: 2-line callout pointing to the brief, following
the existing "opt-in upstream architect plugin" precedent.

No Voyage behavior change. Documentation-only.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-10 16:29:28 +02:00

7.1 KiB
Raw Blame History

Three-tier ecosystem context

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