ADR-009: Superpowers som standard meta-rammeverk for spec-drevet utvikling⚓︎

Kontekst⚓︎

Kai utvikles med AI-agenter (Claude Code) som primærverktøy for koding. Prosjektet følger en Feature → Spec → Implementation-flyt som trenger et strukturert meta-rammeverk for planlegging og spesifisering.

Fire rammeverk ble evaluert i praksis:

1. Native Claude plan mode — innebygd i Claude Code
2. Superpowers skills — brainstorming → writing-plans → executing-plans
3. Get Shit Done — detaljert spec-rammeverk med mange artefakter
4. Spec Kit — spec-som-source-of-truth-tilnærming

Nøkkeldrivere⚓︎

• Token-effektivitet: Lange sesjoner koster — rammeverket må ikke bruke unødvendig mange tokens
• Artefakt-mengde: Færre filer å vedlikeholde er bedre
• Spec-kvalitet: Gode nok til å implementere fra uten oppfølgingsspørsmål
• Prosjekt-match: Kai er mellomstor — trenger ikke enterprise-nivå prosess

Beslutning⚓︎

Vi bruker Superpowers skills som standard meta-rammeverk for all feature-utvikling:

• Brainstorming (/brainstorming) → utforsk krav og design
• Writing plans (/writing-plans) → generer spec og implementasjonsplan
• Executing plans (/executing-plans) → implementer basert på spec

Plan mode brukes kun ad-hoc for trivielle endringer som ikke trenger full spec-prosess.

Artefakt-policy: Specs lagres i docs/specs/. Planer er ephemeral — de brukes under implementering og lagres ikke.

Alternativer vurdert⚓︎

Native Claude plan mode⚓︎

Greit for småting. Mangler strukturert brainstorming-fase og genererer ikke vedvarende spec-artefakter. Brukes fortsatt ad-hoc for trivielle endringer.

Spec Kit⚓︎

Bruker specs som source of truth der koden kun er en implementasjonsdetalj. Ikke slik vi ønsker å jobbe — vi vil at koden skal være autoritativ, med specs som støttedokumentasjon.

Get Shit Done⚓︎

Fant edge cases grundig, men alt for tung på tokenbruk. For detaljert, tok for lang tid, og genererte for mange artefakter. Overkill for Kai sitt scope.

Konsekvenser⚓︎

Positive⚓︎

• Specs lagres i docs/specs/ — gjenbrukbar kontekst for fremtidige sesjoner
• Forutsigbar utviklingsflyt: /feature → /spec → /implement
• Balansert tokenbruk vs kvalitet — sweet spot mellom grundighet og effektivitet
• Brainstorming-fasen sikrer at krav er tydelige før implementering starter

Avveininger⚓︎

• Planer lagres ikke — kontekst kan gå tapt mellom sesjoner (akseptabelt; specs inneholder det viktigste)
• Superpowers skills er en ekstern dependency som må vedlikeholdes og oppdateres