@officesoft/qualadoc

v1.1.0

Published

2 months ago

AI-powered project scaffolding & agent workflow. URS in → specs, backlog, prompts, dashboard out.

0High
0Medium
0Low

devthings

urs requirements ai-agents claude scaffolding project-generator backlog dashboard cli workflow project-management

◆ 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

🎯 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

npm install -g qualadoc
qualadoc --version

Development

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 voor agent functionaliteit (optioneel)
Qdrant 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):

docker run -p 6333:6333 qdrant/qdrant

Status checken:

curl http://localhost:6333
# Of in dashboard: zie Qdrant status indicator

⚡ Snelstart

Optie 1: Start met een template

# 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:

# 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:

qualadoc init --urs urs.md --name mijn-app
cd mijn-app

Stap 3: Start het dashboard

qualadoc dashboard

Browser opent op http://localhost:3005 met het agent dashboard.

📖 Commands

`qualadoc new`

Genereer een URS document vanuit een template.

# 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.

# 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.

# 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.

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.

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.

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.

qualadoc open mijn-app

`qualadoc agent`

Start een agent direct vanuit de CLI (zonder dashboard).

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

# 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

# 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

# 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:

Start dashboard: qualadoc dashboard
Klik "Auto Start" → 3 operators beginnen parallel met taken
Monitor live terminal output per lane
Auto-review triggered na laatste operator klaar
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:

# 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:

# {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:

# 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):

# 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:

# 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

# 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

# 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

# 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

Start met visie — Waarom bestaat dit product?
Duidelijke scope — Wat is in/out of scope?
Atomaire requirements — Elk requirement = 1 feature
Concrete acceptatiecriteria — Hoe weet je dat het af is?
Logische groepering — Group related features
Realistische prioriteiten — Must = echt kritisch

Agent Workflow

Lees ALTIJD specs eerst — Context voor implementatie
Kleine commits — Per taak, niet per sessie
Update backlog status — Keep progress visible
Test voordat je commit — Verify requirements
Werk fase voor fase — Finish foundation before features

Project Organisatie

Feature-based — Group by feature, niet by type
Co-located tests — Test naast implementation
Barrel exports — Clean API per module
Shared utilities — DRY principle
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:

Auto-assign: Elke operator krijgt automatisch volgende 3 🔲 taken uit backlog
Parallel execution: 3 operators werken simultaan aan verschillende taken
Role detection: Agent rol (operator/planner/tester/designer/docs-manager) wordt gedetecteerd op basis van taak-IDs
Auto-review trigger: Na laatste operator klaar → 3s delay → reviewer start automatisch
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

💬 Support

Issues: GitHub Issues
Docs: This README + /docs/
Examples: /tests/test-urs-taskflow.md

Made with ❤️ and Claude Sonnet 4.5