# IDEA.md – ett eget ärendeverktyg för dig och Claude Det här är en fristående uppdragsbeskrivning. Ge den i sin helhet till Claude Code (eller ett liknande verktyg) för att bygga en egen implementation. Den bygger på Relay, ett ärendeverktyg med webbgränssnitt och MCP-server som ersatte Linear och byggdes med Claude Code. ## 1. Vad som ska byggas Ett ärendeverktyg där en människa och Claude delar samma bräda: människan i webbläsaren, Claude genom en MCP-server. Ärendena ligger på din egen server. I Relay: - **kort** med identifierare som aldrig ändras (`AND-55`), status med typ, etiketter, prioritet, beskrivning i Markdown (med klickbara kryssrutor), relationer (blockeras av, relaterad, dubblett) och statushistorik - **bräda och lista** per projekt, med filter - **kommentarer** med trådar, reaktioner, citat ur beskrivningen och skärmbilder - **vems tur**: räknas fram ur etikettens ägare och "väntar på svar" - **en MCP-server** med samma verktygsnamn som det verktyg du byter från, och `get_board` för sessionsstart - **webhooks** som kan väcka en Claude-session - personer och agenter med egna nycklar, delade projekt, inbjudningar, glömt lösenord - startsida, kalender och tidslinje, svenska och engelska, ljust och mörkt läge - **import** från det gamla verktyget, med bilderna ## 2. Stack och arkitektur Det som **spelar roll** är markerat; resten går att byta. - **Webben**: React 18, Vite och TypeScript. - **Servern**: PHP 8.3 utan ramverk, mysqli och MariaDB. - **Viktigt: ett verktygsregister** där varje förmåga definieras en gång med JSON Schema och en hanterare. Både MCP-servern och webbgränssnittets API går genom samma register, så en ny förmåga når båda. - **Viktigt: all domänlogik på ett ställe** – uppslag, svarsformer, varje ändring – och all behörighet på ett annat: varje läsning av kort, kommentarer och bilagor går genom samma kontroll. - **Identifierare från ett enda ställe**: projektets egen räknare om det har ett prefix, annars teamets. Två räknare får aldrig dela prefix. - **Tider i UTC** med millisekunder. - **Bilagor utanför docroten**, typen läst ur filens innehåll, och en fil som skrivits i en transaktion tas bort om transaktionen rullas tillbaka. ## 3. Beslut som visade sig avgörande **Mät vad som faktiskt används innan något byggs.** Gå igenom sessionsloggarnas anrop till det gamla verktygets MCP-server, och bygg det. Resten blir kort i en backlog. **Behåll verktygsnamnen.** Med samma namn, parametrar och fältnamn fungerar arbetssättet och alla instruktioner oförändrade. Felaktiga parametrar vägras med namnet på det som är fel, i stället för att ignoreras. **Vems tur räknas fram, sätts inte.** Varje etikett har en ägare (agent, människa, ingen) och en beskrivning som är en arbetsregel. "Väntar på svar" försvinner när en människa kommenterar. **Ett anrop vid sessionsstart.** `get_board` ger öppna kort per status, etiketternas regler, ändringar och nya kommentarer sedan agenten senast läste. **Ett kort i taget per projekt för agenter**, kontrollerat i samma transaktion som flytten, med ett fel som säger vilket kort som pågår. **Skriv som agenten, för människan.** En agent har eget namn och egen nyckel, och allt den skriver visar vem den arbetar åt. **Ett arbetssätt i en fil**, `RELAY.md`, som kopieras oförändrad till varje projekt och pekas ut från projektets instruktioner. Verktyget lämnar projekt som inte valt det i fred. **`idempotency_key`** på det som skapar något, så att ett omförsök ger samma kort. **Kalender och tidslinje räknas ur historiken.** En aktivitet är en ändring av ett kort eller en kommentar, av en människa eller en agent. Inga datum fylls i för hand, så vyerna visar vad som faktiskt gjordes. Räkna dagarna i webbläsarens tidszon, gruppera i kvartstimmar i UTC innan de flyttas till rätt dag (då blir tidszoner med halvtimmar och sommartid rätt), och låt tidslinjen använda samma räkning som kalendern. ## 4. Fallgropar - **Två sessioner tar varsitt kort i samma projekt.** Lås i databasen, inte i mottagaren. - **Agenten väcker sig själv.** Låt webhooks förvalt bara skicka människors ändringar. - **En långsam webhook-mottagare håller sidan.** Skicka efter svaret, och släpp sessionen först, annars väntar sidans nästa anrop. - **Nya försök som väntar när en webhook stängts av** ska strykas, så att inget gammalt skickas när den slås på igen. - **Tappad anslutning** får inte ersätta sidan med ett fel. Spara utkast i webbläsaren och visa en rad om att anslutningen saknas. - **"Kom ihåg mig" med roterande hemlighet**: en sidladdning skickar flera anrop samtidigt med samma kaka. Ge den förra hemligheten en kort nådatid. - **Antal påverkade rader** ska läsas från satsen, inte från anslutningen, när satsen redan frigjorts. - **Bilder hos det gamla verktyget** måste hämtas över vid importen, annars pekar beskrivningarna på något som försvinner. - **Ett projekt som byter namn** måste kunna hittas på det gamla namnet och den gamla adressen. ## 5. Krav och mätningar - Identifierare ändras aldrig, inte ens när ett kort byter projekt. - En agent kan inte ha två pågående kort i samma projekt. - Ingen läsning av kort, kommentarer eller bilagor förbi behörighetskontrollen. ## 6. Så verifieras det - Typkontroll och lint i bygget. - Ett test från början till slut av API:t och MCP-servern mot en tillfällig databas som startas och rivs av ett skript, aldrig mot den riktiga. - Rena funktioner (som vems tur) testade utan webbläsare. - Webhooks i produktion: kommentera ett kort och se att en session startar. ## 7. Arbetssätt - **Börja med en specifikation** ur det du faktiskt använt. - **Flytta över tidigt**, och styr sedan verktyget från sig självt: varje ny funktion är ett kort. - **Verifiering som egna kort** för det som bara går att prova i produktion. ## 8. Prompten > Bygg ett ärendeverktyg för mig och Claude: kort med status, etiketter, relationer och kommentarer, en bräda i [React] och en MCP-server med samma verktygsnamn som [Linear]. [PHP utan ramverk med MariaDB]. Etiketter har en ägare så att det syns vems tur det är, och en webhook kan väcka en Claude-session. > > Läs hela IDEA.md nedan först. > > Arbeta så här: > 1. Gå igenom mina sessionsloggar och skriv en specifikation av det jag faktiskt använder. > 2. Bygg det, med ett verktygsregister som både MCP och webben går genom. > 3. Testa API:t och MCP-servern mot en tillfällig databas. > > [klistra in IDEA.md här]