Spedy Docs

Integrationsschicht, um deine Anthropic-Claude-Routinen direkt aus einem Spedy-Ticket zu triggern — mit Ticket-Kontext, optionalem Board-/Repo-Scope, Pre- und Post-Actions und Rückmeldung im Ticket.

Claude Routines sind ein Produkt von Anthropic: wiederverwendbare Arbeitsanweisungen, die du in deinem Anthropic-Account definierst und Claude ausführt. Spedy hostet oder startet diese Routinen nicht — Spedy liefert die Integrationsschicht, damit du sie direkt aus einem Ticket triggern kannst.

Konkret übernimmt diese Integration:

das Auflösen von Ticket-Kontext (Titel, Beschreibung, Status, Board, URL) in dein Prompt-Template,
den POST des aufgelösten Prompts an deine Anthropic-Routine-Webhook-URL mit deinem Secret,
optionale Pre- und Post-Schritte am Ticket (Status-Wechsel, Self-Assign, PR-Link-Kommentar),
das Nachhalten und Anzeigen jeder Execution direkt am Ticket.

Die Routinen selbst, das Modell-Budget und die Kosten bleiben in deinem Anthropic-Account.

Die Spedy-Integration ist Teil des Pro-Plans und muss organisationsweit über das Feature-Flag CLAUDE_ROUTINES aktiviert werden.

Konzepte

In Spedy besteht ein Routine-Eintrag aus vier Teilen:

Metadaten — Name, Slug, Beschreibung
Scope — optional Board- und Repository-Scope
Instructions — das Prompt-Template (mit Variablen wie {{ticket.title}})
Pre- und Post-Actions — serverseitige Ticket-Schritte vor und nach dem Handoff an Claude

Jeder Trigger erzeugt eine RoutineExecution, die den Status des Handoffs, den aufgelösten Prompt und Abschluss-Metadaten festhält. Die eigentliche AI-Arbeit passiert bei Anthropic — RoutineExecution ist nur Spedys Sicht darauf.

Berechtigungen und Feature-Flag

Routines sind gegated durch:

Gate	Wert	Wirkung
Organisations-Feature	`CLAUDE_ROUTINES`	Alle `/routines/*`-Endpunkte und die UI brauchen das aktiviert
Permission `routines:manage`	Default in Admin + Team Member	Eigene Routines anlegen, lesen, ändern, löschen
Permission `routines:trigger`	Default in Admin + Team Member	Routines triggern und eigene Executions abbrechen

Kunden (Organisationsrolle CUSTOMER) sind bewusst von beiden Permissions ausgenommen.

Board-Zugriff wird zusätzlich geprüft: ein Trigger auf ein Ticket, dessen Board du nicht sehen darfst, liefert 403 Forbidden.

Prompt-Variablen

In instructions werden folgende {{variable}}-Platzhalter beim Trigger aufgelöst:

Variable	Quelle
`{{ticket.id}}`	Ticket-ID
`{{ticket.displayId}}`	Lesbarer Ticket-Key (z. B. `WEB-42`)
`{{ticket.title}}`	Ticket-Titel
`{{ticket.description}}`	Ticket-Beschreibung
`{{ticket.status}}`	Status-Name
`{{ticket.statusKey}}`	Status-Key (`BACKLOG` … `DONE`)
`{{ticket.boardId}}`	Board-ID
`{{ticket.boardName}}`	Board-Name
`{{ticket.boardSlug}}`	Board-Prefix
`{{ticket.url}}`	Relative URL des Tickets

Wenn der Trigger-Request ein optionales text-Feld mitschickt, wird es unter einem ----Separator als Additional instructions for this run: angehängt.

Pre- und Post-Actions

Drei serverseitige Aktions-Typen sind in preActions und postActions erlaubt:

Typ	Parameter	Wann	Wirkung
`move_status`	`statusKey`: `BACKLOG` \| `TODO` \| `IN_PROGRESS` \| `BLOCKED` \| `DONE`	pre / post	Ticket in den passenden Board-Status verschieben
`assign_self`	—	pre / post	Triggernden User als Assignee setzen
`post_pr_comment`	—	post	Den PR-Link als internen Kommentar am Ticket posten

Aktionen laufen in der Reihenfolge, in der sie im Array stehen. Pre-Actions laufen synchron vor dem Dispatch an Claude; Post-Actions laufen, wenn Claude Abschluss meldet.

Scope

Zwei Felder grenzen ein, wo eine Routine laufen darf:

boardIds — wenn nicht leer, wird die Routine nur auf Tickets dieser Boards angeboten. Ein Trigger auf ein Ticket außerhalb liefert 400.
allowedRepos — Liste von owner/repo-Strings. Nur Repositories, die a) mit dem Ticket-Board verknüpft sind und b) in dieser Liste stehen, werden Claude als Repo-Kontext mitgegeben. Leer = kein Repo-Constraint.

Nutze den Helper GET /routines/available-repos, um die gültigen allowedRepos-Werte deiner Organisation zu bekommen.

Outgoing Webhook

Für den Handoff an die Claude-Code-Routines-API kann jede Routine setzen:

Feld	Beschreibung
`webhookTargetUrl`	HTTPS-URL auf `api.anthropic.com`. Beim Trigger POSTet Spedy `{ "text": resolvedPrompt }` an diese URL.
`webhookTargetSecret`	Wird als `Authorization: Bearer <secret>` gesendet. Erscheint nie in List-/Read-Responses (dort nur das boolsche `webhookTargetSecretSet`).
`webhookTargetHeaders`	Zusätzliche, nicht-geheime Header, z. B. `{"anthropic-version": "2023-06-01"}`. Für `api.anthropic.com` setzt Spedy sinnvolle Defaults, wenn du keine lieferst.

Nach erfolgreichem Handoff springt die Execution von PENDING auf CLAIMED (mit claimedAt), und die Ticket-Karte zeigt An Claude übergeben.

API-Referenz

Alle Endpunkte liegen unter /api/v1/routines, sind durch JwtAuthGuard geschützt und unterstützen Personal Access Tokens.