@eltonssouza/development-utility-kit 0.10.0

package/dashboard/public/content/manual/quickstart.en.md

@@ -0,0 +1,169 @@
+# Quickstart — 5 minutes to first value
+
+Goal: from zero installation to a useful response from `duk` in 5 minutes. No prior knowledge of the harness's internals required.
+
+If you are evaluating whether `duk` fits your workflow, this is the right starting point. Architecture, ADRs, and stack packs come later.
+
+---
+
+## Prerequisites (30 seconds to verify)
+
+```bash
+node --version    # need >= 18
+git --version     # any recent version
+```
+
+If both pass, you are ready. If not, install Node 18+ and Git first.
+
+You also need either **Claude Code** (CLI) or **Cowork** (the conversational desktop app). They are how the harness gets its work done. The harness itself is just installable skills and agents that live in your project — there is no `duk run` command that talks to an LLM. The LLM client (Claude Code / Cowork) reads the skills and invokes the agents.
+
+---
+
+## Path A — Brand new project (1 minute)
+
+```bash
+cd C:/development/source/projects     # or wherever you keep projects
+
+npx @eltonssouza/development-utility-kit new my-app
+cd my-app
+```
+
+What just happened:
+
+- A folder `my-app/` was created
+- `git init -q` initialized a fresh repo
+- The harness was injected: `.claude/` (skills + agents + stacks), `CLAUDE.md` (template), `.claude/local/` placeholder
+- The Project Identity block in `CLAUDE.md` is empty, waiting for you to declare your stack
+
+Open the folder in Cowork or Claude Code, then type in chat:
+
+```
+sabatina pra projeto novo
+```
+
+(or in English: `stack discovery`)
+
+The `stack-discovery` skill walks you through 5–8 questions about your stack (language, framework, version, database, UI lib, domain). Each question comes with a recommended answer — you just confirm. At the end, your `Project Identity` is filled and you can scaffold.
+
+---
+
+## Path B — Existing project (2 minutes)
+
+```bash
+cd path/to/existing-project
+
+npx @eltonssouza/development-utility-kit install
+```
+
+What just happened:
+
+- The CLI scanned `pom.xml`, `package.json`, `pyproject.toml`, `go.mod`, etc. to detect your stack
+- It injected `.claude/` and `CLAUDE.md` into the project
+- A `.claude/.MANIFEST` file was written (sha256 per file) — future installs will detect any local drift and refuse to overwrite without `--force`
+- Your existing `CLAUDE.md` is preserved if present (the `## Project Identity` block in particular)
+
+Open the folder in Cowork or Claude Code. The harness is ready.
+
+---
+
+## Your first useful prompt
+
+In chat, try one of these:
+
+| You say | What happens |
+|---|---|
+| `"scaffold the project"` | `scaffold` skill reads your Project Identity and generates the appropriate skeleton (backend / frontend / fullstack monorepo). |
+| `"cria endpoint POST /api/v1/users"` | `project-manager` routes to `backend-developer` agent, which writes controller + service + DTO + test, following your stack pack's conventions. |
+| `"audita seguranca do projeto"` | `project-manager` routes to `security-engineer` agent, which runs an OWASP/LGPD scan and reports findings. |
+| `"grill me about authentication"` | `grill-me` skill starts a discovery interview — one decision at a time — and persists conclusions to `docs/discovery/DISCOVERY_authentication.md`. |
+| `"executa Sprint 1 do PLAN_users.md"` | `run-sprint` skill executes the sprint with TDD, dispatching `qa-engineer`, `backend-developer`, `frontend-developer`, and `gate-keeper` in parallel. |
+
+Each prompt triggers the right skill via keyword match (declarations in `.claude/skills/<name>/SKILL.md` frontmatter `description`). You do not need to memorize them — just describe what you want.
+
+---
+
+## Inspect what is running — duk dashboard
+
+```bash
+duk dashboard
+```
+
+Opens a local web UI at `http://localhost:4242` (or next free port) with:
+
+- **Telemetry**: which subagent was invoked, when, how long
+- **Model breakdown**: how much Opus vs Sonnet vs Haiku you have used
+- **RTK savings**: if you have RTK on PATH, real token savings from the proxy
+- **Manuals + Tech Docs tabs**: this very page (quickstart), architecture overview, skills reference, agents reference, plugins, ADR catalog
+
+The dashboard reads from `~/.claude/telemetry.db` (SQLite, populated by the `SubagentStop` hook). It is read-only — nothing you do in the UI changes your project.
+
+---
+
+## Validate everything is OK — duk doctor
+
+```bash
+duk doctor
+```
+
+Mechanical health check. No LLM, no API call. Validates:
+
+- Node ≥18, git, npx, python presence
+- Harness `.claude/` structure is complete
+- `~/.claude/settings.json` is valid JSON; hooks point to existing files
+- Stack packs are available
+- Credentials file exists (for VPS-aware skills)
+- If you are inside an adopted project: `MANIFEST` exists and Project Identity is filled
+
+Returns exit code `0` if all PASS. Use `--strict` to fail on WARNs too. Use `--json` for CI parsing.
+
+```bash
+duk doctor --strict
+duk doctor --json | jq .summary
+```
+
+---
+
+## What to read next
+
+You just installed the harness, scaffolded or adopted a project, ran your first prompt, and verified the environment. From here, three reading paths depending on your goal:
+
+| Goal | Read |
+|---|---|
+| "How do skills know when to fire?" | [architecture-overview](../docs/architecture-overview) — 3-layer model, keyword matching, agent dispatch |
+| "What skill should I use for X?" | [skills-reference](../docs/skills-reference) — full catalog, per-skill triggers, when NOT to use |
+| "Which agent does what?" | [agents-reference](../docs/agents-reference) — 25 agents grouped by domain authority |
+| "What is the discovery → delivery pipeline?" | [pipeline](../docs/pipeline) — full canonical flow + shortcuts for small features |
+| "Who decides what, when do I get interrupted?" | [autonomy-matrix](../docs/autonomy-matrix) — the master rule |
+| "Why these external plugins?" | [plugins](../docs/plugins) — selection rationale for grill-me, caveman, impeccable, rtk |
+| "What CLI commands exist?" | [cli-reference](../docs/cli-reference) — all `duk` commands with flags, examples, exit codes |
+| "Java + Spring Boot specifics" | [Fullstack manual](fullstack) |
+| "Angular specifics" | [Frontend manual](frontend) |
+| "Spring Boot backend only" | [Backend manual](backend) |
+| "React Native mobile" | [Mobile manual](mobile) |
+
+If you adopt the harness on a real project and ship something with it, please consider contributing an entry to `docs/EVIDENCE.md` — real metrics from real projects are what move the harness forward.
+
+---
+
+## Troubleshooting
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `duk doctor` reports Node < 18 | Old Node installed | Install Node 18+ from nodejs.org or your package manager |
+| `duk install` aborts with "drift detected" | You modified `.claude/` after the previous install | Move your changes to `.claude/local/` (preserved across installs) OR run `duk install --force` (overwrite + backup) |
+| Chat does not seem to trigger any skill | Keywords do not match any skill's `description` | Try a more explicit phrasing OR fall through to `project-manager` (catch-all) by phrasing as a normal dev request like "create endpoint POST /api/v1/foo" |
+| `duk dashboard` says "port 4242 in use" | Another process holds the port | Pass `--port 5000` (or any free port) |
+| RTK widget shows no data | RTK not on PATH (intentional fallback) | Install rtk separately if you want the metric; otherwise ignore |
+| `duk lint` reports ERRORs in skills you did not touch | Frontmatter incomplete in the harness | Open an issue with the lint output — likely a regression |
+
+For deeper problems: [troubleshooting](../docs/troubleshooting).
+
+---
+
+## What this guide skipped on purpose
+
+- The 8-stage canonical pipeline (`grill-me → to-prd → to-issues → analyst → architect → tech-lead → sprint-runner → gate-keeper → code-reviewer → tech-lead → brain-keeper`). For 99% of tasks you do not invoke it directly — `project-manager` handles routing. Read [pipeline](../docs/pipeline) when you need the formal flow.
+- 34 ADRs. They explain why each architectural choice was made. Read them when you are evaluating whether to adopt the harness for a serious project, or when you propose a change. Not required for daily use.
+- The senior+ quality gate thresholds (coverage ≥85%, mutation ≥70%, a11y, Lighthouse). They run when `gate-keeper` is invoked — you do not need to memorize them.
+
+If after 5 minutes you got the value above and want to go deeper, all of this is one click away in the dashboard. Welcome.

package/dashboard/public/index.html

@@ -0,0 +1,217 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+  <title>development-utility-kit dashboard</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com" />
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;700&display=swap" rel="stylesheet" />
+  <link rel="stylesheet" href="style.css" />
+  <script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"></script>
+  <script
+    src="https://cdn.jsdelivr.net/npm/marked@15/marked.min.js"
+    onerror="(function(){var s=document.createElement('script');s.src='vendor/marked.min.js';document.head.appendChild(s);})()"
+  ></script>
+</head>
+<body>
+
+  <!-- LOADING SCREEN -->
+  <div class="loader" id="loader">
+    <div style="text-align:center">
+      <div class="loader-ring-wrap">
+        <div class="loader-ring"></div>
+        <div class="loader-ring"></div>
+        <div class="loader-ring"></div>
+      </div>
+      <div class="loader-text">INITIALIZING</div>
+    </div>
+  </div>
+
+  <!-- NEURAL NETWORK BACKGROUND -->
+  <canvas id="neuralCanvas"></canvas>
+
+  <header class="app-header">
+    <h1>development-utility-kit</h1>
+    <span class="badge">dashboard</span>
+    <span class="badge" id="last-updated">loading…</span>
+
+    <nav class="tab-nav" role="tablist">
+      <button class="tab-btn active" data-tab="dashboard" role="tab" aria-selected="true">Dashboard</button>
+      <button class="tab-btn" data-tab="manual" role="tab" aria-selected="false">Manual</button>
+      <button class="tab-btn" data-tab="docs" role="tab" aria-selected="false">Tech Docs</button>
+    </nav>
+
+  </header>
+
+  <!-- Panel: Dashboard (existing telemetry) -->
+  <section id="panel-dashboard" class="tab-panel active" role="tabpanel">
+    <main class="grid">
+
+      <!-- Card: Projects -->
+      <section class="card" id="projects-card">
+        <h2 class="card-title">Projects (last 30 days)</h2>
+        <ul class="project-list" id="project-list">
+          <li class="empty-state">Loading…</li>
+        </ul>
+      </section>
+
+      <!-- Card: Models -->
+      <section class="card" id="models-card">
+        <h2 class="card-title">Model Breakdown</h2>
+        <div class="chart-wrap">
+          <canvas id="models-chart"></canvas>
+        </div>
+      </section>
+
+      <!-- Card: RTK Token Savings -->
+      <section class="card" id="rtk-card">
+        <h2 class="card-title">RTK Token Savings</h2>
+        <div class="rtk-summary" id="rtk-summary">
+          <div class="rtk-stat">
+            <span class="value" id="rtk-tokens">—</span>
+            <span class="label">tokens saved</span>
+          </div>
+          <div class="rtk-stat">
+            <span class="value" id="rtk-pct">—</span>
+            <span class="label">savings %</span>
+          </div>
+        </div>
+        <div class="chart-wrap">
+          <canvas id="rtk-chart"></canvas>
+        </div>
+      </section>
+
+    </main>
+
+    <!-- Processes panel: shown when a project is selected from the list -->
+    <section id="processes-panel" class="processes-panel" hidden aria-live="polite">
+      <div class="processes-header">
+        <h2 class="processes-title">Processes — <span id="processes-project-name"></span></h2>
+        <button class="processes-close" id="processes-close" aria-label="Close processes panel">&times;</button>
+      </div>
+      <div id="processes-list" class="processes-list">
+        <p class="empty-state">Loading…</p>
+      </div>
+    </section>
+  </section>
+
+  <!-- Panel: Manual -->
+  <section id="panel-manual" class="tab-panel" role="tabpanel" hidden>
+    <div class="panel-layout">
+      <aside class="toc-sidebar" id="toc-manual" aria-label="Table of contents"></aside>
+      <div class="panel-content">
+        <div class="scenario-selector" id="manual-scenario-selector">
+          <!-- Scenario buttons rendered by app.js from manifest -->
+        </div>
+        <div id="translation-banner-manual" class="translation-banner" hidden>
+        </div>
+        <div class="content-body" id="manual-content-body">
+          <p class="empty-state">Select a scenario above.</p>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <!-- Panel: Tech Docs -->
+  <section id="panel-docs" class="tab-panel" role="tabpanel" hidden>
+    <div class="panel-layout">
+      <aside class="toc-sidebar" id="toc-docs" aria-label="Table of contents"></aside>
+      <div class="panel-content">
+        <div id="translation-banner-docs" class="translation-banner" hidden>
+        </div>
+        <div class="content-body" id="docs-content-body">
+          <p class="empty-state">Select a section.</p>
+        </div>
+      </div>
+    </div>
+  </section>
+
+  <footer class="status-bar">
+    <span><span class="dot"></span>live — polling every 5 s</span>
+    <span id="status-msg">connecting…</span>
+  </footer>
+
+  <!-- Neural canvas + loader dismiss -->
+  <script>
+    (function () {
+      var canvas = document.getElementById('neuralCanvas');
+      var ctx = canvas.getContext('2d');
+      var particles = [];
+
+      function resize() {
+        canvas.width = window.innerWidth;
+        canvas.height = window.innerHeight;
+      }
+      resize();
+      window.addEventListener('resize', resize);
+
+      function Particle() {
+        this.reset();
+      }
+      Particle.prototype.reset = function () {
+        this.x = Math.random() * canvas.width;
+        this.y = Math.random() * canvas.height;
+        this.size = Math.random() * 1.4 + 0.4;
+        this.vx = (Math.random() - 0.5) * 0.35;
+        this.vy = (Math.random() - 0.5) * 0.35;
+        this.opacity = Math.random() * 0.35 + 0.08;
+      };
+      Particle.prototype.update = function () {
+        this.x += this.vx;
+        this.y += this.vy;
+        if (this.x > canvas.width)  this.x = 0;
+        if (this.x < 0)              this.x = canvas.width;
+        if (this.y > canvas.height)  this.y = 0;
+        if (this.y < 0)              this.y = canvas.height;
+      };
+      Particle.prototype.draw = function () {
+        ctx.beginPath();
+        ctx.arc(this.x, this.y, this.size, 0, Math.PI * 2);
+        ctx.fillStyle = 'rgba(109,179,255,' + this.opacity + ')';
+        ctx.fill();
+      };
+
+      function init() {
+        particles = [];
+        var n = Math.min(55, Math.floor((canvas.width * canvas.height) / 22000));
+        for (var i = 0; i < n; i++) particles.push(new Particle());
+      }
+      init();
+      window.addEventListener('resize', init);
+
+      function animate() {
+        ctx.clearRect(0, 0, canvas.width, canvas.height);
+        for (var i = 0; i < particles.length; i++) {
+          particles[i].update();
+          particles[i].draw();
+          for (var j = i + 1; j < particles.length; j++) {
+            var dx = particles[i].x - particles[j].x;
+            var dy = particles[i].y - particles[j].y;
+            var d = Math.sqrt(dx * dx + dy * dy);
+            if (d < 120) {
+              ctx.beginPath();
+              ctx.strokeStyle = 'rgba(26,107,255,' + (1 - d / 120) * 0.1 + ')';
+              ctx.lineWidth = 0.5;
+              ctx.moveTo(particles[i].x, particles[i].y);
+              ctx.lineTo(particles[j].x, particles[j].y);
+              ctx.stroke();
+            }
+          }
+        }
+        requestAnimationFrame(animate);
+      }
+      animate();
+
+      window.addEventListener('load', function () {
+        setTimeout(function () {
+          var loader = document.getElementById('loader');
+          if (loader) loader.classList.add('hidden');
+        }, 900);
+      });
+    })();
+  </script>
+
+  <script src="app.js"></script>
+</body>
+</html>