PRD-till-PR-pipeline

Maskinöversatt från engelska — källa: prd-to-pr-pipeline.md.

Implementeringsstatus: Designanteckning — den åttastegsstabell som följer är målet. Vissa steg är på plats idag; andra är endast design. Se kolumnen Status.

Byggt idag: steg 0 (PRD-konventionen är ok; konvertering Cursor → wiki är manuell), steg 1 (människor skriver redan wiki/plans/<feature>-YYYY-MM-DD.md), steg 5 (granskande underagenter resolver-reviewer / dashboard-reviewer / perf-reviewer är på plats och körs proaktivt), steg 8 delvis (GitHub Merge Queue är live; skärmbild-till-människa är manuell).

Mål-tillägg: Architect / Test-writer / Editor / Verifier / Reviewer-feedback som namngivna agenter; pipeline-runnern som binder ihop dem; automatiserad dossier-buntare; Codex/CodeRabbit-polling. Spårat i darwin-component-map.md §(c).

Standardvägen för leverans: människan skriver en PRD, agenter sköter resten, människan godkänner en skärmbild. Denna sida beskriver varje stegs input, output, grind och lagringsplats.

Pipeline-översikt

Steg 0 — Intagsnormalisering

Orkestreraren kan ta emot en grov chattförfrågan, en Cursor-plan under .cursor/plans/, eller en redan skriven wiki-PRD. Innan den startar implementationsagenter normaliserar den input till en portabel PRD:

• Om input är .cursor/plans/<feature>.md, konvertera den till wiki/plans/<feature>-YYYY-MM-DD.md.
• Om input bara är chatt, skriv utkast till PRD:n i wiki/plans/ innan något spec- eller kodarbete.
• Bevara den ursprungliga källsökvägen i frontmatter sources:.
• Tilldela en stabil funktions-slug som används av spec, worktree, branch och dossier.
• Skapa ett isolerat worktree/branch automatiskt för funktionsexekveringen; inget separat mänskligt branch-godkännande krävs för PRD-drivna arbetsflöden.

Steg 0 får ställa en blockerande fråga endast när det efterfrågade produktbeteendet är så otydligt att specen skulle kunna ändras. Det ska inte be om tillstånd att skapa worktreet.

Steg 1 — PRD

En wiki/plans/<feature>-YYYY-MM-DD.md-fil. Frontmatter måste deklarera implementation_status: planned (eller liknande) och brödtexten måste öppna med ett synligt statuscallout enligt SCHEMA.md.

En bra PRD svarar på:

• Vad är användarens synliga ändring?
• Vad är framgångsmåttet (och felmåttet)?
• Vad är uttryckligen utanför omfånget?

PRD:n är den enda plats där en människa krävs. Allt nedströms konsumerar den.

Steg 2 — Spec

Architect-agenten läser PRD:n och producerar wiki/specs/<feature>.md. Specen är maskinkontrollerbar Gherkin-acceptans:

Feature: Lab promotion banner
  Scenario: Best trial is shown above the leaderboard
    Given a service area with at least one completed lab trial
    And one trial is pinned in ServiceAreaBestLabScenario
    When the user opens /admin/optimization-lab/<id>
    Then the BestTrialBanner is visible
    And it shows the pinned trial's metrics

  Scenario: Promote button is disabled for in-progress trials
    Given a trial whose solution.status is solving_active
    Then the Promote button is disabled
    And hovering shows "Trial still solving"

Specen är koordinationsobjektet mellan agenter. Den definierar vad som räknas som klart.

Steg 3 — Teststubbar

Test-writer-agenten läser specen och skriver misslyckande tester:

• Vitest för enhets- och integrationstäckning av resolvers, services, hooks.
• Playwright för de acceptansscenarier som namnges i specen.

Pre-commit-asserten: varje teststubb måste köra och falla med ett informativt fel (typiskt "X är inte implementerat"). Detta fångar oavsiktligt tautologiska tester innan editor-steget startar.

Steg 4 — Implementation

Editor-agenten (billigare Sonnet-modell) itererar på diffen tills teststubbarna går grönt. Begränsningar:

• Worktree per funktion (./scripts/git/worktree-add.sh <name> <branch>) — redigera aldrig main direkt för PRD-drivet arbete. Pipelinen får skapa worktreet automatiskt.
• Inga nya filer utanför vad specen antyder (inga premature abstraktioner).
• Inga kommentarer om inte varför är icke-uppenbart.
• React-hook-form + Zod + Form*-primitiver för formulärarbete; resolver-layout enligt .cursor/rules/appcaire-monorepo.mdc.

Editorn får misslyckas. Om specens tester inte är gröna efter MAX_ITERATIONS lyfter den misslyckandet till orkestreraren istället för att mala för evigt.

Steg 5 — Självgranskning

Orkestreraren kör lämpliga underagenter parallellt:

• resolver-reviewer — om apps/dashboard-server/src/graphql/resolvers/ rörts.
• dashboard-reviewer — om apps/dashboard/src/ rörts.
• perf-reviewer — om någon list-resolver, fält-resolver eller loop-över-Prisma rörts.

Fynd kategoriseras P1 (blockerar) / P2 (måste åtgärdas) / P3 (kvitteras). Editorn körs igen med fynden som extra input.

Steg 6 — Verifiering

Verifier-agenten kör:

• yarn type-check, yarn lint, yarn test:dashboard-stack.
• En playwright test-körning som fångar failure-dossiern (trace + skärmbild + console + DOM-snapshot + maskinläsbar sammanfattning).
• Dossiern skrivs till docs/dossiers/<feature>/ och commitas tillsammans med diffen.

Detta steg går inte att kringgå. Utan dossier kan PR:n inte mergas. Se verification-and-evidence.md.

Steg 7 — Granskningsloop

Efter git push pollar Reviewer-feedback-agenten gh api repos/{org}/{repo}/pulls/<n>/comments tills Codex / CodeRabbit har slutfört sin granskning. Varje oadresserad P1- eller P2-kommentar gör att Editor-steget körs igen. Detta kodifierar den stående minnesregeln om polling av Codex-granskningar.

Steg 8 — Merge + bevis

När (a) CI är grön, (b) dossiern finns, och (c) granskningsloopen är stabil, köar orkestreraren PR:n med gh pr merge --auto --squash mot merge-gruppen. Efter merge skickas skärmbilden från dossiern till den mänskliga kanalen (Telegram via interface-agent).

Människans uppgift vid den här tidpunkten är att titta på skärmbilden och antingen godkänna (tystnad = godkännande efter deadline) eller avvisa. Avvisning öppnar specen för förtydligande igen.

Lagringslayout

<repo>/
├── wiki/plans/<feature>-YYYY-MM-DD.md      ← PRD (människoskriven)
├── wiki/specs/<feature>.md                 ← Architect-output (Gherkin)
├── docs/dossiers/<feature>/                ← Verifier-output
│   ├── trace.zip
│   ├── screenshot.png
│   ├── console.log
│   └── summary.json                        ← Maskinläsbara testresultat
└── .compound-state/agent-service.db        ← Genomströmning + kostnadsmått per steg

Allt utom dossiern commitas till feature-branchen. Dossiern commitas för auditerbarhet och för att göra rebuild deterministisk.

Korsreferenser

• Vision och mandat — de fyra åtaganden denna pipeline implementerar.
• Agentroller och modellroutning — vilken modell varje steg använder.
• Specen som kontrakt — varför specen är koordinationsobjektet.
• Verifiering och bevis — dossier-format.
• Granskningsåterkoppling — Codex-polling.
• Genomströmning och affärssignaler — funktioner/sek/token-mätning.
• Merge-flöde och PR-velocitet — merge-queuen denna pipeline siktar på.