npm package: @officesoft/qualadoc
Description: AI-powered project scaffolding & agent workflow. URS in → specs, backlog, prompts, dashboard out.
Author: Steve Mangelschots
Latest version: 1.1.0

# ◆ Qualadoc

**AI-powered project scaffolding & agent workflow CLI.**

Van URS naar volledig project in minuten. Qualadoc genereert automatisch documentatie, mappenstructuur, backlog, specs, prompts, en een agent dashboard.

> Monorepo layout (v3 UI preview):
> - `backend/` (this folder): CLI + API server
> - `frontend/`: Next.js UI

## Monorepo Runtime (Current)

For current day-to-day usage, prefer this flow:

- From repo root: `npm run dev:all`
- Backend health: `http://localhost:3005/api/agents`
- Frontend health: `http://localhost:3001`

Logging:
- `npm run dev:all` logs to terminal only
- `qualadoc dashboard` (CLI command path) writes `backend/logs/dashboard-server.log`
- Agent sessions write `backend/logs/agent-*.log`

Dependency policy (current):
- Backend/CLI: keep zero-dependency principle
- Frontend (`frontend/`): modern npm dependencies are expected

---
[![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/stevemangelschots/qualadoc)
[![Node](https://img.shields.io/badge/node-%3E%3D20.0.0-green.svg)](https://nodejs.org)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

---

## 🎯 Wat doet Qualadoc?

Qualadoc transformeert een **URS (requirements document)** in een compleet project setup:

```
URS.md → qualadoc init → Complete project + AI agents → Working application
```

**Output:**
- 📄 **CLAUDE.md** — Complete project context voor AI agents
- 📋 **Backlog** — Alle taken gefaseerd met status tracking
- 📚 **Specs** — Uitgewerkte feature specificaties per groep
- 🗺️ **Roadmap** — Fasering en prioriteiten
- 🤖 **Agent prompts** — Ready-to-use prompts per fase
- 📂 **Project structuur** — Tech-specifieke mappenindeling
- 🖥️ **Agent dashboard** — Visual interface om agents te sturen

---

## 📦 Installatie

### Via npm
```bash
npm install -g qualadoc
qualadoc --version
```

### Development
```bash
git clone https://github.com/stevemangelschots/qualadoc.git
cd qualadoc
npm link
qualadoc --version
```

**Vereisten:**
- Node.js ≥ 20.0.0
- Geen andere dependencies (zero deps)
- [Claude Code CLI](https://claude.ai/code) voor agent functionaliteit (optioneel)
- [Qdrant](https://qdrant.tech) voor semantische zoeken (optioneel, zie hieronder)

### Optional: Qdrant voor Semantische Zoeken

Qualadoc ondersteunt **Qdrant** als vector database voor semantische zoeken in documentatie. Dit is volledig optioneel — de tool werkt zonder Qdrant, maar semantische zoeken is dan uitgeschakeld.

**Zonder Qdrant:**
- Dashboard werkt normaal
- Semantische zoekbalk toont "Qdrant niet beschikbaar" melding
- Alle andere features blijven functioneel

**Met Qdrant:**
- Semantische zoeken in alle project documenten
- Automatische document indexatie bij `qualadoc init` en `qualadoc update`
- Related requirements detection
- Duplicate requirements detection

**Installatie (via Docker):**
```bash
docker run -p 6333:6333 qdrant/qdrant
```

**Status checken:**
```bash
curl http://localhost:6333
# Of in dashboard: zie Qdrant status indicator
```

---

## ⚡ Snelstart

### Optie 1: Start met een template

```bash
# Bekijk beschikbare templates
qualadoc new --list

# Genereer URS vanuit template
qualadoc new react-dashboard \
  --name "TaskDashboard" \
  --description "Modern task management dashboard" \
  --output urs.md

# Review en pas aan naar wens
code urs.md

# Genereer project
qualadoc init --urs urs.md --name taskdashboard
```

### Optie 2: Schrijf je eigen URS

**urs.md:**
```markdown
# MijnApp — URS

> **Product:** MijnApp — Moderne taakmanager
> **Versie:** 1.0
> **Datum:** 2026-02-07

## 1. Productvisie
Een moderne webapplicatie voor taakbeheer met focus op productiviteit.

## 2. Scope
### In Scope
- Taken aanmaken en beheren
- Dashboard met overzicht
- Dark mode

### Out of Scope
- Team collaboration (later)

## 3. Functionele Requirements

### 3.1 Taakbeheer
| ID | Requirement | Prioriteit |
|----|-------------|------------|
| FR-001 | Gebruiker kan taken aanmaken met titel en beschrijving | Must |
| FR-002 | Gebruiker kan taken als voltooid markeren | Must |
| FR-003 | Gebruiker kan taken verwijderen | Must |

### 3.2 Dashboard
| ID | Requirement | Prioriteit |
|----|-------------|------------|
| FR-010 | Dashboard toont alle open taken | Must |
| FR-011 | Filter op status | Should |

## 4. Technische Requirements

### 4.1 Tech Stack
- **Framework:** React 18 + TypeScript
- **Build:** Vite
- **State:** Zustand
- **Styling:** Tailwind CSS
```

**Genereer project:**
```bash
qualadoc init --urs urs.md --name mijn-app
cd mijn-app
```

### Stap 3: Start het dashboard

```bash
qualadoc dashboard
```

Browser opent op `http://localhost:3005` met het agent dashboard.

---

## 📖 Commands

### `qualadoc new`
Genereer een URS document vanuit een template.

```bash
# Toon alle templates
qualadoc new --list

# Interactieve modus
qualadoc new react-dashboard

# Non-interactieve modus
qualadoc new node-api \
  --name "UserAPI" \
  --description "User management REST API" \
  --output api-urs.md \
  --force
```

**Templates:**
- `react-dashboard` — Dashboard met data visualisatie, auth, charts (44 requirements)
- `node-api` — REST API met Express/Fastify, JWT, database (32 requirements)
- `cli-tool` — CLI tool met subcommands en prompts (24 requirements)

### `qualadoc init`
Creëer een nieuw project vanuit een URS document.

```bash
# Interactief
qualadoc init

# Met flags
qualadoc init \
  --urs urs.md \
  --name "mijn-app" \
  --dir ./output \
  --tech react-vite \
  --force
```

**Flags:**
- `--urs <file>` — Pad naar URS document
- `--name <naam>` — Projectnaam (default: afgeleid van URS)
- `--dir <pad>` — Output directory (default: `./<naam>`)
- `--tech <stack>` — Tech stack: `react-vite` | `node-api` | `generic`
- `--force` — Overschrijf bestaand project

**Output structuur:**
```
mijn-app/
├── .qualadoc.json              ← Project metadata
├── CLAUDE.md                   ← AI agent context (architectuur, regels, stack)
├── AGENTS.md                   ← Agent leeswijzer en workflow
├── package.json                ← Tech-specifieke scripts
├── .gitignore
├── docs/
│   ├── urs/
│   │   ├── urs.md              ← Originele URS
│   │   └── requirements-index.md
│   ├── specs/
│   │   ├── taakbeheer.md       ← Feature spec per groep
│   │   └── dashboard.md
│   ├── planning/
│   │   ├── backlog.md          ← Gefaseerde taken met status (🔲/🔨/✅)
│   │   ├── roadmap.md          ← Fasering overzicht
│   │   └── prompts/
│   │       ├── fase-0-foundation.md
│   │       └── fase-1-*.md     ← Agent prompts per feature
│   ├── devops/workflow.md      ← Agent procedure
│   └── STRUCTURE.md            ← Mappenstructuur uitleg
├── scripts/dashboard/
│   ├── server.mjs              ← Dashboard backend (SSE + agent spawning)
│   └── index.html              ← Dashboard UI (zero deps)
├── logs/                       ← Agent sessie logs
└── src/                        ← Tech-specifieke structuur
```

### `qualadoc update`
Update een bestaand project met een gewijzigde URS.

```bash
# Auto-detect project in huidige directory
qualadoc update --urs urs-v2.md

# Specifieke directory
qualadoc update --urs urs-v2.md --dir ./mijn-app
```

**Wat doet het:**
- ✅ Re-parsed URS en detecteert wijzigingen
- ✅ **Behoudt task status** (✅ blijft ✅, 🔨 blijft 🔨)
- ✅ Regenereert alle documentatie (backlog, specs, prompts, roadmap)
- ✅ Update CLAUDE.md bij tech stack wijzigingen
- ✅ Schrijft update log naar `logs/update-{timestamp}.md`

**Use case:** Je voegt requirements toe of wijzigt tech stack → update het project zonder je voortgang te verliezen.

### `qualadoc dashboard`
Start het multi-agent dashboard in de browser.

```bash
cd mijn-app
qualadoc dashboard

# Custom poort
qualadoc dashboard --port 3006
```

**Dashboard Layout:**

```
┌─────────────────────────────────────────────────────────────────┐
│  ◆ Qualadoc    [C1 🟢] [C2 🟢] [C3 ⚪] [🔍 ⚪]    Auto-review ☑  │
├────────────────┬─────────────────────────────────────────────────┤
│                │  ┌─ Operator C1 ─┐  ┌─ Operator C2 ─┐  ┌─ Operator C3 ─┐│
│  📋 Backlog    │  │ F0-01      │  │ F0-04      │  │             ││
│  ─────────     │  │ F0-02      │  │ F0-05      │  │             ││
│  Fase 0        │  │ F0-03      │  │ F0-06      │  │             ││
│  • F0-01 ✅    │  ├────────────┤  ├────────────┤  ├─────────────┤│
│  • F0-02 🔨    │  │ Terminal   │  │ Terminal   │  │ Terminal    ││
│  • F0-03 🔲    │  │ output...  │  │ output...  │  │             ││
│                │  └────────────┘  └────────────┘  └─────────────┘│
│  🔀 Git Log    │                                                  │
│  ─────────     │  ┌────────── Reviewer R1 ──────────────────────┐│
│  abc1234 fix   │  │ Mode: full  │ Start: 14:32  │ Findings: 3   ││
│  def5678 feat  │  ├──────────────────────────────────────────────┤│
│                │  │ Terminal output...                           ││
│  📄 Changes    │  └──────────────────────────────────────────────┘│
│  ─────────     │                                                  │
│  M backlog.md  │                                                  │
│                │                                                  │
│  📄 Docs       │                                                  │
│  ─────────     │                                                  │
│  Draft: v5.0   │                                                  │
└────────────────┴──────────────────────────────────────────────────┘
```

**Features:**
- 🤖 **Multi-Agent Execution** — 3 operators + 1 reviewer parallel
- 🎯 **Auto-assign** — Automatische taak-toewijzing: volgende 3 🔲 taken per operator
- 🔍 **Auto-review** — Reviewer start 3s na laatste operator (configurable)
- 📝 **Reviewer Modi:**
  - `full` — Review + docs + voorbereiding (default)
  - `review` — Alleen code review + tests
  - `docs` — Alleen documentatie updates
  - `prepare` — Alleen voorbereiding volgende taken
- 💬 **Live Terminal** — SSE streaming per agent lane
- 📊 **Progress Tracking** — Visual status per fase in sidebar
- 🔀 **Git Integration:**
  - Recent commits (hash, message, author, time)
  - Uncommitted changes (M/A/D status)
  - Last commit diff stats
- 📄 **Docs Lifecycle:**
  - Draft status (scope, reason, target version)
  - Diff viewer (modified/added/deleted files)
  - Start draft, approve, discard actions
- 🎨 **Zero Dependencies** — Single HTML file, dark theme
- ⚙️ **Configurable Port** — Via `~/.qualadoc/config.json` of `--port` flag

**🆕 Nieuwe Dashboard Features (v1.0.0):**
- 📊 **Project Info Modal** — Complete project overview (Hamburger menu → Bestand → Project Info)
  - Project naam, pad, versie
  - Git branch, uncommitted/untracked files
  - Backlog statistics (totaal, compleet %, openstaand)
  - Server poort, uptime, Node versie
- 📥 **URS Export** — Download URS als markdown (Hamburger menu → Bestand → Export URS)
- 📈 **Live Phase Progress** — Metrics bar toont real-time voortgang percentage
- 🔍 **Agent Log Viewer** — Klik op agent status → "View Log" → gefilterde logs per agent
- 🔗 **Related Requirements** — Klik op requirement ID → zie gerelateerde requirements via Qdrant
- 📄 **Document Viewer** — Klik op context document → full viewer met annotations
- 🔎 **Quick Search Navigation** — Ctrl+K → zoek → klik → open document
- 🎨 **Custom Alerts** — Alle browser popups vervangen door styled modals (dark theme)

### `qualadoc status`
Toon voortgang van het huidige project.

```bash
cd mijn-app
qualadoc status
```

Output:
```
◆ Qualadoc — Project Status

📂 Project: mijn-app
📁 Directory: /path/to/mijn-app

Progress per fase:
  Fase 0 — Foundation        [████████████████████] 14/14 (100%)
  Fase 1 — MVP Core          [█████████░░░░░░░░░░░]  9/17 ( 53%)
  Fase 2 — Polishing         [░░░░░░░░░░░░░░░░░░░░]  0/12 (  0%)

Overall: 23/43 taken (53%)
```

### `qualadoc projects`
Toon alle Qualadoc projecten.

```bash
qualadoc projects
```

Output:
```
◆ Qualadoc — Projecten

Gevonden projecten (3):

  mijn-app
    /Users/me/projects/mijn-app
    Tech: react-vite
    Created: 2026-01-15

  api-backend
    /Users/me/projects/api-backend
    Tech: node-api
    Created: 2026-01-20

  cli-tool
    /Users/me/projects/cli-tool
    Tech: generic
    Created: 2026-02-01
```

### `qualadoc open`
Open een project en start het dashboard.

```bash
qualadoc open mijn-app
```

### `qualadoc agent`
Start een agent direct vanuit de CLI (zonder dashboard).

```bash
cd mijn-app
qualadoc agent fase-0-foundation

# Of custom prompt
qualadoc agent custom-prompt
```

---

## 🏗️ Project Structuur

### Tech Stack Detection

Qualadoc detecteert automatisch je tech stack uit de URS:

| Keywords in URS | Template | Mappenstructuur |
|-----------------|----------|-----------------|
| "React", "Vite" | `react-vite` | `src/features/`, `src/shared/`, `src/styles/` |
| "Next" | `nextjs` | `src/features/`, `src/shared/` |
| "Express", "Fastify" | `node-api` | `src/modules/`, `src/config/`, `src/middleware/` |
| Geen match | `generic` | `src/features/`, `src/shared/` |

### React + Vite Template

```
src/
├── features/              ← Feature modules
│   └── {feature}/
│       ├── components/    ← React componenten
│       ├── hooks/         ← Custom hooks
│       ├── store/         ← State management (Zustand)
│       ├── types.ts       ← Feature types
│       └── index.ts       ← Barrel export
├── shared/
│   ├── types/            ← Shared TypeScript types
│   ├── ui/               ← Reusable UI componenten
│   ├── hooks/            ← Shared hooks
│   └── utils/            ← Helpers
└── styles/               ← Global CSS
```

### Node API Template

```
src/
├── modules/              ← Feature modules
│   └── {module}/
│       ├── controller.ts
│       ├── service.ts
│       ├── model.ts
│       └── routes.ts
├── config/               ← Config files
├── middleware/           ← Express middleware
├── utils/                ← Helpers
└── types/                ← Shared types
```

---

## 🤖 Agent Workflow

Qualadoc genereert alles wat een AI agent nodig heeft om je project te bouwen:

### 1. CLAUDE.md — Project Context

```markdown
# CLAUDE.md — mijn-app

## Project
Moderne taakmanager met React en TypeScript.

## Tech Stack
- Framework: React 18 + TypeScript
- Build: Vite
- State: Zustand
- Styling: Tailwind CSS

## Architectuur
src/
  features/
  shared/

## Conventies
- Functional components met named exports
- Zustand stores in src/features/{feature}/store/
- CSS Modules voor styling
...

## Huidige Prioriteit — Fase 0 Foundation
Start met Fase 0 taken in docs/planning/backlog.md
Lees specs in docs/specs/ voordat je begint.

## Regels
1. Lees ALTIJD de spec voordat je implementeert
2. Update backlog.md status na afronding (🔲 → ✅)
3. Commit PER TAAK, niet per sessie
...
```

### 2. AGENTS.md — Leeswijzer

```markdown
# AGENTS.md — Agent Leeswijzer

## Stap-voor-stap workflow

1. Lees CLAUDE.md voor project context
2. Open docs/planning/backlog.md
3. Zoek een 🔲 taak in de huidige fase
4. Lees de relevante spec in docs/specs/
5. Implementeer de taak
6. Update backlog.md status (🔲 → ✅)
7. Commit met descriptieve message
8. Repeat
...
```

### 3. Prompts — Ready-to-use

```markdown
# Fase 0: Foundation

Lees CLAUDE.md en AGENTS.md voor volledige context.

Taken:
- F0-01: Project init + build tool setup
- F0-02: State management setup
- F0-03: CSS basis
...

Acceptatiecriteria:
✓ npm run dev werkt
✓ State management getest
✓ Styling toegepast
```

### 4. Dashboard — Multi-Agent Interface

Het multi-agent dashboard biedt een visuele interface om meerdere AI agents parallel te laten werken:

**Agent Lanes:**
- **3 Operator Agents (C1, C2, C3)** — Parallelle implementatie van taken
  - Automatische taak-toewijzing: elk krijgt volgende 3 🔲 taken uit backlog
  - Live terminal output per lane via SSE streaming
  - Task chips tonen actieve taken
  - Stats: start tijd, logs
- **1 Reviewer Agent (R1)** — Code review + documentatie
  - Auto-start na alle operators klaar (configureerbaar)
  - 4 modi: full (alles), review (alleen code), docs (alleen documentatie), prepare (voorbereiding)
  - Findings panel voor review notities
  - Inklapbaar en resizable

**Sidebar Features:**
- 📋 **Backlog tab** — Alle taken per fase met status icons
- 🔀 **Git Log tab** — Recente commits met hash, message, author
- 📄 **Changes tab** — Uncommitted changes
- 📄 **Docs tab** — Document lifecycle (draft/approve/archive)

**Workflow:**
1. Start dashboard: `qualadoc dashboard`
2. Klik "Auto Start" → 3 operators beginnen parallel met taken
3. Monitor live terminal output per lane
4. Auto-review triggered na laatste operator klaar
5. Reviewer analyseert code, updatet docs, bereidt volgende taken voor

**SSE Events:**
- `agents-update` — Agent status wijzigingen
- `agent-output` — Terminal output per regel
- `agent-done` — Agent klaar (exit code + duration)
- `auto-review-starting` — Reviewer auto-start notificatie

---

## 🔌 Dashboard API Endpoints

Het multi-agent dashboard exposeert een REST API voor integratie:

### Agent Management
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/agents` | Alle agent slots met status |
| POST | `/api/agent/start` | Start agent (auto of specifiek slot) |
| POST | `/api/agent/stop` | Stop agent (enkel of alle) |
| GET | `/api/stream` | SSE stream voor live updates |

### Backlog & Tasks
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/tasks` | Backlog als fases array |
| GET | `/api/tasks/next?count=3` | Volgende N taken |

### Reviewer
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/reviewer/prompt?mode=full` | Reviewer prompt preview |
| GET | `/api/reviewer/settings` | Auto-review instellingen |
| POST | `/api/reviewer/settings` | Toggle auto-review |

### Git Integration
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/git/log?count=20` | Recente commits |
| GET | `/api/git/status` | Uncommitted changes |

### Docs Lifecycle
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/docs/status` | Draft status, manifest, archive count |
| POST | `/api/docs/draft` | Start draft cyclus (scope, reason) |
| POST | `/api/docs/start-agent` | Start docs-manager agent |
| POST | `/api/docs/approve` | Archiveer + publiceer draft |
| POST | `/api/docs/discard` | Verwerp actieve draft |

### Prompts
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/prompts` | Alle prompt bestanden |
| GET | `/api/prompt/:name` | Prompt inhoud |

### Project Info & Export 🆕
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/server/info` | Server + project metadata |
| GET | `/api/swim/urs` | URS content (voor export) |

### Logs 🆕
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/logs?level=error&category=agent&limit=100` | Log events met filtering |

### Related Requirements 🆕
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/qdrant/related/:reqId?limit=5` | Gerelateerde requirements via Qdrant |

### Agent Roles 🆕
| Methode | Endpoint | Doel |
|---------|----------|------|
| GET | `/api/agents/roles` | Alle beschikbare agent rollen |

**Voorbeeld:**
```bash
# Start een operator agent met specifieke taken
curl -X POST http://localhost:3005/api/agent/start \
  -H "Content-Type: application/json" \
  -d '{"slot": "c1", "taskIds": ["F0-01", "F0-02"]}'

# Toggle auto-review
curl -X POST http://localhost:3005/api/reviewer/settings \
  -H "Content-Type: application/json" \
  -d '{"autoReview": true, "autoReviewMode": "full"}'
```

---

## 🎨 URS Format

Een Qualadoc URS volgt deze structuur:

```markdown
# {Project} — URS

> **Product:** {Name} — {Tagline}
> **Versie:** 1.0
> **Datum:** YYYY-MM-DD

---

## 1. Productvisie
{High-level beschrijving}

---

## 2. Scope

### In Scope
- Feature 1
- Feature 2

### Out of Scope
- Future feature 1

---

## 3. Functionele Requirements

### 3.1 {Feature Group}

| ID | Requirement | Prioriteit |
|----|-------------|------------|
| FR-001 | {Description} | Must |
| FR-002 | {Description} | Should |
| FR-003 | {Description} | Could |

### 3.2 {Feature Group}
...

---

## 4. Technische Requirements

### 4.1 Tech Stack

- **Framework:** React 18 + TypeScript
- **Build:** Vite
- **State:** Zustand
- **Styling:** Tailwind CSS
- **Testing:** Vitest

### 4.2 Performance

| ID | Requirement | Prioriteit |
|----|-------------|------------|
| TR-001 | Load time < 2s | Must |

---

## 5. Non-Functional Requirements

### 5.1 Security
...
```

**Prioriteiten:**
- **Must** — Kritisch voor MVP
- **Should** — Belangrijk maar niet kritisch
- **Could** — Nice-to-have
- **Won't** — Expliciet uitgesloten

---

## 📊 Backlog & Status Tracking

Qualadoc genereert een gefaseerde backlog met status tracking:

```markdown
# Product Backlog — mijn-app

## Fase 0 — Foundation

| # | Taak | FR | Status |
|---|------|----|--------|
| F0-01 | Project init + build setup | FR-001 | ✅ |
| F0-02 | State management setup | FR-002 | 🔨 |
| F0-03 | CSS basis | FR-003 | 🔲 |

## Fase 1 — MVP Core

### 1A: Taakbeheer

| # | Taak | FR | Status |
|---|------|----|--------|
| F1-01 | Taken aanmaken | FR-001 | 🔲 |
| F1-02 | Taken voltooien | FR-002 | 🔲 |
```

**Status icons:**
- 🔲 Todo — Nog niet begonnen
- 🔨 In Progress — Mee bezig
- ✅ Done — Af en getest
- ⏸ Blocked — Wacht op iets
- 🚫 Dropped — Geschrapt

**Fasering:**
- **Fase 0** — Foundation (build, state, styling, config)
- **Fase 1** — MVP Core (Must requirements)
- **Fase 2** — Enhancement (Should requirements)
- **Fase 3** — Polish (Could requirements)

---

## 🔄 Update Workflow

Wanneer je URS wijzigt (nieuwe requirements, tech stack change):

```bash
# Pas URS aan
code urs.md

# Update project (behoudt task status!)
qualadoc update --urs urs.md

# Check wijzigingen
cat logs/update-{timestamp}.md
```

**Update log voorbeeld:**
```markdown
# Update Log — 2026-02-07T15:30:00

## Summary
- Previous: 28 requirements (6 groups)
- Current: 32 requirements (7 groups)
- Delta: +4 requirements
- Status preserved: 15 tasks

## Changes Detected
- Requirements: 28 → 32 (+4)
- Feature groups: 6 → 7
- Tech stack changed

## Files Regenerated
- ✓ docs/planning/backlog.md (status merged)
- ✓ docs/planning/roadmap.md
- ✓ CLAUDE.md
- ✓ AGENTS.md
- ✓ docs/specs/ (7 files)
- ✓ docs/urs/requirements-index.md
- ✓ docs/planning/prompts/ (8 files)
```

---

## 🎯 Use Cases

### Use Case 1: Rapid Prototyping
```bash
# Start met template
qualadoc new react-dashboard --name "AdminPanel" --output urs.md

# Review + aanpassen
code urs.md

# Generate + build
qualadoc init --urs urs.md --name admin-panel
cd admin-panel
qualadoc dashboard
# → Agent bouwt prototype in minuten
```

### Use Case 2: Requirements → Production
```bash
# Schrijf gedetailleerde URS
code product-urs.md

# Genereer project
qualadoc init --urs product-urs.md --name production-app

# Fase voor fase bouwen via dashboard
cd production-app
qualadoc dashboard
# → Werk fase per fase af met agents
```

### Use Case 3: Update Bestaand Project
```bash
# Nieuwe requirements toevoegen
code urs.md  # Add FR-025, FR-026

# Update project
qualadoc update --urs urs.md
# → Backlog updated, old status preserved

# Check delta
cat logs/update-*.md

# Continue building
qualadoc dashboard
```

---

## 🏆 Best Practices

### URS Schrijven
1. **Start met visie** — Waarom bestaat dit product?
2. **Duidelijke scope** — Wat is in/out of scope?
3. **Atomaire requirements** — Elk requirement = 1 feature
4. **Concrete acceptatiecriteria** — Hoe weet je dat het af is?
5. **Logische groepering** — Group related features
6. **Realistische prioriteiten** — Must = echt kritisch

### Agent Workflow
1. **Lees ALTIJD specs eerst** — Context voor implementatie
2. **Kleine commits** — Per taak, niet per sessie
3. **Update backlog status** — Keep progress visible
4. **Test voordat je commit** — Verify requirements
5. **Werk fase voor fase** — Finish foundation before features

### Project Organisatie
1. **Feature-based** — Group by feature, niet by type
2. **Co-located tests** — Test naast implementation
3. **Barrel exports** — Clean API per module
4. **Shared utilities** — DRY principle
5. **Type safety** — Leverage TypeScript

---

## 🔧 Technische Details

### Architecture
- **Zero dependencies** — Only Node.js built-ins
- **ESM modules** — Modern `.mjs` files
- **Cross-platform** — Works on Windows, Mac, Linux
- **No build step** — Plain JavaScript, runs directly

### Multi-Agent Dashboard Architecture

**Backend (`src/dashboard/server.mjs`):**
- HTTP server met SSE streaming voor live updates
- REST API voor agent management, backlog, git, docs lifecycle
- 4 agent slots: c1, c2, c3 (coders) + r1 (reviewer)
- Agent spawning via `claude -p --verbose` CLI subprocess
- Graceful shutdown: SIGINT/SIGTERM handlers stoppen agents netjes
- Per-session logging in `logs/agent-{slot}-{label}-{timestamp}.log`

**Agent Workflow:**
1. **Auto-assign:** Elke operator krijgt automatisch volgende 3 🔲 taken uit backlog
2. **Parallel execution:** 3 operators werken simultaan aan verschillende taken
3. **Role detection:** Agent rol (operator/planner/tester/designer/docs-manager) wordt gedetecteerd op basis van taak-IDs
4. **Auto-review trigger:** Na laatste operator klaar → 3s delay → reviewer start automatisch
5. **Review modes:** Reviewer kan draaien in full/review/docs/prepare modus

**Frontend (`src/dashboard/index.html`):**
- Single HTML file, zero dependencies, ~800 regels
- Dark theme met CSS variables
- 3 operator lanes + 1 reviewer lane (resizable, inklapbaar)
- Sidebar met 4 tabs: backlog, git log, changes, docs lifecycle
- SSE event handling voor real-time updates
- Agent pills in header met status animatie

**Configuration:**
- Poort: `~/.qualadoc/config.json` → `QUALADOC_PORT` env var → default 3005
- Auto-review: Configureerbaar via UI of `/api/reviewer/settings`
- Max coders: 3 (hardcoded in `MAX_CODERS`)

### Config
- **Global:** `~/.qualadoc/config.json`
- **Per-project:** `.qualadoc.json`
- **Registry:** Centraal project register

---

## 📚 Examples

Check `/tests/test-urs-taskflow.md` voor een complete voorbeeld URS (28 requirements, 6 feature groups).

Check `/docs/urs/qualadoc-urs-v2.md` voor de Qualadoc URS zelf (meta! 123 requirements, 14 categorieën).

---

## 🗺️ Roadmap

**✅ Fase 0-6: MVP Complete**
- URS parser
- All generators (backlog, specs, prompts, CLAUDE.md, AGENTS.md)
- Project scaffolding
- Agent dashboard
- CLI commands

**🔨 Fase 7: Stabilisatie & Integratie (3/7)**
- ✅ E2E tests updaten voor multi-agent endpoints
- 🔨 Scaffold generator: multi-agent dashboard meegeven bij init
- 🔲 CLAUDE.md generator: multi-agent architectuur sectie
- 🔲 Prompt generator: multi-agent prompt templates
- ✅ Graceful shutdown (Ctrl+C stopt agents netjes)
- ✅ Dashboard poort uit config.json respecteren
- 🔨 README.md updaten met multi-agent documentatie

**🔲 Fase 8: Publiceren v1.0.0 (0/4)**
- 🔲 E2E tests volledig groen
- 🔲 npm link testen (global install)
- 🔲 Cross-platform test (Windows paden)
- 🔲 npm publish v1.0.0

**Future (Fase 9+):**
- Watch mode — Auto-regenerate on URS changes
- Git integration — Auto-commit per task
- Multi-project hub dashboard
- VS Code extension
- Web UI voor URS editor
- Template marketplace
- AI-powered URS generation
- Team collaboration features

---

## 🤝 Contributing

Contributions welcome! Check the backlog in `docs/planning/backlog.md` for open tasks.

---

## 📄 License

MIT © Steve Mangelschots

---

## 💬 Support

- Issues: [GitHub Issues](https://github.com/stevemangelschots/qualadoc/issues)
- Docs: This README + `/docs/`
- Examples: `/tests/test-urs-taskflow.md`

---

**Made with ❤️ and Claude Sonnet 4.5**