open/app-creator
1
0
Fork 0
Code Issues Releases Activity
app-creator/CLAUDE.md
Kjell Tore Guttormsen daaadb4a15 docs(a1): dok-resync mot verifisert virkelighet per review-2026-07 
Sesjon A1 i docs/masterplan.md § Fase A. Fjerner utdaterte/usanne premisser
fra normativ tekst, med docs/review-2026-07.md som fasit. Ingen nye
design-beslutninger (de hører i A2/A5/C2); domain-packs urørt (A3).

- R-01: «v4.3 Plugin Playground» merket historisk overalt (flaten slettet i
  Voyage v5.0.0, 2026-05-12; mønstrene er arven). Drill-down redefinert til
  feature-ens voyage_run_dir-artefakter + annotate-HTML. Handover 8 og
  /trekrevise fjernet som gjeldende mønster — S5-beslutningen om «to
  gate-nivåer» faller bort; det er én, den lette.
- R-05: død annotate-/kontrakt-sti (plugins/marketplaces/…) erstattet med
  cache-sti-regel + oppslag av nyeste versjon. Sidecar-fila
  <artefakt>.review.md korrigert: den finnes ikke — annotasjoner lever i
  localStorage; eksport-til-fil er D7.
- R-09: § Flersesjons-protokoll omskrevet til STATE.md-konvensjonen;
  prototype-run/README-tabellen rettet.
- R-13: iOS-versjonseksempler gjort domene-nøytrale; HTML-invarianten
  avklart til WCAG 2.2 AA.
- R-14: fase 2s pack-input strøket (motsa pack-manifestets phases).
- R-15: max-3-regelen redefinert — snapshot = én lasting, maks 3
  supplementary utover; fase 5-inputlista rettet.
- R-16: runtime-asymmetrien omformulert til skjema-asymmetri (ingen
  runtime-kobling, Handover 1 eneste kobling, ingen privilegert produsent).
- R-06 (delvis): phase_status samlet i én autoritativ enum-tabell,
  pending-review lagt til i frontmatter-enumen; kjente avvik henvist til C2.
- R-04/R-02: § Fase 7 merket STALE (2.0-pin, stale verifikasjonsnote,
  «round-trip PASS» = mental simulering, ikke kjøring).
- R-17: CHANGELOG-referansene rettet + Unreleased-entry for denne resyncen.
- R-20: «6-tema-intervju» → «8-tema» (sjekklisten lister 8).

Verifisering: iOS 19 → 0; iOS 18 → 0; 6-tema-intervju → 0; WCAG 2.1 i
CLAUDE.md → 0; «ROADMAP, TODO» → 0; pending-review → 7; Handover
8/trekrevise og plugins/marketplaces kun i eksplisitt historisk-merkede
eller advarende treff.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TJ99ZtNvvxaDPfNTED7gnC
2026-08-10 20:48:01 +02:00

137 lines
10 KiB
Markdown
Raw Blame History

# app-creator
## Status
**Pre-design.** Ingen kode skal skrives i dette repoet ennå.
Implementering starter ikke før:
1. Forfatteren har drevet én reell iOS app gjennom hele app-creator → Voyage-pipelinen manuelt — håndholdte fase-artefakter, briefer skrevet for hånd, Voyage som engine
2. Friksjons-data fra prototypen er sammenstilt
3. Pre-brief er skrevet basert på det observerte mønsteret
Inntil det: dette repoet eksisterer som et tenke-rom. Hvis du som Claude blir bedt om å "begynne å bygge", stopp og bekreft at forutsetningene over er oppfylt.
Design-/kunnskaps-artefakter finnes (de er *ikke* implementerings-kode): `docs/phase-design-draft.md` (7-fase-designet), `docs/domain-pack-spec.md` (domene-nøytral spec), `domain-packs/` (referanse-domain-packs — `ios-app` komplett, `claude-code-plugin` som stub), `prototype-run/` (friksjons-logg + research fra prototype-arbeidet drevet av Akashic-instansen). "Ingen kode i pre-design" gjelder Swift/implementerings-kode, ikke disse markdown-/data-fil-artefaktene.
Lag-alignment mot Voyage og app-factory er dokumentert i `../app-factory/docs/alignment-brief.md` (kontrakter) og `../app-factory/docs/architecture-brief.md` (tre-tier HTML-arkitektur og verktøy-agnostisk invariant). Disse dokumentene låser kontrakter og arkitektur-invarianter; runtime-asymmetrien (app-creator vet ikke om app-factory) er bevart — referansene er kun for design-fasen.
## Hva app-creator er
Tier 2 i et tre-tier HTML-system. Per-app-disiplin.
| Tier | Plugin | Disiplin | Spørsmål den svarer på |
|------|--------|----------|------------------------|
| 1 | Voyage | Per-task (brief → research → plan → execute → review) | Hvordan utfører vi denne oppgaven riktig? |
| 2 | app-creator (dette) | Per-app (per-app HTML) | Hva trenger appen, og hva er neste brief? |
| 3 | app-factory | Per-portefølje (portefølje-HTML) | Hvilken app trenger meg nå, og hvilken handling er nødvendig? |
app-creator er en pipeline fra app-konsept til feature-klare briefer. Voyage konsumerer briefene og leverer features. app-creator er pre-Voyage — den løser problemet "hva skal bygges" før Voyage løser "hvordan bygges det".
Hver tier har samme arkitektoniske form: AI skriver state i filer, tynt HTML rendrer dem, menneske handler i terminal. Mønsteret er arvet fra Voyages v4.3 Plugin Playground — **historisk forfar: flaten ble slettet i Voyage v5.0.0 (2026-05-12), mønstrene er arven.**
## Hva app-creator skal levere
To leveranser, sammensatt:
### Fase-pipeline (AI-laget)
En fase-basert pipeline fra app-konsept til briefer som er ready som input til Voyage:
1. **Intervju** — strukturert dialog som henter ut app-intent, målgruppe, omfang, suksesskriterier
2. **Research** (valgfri) — markedsanalyse, presedens, feasibility-sjekk, plattform-spesifikke gotchas
3. **Arkitekturavklaringer** — tech-stack, deployment-modell, integrasjoner, sentrale patterns
4. **Designsystem** — visuelle + interaksjons-tokens som binder alle features (HIG for iOS, Material for Android, egen for web osv.)
5. **Constraints** — A11Y, ytelse, sikkerhet, plattform-regler (App Store, GDPR), governance
6. **Feature-derivasjon** — backlog avledet fra alt over, med dependency-pekere mellom features
7. **Brief per feature** — én markdown-fil per feature, formatert som Voyage-kompatibel input (Handover 1)
Hver fase produserer en artefakt på filsystemet. Faser kan re-besøkes når app-en lærer av Voyage-kjøringer.
### Per-app HTML (presentasjons-laget)
Et tynt HTML-grensesnitt per app som rendrer:
- **Fase-progress** — hvor i pipelinen er appen, visuell 1-7
- **Alle artefakter** — intervju-transkript, research-notater, arkitektur-beslutninger, designsystem (med visuelle prøver), constraints, feature-backlog, alle briefer
- **Attention per app** — hva må gjøres nå (godkjenn brief, ta arkitektur-beslutning, start neste fase, review feature-backlog)
- **Drill-down til feature-ens Voyage-artefakter** — klikk en feature → åpne artefaktene fra dens Voyage-kjøring (`voyage_run_dir`) og/eller annotate-HTML-filene; er den ikke kjørt, vis dens brief
HTML-grensesnittet gjenbruker **mønstrene** fra v4.3 Plugin Playground 1:1: single-file, vendored DS, polling, theme-bootstrap, WCAG. Selve playground-flaten finnes ikke lenger (slettet i Voyage v5.0.0) — den er forfar, ikke lenke-mål.
## Hva app-creator IKKE skal absorbere
- **Per-task pipeline-disiplin** — det er Voyages ansvar. app-creator skriver briefer; Voyage utfører dem.
- **Eksekvering av Voyage** — app-creator overleverer briefer som filer. Aldri runtime-kall, aldri helper-process som kjører Voyage-kommandoer.
- **Multi-app portefølje-styring** — det er app-factorys ansvar.
- **Innebygd Linear/Jira-integrasjon** — verktøy-agnostisk er hard invariant; tredjeparts sync-plugins er opt-in
- **Team-koordinering** — solo-først per design.
- **Project management-erstatning** — Linear, Jira, GitHub Projects gjør det bedre. Bruk dem hvis du trenger dem; app-creator integrerer ikke direkte.
- **Autonome loops uten human-in-the-loop**
## Den sentrale arkitektur-grensen
app-creator skal aldri eksekvere Voyage og aldri modifisere Voyage. Briefer overleveres som markdown-filer. Voyage kjøres separat med brief-fila som input.
Asymmetrien som skal beskyttes er **skjema-asymmetrien, ikke en kunnskaps-påstand**: ingen runtime-kobling i noen retning; briefen er umerket og bare en velformet Voyage-brief; Handover 1 er eneste koblingspunkt; ingen produsent er privilegert. Det er dette som gjør at lag 1 og lag 2 kan utvikles uavhengig uten å lekke ansvar.
Voyages egen kontrakt navngir «Tier 2 `app-creator`» i en informasjonell produsent-kontekst (`HANDOVER-CONTRACTS.md`) samtidig som den slår fast at ingen produsent er privilegert og at Handover 1 er eneste kobling. Å kreve at Voyage «ikke vet om» app-creator er derfor både usant og verdiløst — kravet er at ingenting i Voyage *avhenger* av app-creator. Ikke «rett» Voyage-dokumentasjon på dette punktet (det ville brutt «aldri modifisere Voyage»).
Verktøy-agnostisk er **hard invariant** — kjerne-arkitekturen forutsetter ingen eksterne PM-verktøy. Sync-plugins er valgfri tredjepart. Se `../app-factory/docs/architecture-brief.md` for full begrunnelse.
## Forholdet til Voyage
app-creator produserer briefer. Voyage konsumerer briefer. Handover er en filoverlevering, ikke en runtime-kobling.
Brief-format-kontrakten er det eneste integrasjonspunktet. app-creator må produsere briefer som Voyage `/trekplan` kan konsumere uten endringer (Handover 1). Hvis Voyage endrer brief-formatet, må app-creator oppdatere sin generator — Voyage skal ikke kjenne til app-creator som downstream-konsument.
Voyages v4.3 Plugin Playground er den **arkitektoniske forfaren** for app-creators per-app HTML — samme single-file-mønster, vendored DS, polling, theme-bootstrap. app-creator gjenbruker disse mønstrene 1:1. **Forfaren er historisk:** Voyage v5.0.0 (2026-05-12) slettet `playground/`, Handover 8 og `/trekrevise`; dagens Voyage-flate for annotering er `scripts/annotate.mjs` (per-artefakt HTML). Mønstrene er fortsatt arven — flaten er ikke noe å lenke til.
## Forholdet til app-factory
app-creator vet ikke om app-factory finnes. Den eksporterer kun strukturert state — fase-status, feature-backlog, brief-pipeline-status, Voyage-runs-status — som app-factory kan **lese og aggregere**. Ingen tilbake-kall, ingen avhengighet andre veien.
## Posisjonering
- Solo-maintained, fork-and-own
- Primær-konsumert av forfatteren for forfatterens eget arbeid
- Issues velkommen som signaler; pull requests aksepteres ikke
- Ingen backward compatibility-garantier før v1.0.0
## Tekniske invarianter (arvet fra Voyage og v4.3)
- **Zero npm dependencies** utover Node.js built-ins (vendored DS er ok)
- **Single-file HTML** — ingen build-step
- **Hooks og validators** som self-contained `.mjs`-filer
- **Filsystem som primær state-backend** (fase-artefakter er filer)
- **Browser-state er ephemeral** — sannheten lever i filer
- **Polling, ikke websockets** — sub-30s latency er nok
- **`data-theme` med bootstrap-script + WCAG 2.2 AA-kontrast** (2.2 er gjeldende W3C Rec; konsistent med fase 5 og domain-pack-ene, som alle krever 2.2 — avklart i A1, jf. R-13)
- **Markdown for alt menneske-leselig** (intervju-transkripter, arkitektur-notater, briefer)
## Arbeidsregler for Claude Code
1. **Forstå at dette er konseptuelt, ikke leveringsklart.** Ikke generer kode med mindre forutsetningene under "Status" er oppfylt og forfatteren eksplisitt har bedt om det.
2. **Hold lag-grensene rene.** Ikke absorbere ansvar fra Voyage eller app-factory. Hvis en idé sklir inn i task-execution eller portefølje-aggregering, hører den hjemme i et annet lag.
3. **Respekter den sentrale arkitektur-grensen.** Aldri foreslå at app-creator eksekverer Voyage eller modifiserer den. Aldri forutsett eksterne PM-verktøy i kjerne. Briefer overleveres som filer.
4. **Respekter posisjoneringen.** Solo-maintained, fork-and-own, ærlig om status. Ikke skriv som om dette var et offentlig produkt med brukere.
5. **Anvend scope-testen for nye ideer.** Tre spørsmål, alle må besvares ja:
- Er dette per-app-disiplin (ikke per-task, ikke per-portefølje)?
- Hører ideen hjemme i en av de syv fasene eller i per-app HTML, eller utvider den scope?
- Tjener det forfatterens egen arbeidsflyt (reell friksjon, ikke spekulativ)?
6. **Følg samme tone som Voyage** — ærlig, kompromissløs, eksplisitt om grenser. Ingen salgsspråk. Ingen vaporware-formuleringer.
## Communication patterns
### Linking to local files
When pointing to local files in responses, always use markdown link syntax with a descriptive name:
- Use `[Human-friendly name](file:///absolute/path)` — never bare `file:///...` URLs or autolinks `<file://...>`.
- Always use absolute paths. Never `~/` or relative paths.
- For multiple files, render as a bullet list of named markdown links.
Why: bare `file://` URLs only render the first as clickable across multiple lines. Named markdown links make each entry independently clickable and look cleaner.
Example:
- [Brief](file:///Users/ktg/.../brief.html)
- [Research summary](file:///Users/ktg/.../research/summary.md)
Reference in a new issue View git blame Copy permalink