355 lines
18 KiB
Markdown
355 lines
18 KiB
Markdown
---
|
|
title: "Tweede Claude Agent — Planning Agent"
|
|
status: proposal
|
|
audience: [maintainer, contributor]
|
|
language: nl
|
|
last_updated: 2026-05-03
|
|
applies_to: []
|
|
---
|
|
|
|
# Plan: Tweede Claude Agent — Planning Agent (PBI/Story → children)
|
|
|
|
> **Eerder goedgekeurd plan in deze file:** *Scrum4Me v1.0 Release* (mobile shell + sprint-snapshots + release-discipline). Beschikbaar in chat-history; te verhuizen naar `docs/plans/v1-release.md` op een later moment. Dit nieuwe plan vervangt de plan-file inhoudelijk niet — het v1.0-werk blijft van kracht parallel hieraan.
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
**Wat de gebruiker wil:** twee gespecialiseerde Claude-agents, elk met eigen context.
|
|
|
|
| Agent | Doel | Context | Status |
|
|
|---|---|---|---|
|
|
| **Implementation Agent** | Codeert één task af → branch + PR | Code-repo (filesystem), `implementation_plan`, story, pbi, sprint, repo_url | ✅ Live (M13 / ST-1111) |
|
|
| **Planning Agent** *(nieuw)* | Genereert children: PBI→stories of story→tasks (incl. `implementation_plan` per task) | Specs + architectuur + patterns (filesystem in Scrum4Me-checkout), parent-record, bestaande children | ❌ Te bouwen |
|
|
|
|
**Wat al staat (hergebruikbaar):**
|
|
|
|
- `ClaudeJob`-model met state-machine `QUEUED→CLAIMED→RUNNING→DONE/FAILED`, `CANCELLED`-pad, stale-cleanup >30min
|
|
- `ClaudeWorker`-model voor presence-heartbeat
|
|
- SSE-pijplijn op `/api/realtime/solo` met payload-routing op `user_id + product_id`
|
|
- MCP-tools `wait_for_job`, `update_job_status`, `get_claude_context`, `create_pbi`, `create_story`, `create_task`, `update_task_plan`, `log_implementation`
|
|
- Idempotency-pattern: max 1 actieve job per resource
|
|
|
|
**Vastgelegde keuzes (uit AskUserQuestion-sessies):**
|
|
|
|
1. Agent kan **beide** niveaus: PBI→stories én story→tasks (één agent, twee modi via `target_type`)
|
|
2. Output: items **direct in DB** aanmaken via bestaande `create_*`-tools — geen review-stap in v1
|
|
3. Context: **lokaal draaien + filesystem-toegang** tot Scrum4Me-checkout (zoals impl-agent al doet)
|
|
4. Rol-scheiding: **`ClaudeJob.kind` enum** (`IMPLEMENTATION` | `PLANNING`) — één table, polymorf
|
|
5. Bestaande children: **aanvullen** — agent leest bestaande titels en voegt alleen ontbrekende toe
|
|
6. Live feedback: **stille SSE + status-pill** op de PBI/Story-card; geen aparte modal
|
|
7. MCP-shape: **bestaande `wait_for_job` uitbreiden** met `accept_kinds: string[]`-arg, default `['IMPLEMENTATION']` (backwards-compat)
|
|
|
|
---
|
|
|
|
## Approach (8 stappen)
|
|
|
|
### Stap 1 — Schema-uitbreiding
|
|
|
|
**`prisma/schema.prisma`:**
|
|
|
|
```prisma
|
|
enum ClaudeJobKind {
|
|
IMPLEMENTATION
|
|
PLANNING
|
|
}
|
|
|
|
enum PlanningTargetType {
|
|
PBI
|
|
STORY
|
|
}
|
|
|
|
enum ApiTokenKind {
|
|
IMPLEMENTATION
|
|
PLANNING
|
|
// beide kinds simultaan = afzonderlijke tokens; eenvoudiger dan multi-kind-flag
|
|
}
|
|
|
|
model ClaudeJob {
|
|
// ... bestaande velden ...
|
|
kind ClaudeJobKind @default(IMPLEMENTATION)
|
|
task_id String? // wordt nullable — planning-jobs hebben geen task
|
|
task Task? @relation(fields: [task_id], references: [id], onDelete: Cascade)
|
|
planning_target_type PlanningTargetType?
|
|
planning_target_id String?
|
|
|
|
@@index([kind, status])
|
|
@@index([planning_target_type, planning_target_id, status])
|
|
}
|
|
|
|
model ApiToken {
|
|
// ... bestaande velden ...
|
|
kind ApiTokenKind @default(IMPLEMENTATION)
|
|
}
|
|
|
|
model ClaudeWorker {
|
|
// ... bestaande velden ...
|
|
// accepted_kinds wordt afgeleid uit token.kind (geen extra kolom nodig)
|
|
}
|
|
```
|
|
|
|
**Constraint via DB-check (CHECK constraint of app-level):** een `ClaudeJob` heeft óf `task_id` (kind=IMPLEMENTATION) óf `planning_target_*` (kind=PLANNING). Nooit beide leeg, nooit beide gevuld.
|
|
|
|
**Migratie:** alle bestaande rijen krijgen `kind=IMPLEMENTATION` + `apiToken.kind=IMPLEMENTATION` als default. Backwards-compatible.
|
|
|
|
**Bestand:** `prisma/migrations/<date>_planning_job_kind/migration.sql`
|
|
|
|
### Stap 2 — Status-mappers + Zod-schemas
|
|
|
|
- `lib/claude-job-status.ts` — voeg `kind` toe aan API-shape (lowercase: `implementation` | `planning`)
|
|
- `lib/schemas/claude-job.ts` (NEW of MODIFY) — discriminated union op `kind`
|
|
- `lib/schemas/planning-target.ts` (NEW) — `{ type: 'PBI'|'STORY', id: string }` validator
|
|
|
|
### Stap 3 — Server actions
|
|
|
|
**`actions/claude-jobs.ts`** uitbreiden:
|
|
|
|
```ts
|
|
export async function enqueuePlanningJobAction(input: {
|
|
productId: string
|
|
target: { type: 'PBI' | 'STORY', id: string }
|
|
}): Promise<EnqueueResult>
|
|
```
|
|
|
|
Logica:
|
|
1. Auth-scope-check (`productAccessFilter`) — target moet binnen product zitten
|
|
2. Demo-block (`session.isDemo` → 403)
|
|
3. Idempotency: weiger als er al een `PLANNING`-job actief is voor dit `(target_type, target_id)`
|
|
4. Insert `ClaudeJob` met `kind=PLANNING`, `task_id=null`, `planning_target_*` ingevuld
|
|
5. `pg_notify('scrum4me_changes', { type: 'claude_job_enqueued', kind: 'planning', ... })`
|
|
|
|
`cancelClaudeJobAction` (bestaand) blijft werken — accepteert nu ook PLANNING-jobs (zelfde state-machine).
|
|
|
|
### Stap 4 — SSE-routing
|
|
|
|
**`app/api/realtime/solo/route.ts`:**
|
|
|
|
- Bestaande `claude_job_*`-events krijgen `kind` in payload
|
|
- Bij connect: `claude_jobs_initial`-event bevat ook actieve PLANNING-jobs van vandaag
|
|
- Filter blijft `user_id + product_id` — geen extra topic nodig
|
|
|
|
### Stap 5 — UI: triggers + status-pills
|
|
|
|
**Trigger in beide dialog-profielen** (geprofileerd in PR #45):
|
|
|
|
| Locatie | Knop-label | Target |
|
|
|---|---|---|
|
|
| `components/backlog/story-dialog.tsx` (edit-mode) | `🤖 Genereer taken met Claude` | `{ type: 'STORY', id: story.id }` |
|
|
| `components/backlog/pbi-dialog.tsx` (edit-mode) | `🤖 Genereer stories met Claude` | `{ type: 'PBI', id: pbi.id }` |
|
|
|
|
Knop-gedrag:
|
|
- `<DemoTooltip show={isDemo}>` rond knop (laag 3 demo-policy)
|
|
- `disabled` als er al een PLANNING-job actief is voor deze target (live via SSE-store)
|
|
- Tooltip bij disabled: "Plan-job al gestart — wachten op resultaat"
|
|
- Klik → `enqueuePlanningJobAction` → toast "Plan gestart" → dialog blijft open zodat user resultaat ziet binnenkomen
|
|
|
|
**Status-pill component (NEW):**
|
|
|
|
`components/shared/planning-job-pill.tsx` — kleine badge die de status van een lopende PLANNING-job toont:
|
|
- `QUEUED` — grijs, "In wachtrij"
|
|
- `CLAIMED / RUNNING` — blauw met spinner, "Plan wordt gegenereerd…"
|
|
- `DONE` — groen, fade-out na 5s
|
|
- `FAILED` — rood, klikbaar voor error-detail
|
|
- `CANCELLED` — niet getoond (verwijdert pill)
|
|
|
|
Plaatsing:
|
|
- Op `PbiList`-card naast PBI-titel (rechts)
|
|
- Op `StoryPanel`-card naast story-titel (rechts)
|
|
- In `PbiDialog` / `StoryDialog`-header (edit-mode) als large variant
|
|
|
|
**Live updates:** bestaande `useClaudeJobsStore` (Zustand, populated uit SSE) — alleen `kind` toevoegen aan filter-helpers.
|
|
|
|
### Stap 6 — MCP-tools (`mcp` repo, aparte PR)
|
|
|
|
**Wijziging 1 — bestaande tool uitbreiden:**
|
|
|
|
```ts
|
|
// wait_for_job tool input schema
|
|
{
|
|
accept_kinds?: ('IMPLEMENTATION' | 'PLANNING')[] // default: ['IMPLEMENTATION']
|
|
wait_seconds?: number // bestaand
|
|
}
|
|
```
|
|
|
|
Server-side: `WHERE kind = ANY($1) AND status = 'QUEUED'` in de `FOR UPDATE SKIP LOCKED`-query. Token-kind moet ook compatibel zijn (token.kind `IN` accept_kinds-overlap).
|
|
|
|
Response-shape voegt `kind` toe; voor `PLANNING`-jobs vervangt `task` door `planning_target` met embedded record:
|
|
|
|
```ts
|
|
{
|
|
job_id: string
|
|
kind: 'IMPLEMENTATION' | 'PLANNING'
|
|
product: { id, name, repo_url, ... }
|
|
// IMPL-only:
|
|
task?: { ..., implementation_plan, story, pbi, sprint }
|
|
// PLANNING-only:
|
|
planning_target?: {
|
|
type: 'PBI' | 'STORY'
|
|
pbi?: { id, code, title, description, priority, status, existing_stories: [{ id, code, title, priority }] }
|
|
story?: { id, code, title, description, acceptance_criteria, priority, status, pbi: {...}, existing_tasks: [{ id, title, priority, status }] }
|
|
}
|
|
}
|
|
```
|
|
|
|
**Wijziging 2 — nieuwe MCP-tool:**
|
|
|
|
`get_planning_context(target_type, target_id)` — losstaande lookup voor agent die handmatig een planning wil starten zonder job-claim. Optioneel; `wait_for_job` retourneert dezelfde data al.
|
|
|
|
**Geen nieuwe write-tools nodig:** bestaande `create_story` + `create_task` + `update_task_plan` werken al.
|
|
|
|
**Schema-sync:** vendor/scrum4me submodule update na Scrum4Me-PR merge.
|
|
|
|
### Stap 7 — Agent-prompt + lokale Claude-command
|
|
|
|
In de Scrum4Me-checkout (of in een gedeelde plek voor agent-prompts) twee Claude Code commands:
|
|
|
|
**`/implement-next-story`** — bestaand, gebruikt `wait_for_job({ accept_kinds: ['IMPLEMENTATION'] })`
|
|
|
|
**`/generate-plan`** — nieuw:
|
|
|
|
Korte prompt-flow:
|
|
1. `wait_for_job({ accept_kinds: ['PLANNING'], wait_seconds: 600 })` — claim
|
|
2. Lees `planning_target` uit response (PBI of STORY) + `existing_*`
|
|
3. **Lees lokale docs uit Scrum4Me-checkout:**
|
|
- `docs/specs/functional.md` (functioneel kader)
|
|
- `docs/architecture.md` (technisch kader)
|
|
- `docs/patterns/*.md` (relevante patterns op basis van target-titel/-beschrijving)
|
|
- `docs/design/styling.md` als target UI-werk betreft
|
|
4. Bedenk children:
|
|
- Voor `STORY`-target: 3-7 taken met titel, korte beschrijving, `implementation_plan` (verwijst naar relevante patterns + bestanden), priority
|
|
- Voor `PBI`-target: 2-5 stories met titel, beschrijving in user-story-format, acceptance_criteria, priority
|
|
5. Filter ontbrekende items: skip wat overlapt met `existing_*` (titel-match)
|
|
6. Voor elk: `create_task` of `create_story` via MCP
|
|
7. `update_job_status({ status: 'DONE', summary: 'Aangemaakt: 4 taken / 0 overgeslagen (titel-overlap)' })`
|
|
|
|
Bij failure: `update_job_status({ status: 'FAILED', error })` + toast voor user.
|
|
|
|
**Mens-rolverdeling:** twee Claude Code-sessies tegelijk draaien (één met `/implement-next-story` running, één met `/generate-plan` running). Beide claimen alleen hun eigen kind via `accept_kinds`. Dezelfde gebruiker-token of twee aparte (afhankelijk van hoe je workers wilt scheiden).
|
|
|
|
### Stap 8 — Tests
|
|
|
|
| Test | Locatie |
|
|
|---|---|
|
|
| `enqueuePlanningJobAction` — auth, demo, idempotency, scope | `__tests__/actions/claude-jobs-planning.test.ts` |
|
|
| Schema-mapper voor `kind` + `planning_target_*` | `__tests__/lib/claude-job-status.test.ts` |
|
|
| SSE-event format met `kind` | `__tests__/api/realtime-solo-planning.test.ts` |
|
|
| Status-pill rendering per status | `__tests__/components/shared/planning-job-pill.test.tsx` |
|
|
| Knop disabled-state in StoryDialog/PbiDialog bij actieve job | `__tests__/components/backlog/dialog-planning-button.test.tsx` |
|
|
|
|
MCP-tools testen in `mcp` repo (aparte PR).
|
|
|
|
---
|
|
|
|
## Critical files
|
|
|
|
### Scrum4Me-repo
|
|
|
|
| File | Action | Reden |
|
|
|---|---|---|
|
|
| `prisma/schema.prisma` | MODIFY | `ClaudeJobKind`, `PlanningTargetType`, `ApiTokenKind` enums + nullable `task_id` + `planning_target_*` velden |
|
|
| `prisma/migrations/<date>_planning_job_kind/` | NEW | Migratie + check-constraint |
|
|
| `lib/claude-job-status.ts` | MODIFY | `kind` in API-shape |
|
|
| `lib/schemas/claude-job.ts` | NEW/MODIFY | Discriminated union op `kind` |
|
|
| `lib/schemas/planning-target.ts` | NEW | Target-validator |
|
|
| `actions/claude-jobs.ts` | MODIFY | `enqueuePlanningJobAction` toevoegen, idempotency uitbreiden |
|
|
| `app/api/realtime/solo/route.ts` | MODIFY | `kind` in payload, initial-state ook PLANNING-jobs |
|
|
| `stores/claude-jobs-store.ts` (of vergelijkbaar) | MODIFY | `kind`-filter helpers |
|
|
| `components/backlog/story-dialog.tsx` | MODIFY | "Genereer taken"-knop + status-pill in header |
|
|
| `components/backlog/pbi-dialog.tsx` | MODIFY | "Genereer stories"-knop + status-pill in header |
|
|
| `components/backlog/story-panel.tsx` | MODIFY | Status-pill op story-card |
|
|
| `components/backlog/pbi-list.tsx` | MODIFY | Status-pill op pbi-card |
|
|
| `components/shared/planning-job-pill.tsx` | NEW | Generic pill-component |
|
|
| `docs/patterns/claude-agent-roles.md` | NEW | Pattern-doc: één table, kind-enum, accept_kinds-arg, lokale agent-prompts |
|
|
| `docs/architecture.md` | MODIFY | Sectie "Claude Agents" uitbreiden — twee rollen, schema, queue, prompts |
|
|
| `docs/specs/dialogs/pbi.md` | MODIFY | Sectie "Speciale gedragingen → Planning-trigger" toevoegen |
|
|
| `docs/specs/dialogs/story.md` | MODIFY | Idem |
|
|
| `docs/specs/dialogs/task.md` | MODIFY | Vermelden dat tasks ook door planning-agent kunnen ontstaan |
|
|
| `__tests__/actions/claude-jobs-planning.test.ts` | NEW | |
|
|
| `__tests__/lib/claude-job-status.test.ts` | MODIFY | `kind`-mapping testen |
|
|
| `__tests__/api/realtime-solo-planning.test.ts` | NEW | |
|
|
| `__tests__/components/shared/planning-job-pill.test.tsx` | NEW | |
|
|
| `__tests__/components/backlog/dialog-planning-button.test.tsx` | NEW | |
|
|
|
|
### mcp repo (aparte PR, na Scrum4Me-merge)
|
|
|
|
| File | Action |
|
|
|---|---|
|
|
| `src/tools/wait_for_job.ts` | MODIFY — `accept_kinds`-arg + polymorf response |
|
|
| `src/tools/get_planning_context.ts` | NEW (optioneel, helper) |
|
|
| `src/types/job.ts` | MODIFY — kind + planning_target |
|
|
| `src/prompts/generate-plan.md` | NEW — Claude command-prompt |
|
|
| `vendor/scrum4me/` (submodule) | UPDATE — na Scrum4Me-merge |
|
|
|
|
---
|
|
|
|
## Volgorde van uitvoering
|
|
|
|
1. **Schema + migratie + status-mapper** (Stap 1+2) — eigen commit, geen UI-impact
|
|
2. **Server action `enqueuePlanningJobAction` + tests** (Stap 3) — werkt headless via curl/test
|
|
3. **SSE-payload uitbreiden + claude-jobs-store** (Stap 4) — backend pipe klaar
|
|
4. **Status-pill component + tests** (Stap 5a) — losstaande primitive
|
|
5. **Trigger-knoppen in StoryDialog + PbiDialog** (Stap 5b) — UI-trigger werkt, agent nog niet
|
|
6. **Pause** — verifieer end-to-end met handmatig insert in `claude_jobs` (kind=PLANNING) of via mock-MCP-call
|
|
7. **MCP-PR in mcp repo** (Stap 6) — `wait_for_job` uitbreiden, types updaten
|
|
8. **Lokaal `/generate-plan`-command schrijven + testen** (Stap 7) — agent claimt, leest, schrijft
|
|
9. **End-to-end test** (Stap 8) — story → klik knop → agent rendert taken → SSE → live in TaskPanel
|
|
10. **Docs-PR** — pattern-doc `claude-agent-roles.md`, architecture-update, dialog-profielen aanvullen
|
|
|
|
Branch-naming: `feat/M15-planning-agent` (Scrum4Me) + `feat/planning-agent` (mcp).
|
|
|
|
Conform CLAUDE.md "branch-per-milestone": commits accumuleren lokaal, pushen pas na gebruikerstest.
|
|
|
|
---
|
|
|
|
## Verification
|
|
|
|
1. `npm run lint && npm test && npm run build` groen
|
|
2. **Schema-migratie:** bestaande `claude_jobs`-rijen krijgen `kind=IMPLEMENTATION`; check-constraint blokkeert ongeldige combinaties
|
|
3. **Idempotency:** twee keer klikken op "Genereer taken" → tweede klik geeft toast "Plan-job al gestart", knop disabled
|
|
4. **Demo-block:** demo-user ziet knop disabled met DemoTooltip; server action returnt 403 als je 'm toch aanroept
|
|
5. **SSE live:** trigger planning-job → status-pill verschijnt op story-card binnen 1s zonder refresh
|
|
6. **End-to-end:** lokale `/generate-plan` agent claimt job, leest target via `wait_for_job`, leest 3-4 docs uit Scrum4Me-checkout, maakt 3-5 taken via `create_task`, status DONE → taken zichtbaar in TaskPanel zonder refresh
|
|
7. **Cancel-flow:** gebruiker kan vanuit dialog een running PLANNING-job cancellen → status-pill verdwijnt, agent ziet job-status `CANCELLED` bij volgende `update_job_status`
|
|
8. **Cross-kind isolation:** een implementation-agent met `accept_kinds=['IMPLEMENTATION']` (default) ziet PLANNING-jobs niet; idem omgekeerd
|
|
9. **Aanvullen-policy:** trigger op story die al 2 taken heeft — agent voegt alleen ontbrekende toe (logged in summary: "Aangemaakt: 3 / Overgeslagen: 2 (titel-overlap)")
|
|
10. **Documentatie:** `docs/patterns/claude-agent-roles.md` beschrijft beide agent-rollen, hun job-flow, en hoe je een derde agent zou toevoegen
|
|
|
|
---
|
|
|
|
## Open punten (na approval expliciet maken)
|
|
|
|
1. **Token-strategie:** krijgt elke agent-rol een eigen ApiToken (cleaner, twee credentials), of bestaat er één multi-kind-token per user? *Voorstel: aparte tokens — één per kind. Gebruiker beheert ze in Settings.*
|
|
2. **Concurrency in 1 worker:** mag `accept_kinds: ['IMPLEMENTATION', 'PLANNING']` (één worker pakt allebei)? *Voorstel: ja, technisch toegestaan, maar in v1 raad je af want context-pollution. Documenteren als "kan, maar gebruik gescheiden processen".*
|
|
3. **Doc-selectie:** hoe bepaalt de agent welke `docs/patterns/*.md` relevant zijn? *Voorstel: lees `docs/patterns/`-index op + match op keywords uit target-titel/-beschrijving. Geen embeddings in v1.*
|
|
4. **Hoeveel children per run?** *Voorstel: hard cap 8 in de prompt (anders gaat 'ie speculeren). Gebruiker kan opnieuw klikken voor meer.*
|
|
5. **Editable plan-text:** wanneer agent `implementation_plan` invult op een nieuwe task, kan de gebruiker die later via TaskDialog editen — dat werkt al, geen extra werk.
|
|
6. **Failure-recovery:** wat als agent halverwege crasht? Stale-cleanup >30min werkt al; partial-children blijven aangemaakt. *Voorstel: accepteer partial — gebruiker kan opnieuw triggeren, aanvullen-policy filtert duplicaten.*
|
|
|
|
---
|
|
|
|
## Out of scope (v1 van deze feature)
|
|
|
|
- ❌ Diff-review-flow (vervangen-modus uit eerdere AskUserQuestion)
|
|
- ❌ Live streaming-output van agent (alleen status-events, geen tekst-stream)
|
|
- ❌ Meerdere parallele PLANNING-jobs op dezelfde target (idempotency blokkeert)
|
|
- ❌ Custom prompts per product (vaste prompt-template `/generate-plan`)
|
|
- ❌ Embeddings / vector-search over docs (agent leest plain files)
|
|
- ❌ Cross-user planning (agent werkt altijd binnen eigen product-scope)
|
|
- ❌ Auto-trigger (bv. "elke nieuwe lege story krijgt automatisch een plan-job") — handmatige trigger blijft regel
|
|
- ❌ Agent-tot-agent-orkestratie (planning-agent kan geen impl-agent triggeren) — gebruiker blijft in the loop
|
|
- ❌ Planning op product-niveau (PBI's genereren) — pas zinvol als product-spec-input bestaat
|
|
- ❌ Planning-agent UI in Solo Paneel (Solo blijft impl-only) — triggers zitten in backlog-dialogs
|
|
|
|
---
|
|
|
|
## Migratie-pad voor toekomstige derde agent (referentie)
|
|
|
|
Als er ooit een derde agent komt (bv. **review-agent** die een PR review't):
|
|
|
|
1. `ClaudeJobKind` enum uitbreiden met `REVIEW`
|
|
2. `ApiTokenKind` enum uitbreiden met `REVIEW`
|
|
3. `enqueueReviewJobAction` aanmaken (kopieert pattern van planning)
|
|
4. `wait_for_job` accepteert nieuwe `kind` automatisch via `accept_kinds`
|
|
5. Pattern-doc `claude-agent-roles.md` uitbreiden met de derde rol
|
|
|
|
Geen schema-revolutie nodig — `kind`-enum is het uitbreidingspunt.
|